hoi4-agent-tools 0.2.0 → 1.0.0

package/docs/gui-workflow.md

@@ -1,125 +0,0 @@
-# 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 be journaled or applied.
-
-With `writePolicy: "autonomous"`, call `hoi4.gui_rewrite` in `source`, `patches`, or `helpers` mode. The one call validates the proposal, persists exact recovery bytes, applies under the workspace lock, rebuilds the index, and post-validates. A successful result reports `execution: "applied"`; a blocked proposal reports `execution: "blocked"` and changes no source; a valid no-change request reports `execution: "unchanged"`. Any application or post-validation failure restores the original bytes automatically. No transaction diff/apply/rollback tools are exposed in autonomous mode.
-
-The optional `"transactions"` compatibility policy exposes `hoi4.gui_plan_changes` and the separate transaction review/apply tools instead. Both policies use the same source-preserving compiler, validation, journal, and recovery implementation.
-
-## Declarative helper compilation
-
-`hoi4.gui_rewrite` in `helpers` mode compiles a strict, build-time helper document into explicit `.gui` source and runs it through the normal autonomous rewrite path. In compatibility mode, use `hoi4.gui_plan_changes` with the same input. 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 rewrite 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

@@ -1,32 +0,0 @@
-# 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.
-- The aggregate shared index is bounded to 500,000 symbol records and 500,000 reference records. Reaching either ceiling returns an explicitly incomplete inventory. A symbol-ceiling drop records the affected symbol kind so unresolved definitions are reported as partial only where dropped symbols could contain them; the reference ceiling reports incomplete outbound-reference coverage without implying that a missing definition might exist. The server never presents a capped inventory as complete.
-- 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.
-- Autonomous mode deliberately exposes only `hoi4.focus_rewrite`, `hoi4.gui_rewrite`, and `hoi4.map_rewrite`; it does not expose transaction diff, status, apply, or explicit rollback tools. Failed application and post-validation restore automatically. An intentional later reversal requires Git or another explicit domain rewrite. The tools advertise `destructiveHint: true`, but MCP does not mandate per-tool confirmation and the server cannot override its host's approval policy.
-- 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 automatic failure restoration (plus explicit rollback in reviewed compatibility mode). 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. Git supplies project history but is not required for the internal recovery guarantee.
-- 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. Internal rewrite/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 [autonomous rewrites 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.

package/docs/map-workflow.md

@@ -1,95 +0,0 @@
-# Agent Nudger map workflow
-
-Agent Nudger is a headless declarative map rewrite service for coding agents. HTML/PNG/JSON maps are inspection evidence, not a manual editor.
-
-## Indexed sources
-
-The shared scan connects province bitmap and definitions, states, strategic regions, terrain/continent values, adjacency CSV, supply nodes, railways, victory points, resources/buildings, ownership/control/cores/claims, coast/ports, placement files, localisation, and dependency overrides. It honors each workspace's configured `roots.map`, `roots.states`, and `roots.localisation` directories. Files named by the active `default.map` (including adjacency, supply-node, railway, province, definition, and position files) remain authoritative for active reads and additive writes. Allocation and collision evidence additionally resolves every scanned root's own `default.map`-selected definition filename. A partial root without its own selector inherits the active definition filename for evidence only. If any selector-owning root has a malformed, parser-limited, or otherwise diagnostic-bearing `default.map`, map scan and indexing stop with `MAP_DEFAULT_MAP_SELECTOR_BLOCKED`; the service never substitutes `definition.csv`, `provinces.bmp`, or an inherited selector for an untrustworthy file.
-
-## Geometry input
-
-Province geometry rewrite requires one exact representation:
-
-- selected existing province IDs;
-- polygon with integer raster-boundary coordinates and explicit `fillRule: "even-odd"`;
-- raster mask manifest with dimensions, origin, exact selected-pixel count, SHA-256, and canonical Base64 data;
-- explicit absolute pixel region (`kind: pixels`).
-
-Natural-language descriptions can guide a coding agent, but are not accepted as rewrite geometry.
-
-Polygon vertices describe raster cell boundaries, not pixel indices. For a raster of `width` by `height`, every vertex must use an integer `x` from `0` through `width` and an integer `y` from `0` through `height`; the right and bottom boundary values `width` and `height` are valid. A greater coordinate is rejected with `MAP_GEOMETRY_OUT_OF_BOUNDS` before bounding-box or raster-work allocation, and polygon geometry is never silently clipped. Rasterization samples each candidate pixel at its center, `(x + 0.5, y + 0.5)`, using the required even-odd fill rule. Every selected center must still belong to the declared source province.
-
-Raster-mask `data` is one byte per cell in row-major order. Every byte is exactly `0` or `1`; the SHA-256 is computed over those decoded bytes. The declared rectangle must fit the active raster, its byte length must equal `width * height`, and both the selected count and hash must match before every selected absolute pixel is checked against the source province. A mask may describe at most 20,000,000 cells, while any one split, mask, polygon, normal-adjacency transfer set, whole-province color update, or merge may select/recolor at most 1,000,000 pixels. Polygon admission also stops at 50,000,000 cell-point comparisons. Counts known from the manifest or indexed province geometry are checked before decoding, raster scanning, or selection-buffer allocation; an over-limit operation returns `MAP_SELECTED_PIXEL_BUDGET_BLOCKED` without proposing changes.
-
-Selected geometry is represented internally as deterministic row-major numeric offsets rather than coordinate strings or `{x, y, color}` object arrays. The fixed 1,000,000-pixel ceiling keeps the primary four-byte offset buffer below 4 MiB (4,000,000 bytes), and uniform recolors copy the BMP once and write directly through those offsets. Explicit-coordinate duplicates and normal-adjacency transfer duplicates are detected by numeric offset. Source BMP operations use exact colors without antialiasing, interpolation, resizing, alpha conversion, or palette quantization. Untouched bytes and pixels remain identical.
-
-## State payload policies
-
-Split/merge/move operations do not guess manpower, resources, buildings, victory points, ownership, control, cores, claims, supply, or railway behavior. Each applicable payload must select an explicit policy:
-
-- remain with original state;
-- move with a named province;
-- deterministic proportional distribution;
-- exact manifest values;
-- block until resolved.
-
-Proportional rounding is deterministic and checked for conservation. The rewrite remains blocked while any required policy is unresolved.
-
-State move, split, and merge manifests also declare `ports`, `supplyNodes`, `railways`, and `positions` as `follow-province`. Those records are keyed by a selected province or its state association, so their source bytes remain unchanged except for the already modelled state-ID field on applicable position rows. The explicit literals make that behavior reviewable and prevent a partial distribution object from silently choosing it.
-
-New states require an explicit name localisation key and a strict `localisation` policy. `existing` requires exactly one safe active `l_english` entry. `upsert` updates only the quoted value of that exact entry, appends to an explicitly targeted existing file, or creates an explicitly targeted file in a configured localisation root. Created and edited files are UTF-8 with BOM. Comments, key versions, spacing, line endings, ordering, unknown lines, and unrelated entries are preserved. Missing policy/target/key, duplicate active keys, unsafe paths, target mismatch, non-BOM encoding, or malformed target source blocks the whole operation before it contributes changes.
-
-`StateRecord.capital` is inspection-only derived data: select the province with the highest exact victory-point value, then the lowest province ID on a tie. Current state source has no generic `capital = <province>` field. Agent Nudger never emits or patches that assignment. `update_state.changes.capital` is therefore an assertion, not a write: it is accepted only beside an exact `victoryPoints` payload whose derived result matches the assertion (including `null` for no victory points). State moves, splits, and merges derive the result from their explicit VP policy.
-
-## Province merge and removal
-
-`merge_provinces` and `remove_province` accept arbitrary compatible source IDs; removed IDs do not need to be the highest rows in `definition.csv`. Surviving definitions are compacted deterministically to contiguous IDs from zero in old-ID order. Removed source IDs map to the target's compacted ID, including when the target itself moves downward.
-
-The same total old-to-new map is applied as one recoverable operation to state membership, victory points, province buildings, strategic regions, special-adjacency endpoints and through-provinces, supply nodes, railways, unit positions, and building-position sea references. Source pixels are repainted with the target color; other province colors and pixels remain unchanged. Reference collisions created by the merge are resolved by the declared sum/deduplicate policy. Definition row order, comments and extra fields, text-file comments, line endings, and source encoding are retained by targeted rewrites. A failed application or post-validation restores every affected file byte-for-byte.
-
-Compaction requires an active definition table that is already contiguous from zero and unambiguous by ID and color. The merge also requires every source and target to share province type plus exact state and strategic-region membership; these are refusal cases rather than guessed redistribution.
-
-Province split/create manifests explicitly retain existing victory points, province buildings, ports, supply nodes, railways, special adjacencies, positions, and entity locators on the source province while the selected pixels and new ID join the declared state and strategic region. To move connected data to the new province, place the corresponding exact remove/add or update operations after the split in the same ordered rewrite. Omitting any retention field blocks the split before geometry changes are proposed.
-
-## Province type migration
-
-`update_province_definition` can migrate among `land`, `sea`, and `lake`. A real type change requires the complete strict `distribution` object; missing, partial, unknown, or transition-incompatible policies block the operation before it contributes any file change.
-
-The policy explicitly covers:
-
-- exact state membership (`retain`, `remove` with the indexed state ID, or `assign` with a target state ID);
-- retention of state-level values in their current states and strategic-region membership;
-- victory points and non-port province buildings (`retain-if-valid` or `remove`);
-- naval-base buildings plus port placements/references (`retain-if-valid` or `remove`);
-- supply nodes (`retain-if-valid` or `remove`);
-- railways (`retain-if-valid` or remove every containing route; routes are never silently spliced);
-- building and unit positions (`retain-if-valid` or `remove`) and entity locators (`retain-at-coordinate`, because type migration does not alter geometry);
-- special adjacency endpoint/through references (`retain-if-valid` or `remove-referencing`).
-
-Land-to-water requires removal from the exact indexed state and cannot leave that state without land. Water-to-land requires an explicit existing target state in the same strategic region. Sea targets require `ocean` terrain and continent `0`; lake targets require `lakes` and continent `0`; land targets require a non-water terrain and nonzero continent. Coastal fields and neighboring coastal changes remain exact manifest inputs and are verified by final map validation. Dependency removals and the definition edit share one hash-bound journal, so success or automatic failure restoration covers every affected state, definition, network, position, and adjacency file together.
-
-When a dependency should move rather than disappear, place the corresponding exact `update_state`, position, supply, railway, or adjacency operation after the type migration in the same ordered manifest. The migration policy removes or retains the old record explicitly; the later operation supplies the new target explicitly.
-
-## Normal and special adjacency
-
-Special adjacency rows remain declarative `add_adjacency` and `remove_adjacency` operations against the active `default.map` adjacency CSV. Normal topological adjacency is derived only from four-neighbor province bitmap geometry (including horizontal map wrap) and uses separate `add_normal_adjacency` and `remove_normal_adjacency` operations.
-
-Every normal-adjacency operation carries unique exact pixel transfers with a coordinate, the province currently owning that pixel, and the destination province. Both requested endpoints and all transfer provinces must exist, every source must match the active raster, and every transfer must involve at least one requested endpoint. Agent Nudger repaints only those 24-bit pixels, rebuilds topology, and restores the operation unless the requested pair is present after an add or absent after a remove. Related coastal-definition changes remain explicit ordered operations in the same rewrite.
-
-## Allocation
-
-ID/color allocation scans current game, dependencies, and mod sources first, including the definition table selected by each root's own `default.map` even when its filename differs from the active table. It records per-file/root maxima, used ranges, active definition contiguity, collisions, reserved values, selected value/color, and source revision. Explicit values are checked against the same evidence. A lower-root ID/color collision is returned as a named dependency conflict on the manifest operation that requested it. The allocator never assumes the numerically next value is safe.
-
-## Autonomous rewrite
-
-With `writePolicy: "autonomous"`, submit the complete ordered operation manifest once to `hoi4.map_rewrite`. The tool scans dependencies, resolves exact geometry and policies, renders baseline/proposed/diff evidence, validates, journals exact before-bytes, applies all affected text and binary files under the workspace lock, rescans, and post-validates. `execution: "applied"` means the final hashes and validation passed. A blocked proposal reports `execution: "blocked"` and changes nothing; a valid no-change request reports `execution: "unchanged"`; a failure after replacement begins restores every affected file automatically.
-
-No transaction tools are registered in autonomous mode. The optional `"transactions"` compatibility policy exposes `hoi4.map_plan` followed by the separate diff/apply/status/rollback tools, using the same internal journal and recovery engine.
-
-## Artifacts and validation
-
-Map base layers cover province, state, strategic region, terrain, continent, owner, controller, cores, claims, and coast. Overlays cover coastlines, ports, victory points, resources, state buildings, province buildings, supply nodes, railways, special adjacencies, building positions, unit positions, and weather positions. Resource/building data is present in canonical JSON as exact sorted state/province maps as well as deterministic PNG markers; HTML embeds the same JSON and PNG with pan/zoom controls. Render loops honor cancellation signals.
-
-Every map preflight stores three content-addressed PNG/JSON/HTML triplets: baseline (`map-before.*`), proposed (`map-proposed.*`), and changed-pixel/semantic diff (`map-diff.*`). Their links and content hashes are included in the internal plan hash. Semantic diff JSON includes definitions, state/region membership, full state values (manpower, category, resources, owner/controller, cores/claims, VPs, state/province buildings, and derived capital), ports, building/unit/weather positions, entity locators, supply, railways, exact special-adjacency records, and exact bitmap-derived normal-adjacency pairs.
-
-Validation detects duplicate IDs/colors, bitmap-definition mismatches, invalid references, unassigned/multi-state land, invalid derived capitals/VPs/ports/regions/adjacency/supply/rail/placements, removed references, coast inconsistencies, duplicate state IDs, missing localisation, ownership/control conflicts, lost payload, changes outside declared bounds, and dependency conflicts. Geometry review includes disconnected components, one-pixel corridors, and enclosed province holes. Hole detection uses one bounded digital-topology pass and reports `MAP_PROVINCE_HOLE_REVIEW` as a warning because intentional enclaves can be valid; provinces crossing the horizontally wrapping seam are excluded from planar hole classification. Baseline comparisons diagnose dimensions, file/DIB header, row orientation, pixel offset, bit depth, and palette changes separately. Sea and legitimate lake/island cases are not misclassified as missing state membership.

package/docs/performance.md

@@ -1,117 +0,0 @@
-# Performance benchmark
-
-Performance is recorded by an explicit developer command, not by a required CI timing assertion:
-
-```bash
-npm ci
-npm run benchmark
-```
-
-The command prints a structured JSON report to stdout and exits nonzero only for correctness failures such as a fixture below its required size, a changed deterministic output, or unsafe cache invalidation. It has no elapsed-time or memory pass threshold. Timing and memory naturally vary by host, runtime, system load, and native codec build.
-
-## Workload and methodology
-
-The benchmark reads only checked-in, project-owned synthetic fixtures:
-
-- `fixtures/focus`: 255 focuses in ten route families, scanned and indexed through `CoreEngine`, then laid out, linted, rendered, and stored through `FocusWorkbench`;
-- `fixtures/gui`: 158 source elements and 203 visible scene elements, rendered through `ScriptedGuiStudio` as fourteen state scenes, three resolution/UI-scale scenes, five primary variants, comparison evidence, and 24 stored artifacts;
-- `fixtures/map`: the complete 256×256 map fixture across game, dependency, and mod fixture roots, scanned and indexed through `AgentNudger`, then rendered in all ten current base layers (including continent) with all twelve current overlays enabled;
-- a temporary copy of the focus workspace for metadata/content-hash cache checks.
-
-The 255-focus fixture's 13,152×3,600 raster (47,347,200 pixels) is intentionally below the fixed 48-Mi-pixel per-artifact ceiling. The vanilla 5,632×2,048 map is also below the ceiling at scale 1, and its diff/before/proposed output trio charges 34,603,008 of the 64-Mi-pixel aggregate request budget. Larger scale or variant combinations are refused before allocation rather than included in benchmark timing.
-
-Each workload runs twice in one process. **Cold** means the first invocation using a fresh service and empty temporary artifact/cache roots. **Warm** means the immediate repeat in the same Node process. The script does not evict the operating system's file cache, so “cold” is an application-level cold run, not a physical-disk cold run. With `--expose-gc`, garbage collection is requested before each measured pass.
-
-Elapsed values use the monotonic Node performance clock. Memory is the process endpoint measurement from `process.memoryUsage()`, not a sampled peak. RSS includes native allocations from Sharp/libvips; because suites run sequentially, native allocator retention can affect later baselines and deltas. One cold and one warm pass keep the command bounded; rerun it several times externally when investigating variance.
-
-The GUI total deliberately includes an explicit source scan followed by `renderAndStore`, which performs its own scan as part of the public workflow. The map render phase operates on the fully scanned index and renders all base layers without artifact-store I/O. Output fingerprints must match between cold and warm passes.
-
-## Recorded result
-
-Recorded at `2026-07-10T22:22:50.905Z` with this exact command from the repository root:
-
-```bash
-npm run benchmark
-```
-
-Runtime and platform:
-
-- Windows (`win32`) release `10.0.26200`, x64;
-- AMD Ryzen 5 7500F 6-Core Processor; 12 logical processors;
-- 32,375.906 MiB total physical memory;
-- Node.js `v24.15.0`, V8 `13.6.233.17-node.48`;
-- Sharp `0.35.3`, libvips `8.18.3`.
-
-Times are milliseconds. Memory columns are endpoint delta MiB for the measured pass.
-
-| Workload                       | Pass |      Total |           Scan/index |                      Layout or render/store |   RSS Δ | Heap-used Δ |
-| ------------------------------ | ---- | ---------: | -------------------: | ------------------------------------------: | ------: | ----------: |
-| Focus (255 nodes)              | Cold | 15,082.652 |               36.402 | layout 62.085; lint/render/store 14,983.948 |  21.820 |      12.223 |
-| Focus (255 nodes)              | Warm | 16,721.268 |                8.274 | layout 59.933; lint/render/store 16,652.932 |  55.937 |       4.343 |
-| GUI (158 source / 203 visible) | Cold | 11,507.893 | 59.041 explicit scan |             gallery render/store 11,448.837 | 200.343 |      47.387 |
-| GUI (158 source / 203 visible) | Warm |  5,607.155 | 46.417 explicit scan |              gallery render/store 5,560.708 |  49.492 |      48.742 |
-| Map (65,536 pixels)            | Cold |    852.390 |               31.467 |        ten layers × twelve overlays 820.908 | -38.598 |      58.195 |
-| Map (65,536 pixels)            | Warm |    671.601 |               21.518 |        ten layers × twelve overlays 650.073 |  20.762 |      30.028 |
-
-Relevant output and input counts from the same run:
-
-| Workload | Counts                                                                                                                                                                                |
-| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Focus    | 8 scanned files; 255 focuses; 10 route families; 6 artifacts                                                                                                                          |
-| GUI      | 7 scanned files; 158 source elements; 203 visible elements; 14 states; 3 resolutions; 5 primary variants; 24 artifacts; 14,455,435 output bytes                                       |
-| Map      | 21 scanned files / 198,897 bytes; 65,536 pixels; 5 definition rows; 4 provinces with geometry; 3 states; 2 strategic regions; 10 base layers; 12 overlays per layer; 14,339 PNG bytes |
-
-Cold and warm output fingerprints matched for all three workloads.
-
-## Cache invalidation behavior
-
-`WorkspaceScanner` reads file metadata and bytes on every scan and computes a SHA-256 content hash. `CoreEngine` derives its revision from each file's display path, load order, and content hash, then keys its in-memory scan/index cache by workspace ID and revision. Size and modification time are recorded as evidence but are not trusted as the semantic cache key.
-
-Scan admission normally serializes physical scans for a workspace. If a scanner ignores cancellation, one replacement scan may run after the original request is aborted so current callers are not held behind abandoned work. At most two physical scanners may exist for that workspace in this state; a third request waits. Generation fencing prevents a stale late completion from replacing the current cache entry.
-
-The benchmark changes only the copied fixture's modification time and confirms that the revision remains unchanged and the in-memory snapshot is reused. It then changes source bytes without changing file size or modification time and confirms that the content hash changes, the revision changes, and the cached snapshot is not reused. In the recorded run:
-
-- baseline scan: 21.353 ms;
-- metadata-only rescan/cache hit: 5.431 ms;
-- same-size, same-mtime content change/rescan: 20.300 ms.
-
-The deterministic unit test in `tests/unit/core-cache.test.ts` continuously checks this correctness property without asserting timing. Autonomous rewrites and reviewed transaction apply/rollback paths all invalidate the workspace cache; the content-derived revision remains the safety backstop for external edits.
-
-The Scripted GUI Studio and Agent Nudger benchmark paths currently rebuild their domain scans/indexes on each call. Their warm figures therefore reflect runtime/JIT and operating-system cache effects rather than a domain-level memoization claim. Stored artifacts are content-addressed, but artifact storage is not treated as a parsed-source cache.
-
-## Reproducing and comparing runs
-
-Run from a clean install on the host being measured:
-
-```bash
-npm ci
-npm run --silent benchmark > benchmark-result.json
-```
-
-No game installation, mod workspace, environment variable, network access, or proprietary input is used. The script creates all runtime storage below the operating system temporary directory and removes it on completion. Compare the JSON phase timings, memory samples, counts, and runtime/platform block; do not compare only the total time across unlike hosts.
-
-To check cache correctness without collecting performance data:
-
-```bash
-npm test -- tests/unit/core-cache.test.ts
-```
-
-## Opt-in installed-data qualification
-
-The opt-in local suite is a compatibility qualification, not a CI performance threshold. It reads configured installed-game and external-mod roots in place, writes only to an operating-system temporary directory, and neither launches the game nor copies proprietary inputs into the project.
-
-On the same Windows/Node host documented above, the final `2026-07-10` qualification completed all three required tests through the fail-closed `npm run test:local` harness:
-
-| Workflow                                                                                                    |   Elapsed |
-| ----------------------------------------------------------------------------------------------------------- | --------: |
-| Large vanilla focus import, stable layout, and two deterministic renders, plus an external-mod focus render |  83.551 s |
-| External GUI/GFX/font graph construction and two deterministic full/annotated renders                       |  56.019 s |
-| External map scan plus state/coastline/supply/railway render and content-addressed PNG/JSON/HTML storage    |  22.981 s |
-| Total test time                                                                                             | 162.578 s |
-
-The GUI qualification's canonical source-graph JSON was 302,497,021 bytes. The default
-134,217,728-byte per-object ceiling remained enabled: storage produced a byte-exact three-chunk
-resource bundle plus its canonical index, repeated the same render/storage call, and verified
-deterministic output without truncating the graph or increasing the ceiling.
-
-The reporter independently confirmed three completed tests and no unhandled worker error. Root paths and source-derived content are intentionally absent from the report. These timings vary with installed data, disk/cache state, processor, memory, and codec versions; only completion and deterministic/correct output are assertions.