s2cfgtojson 7.0.16 → 7.0.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "s2cfgtojson",
-  "version": "7.0.16",
+  "version": "7.0.18",
   "description": "Converts Stalker 2 Cfg file into POJOs",
   "keywords": [
     "stalker",
@@ -50,7 +50,8 @@
   },
   "files": [
     "dist",
-    "readme.md"
+    "readme.md",
+    "skills/public"
   ],
   "scripts": {
     "build": "node ./scripts/build.mjs",

package/readme.md

@@ -58,6 +58,28 @@ console.log(parsed.TriggeredCooldowns);
 
 ---
 
+## Quest Node Planner Skill
+
+This package includes a **Quest Node Planner** skill for AI-assisted quest authoring. It turns plain-language quest descriptions into complete S.T.A.L.K.E.R. 2 quest content packages — quest node graphs, dialog chains, journal entries, markers, rewards, and all supporting structs.
+
+Describe a quest in plain language and the planner will:
+
+1. Resolve real content IDs from your local `GameLite` data (NPCs, items, dialogs, journals, markers)
+2. Determine every struct the quest needs (nodes, dialog, journal, globals, rewards, generators)
+3. Produce a structured plan with concrete SIDs, a node graph, edges, placement guidance, and validation risks
+
+Example prompt:
+
+> Plan a fetch quest where Barkeep in the Skadovsk asks the player to retrieve a unique PDA from a bandit camp, with a money reward on turn-in and an option to decline.
+
+### Key design principles
+
+- All new structs must patch an **existing base cfg file** — the game won't read arbitrary new files.
+- The skill prefers **reusing existing content** (items, markers, generators) over creating new prototypes.
+- If something can't be resolved from local data, the skill asks you instead of guessing.
+
+---
+
 ## Development
 
 ### Tests

package/skills/public/quest-node-planner/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: quest-node-planner
+description: "Plan and author complete S.T.A.L.K.E.R. 2 quest content packages from human quest descriptions using the quest prototype docs and local GameLite data in this repository. Use when Codex needs to convert plain-language quest intent into all required structs: quest nodes, dialog chains and topics, journal entries, markers, globals, reward generators, stash or item generators, quest prototypes, supporting references, and new items or supporting data when existing content does not cover the need."
+---
+
+# Quest Node Planner
+
+Turn human quest intent into a complete quest content package grounded in this repo's quest documentation and local `GameLite` content. Produce whatever structs are required for the quest to exist coherently, not just the quest graph.
+
+## Workflow
+
+1. Read the user's quest intent and restate it as:
+   - trigger
+   - progression steps
+   - success/fail outcomes
+   - actors, items, locations, or interactables
+   - persistence or repeatability needs
+2. Resolve real content IDs before planning whenever the workspace contains game data:
+   - NPC or object placeholders from `GameLite/GameData/SpawnActorPrototypes/**`
+   - object or actor prototype SIDs from `GameLite/GameData/ObjPrototypes/**`
+   - item SIDs from `GameLite/GameData/ItemPrototypes/**` or other concrete prototype sources
+   - dialog chain or infotopic IDs from `GameLite/GameData/DialogPrototypes/**`
+   - journal quest or stage IDs from `GameLite/GameData/JournalQuestPrototypes/**`
+   - existing globals, guideway flags, or precondition names from local quest, dialog, world, and support data
+   - region, marker, or hub guidance data from `GameLite/GameData/MarkerPrototypes.cfg`, `FastTravelLocationPrototypes.cfg`, and related world data
+   - if the user gives a display name but no exact internal SID, search for the exact internal ID before treating it as an assumption
+3. Determine the full struct surface the quest needs:
+   - quest node graph
+   - accept entry
+   - reminder or in-progress entry
+   - turn-in entry
+   - cancel or decline entry when the quest should support backing out
+   - journal quest and stage definitions
+   - globals or other state carriers
+   - markers, search areas, or region guidance
+   - reward generators, item generators, stash generators, or direct items
+   - any supporting quest prototype, actor reference, or item prototype that must exist for the design to work
+4. Reuse existing structs where they fit. Create new structs only when the existing content does not cover the need cleanly.
+   - Even when a struct is new, place it into a patch for an existing cfg file in the correct family. Do not plan brand-new standalone cfg files that the game will not read.
+   - In implementation mode, resolve the exact existing base cfg filename for each struct family being patched.
+5. If core inputs are still missing after local lookup, make the smallest safe assumptions and label them clearly.
+   - For quest-objective stashes or reward stashes, do a brief local lookup first.
+   - If a suitable stash cannot be found quickly, ask the user whether to reuse a known stash, point to a specific stash, or author a new stash-related struct.
+   - If implementation guidance is requested and the exact base cfg filename for a required patch cannot be found quickly, ask the user instead of guessing.
+6. Read only the references needed for the task:
+   - Start with `references/workflow.md`.
+   - Read `references/patterns.md` when the quest has branching, synchronization, journals, dialog, or reusable subgraphs.
+   - Read `references/node-selection.md` when node choice is the hard part.
+   - Read `references/constraints.md` when wiring, GUIDs, or evidence strength matters.
+   - Read `references/examples.md` when the quest needs a concrete template from local content.
+   - Read `references/poi-and-rewards.md` when the quest needs regional guidance, marker logic, or composed rewards.
+   - Read `references/mod-workflow.md` and `references/patch-layout.md` when the user wants actual mod placement guidance.
+   - Read `references/environment-prompts.md` when environment-specific paths or target mod location are unknown.
+7. Build the package in this order:
+   - IDs and reusable existing content
+   - journal and state model
+   - dialog surface
+   - quest node graph
+   - navigation and marker layer
+   - rewards and supporting generators
+   - any missing supporting structs
+   - explicit termination and cleanup
+8. Prefer structures that are easy to patch or extend later:
+   - use `Technical` as glue
+   - use exact launcher targeting
+   - keep helper subgraphs explicit
+   - prefer additive structure over giant rewrites
+
+## Output Contract
+
+Always return these sections:
+
+- `Intent summary`: one short paragraph
+- `Resolved IDs`: concrete SIDs, GUIDs, dialog chains, journal identifiers, markers, or generator references found locally
+- `Assumptions`: only unresolved or inferred details after local lookup
+- `Required structs`: every struct family the quest needs, split into reuse vs new authoring
+- `Dialog surface`: accept / reminder / turn-in / cancel entries and whether they reuse existing dialog or need new entries
+- `POI guidance`: region, hub, marker, search point, or location references if navigation matters
+- `Recommended graph`: short narrative of flow
+- `Nodes`: a table with `SID`, `NodeType`, purpose, key fields, and notable pins
+- `Supporting structs`: journal quests, markers, globals, reward generators, item generators, stash generators, items, or other supporting content
+- `Placement guidance`: where each new or patched struct family should live in the mod layout, including the exact existing base cfg file being patched whenever implementation guidance is in scope
+- `Edges`: upstream `SID` plus output `Name` for each launcher binding
+- `State and references`: globals, journal state, signals, bridges, GUID placeholders
+- `Validation risks`: anything that remains inference or needs live verification
+
+If the user asks for variants, provide a primary plan first, then 1-2 alternatives with the tradeoff.
+
+## Constraints
+
+- Stay within real game content systems. Do not invent non-schema systems.
+- Treat the repo docs as the authority for node names and field shapes.
+- Separate `Schema-confirmed`, observed practice, and inference when confidence matters.
+- Do not imply exact runtime semantics unless the docs support them.
+- Distinguish user-facing names from internal SIDs. Do not present a display name as if it were already the engine-facing item or actor ID.
+- Distinguish player GUID usage from NPC or object placeholders.
+- Treat quest-facing dialog as part of the quest design, not as optional flavor text.
+- When the quest requires new conversation content, plan both the quest node hooks and the dialog chain/topic skeleton.
+- When extending an existing NPC, prefer placing new dialog chains and dialog structs next to that NPC's existing dialog file family.
+- For NPC giver interactions, prefer dialog-triggered state changes: expose the dialog with `SetDialog`, then drive accept, turn-in, cancel, or defer outcomes from `LastPhraseSID` outputs or dialog-linked events.
+- Do not default to quest-state nodes auto-firing giver conversations. Reserve forced or auto-started dialog for explicit comment, radio, cutscene, or user-requested cases.
+- Treat journal, marker, reward, and generator structs as part of the quest package, not as optional extras.
+- Create new item or support prototypes only when existing items, markers, generators, or world references are insufficient.
+- When the user wants implementation guidance, explain the expected mod folder structure and patch file family placement.
+- The game will not read arbitrary brand-new cfg files. Every new or changed struct must be emitted into a patch derived from an existing base cfg file in the correct family.
+- In implementation mode, the exact existing base cfg filename is mandatory for each patched struct family.
+- Do not invent a specific quest stash or reward stash if local lookup does not surface one quickly; ask the user instead.
+- If a quest grants a stash as a reward, do not plan it as pre-lootable world content with the final reward already inside; use `SetItemGenerator` in the quest completion flow to populate or unlock the stash reward at completion time.
+- When a node has named outputs, bind the exact output `Name`.
+- When a simple gate is enough, prefer `Condition`; when explicit `True` / `False` routing is needed, prefer `If`.
+
+## Default Planning Heuristics
+
+- For automatic startup, begin with `Technical { LaunchOnQuestStart = true }` unless an event root is clearly better.
+- For reactive quests, prefer `event -> If/Condition -> actions`.
+- For multi-outcome flow, prefer nodes with named outputs such as `If`, `SetDialog`, `Random`, or `Container`.
+- For waiting or joins, prefer `BridgeEvent`, bridge conditions, node-state conditions, or signals instead of brittle linear chaining.
+- For staged progression, use journal state or globals rather than hidden incidental ordering.
+- For compatibility-minded plans, isolate risky behavior in helper subgraphs entered by one explicit edge or signal.
+- For fetch quests, usually separate three states: quest offered/accepted, objective item acquired, and turn-in resolution.
+- When the user implies abandon or backing out, include an explicit cancel or decline path rather than assuming only success/failure.
+- For NPC-given quests, plan the dialog entry points first, then connect them to quest-state nodes.
+- Use `SetDialog`, `OnDialogStartEvent`, and `OnInfotopicFinishEvent` when dialog is the natural trigger or branch surface.
+- For accept, turn-in, and cancel flows, prefer player-initiated conversation that changes quest state after the relevant dialog phrase finishes, rather than quest state launching the conversation itself.
+- For existing NPCs, prefer extending their established dialog chain family instead of inventing a disconnected dialog namespace.
+- For local regions and hubs, prefer concrete region, hub, or search-area data over vague place text.
+- For rewards, choose the gameplay fantasy explicitly: direct item grant, inventory package, or stash reveal.
+- For rewards in this repo, treat money reward generators as first-class authored content, not as an afterthought.
+- For stash rewards, prefer `SetItemGenerator`-driven completion gating so the player cannot loot the final reward before finishing the quest.
+- Default to reusing existing items, markers, reward generators, and location structures before inventing new prototypes.
+- If the quest cannot work without a missing struct, call it out and specify the minimal new struct needed.
+- If implementation paths are unknown, ask the user for the GameLite source path, implementation repo path, and target mod folder rather than guessing.
+
+## Response Style
+
+- Use concrete SIDs that are readable and consistent, such as `<QuestSID>_Start`, `<QuestSID>_CheckHasItem`, or `<QuestSID>_Reward`.
+- Keep node lists concise. Include only fields needed to communicate the design.
+- When dialog must be created, include a short dialog chain/topic outline with entry purpose, final phrase, and branch result, not full prose unless the user asks for writing.
+- When support structs must be created, group them by file family such as journal, markers, rewards, generators, or items.
+- When implementation placement matters, group the answer by `GameData` family and target mod path.
+- When naming placements, identify the existing base cfg file being patched, not just the folder family.
+- If the exact base cfg file is unknown, say so and ask instead of inventing one.
+- If the user wants a `readme.md`, keep it short and make sure it describes the quest flow, main stages, and reward/cancel outcomes.
+- End by naming the smallest next implementation step, such as cfg authoring, patch insertion, or GUID resolution.

package/skills/public/quest-node-planner/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Quest Node Planner"
+  short_description: "Plan S.T.A.L.K.E.R. 2 quest-node graphs"
+  default_prompt: "Use $quest-node-planner to turn a human quest concept into a quest-node-only graph plan."

package/skills/public/quest-node-planner/references/constraints.md

@@ -0,0 +1,54 @@
+# Constraints
+
+Read this file when precision matters.
+
+## Source of Truth
+
+- Treat this repo's quest documentation as the authority for node names and field shapes.
+- Treat statements labeled as inference as design guidance, not proof of exact engine behavior.
+
+## Launchers
+
+- `Launchers` encode inbound edges.
+- A launcher connection identifies an upstream `SID` and an output `Name`.
+- Empty `Name` usually means ordinary pass-through.
+- `True` and `False` matter for `If`.
+- Custom names matter for nodes such as `Random`, `SetDialog`, `Container`, and other named-output nodes.
+
+## Conditions
+
+- `Condition` and `If` both use `Conditions`.
+- Use `Condition` when the graph only needs to pass or stop.
+- Use `If` when the graph needs explicit branch outputs.
+
+## GUIDs and Targets
+
+Common target fields include:
+
+- `TargetQuestGuid`
+- `TargetCharacter`
+- `TargetNPC`
+- `InteractableQuestGuid`
+- `TriggerQuestGuid`
+- `SignalSenderGuid`
+- `SignalReceiverGuid`
+
+Observed convention:
+
+- `AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA` refers to the player
+
+Do not assume target fields are interchangeable even when they point at the same logical actor.
+
+## Evidence Rules For IDs
+
+- Prefer concrete IDs found in local `GameLite` files over guessed placeholders.
+- If an actor is found through spawn data, report both the `SpawnedPrototypeSID` and the `PlaceholderActorGuid` when relevant.
+- If a display name cannot be matched to an internal item SID, keep the plan generic and call out the unresolved mapping.
+
+## Practical Guardrails
+
+- Prefer exact launcher targeting.
+- Prefer helper `Technical` nodes over rewriting large chains.
+- Keep helper subgraphs explicit and clearly named.
+- Prefer additive patching patterns over destructive rewrites.
+- Prefer stateful joins through globals, journal state, signals, or bridges over brittle linear chaining.

package/skills/public/quest-node-planner/references/environment-prompts.md

@@ -0,0 +1,27 @@
+# Environment Prompts
+
+Read this file when the skill is moving from design to implementation guidance.
+
+## Ask The User When Unknown
+
+Ask for these values if they are needed and cannot be inferred safely:
+
+- implementation repo path
+- GameLite source folder path
+- target mod folder or mod name
+- whether the quest should be a new mod or part of an existing mod
+- whether the user wants design-only output or implementation-ready placement guidance
+
+## Do Not Ask By Default
+
+Do not stop to ask for:
+
+- exact coordinates when broad area guidance is acceptable
+- exact reward values when placeholders are acceptable
+- exact dialog prose when the user only needs structure
+
+Instead:
+
+- use broad region or marker-radius guidance
+- propose placeholder reward values
+- provide dialog chain and phrase skeletons

package/skills/public/quest-node-planner/references/examples.md

@@ -0,0 +1,61 @@
+# Examples
+
+Read this file when the user wants a plan that should follow an existing local quest pattern.
+
+## SQ86: Full Fetch Quest With Dialog State
+
+Primary files:
+
+- `GameLite/GameData/QuestNodePrototypes/SQ86.cfg`
+- `GameLite/GameData/DialogPrototypes/SQ86_Dialog_Genij_FirstMeet.cfg`
+- `GameLite/GameData/DialogPrototypes/SQ86_Comment_Genij_AfterSecondDialog.cfg`
+
+What to reuse:
+
+- `SetDialog` with explicit `OutputPinNames`
+- `LastPhrases` mapped to named outputs
+- multiple dialog phases represented by different chains or comments
+- dialog-side conditional routing using `Bridge` conditions and `LinkedNodePrototypeSID`
+- quest state exposed through dialog availability instead of auto-fired giver conversations
+
+Use this as the main template for:
+
+- a full fetch quest
+- in-progress recontact
+- state-dependent reminder or alternate lines
+- dialog branches that need to trigger or reflect quest progress
+
+## RSQ06: Sidorovich Turn-In And Cancel Confirmation
+
+Primary files:
+
+- `GameLite/GameData/QuestNodePrototypes/RSQ06_C05___B_B.cfg`
+- `GameLite/GameData/DialogPrototypes/RSQ06_Dialog_Sidorovich_C10_Finish.cfg`
+
+What to reuse:
+
+- finish dialog presented via `SetDialog`
+- `LastPhraseSID` mapped back into quest-node outputs
+- multi-step cancel confirmation inside the dialog chain
+- quest completion triggered from the finish phrase
+- turn-in state changes happening after the player-selected finish line, not by auto-launching a giver conversation
+
+Use this as the main template for:
+
+- turn-in conversations
+- "not yet" fallback responses
+- cancel confirmation branches
+- Sidorovich-style giver interactions
+
+Placement rule:
+
+- when extending an existing quest giver, place the new `DialogChainPrototypeSID` and dialog structs alongside that NPC's existing dialog file family
+- do not default to a separate quest-only dialog namespace unless there is a concrete reason
+
+## Example Reading Rule
+
+When the user asks for:
+
+- a complete fetch quest: start with `SQ86`
+- a turn-in with cancellation or confirmation: start with `RSQ06`
+- both: use `SQ86` for the broader flow and `RSQ06` for the turn-in/cancel surface

package/skills/public/quest-node-planner/references/mod-workflow.md

@@ -0,0 +1,51 @@
+# Mod Workflow
+
+Read this file when the user wants guidance for turning a quest package into an actual mod layout.
+
+## Scope
+
+This skill teaches the authoring model used in the local mod repo. It does not assume packaging, SDK cooking, or publishing should happen in this repo.
+
+## Expected Mod Layout
+
+The implementation repo uses a per-mod folder under:
+
+- `Mods/<ModName>/`
+
+In the local implementation repo, generated content is typically stored under:
+
+- `Mods/<ModName>/raw/Stalker2/Content/GameLite/...`
+
+The important game-facing content tree inside that layout is:
+
+- `Stalker2/Content/GameLite/...`
+
+Other files such as metadata, package manifests, readmes, images, or publishing files are repo-specific and optional for mod creation guidance in this skill.
+
+If the user does want a `readme.md`, treat it as lightweight supporting documentation. It should summarize:
+
+- the quest premise
+- the main quest stages or flow
+- the success, failure, or cancel outcomes
+- notable rewards or side effects
+
+Generated cfg patches live under:
+
+- `Mods/<ModName>/raw/Stalker2/Content/GameLite/...`
+
+Example:
+
+- quest node patches end up under `Stalker2/Content/GameLite/GameData/QuestNodePrototypes/...`
+- dialog patches end up under `Stalker2/Content/GameLite/GameData/DialogPrototypes/...`
+
+## Source GameLite Path
+
+The implementation repo reads base cfg files from the SDK GameLite tree:
+
+- `SDK_PATH/Stalker2/Content/GameLite`
+
+If the user asks for implementation guidance and the actual path is not known, ask for:
+
+- the implementation repo path
+- the GameLite source path
+- the target mod folder or mod name

package/skills/public/quest-node-planner/references/node-selection.md

@@ -0,0 +1,87 @@
+# Node Selection
+
+Read this file when choosing concrete node families.
+
+## Control
+
+- `Technical`: safest glue node for bootstrap, delay, pass-through, and replacement logic
+- `Condition`: simple gate
+- `If`: explicit branching with `True` / `False`
+- `Random`: weighted or named branching
+- `BridgeEvent`: synchronization
+- `Container` / `ScheduledContainer`: multi-output or grouped flow where container semantics fit
+
+## Events
+
+Reach for an event node when the quest should react to something instead of auto-starting. Particularly useful families include:
+
+- item events
+- trigger or overlap events
+- dialog-related events
+- journal-related events
+- signal receive nodes
+
+## State / Progression
+
+- `SetGlobalVariable`: phase or flag changes
+- `SetJournal`: objective and quest-stage updates
+- `TrackJournal`: tracked objective changes
+- `SendSignal` / `OnSignalReceived`: cross-fragment control
+- journal quest prototype structs
+- global variable definitions or reused variable namespaces
+
+## Inventory / Reward
+
+- `ItemAdd`
+- `ItemRemove`
+- `SetItemGenerator`
+- `GiveCache`
+- money-related conditions or events when affordability or payment gating matters
+- reward generator structs
+- stash and item-generator structs
+- item prototypes when a genuinely new item must exist
+
+## World / Interaction
+
+- spawn-family nodes
+- `Despawn`
+- `ActivateInteractableObject`
+- `ForceInteract`
+- trigger-related nodes
+
+## Character / AI
+
+- `SetCharacterParam`
+- `SetCharacterEffect`
+- `SetAIBehavior`
+- `ChangeRelationships`
+- `ChangeFaction`
+
+## Dialog / Narrative
+
+- `SetDialog`
+- dialog-start or infotopic-finish events
+- `SetJournal` for stage reflection after dialog
+- dialog-chain/topic structs when new conversation content must be authored
+
+## Navigation / POI
+
+- `SetJournal` with embedded markers
+- `ShowMarker`
+- `SearchPoint`
+- region or hub data from local world definitions
+- marker prototype structs or reused marker families
+
+## Supporting Content
+
+- quest prototype and container structs when the quest must be registered in a broader quest family
+- NPC prototype or spawn references when the quest depends on a specific giver or target
+- world or support structs only when the quest cannot function by referencing existing data
+
+## Selection Rule
+
+Prefer the smallest node set that communicates the design cleanly. If two approaches work, prefer the one that uses:
+
+- explicit launchers
+- fewer inferred semantics
+- clearer patch points

package/skills/public/quest-node-planner/references/patch-layout.md

@@ -0,0 +1,59 @@
+# Patch Layout
+
+Read this file when the user wants to know where new cfg patches and supporting structs should go.
+
+## Core Rule
+
+Patch files are generated per target cfg family and stored under the mod's `raw/` tree, preserving the `GameLite/GameData` folder family.
+
+The game does not read arbitrary new cfg files. New structs still have to be written into a patch whose target is an existing base cfg file from the relevant family.
+
+For implementation guidance, the exact base cfg filename is mandatory. Do not stop at the family name alone.
+
+Base pattern:
+
+- `Mods/<ModName>/raw/Stalker2/Content/GameLite/GameData/...`
+
+Observed processor behavior from `S2Mods/src/get-cfg-file-processor.mts`:
+
+- it starts from a real source cfg file path
+- it preserves that file's family and base name
+- it writes the patch under a folder derived from the base file name
+- it names the patch from the existing file name, not from the new struct name
+
+## File Family Placement
+
+Place content by family:
+
+- quest nodes: `GameData/QuestNodePrototypes/...`
+- dialog structs: `GameData/DialogPrototypes/...`
+- journal quests: `GameData/JournalQuestPrototypes/...`
+- item and reward generators: `GameData/ItemGeneratorPrototypes/...`
+- markers: `GameData/MarkerPrototypes...` or embedded in journal updates when appropriate
+- item prototypes: `GameData/ItemPrototypes/...`
+- quest prototypes: `GameData/QuestPrototypes/...` if the quest package needs registration there
+
+## Patch Naming
+
+Observed implementation pattern:
+
+- ordinary cfg family: `<BaseName>_patch_<ModName>.cfg`
+- special case for `CoreVariables.cfg`: `<BaseName>.cfg_patch_<ModName>`
+
+Do not invent a different naming pattern unless the user explicitly wants one.
+
+## New Struct Placement
+
+Placement rules:
+
+- add new dialog chains and dialog structs next to the existing NPC dialog family
+- add new journal quest structs in the journal quest family
+- add new reward generators in the quest reward or item-generator family
+- add new quest nodes in the quest node family
+- add new items only when existing items cannot satisfy the design
+- for every one of the above, choose an existing base cfg file in that family and place the new structs in that file's patch
+- if the exact base cfg file cannot be resolved quickly, ask the user instead of inventing one
+
+## Content Grouping
+
+Keep the guidance grouped by target cfg family. Do not describe the quest as if unrelated edits should be scattered arbitrarily.

package/skills/public/quest-node-planner/references/patterns.md

@@ -0,0 +1,140 @@
+# Patterns
+
+Read this file when the quest is more than a straight line.
+
+## Start-of-Quest Bootstrap
+
+Use:
+
+- `Technical { LaunchOnQuestStart = true, StartDelay = 0 }`
+- downstream actions or helper branches
+
+Use it to initialize globals, stage delayed work, or start a reusable subsystem.
+
+## Event -> Condition -> Action
+
+Use:
+
+- event root
+- `If` or `Condition`
+- one or more actions
+
+This is the default reactive quest pattern.
+
+## Action Fanout
+
+One upstream node can launch several downstream nodes. Use this to split one moment into parallel outcomes such as journal update, reward, marker update, and state change.
+
+## Named-Branch Routing
+
+Use named outputs when different follow-up consequences matter.
+
+High-value branch nodes:
+
+- `If`
+- `Random`
+- `SetDialog`
+- `Container`
+
+## Delay Insertion
+
+Use `Technical { StartDelay = ... }` when two operations should not happen on the same tick.
+
+## Bridge / Synchronization
+
+Use a side branch plus:
+
+- `BridgeEvent`
+- bridge condition
+- node-state condition
+
+Use this when the main branch should continue only after helper work completes.
+
+## Signal Bus
+
+Use:
+
+- `SendSignal`
+- `OnSignalReceived`
+
+Use this to decouple fragments without direct launcher rewiring.
+
+## Stateful Quest Machine
+
+Use:
+
+- event or trigger
+- `If` / `Condition` on a global
+- `SetGlobalVariable`
+
+Use this for phases, repeatable loops, and one-shot guards.
+
+## Journal-Driven Progression
+
+Use:
+
+- `SetJournal`
+- optional `TrackJournal`
+- optional marker updates
+- `If` / `Condition` on `JournalState`
+
+## Dialog to World Consequence
+
+Use:
+
+- `SetDialog` with named outputs
+- branch-specific action nodes
+
+This is the standard player-choice pattern.
+
+## Dialog-Driven Quest Surface
+
+Use:
+
+- existing or new accept entry
+- in-progress reminder entry
+- turn-in entry
+- optional decline or cancel entry
+- `OnInfotopicFinishEvent` or another dialog-linked event for state transitions
+
+Treat these as part of the quest contract. The node graph and the dialog surface should agree on which branch accepts, completes, cancels, or defers the quest.
+
+Implementation guidance:
+
+- use a `SetDialog` node when the quest must expose a dialog state directly
+- map `LastPhraseSID` values to named output pins
+- prefer the NPC conversation itself to be player-initiated; the quest should usually expose dialog availability, not auto-launch the giver's conversation
+- let accept, complete, cancel, and "not yet" outcomes flow from the chosen final phrase or dialog-linked event into quest-state changes
+- use separate chains or comments for major state transitions when needed
+- use dialog-side `If` nodes or bridge conditions when the dialog itself should react to quest state
+- when the quest giver already has dialog content, add new chains and dialog structs alongside that existing dialog family
+- reserve forced dialog, comments, or radio-style conversation for cases where vanilla also treats the line as an unsolicited event rather than a normal NPC interaction
+
+## Fetch And Return
+
+Use:
+
+- accept or start event
+- `SetJournal` for the first objective
+- `SetGlobalVariable` or journal-state gate for quest phase
+- `OnPlayerGetItemEvent` for objective acquisition
+- second `SetJournal` for return-to-giver progression
+- `SetDialog` to expose the giver's quest conversation
+- final phrase output or dialog-linked event on the quest giver
+- `If` checking both quest phase and item possession
+- `ItemRemove` for turn-in
+- reward and completion nodes
+
+Optional branches:
+
+- reminder branch when the player talks to the giver too early
+- decline branch before acceptance
+- cancel branch if the player should be allowed to back out after acceptance
+
+Use this pattern when the quest should not spawn the item itself and only needs to track acquisition and delivery.
+
+Reward add-ons:
+
+- `ItemAdd` for direct money-like or item-like payout if locally appropriate
+- `SetItemGenerator` for a packaged reward
+- `GiveCache` when the reward should arrive as a stash reveal

package/skills/public/quest-node-planner/references/poi-and-rewards.md

@@ -0,0 +1,75 @@
+# POI And Rewards
+
+Read this file when the quest needs navigation guidance or explicit reward composition.
+
+## Regions, Hubs, And Places
+
+Common place names can map to different kinds of data:
+
+- region enum
+- hub or fast-travel location
+- marker prototype
+- world stash or search-point location
+
+Do not assume these are interchangeable.
+
+## Resolving Places
+
+Useful local sources:
+
+- `GameLite/GameData/JournalQuestPrototypes/*.cfg` for quest region usage
+- `GameLite/GameData/MarkerPrototypes.cfg` for marker and region marker definitions
+- `GameLite/GameData/FastTravelLocationPrototypes.cfg` for hub locations and player coordinates
+- `GameLite/GameData/SpawnActorPrototypes/WorldMap_WP/**` for concrete world placements and stash generators
+- `GameLite/GameData/CorpseClueStashPrototypes.cfg` for region-linked stash categories
+
+Use these rules:
+
+- if the player only needs broad regional guidance, use journal region and marker guidance
+- if the player needs a base or hub destination, use the fast-travel or hub location data
+- if the player needs a specific stash or search area, prefer a concrete stash generator, marker target, or search point
+- if the user names a place that could mean several things, resolve whether they mean a region, hub, marker, or specific world location before planning
+- if exact coordinates are unnecessary, prefer a broad area target with a radius over inventing a precise point
+- if the quest depends on a specific stash and local lookup does not reveal a clear candidate quickly, stop and ask the user which stash or stash family to use
+
+## Reward Composition
+
+High-value reward patterns:
+
+- direct deterministic item: `ItemAdd`
+- inventory package or loadout: `SetItemGenerator`
+- stash reveal or cache fantasy: `GiveCache`
+- money payout authored through a quest reward generator with `MoneyGenerator`, then delivered via `SetItemGenerator`
+
+Practical reward planning:
+
+- for money-only rewards, prefer an authored reward generator using `MoneyGenerator`
+- for "money plus stash" rewards, split the reward into two explicit actions
+- for armor rewards such as a plain exoskeleton, prefer an item generator or stash reveal over inventing ad hoc delivery logic
+- if the reward fantasy depends on a stash reveal but no suitable stash can be identified quickly, ask the user before inventing one
+- if the reward is a stash, do not leave the final reward items sitting in a lootable stash from the beginning of the quest
+- prefer `SetItemGenerator` in the quest completion branch to populate or unlock the stash reward so it only becomes available after quest completion
+
+Observed local pattern:
+
+- `EQ50` delivers alternate money rewards through `SetItemGenerator` nodes targeting reward generators such as `EQ50_reward_var2_MoreMoney`
+- quest reward generator files under `GameLite/GameData/ItemGeneratorPrototypes/QuestRewardsPrototypes/**` commonly use `MoneyGenerator`
+- money card item SIDs exist in `GameLite/GameData/ItemPrototypes/MoneyPrototypes.cfg`
+
+## Recommendation For This Repo
+
+When the user wants a combined reward:
+
+1. look for an existing quest reward generator pattern
+2. model the money portion as its own reward generator
+3. if a stash is part of the fantasy, use `SetItemGenerator` in the completion flow with the dedicated stash or reward generator that makes the stash reward available
+4. if the reward should go straight to the player, use `SetItemGenerator` or `ItemAdd`
+
+## Missing Struct Rule
+
+If the quest needs a reward, marker, journal entry, variable, or item that does not already exist:
+
+1. reuse the closest existing local pattern
+2. define the minimal new struct family needed
+3. keep names scoped to the quest SID
+4. avoid creating unrelated support content

package/skills/public/quest-node-planner/references/workflow.md

@@ -0,0 +1,80 @@
+# Workflow
+
+Use this file first for most requests.
+
+## Input Checklist
+
+Extract or infer:
+
+- quest goal
+- start condition
+- exact internal SIDs or GUIDs for actors, items, and key interactables
+- required dialog surface for accept, in-progress, turn-in, decline, or cancel behavior
+- required dialog chains, topics, or final phrase hooks if new dialog must be created
+- progression stages
+- branch conditions
+- rewards or penalties
+- fail or reset behavior
+- point-of-interest or navigation requirements
+- actors, items, triggers, dialog, or world objects
+- whether the quest is one-shot, repeatable, or stateful
+- every supporting struct family the quest will require
+- whether the user needs design-only output or actual mod placement guidance
+
+## Minimal Mental Model
+
+Default flow:
+
+1. Event or `Technical` starts a branch.
+2. `If` or `Condition` decides whether the branch continues.
+3. Action nodes change journal, inventory, AI, world state, or globals.
+4. Named-output nodes create branching.
+5. Bridges, node-state checks, or signals synchronize branches.
+6. `End` closes the fragment.
+
+## Quick Routing
+
+If the user wants:
+
+- automatic startup: `Technical` with `LaunchOnQuestStart = true`
+- yes/no branch: `If`, or `Condition` when a simple gate is enough
+- more than two outcomes: `Random`, `SetDialog`, `Container`, `ScheduledContainer`, or another node with `OutputPinNames`
+- NPC conversation states: `SetDialog`, `OnDialogStartEvent`, or `OnInfotopicFinishEvent`
+- wait-for-completion behavior: `BridgeEvent`, bridge conditions, or node-state checks
+- quest updates and map guidance: `SetJournal`, `TrackJournal`, `ShowMarker`, `SearchPoint`, `AddNote`
+- cross-fragment communication: `SendSignal`, `OnSignalReceived`, globals, or `BridgeEvent`
+- location or hub guidance: journal `Region`, `Markers`, marker prototypes, and fast-travel location data
+- complete quest package authoring: journal quests, globals, reward generators, item generators, stash generators, and support prototypes
+- mod placement guidance: target mod folder, `raw/` tree layout, and patch family placement
+
+## ID Resolution
+
+Before treating names as assumptions, search local game data for:
+
+- NPC placeholders in `SpawnActorPrototypes`
+- NPC or object prototype SIDs in `ObjPrototypes`
+- item SIDs in `ItemPrototypes` or concrete spawn/prototype data
+- dialog chains and dialog node IDs in `DialogPrototypes`
+- journal quest and stage IDs in `JournalQuestPrototypes`
+- region, marker, hub, and fast-travel data when the user names a place
+- existing reward, stash, and item generator patterns before inventing new ones
+- target mod layout and patch family placement when the user wants implementation guidance
+
+If a requested item name does not appear anywhere in local data, say so explicitly and keep the plan generic until the exact internal SID is known.
+
+## Planning Order
+
+Build plans in this order:
+
+1. Resolve concrete IDs.
+2. Resolve place data if navigation matters.
+3. Identify all required struct families.
+4. If needed, ask the user for implementation repo path, GameLite path, and target mod folder.
+5. Define the journal and state model.
+6. Define the dialog surface.
+7. Choose the entry point.
+8. Choose the first gate or branch.
+9. Choose the action and reward nodes.
+10. Add any helper delays with `Technical`.
+11. Add joins or side-branch synchronization.
+12. Add explicit end nodes where the fragment should stop.