hoi4-agent-tools 1.1.0 → 1.2.0

package/docs/events.md

@@ -0,0 +1,113 @@
+# Event chains
+
+The Event Chain Viewer analyzes event definitions and call sites across the active mod, configured dependencies, and vanilla sources. It is read-only: it does not rewrite event files or simulate the game.
+
+Start with `hoi4.mods` to obtain the workspace ID, then use the three event tools as needed.
+
+## Inspect
+
+`hoi4.event_inspect` provides seven focused modes:
+
+- `scan`: inventory event definitions, namespaces, call sites, and unresolved references.
+- `roots`: find likely entry points and explain why they are roots.
+- `trace`: follow bounded incoming or outgoing routes from an event.
+- `explain_path`: explain a selected route edge by edge with exact source locations.
+- `state_flow`: report flags, variables, targets, scopes, and other tracked state read or changed along a route.
+- `lint`: find missing targets, unreachable events, suspicious cycles, conflicting definitions, invalid timing, and unresolved dynamic calls.
+- `impact`: identify callers, descendants, state dependencies, and files affected by a proposed event change.
+
+Use narrow identifiers, direction, and depth limits when the task concerns one chain. The compact response summarizes the result; complete graphs and diagnostics are returned as linked resources.
+
+Selectors use one of these forms:
+
+```json
+{ "kind": "event", "eventId": "namespace.1" }
+{ "kind": "namespace", "namespace": "namespace" }
+{ "kind": "file", "sourcePath": "events/example.txt" }
+{ "kind": "source", "sourcePath": "events/example.txt", "line": 40 }
+{ "kind": "node", "nodeId": "event:namespace.1" }
+{ "kind": "manifest", "manifest": { "eventIds": ["namespace.1", "namespace.2"] } }
+```
+
+`trace` uses `selector`; `explain_path` uses `from` and `to`; and `state_flow` may add a `stateSubject` object with `kind` and `name`. Allowed state kinds are `country_flag`, `global_flag`, `state_flag`, `variable`, `global_variable`, `array`, `event_target`, `global_event_target`, and `saved_scope`.
+
+`impact` requires an `impactSubject` object with `kind` and `name`. Allowed impact kinds are `event`, `helper`, `flag`, `variable`, `array`, `event_target`, and `saved_scope`. Set `refresh: true` after source changes when a prior graph may be cached.
+
+Example `hoi4.event_inspect` arguments:
+
+```json
+{
+  "workspaceId": "my-mod",
+  "mode": "trace",
+  "selector": { "kind": "event", "eventId": "namespace.1" },
+  "direction": "downstream",
+  "maxDepth": 8,
+  "maxNodes": 500,
+  "maxEdges": 2000,
+  "expandHelpers": false,
+  "refresh": false
+}
+```
+
+## Render
+
+`hoi4.event_render` produces deterministic, source-linked views of a chain. The exact `view` values are `overview`, `neighborhood`, `options`, `entries`, `reachability`, `timing`, `state`, `targets`, `scope`, `terminals`, and `unresolved`. JSON is the authoritative graph; SVG and PNG provide visual review, with HTML available for bundled navigation when requested.
+
+Large overview requests return a compact overview plus bounded branch JSON/SVG/PNG resources and a coverage manifest. The manifest indexes every generated data artifact by canonical MCP resource URI, including artifacts omitted from the compact tool response. Follow those links instead of asking the agent to reason from one unreadable all-node image.
+
+Dynamic and meta-generated targets that cannot be resolved statically remain explicit unresolved edges. The renderer never invents a destination.
+
+Example `hoi4.event_render` arguments:
+
+```json
+{
+  "workspaceId": "my-mod",
+  "view": "neighborhood",
+  "selector": { "kind": "event", "eventId": "namespace.1" },
+  "direction": "both",
+  "maxDepth": 4,
+  "maxNodes": 120,
+  "expandHelpers": false,
+  "includeHtml": false,
+  "refresh": false
+}
+```
+
+## Compare
+
+`hoi4.event_compare` compares whole workspace event graphs; it does not accept a chain selector. `before` and `after` each accept exactly one graph reference: `{ "revision": "<sha256>" }` or `{ "artifactUri": "hoi4-agent://..." }`. If no reference or overlay is supplied, the tool compares the previous cached revision with a fresh scan of the current source and reports an error when no prior revision is available. Comparisons refresh current source by default so normal agent file edits are detected; set `refresh: false` only when intentionally comparing cached graphs.
+
+Alternatively, compare the current graph with `proposedSources`, an in-memory list of `{ relativePath, source, expectedSourceHash? }` overlays. Set `source` to a string to add or replace source, or to `null` to delete an existing mod source. `after` and `proposedSources` are mutually exclusive. Proposed sources are analyzed without being written. The result reports added, removed, and changed definitions, edges, options, state operations, diagnostics, and route reachability.
+
+Example `hoi4.event_compare` arguments:
+
+```json
+{
+  "workspaceId": "my-mod",
+  "proposedSources": [
+    {
+      "relativePath": "events/example.txt",
+      "source": "add_namespace = namespace\ncountry_event = { id = namespace.1 }\n"
+    },
+    {
+      "relativePath": "events/obsolete.txt",
+      "source": null
+    }
+  ],
+  "render": true,
+  "maxRenderNodes": 120,
+  "refresh": true
+}
+```
+
+## Agent workflow
+
+A coding agent can combine the viewer with repository instructions, skills, and other tools:
+
+1. call `hoi4.event_inspect` with `scan` or `roots` to locate the chain;
+2. use `trace`, `explain_path`, `state_flow`, or `impact` for the current task;
+3. read linked JSON evidence only when the compact summary is insufficient;
+4. edit event source with the agent's normal file-editing workflow;
+5. call `hoi4.event_compare`, `lint`, and `hoi4.event_render` to review the result; comparison refreshes the edited source by default.
+
+Static analysis cannot prove runtime conditions, random outcomes, delayed scheduling, or arbitrary meta-generated text. Those limits are reported in diagnostics and artifacts rather than hidden or guessed. The server never launches or captures Hearts of Iron IV.

