hoi4-agent-tools 3.8.1 → 3.9.0

package/docs/reference.md

@@ -21,6 +21,7 @@ Markdown headings and recognizable standalone names in generated `.log` files fo
 - When `hoi4.source_lookup` finds no definition, `suggestions` lists up to five indexed identifiers within three edits of the requested symbol, nearest first, which catches typos and near-miss names.
 - `hoi4.source_lookup` with `path` and `line` instead of `symbol` locates a source position, such as a diagnostic or a changed line in a diff. `path` may be a result path such as `mod:events/example.txt`, a path relative to a source root, or an absolute path inside one. The result names the file's layer and whether a later layer shadows it, the indexed definitions that contain the line, innermost first, and the chain of enclosing assignments with zero-based occurrences for repeated keys. Its `keyPath` starts inside the innermost definition: pass that definition's `id` as `symbol`, its `kind`, and the `keyPath` to read or list that exact block. Without `column`, the first non-blank character of the line is used. A file with parse errors returns its definitions but no structural chain. Only the requested file's folder is scanned, in every layer.
 - `hoi4.script_validate`: check a bounded effect or trigger body against installed native-command documentation. Supply the body in `source`, its `kind`, and its current `scope`. Results cover syntax, command kind, and declared scope, with exact documentation citations. They do not validate command parameters or prove game execution.
+- `hoi4.script_validate` with `path` instead of `source` checks a whole mod file: every effect and trigger body of an event, decision, national focus, scripted effect, scripted trigger, or on-action file, with the scope the file's structure fixes. It is meant to catch the game's own load errors before launch.
 
 ## Navigate a definition
 