package/docs/setup.md

@@ -5,11 +5,11 @@ HOI4 Agent Tools requires Node.js 22 or 24.
 ## Install and initialize
 
 ```bash
-npm install --global hoi4-agent-tools@1.1.0
+npm install --global hoi4-agent-tools@1.2.0
 hoi4-agent-tools-setup --init
 ```
 
-The setup command discovers standard HOI4 game and mod locations, creates a separate storage folder for generated workspace data, and writes the default per-user config. Each configured mod root is a parent folder whose immediate child directories are individual mods. Every discovered mod is writable through the three rewrite tools; no per-mod write switch or approval step is required. The installed game remains reference-only.
+The setup command discovers standard HOI4 game and mod locations, creates a separate storage folder for generated workspace data, and writes the default per-user config. Each configured mod root is a parent folder whose immediate child directories are individual mods. Every discovered mod is available through the focus, GUI, map, and read-only event tools without per-mod setup. The game root supplies vanilla references.
 
 After connecting the MCP server, call `hoi4.mods` to confirm which mods are available.
 
@@ -22,7 +22,7 @@ hoi4-agent-tools-setup --init --mod-root /projects/hoi4-mods --mod-root /worksho
 ```
 
 - `--mod-root PATH` adds a parent folder containing mods. Repeat it for additional locations.
-- `--game-root PATH` selects the installed game folder used as a read-only reference.
+- `--game-root PATH` selects the installed game folder used for vanilla references.
 - `--workspace-storage-root PATH` selects where indexes, renders, and other generated workspace files are stored.
 - `--config PATH` writes or reads a config at a custom path instead of the default per-user location.
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "hoi4-agent-tools",
   "mcpName": "io.github.klimPaskov/hoi4-agent-tools",
-  "version": "1.1.0",
-  "description": "MCP tools for coding agents to create and clean HOI4 focus trees, scripted GUIs, and maps",
+  "version": "1.2.0",
+  "description": "Analyze HOI4 event chains; create and clean focus trees, scripted GUIs, and maps with coding agents.",
   "type": "module",
   "license": "Apache-2.0",
   "author": "HOI4 Agent Tools contributors",
@@ -21,6 +21,8 @@
     "coding-agents",
     "clausewitz",
     "focus-trees",
+    "event-chains",
+    "hoi4-events",
     "scripted-gui",
     "hoi4-map"
   ],
@@ -31,6 +33,7 @@
     "dist/",
     "docs/README.md",
     "docs/setup.md",
+    "docs/events.md",
     "docs/focus.md",
     "docs/gui.md",
     "docs/map.md",
@@ -60,10 +63,11 @@
     "test:local": "tsx scripts/run-local-tests.ts",
     "test:coverage": "vitest run --coverage",
     "benchmark": "node --expose-gc --import tsx scripts/benchmark.ts",
-    "fixtures:generate": "npm run fixtures:generate:focus && npm run fixtures:generate:gui && npm run fixtures:generate:map",
+    "fixtures:generate": "npm run fixtures:generate:focus && npm run fixtures:generate:gui && npm run fixtures:generate:map && npm run fixtures:generate:event",
     "fixtures:generate:focus": "tsx scripts/generate-fixtures.ts",
     "fixtures:generate:gui": "tsx scripts/generate-gui-fixture.ts",
     "fixtures:generate:map": "tsx scripts/generate-map-fixture.ts",
+    "fixtures:generate:event": "tsx scripts/generate-event-fixture.ts",
     "fixtures:check": "npm run fixtures:generate && tsx scripts/check-generated.ts fixtures",
     "schemas:generate": "tsx scripts/generate-schemas.ts",
     "schemas:check": "tsx scripts/generate-schemas.ts && tsx scripts/check-generated.ts schemas",

package/server.json

@@ -2,8 +2,8 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.klimPaskov/hoi4-agent-tools",
   "title": "HOI4 Agent Tools",
-  "description": "Create and clean HOI4 focus trees, scripted GUIs, and maps with coding agents.",
-  "version": "1.1.0",
+  "description": "Analyze HOI4 event chains; create and clean focus trees, scripted GUIs, and maps with coding agents.",
+  "version": "1.2.0",
   "repository": {
     "url": "https://github.com/klimPaskov/hoi4-agent-tools",
     "source": "github"
@@ -13,7 +13,7 @@
     {
       "registryType": "npm",
       "identifier": "hoi4-agent-tools",
-      "version": "1.1.0",
+      "version": "1.2.0",
       "transport": {
         "type": "stdio"
       }