@@ -58,6 +59,43 @@ It reads supported scopes from `effects_documentation.md`, `triggers_documentati
 `valid: true` applies only to `checksPerformed`; `parametersChecked` remains false.
 Inspect the cited parameter syntax and use the relevant domain tools for broader validation.
 Replies prioritize problems, bound `findings`, and report `omittedFindings`; execution is bounded to 256 visited entries and 64,000 UTF-8 source bytes.
+
+### Check a whole file
+
+Pass `path` (a result path, a path relative to a source root, or an absolute path inside one) without `source`, `kind`, `scope`, or `bindings`.
+The file's folder decides its family and root scopes: event `trigger`, `immediate`, `after`, and option bodies use the event type's scope; decision and focus triggers and effects use country scope; scripted effects, scripted triggers, on actions, and decision `target_trigger` bodies have no fixed scope, so their command kinds are checked and scope rules are skipped.
+`file` reports the family, the number of checked bodies, and how many had no fixed scope; a body without a fixed scope keeps `valid` at `null`.
+File mode lists only problems: matching commands are counted in `checkedCommands`, and unchecked native argument blocks are counted in `argumentBlocksUnchecked`.
+It is bounded to 50,000 visited entries.
+
+The mod's scripted effects and triggers count as known commands of their kind.
+Building, ideology, and resource names count as the documented generic triggers that take them as keys (`arms_factory > 2`, `communism > 0.4`), from the documentation's supported lists and from the `common/buildings`, `common/ideologies`, and `common/resources` databases of every source layer.
+`FROM`, chained keywords, `event_target:`, `var:`, `mio:`, and `sp:` blocks are checked for command kinds without scope rules.
+
+Two checks predict load errors the game reports:
+
+- `SCRIPT_DYNAMIC_VARIABLE_AS_TRIGGER`: a dynamic variable from `dynamic_variables_documentation.md` compared directly as a trigger, such as `num_owned_states > 1`; compare it with `check_variable` instead.
+- `SCRIPT_SCOPE_LINK_WRONG_SCOPE`: a scope link used outside the scopes the wiki's Scopes page allows, such as `controller` in country scope.
+
+The scope links `owner`, `controller`, `capital_scope`, `overlord`, and `faction_leader` are recognized in any letter case in both modes.
+
+### Player-facing text
+
+For event, decision, and national focus files, file mode also checks English text as the game resolves it, from the last loaded definition of each key, and adds `player_text` to `checksPerformed`.
+These findings have `status: "warning"` and never change `valid`:
+
+- `SCRIPT_NEWS_TEXT_COLOUR_CODE`: a news event, or an event with a `GFX_report_event` picture, whose title, description, or option text contains a `§` or `£` code, directly or through a `defined_text` branch it shows.
+- `SCRIPT_TEXT_IMPLEMENTATION_WORDING`: event text, or a decision's or focus's name or description, containing development wording such as TODO, placeholder, hardcoded, newly added, or reworked.
+- `SCRIPT_FLAG_TOOLTIP_UNLOCALISED`: a `has_country_flag`, `has_global_flag`, or `has_state_flag` check in a decision's `available` block or a focus's `available` or `bypass` block whose flag has no localisation key, so the requirement tooltip prints the raw flag name. Checks inside `hidden_trigger` and `custom_trigger_tooltip` are skipped, and scripted triggers called from those blocks are not expanded.
+
+Each message names the localisation file and line that carries the text.
+
+### Repeated event windows
+
+File mode reports `SCRIPT_EVENT_POPUP_REPEATED` warnings for any family and adds `event_popups` to `checksPerformed`.
+A visible event fired inside an `every_*` loop reaches one player once per loop member when it is sent to a fixed recipient (`ROOT`, `FROM`, `PREV`, `global`, a tag, an `event_target:` or a `var:` scope), or when it is `major = yes` without `fire_only_once`, because a major event is shown to every country.
+An event sent to each loop member in turn, a hidden event, and an event the scanned sources do not define are not reported.
+Scripted effects called inside a loop are checked in their own file, not followed from the caller.
 Search and context replies also report `limitedByBytes` when metadata exceeds their reply budget.
 Read omitted required sources with targeted calls rather than repeatedly requesting the same oversized bundle.
 Reference text supports UTF-8, Windows-1252, and explicitly BOM-marked UTF-16; native engine source encoding rules remain separate.

package/docs/setup.md

@@ -84,6 +84,16 @@ See [Local references](reference.md) for source selection and missing-source rep
 | A render lacks icons or fonts       | Confirm `--game-root` and the mod's asset paths. Read the missing-file findings.                                            |
 | A control's state is unresolved     | Supply the scenario's required country, state, controller or variable inputs; do not assume a visible control is available. |
 | A large query takes several minutes | Start with the specific tree, window or source area you need. Use [background jobs](jobs.md) when supported by your client. |
+| Idle server processes accumulate    | Set an idle limit as described in [Server lifetime](#server-lifetime).                                                      |
 
 The supplied Codex registration allows 120 seconds for startup and 600 seconds per tool call.
+
 For remote or shared deployments, use the [HTTP guide](http.md).
+
+### Server lifetime
+
+A stdio server exits when its client closes stdin, and when the process that launched it, such as a `cmd.exe` shim, has exited.
+Some clients start a server for every subagent and keep each connection open after the subagent finishes, so idle servers accumulate and each holds its own index in memory.
+A server with no client traffic and no open request for `stdioIdleExitMinutes` minutes exits.
+That setting applies to every client sharing the server configuration, so prefer the `HOI4_AGENT_STDIO_IDLE_EXIT_MINUTES` environment variable in the affected client's registration; the Codex registrations printed by `hoi4-agent-tools-setup --print-client-config` set it to 30.
+A client that later calls an exited server reports it as disconnected, so leave the limit at `0` (never) for a single long-lived session.

package/docs/tools.md

@@ -20,7 +20,7 @@ Use the connected server's live schema for the fields accepted by each call.
 | `hoi4.reference_search`     | Search local documentation in plain words or script names; each result names its answering line.                 |
 | `hoi4.reference_read`       | Read one revision-bound section, with line continuation.                                                         |
 | `hoi4.source_lookup`        | Find exact definitions, overrides and usages across game, DLC and mod, or the definition containing a file line. |
-| `hoi4.script_validate`      | Check snippet syntax, native command kinds, and declared scopes against local documentation.                     |
+| `hoi4.script_validate`      | Check a snippet or a whole mod file for syntax, command kinds, and scopes against local documentation.           |
 | `hoi4.event_inspect`        | Scan, trace, explain, lint, or assess event chains and their state flow.                                         |
 | `hoi4.event_render`         | Render source-linked event routes, options, timing, state, scope, and unresolved edges.                          |
 | `hoi4.event_compare`        | Compare event-chain topology and diagnostics between revisions.                                                  |

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "hoi4-agent-tools",
-  "version": "3.8.1",
+  "version": "3.9.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "hoi4-agent-tools",
-      "version": "3.8.1",
+      "version": "3.9.0",
       "license": "Apache-2.0",
       "dependencies": {
         "@fontsource-variable/roboto": "5.3.0",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "hoi4-agent-tools",
   "mcpName": "io.github.klimPaskov/hoi4-agent-tools",
-  "version": "3.8.1",
+  "version": "3.9.0",
   "description": "HOI4 modding tools for agents: local references, visual previews, focus trees, interfaces and maps.",
   "type": "module",
   "license": "Apache-2.0",