Add numbered architecture knowledge docs for OpenKore LLM KB

openkore_llm_knowledge/knowledge/01_llm_context.md

@@ -0,0 +1,21 @@
+# OpenKore LLM Context
+
+## Objective
+This layer gives an LLM enough structural context to reason about OpenKore runtime behavior, module boundaries, and extension points.
+
+## Runtime model (high level)
+1. `src/functions.pl` boots runtime services, loads config/tables, initializes network mode, and drives the main loop.
+2. Network receive handlers (`src/Network/Receive*.pm`) transform packets into world-state updates.
+3. Actor state (`src/Actor.pm`, `src/ActorList.pm`) becomes the shared world model for decision logic.
+4. AI (`src/AI.pm`, `src/AI/CoreLogic.pm`) evaluates state and schedules actions through tasks.
+5. Task execution (`src/TaskManager.pm`, `src/Task/*.pm`) performs multi-step actions and emits packets through send modules (`src/Network/Send*.pm`).
+6. Plugins (`src/Plugins.pm`, `plugins/*`) and macro layers (`plugins/macro`, `plugins/eventMacro`) inject automation and custom behavior.
+
+## Key architecture anchors
+- **Entry/control loop**: `src/functions.pl`
+- **Global state/config loading**: `src/Globals.pm`, `src/Settings.pm`, `src/FileParsers.pm`, `control/`
+- **AI + behavior**: `src/AI.pm`, `src/AI/CoreLogic.pm`
+- **Actor model**: `src/Actor.pm`, `src/ActorList.pm`, `src/Actor/*`
+- **Task orchestration**: `src/Task.pm`, `src/TaskManager.pm`, `src/Task/*`
+- **Networking and packets**: `src/Network.pm`, `src/Network/*`
+- **Plugin/macro automation**: `src/Plugins.pm`, `plugins/macro/*`, `plugins/eventMacro/*`

openkore_llm_knowledge/knowledge/02_architecture_overview.md

@@ -0,0 +1,23 @@
+# OpenKore Architecture Overview
+
+## Top-level structure
+- `src/`: core runtime modules (AI, actor model, networking, tasks, plugins API, command layer).
+- `control/`: operator configuration and behavior policies (`config.txt`, control lists, route/macro inputs).
+- `tables/`: protocol/game data mappings (packet maps, item/skill/map metadata, server-specific variants).
+- `plugins/`: optional extensions, including macro/eventMacro automation stacks.
+- `fields/`: map field data used by routing/navigation.
+
+## Core runtime layers
+1. **Bootstrap + loop**: `src/functions.pl` and `src/Modules.pm`
+2. **State + config**: `src/Globals.pm`, `src/Settings.pm`, `src/FileParsers.pm`
+3. **Network transport + packet translation**: `src/Network.pm`, `src/Network/{Receive,Send,PacketParser}.pm`
+4. **World model**: `src/Actor.pm`, `src/ActorList.pm`, `src/Field.pm`
+5. **Decision engine**: `src/AI.pm`, `src/AI/CoreLogic.pm`
+6. **Execution engine**: `src/TaskManager.pm`, `src/Task/*.pm`
+7. **Extension surface**: `src/Plugins.pm`, `src/Commands.pm`, `plugins/*`
+
+## Architectural characteristics
+- **Event-driven and loop-based**: runtime state is advanced each tick by receive updates + AI/task progression.
+- **Protocol-adapter design**: packet send/receive classes are split by server type under `src/Network/Receive/*` and `src/Network/Send/*`.
+- **Policy outside code**: behavior is heavily configured via `control/` and `tables/` files.
+- **Extension-first automation**: macro/eventMacro run as plugins and reuse command/hook/task pathways.

openkore_llm_knowledge/knowledge/03_system_architecture_map.md

@@ -0,0 +1,43 @@
+# System Architecture Map (Textual)
+
+## Primary flow
+`functions.pl main loop` -> `Network receive` -> `Actor/Globals update` -> `AI decision` -> `Task execution` -> `Network send`
+
+## Subsystem map
+
+### 1) Networking
+- Connection/mode handling: `src/Network.pm`, `src/Network/DirectConnection.pm`, `src/Network/XKore*.pm`
+- Packet ingestion and dispatch: `src/Network/MessageTokenizer.pm`, `src/Network/PacketParser.pm`, `src/Network/Receive.pm`, `src/Network/Receive/*`
+- Packet construction: `src/Network/Send.pm`, `src/Network/Send/*`
+
+### 2) Actor system
+- Base entity model: `src/Actor.pm`, `src/Actor/*`
+- Actor collections and lookup: `src/ActorList.pm`
+- World/map coupling: `src/Field.pm`, map and position state in globals
+
+### 3) AI subsystem
+- AI stack state and sequencing: `src/AI.pm`
+- Core behavior logic: `src/AI/CoreLogic.pm`
+- Uses actor/world/config state; issues actions via task manager and commands
+
+### 4) Task subsystem
+- Task abstraction: `src/Task.pm`
+- Scheduler and lifecycle: `src/TaskManager.pm`
+- High-impact tasks: `src/Task/Route.pm`, `src/Task/Move.pm`, `src/Task/TalkNPC.pm`, `src/Task/UseSkill.pm`
+
+### 5) Configuration subsystem
+- Config discovery/loading: `src/Settings.pm`, `src/FileParsers.pm`
+- Runtime shared state: `src/Globals.pm`
+- Policy sources: `control/*`, `tables/*`
+
+### 6) Plugin + macro subsystem
+- Hook and plugin lifecycle: `src/Plugins.pm`
+- Command bridge: `src/Commands.pm`
+- Macro engines: `plugins/macro/*`, `plugins/eventMacro/*`
+
+## Key entry points
+- Startup/main loop: `src/functions.pl`
+- Command dispatch: `src/Commands.pm`
+- Hook registration: `src/Plugins.pm`
+- AI tick path: `src/AI.pm` -> `src/AI/CoreLogic.pm`
+- Packet receive path: `src/Network/Receive.pm` + server-specific receivers

openkore_llm_knowledge/knowledge/04_core_subsystems.md

@@ -0,0 +1,49 @@
+# Core Subsystems
+
+## AI
+- Main modules: `src/AI.pm`, `src/AI/CoreLogic.pm`
+- Role: maintain AI queues/state machines, evaluate combat/loot/movement priorities, enqueue tasks.
+- Inputs: actor state, config policies, packet-driven updates.
+- Outputs: task requests, command invocations, action intents.
+
+## Actor system
+- Main modules: `src/Actor.pm`, `src/ActorList.pm`, `src/Actor/*`
+- Role: represent player/NPC/monster/portal entities, with indexed lookup for targeting and proximity logic.
+- Inputs: receive handlers and map updates.
+- Outputs: query surface for AI, tasks, commands, and plugins.
+
+## Networking
+- Main modules: `src/Network.pm`, `src/Network/{Receive,Send,PacketParser,MessageTokenizer}.pm`, `src/Network/XKore*.pm`
+- Role: manage transport mode, parse inbound packets, encode outbound actions, support server-specific packet families.
+- Inputs: socket data + outgoing action intents.
+- Outputs: state mutations via receive handlers and serialized packets to servers/clients.
+
+## Task system
+- Main modules: `src/Task.pm`, `src/TaskManager.pm`, `src/Task/*`
+- Role: run asynchronous multi-step actions (route, move, NPC dialogs, skill/item use).
+- Inputs: AI/command/plugin action requests.
+- Outputs: packet sends, follow-up tasks, completion/failure states consumed by AI.
+
+## Plugin system
+- Main modules: `src/Plugins.pm`, `plugins/*`
+- Role: dynamic extension lifecycle (`register`, hooks, unload), runtime behavior injection.
+- Inputs: startup/load events, packet-related hooks, periodic loop hooks.
+- Outputs: custom commands, state transitions, automation triggers.
+
+## Configuration system
+- Main modules: `src/Settings.pm`, `src/FileParsers.pm`, `control/*`, `tables/*`
+- Role: load policy and data files that parameterize AI, networking, and gameplay handling.
+- Inputs: text configs and table files.
+- Outputs: normalized runtime config/state in globals and subsystem-specific structures.
+
+## Macro system
+- Main modules: `plugins/macro/macro.pl`, `plugins/macro/Macro/*`, `plugins/eventMacro/eventMacro.pl`, `plugins/eventMacro/eventMacro/*`
+- Role: declarative automation over hooks and game events, with conditional triggers and scripted actions.
+- Inputs: macro definitions and live runtime events.
+- Outputs: command execution and indirect task/network activity.
+
+## Routing
+- Main modules: `src/Task/Route.pm`, `src/Task/Move.pm`, `src/Field.pm`, `fields/*`
+- Role: compute and execute navigation paths across map cells/portals.
+- Inputs: destination intents, field data, actor position/state.
+- Outputs: stepwise movement actions and route completion/fallback states.

openkore_llm_knowledge/knowledge/05_module_dependency_map.md

@@ -0,0 +1,29 @@
+# Module Dependency Map
+
+## Dependency chains (high impact)
+1. `src/functions.pl` -> `src/Settings.pm` / `src/FileParsers.pm` / `src/Modules.pm` (bootstrap)
+2. `src/functions.pl` -> `src/Network.pm` + `src/Network/*` (connection and packet loop)
+3. `src/Network/Receive*.pm` -> `src/Globals.pm` + `src/Actor*.pm` (state mutation)
+4. `src/AI.pm` -> `src/AI/CoreLogic.pm` -> `src/TaskManager.pm` + `src/Task/*` (decision to execution)
+5. `src/Task/*` -> `src/Network/Send*.pm` (action serialization)
+6. `src/Plugins.pm` + `plugins/*` -> `src/Commands.pm` / AI / TaskManager (extension control paths)
+
+## Subsystem dependency view
+- **AI depends on**: Actor state, config policies, task scheduler, command surface.
+- **Actor system depends on**: Network receive updates and global runtime registries.
+- **Task system depends on**: AI/commands/plugins for intents; network send + actor/map updates for progression.
+- **Plugin/macro depends on**: hook lifecycle (`src/Plugins.pm`), command execution (`src/Commands.pm`), global state.
+- **Routing depends on**: task framework, field data (`fields/*`), movement packet sends.
+
+## Coupling hotspots
+- `src/Globals.pm`: shared mutable state touched by receive, AI, and plugins.
+- `src/Commands.pm`: cross-cutting control surface used by user input and automation.
+- `src/TaskManager.pm`: convergence point for AI and scripted automation.
+- `src/Network/Receive.pm`: ingress bridge from protocol events to internal state transitions.
+
+## Practical navigation order for analysis
+1. Start at `src/functions.pl`.
+2. Follow receive path (`src/Network/Receive.pm`, subtype receivers).
+3. Inspect AI loop (`src/AI.pm`, `src/AI/CoreLogic.pm`).
+4. Inspect task execution (`src/TaskManager.pm`, route/move/NPC tasks).
+5. Inspect extension points (`src/Plugins.pm`, macro/eventMacro plugins).

openkore_llm_knowledge/knowledge/06_execution_flows.md

@@ -0,0 +1,29 @@
+# Execution Flows
+
+## Runtime execution loop
+OpenKore runs a tick-oriented loop rooted in `src/functions.pl`, where network ingestion, state updates, AI decisions, and task execution are iterated continuously.
+
+Operational sequence:
+1. Main loop tick in `src/functions.pl` advances network, AI, and task phases.
+2. Receive handlers (`src/Network/Receive.pm`, `src/Network/Receive/*`) apply packet-driven state updates.
+3. Shared state (`src/Globals.pm`, `src/ActorList.pm`) becomes input for AI logic.
+4. AI (`src/AI.pm`, `src/AI/CoreLogic.pm`) chooses actions and updates task queues.
+5. Tasks (`src/TaskManager.pm`, `src/Task/*`) execute stepwise and emit outgoing packets through send modules.
+
+## AI execution loop
+
+```mermaid
+flowchart TD
+    A[AI tick\nsrc/AI.pm] --> B[Gather context\nGlobals + ActorList + config]
+    B --> C[Core logic\nsrc/AI/CoreLogic.pm]
+    C --> D{Action required?}
+    D -- No --> E[Idle/monitor state]
+    D -- Yes --> F[Create/adjust tasks\nsrc/TaskManager.pm]
+    F --> G[Run task step\nsrc/Task/*.pm]
+    G --> H[Emit commands/packets\nCommands + Network::Send]
+    H --> I[Wait for receive updates]
+    E --> I
+    I --> A
+```
+
+AI is decision-oriented; tasks hold execution state between ticks while receive handlers provide feedback.

openkore_llm_knowledge/knowledge/07_npc_interaction_flow.md

@@ -0,0 +1,26 @@
+# NPC Interaction Flow
+
+NPC interactions are executed as task-driven conversations, typically using `src/Task/TalkNPC.pm` and packet handlers under `src/Network/Receive/*.pm`.
+
+```mermaid
+sequenceDiagram
+    participant U as AI/Command/Plugin
+    participant TM as TaskManager
+    participant TN as Task::TalkNPC
+    participant NS as Network::Send
+    participant S as Ragnarok Server
+    participant NR as Network::Receive
+    participant G as Globals/Actor state
+
+    U->>TM: enqueue NPC interaction
+    TM->>TN: start dialogue task
+    TN->>NS: send talk/response packet
+    NS->>S: outbound packet
+    S->>NR: NPC response packet
+    NR->>G: update dialogue/state flags
+    NR->>TM: task-relevant updates
+    TM->>TN: advance next dialogue step
+    TN-->>TM: complete/fail
+```
+
+`Task::TalkNPC` keeps dialogue progression explicit, while receive handlers synchronize server-side conversation state back into runtime state.

openkore_llm_knowledge/knowledge/08_routing_and_movement.md

@@ -0,0 +1,20 @@
+# Routing and Movement
+
+Routing converts destination intent into path segments and movement packets using `src/Task/Route.pm`, `src/Task/Move.pm`, `src/Field.pm`, and `fields/*` data.
+
+```mermaid
+flowchart TD
+    A[AI/Command target\nmap + coordinates] --> B[Task::Route init]
+    B --> C[Load field graph\nsrc/Field.pm + fields/*]
+    C --> D[Compute path segments]
+    D --> E[Task::Move executes step]
+    E --> F[Send move packet\nsrc/Network/Send.pm]
+    F --> G[Receive position update\nsrc/Network/Receive.pm]
+    G --> H{Reached waypoint?}
+    H -- No --> E
+    H -- Yes --> I{Reached destination?}
+    I -- No --> D
+    I -- Yes --> J[Route complete]
+```
+
+Routing is iterative and feedback-driven: each movement step is validated by receive updates before continuing.

openkore_llm_knowledge/knowledge/09_networking_packets.md

@@ -0,0 +1,22 @@
+# Networking and Packet Flow
+
+OpenKore packet handling combines framing/tokenization, opcode parsing, and server-type receive/send classes under `src/Network/*`.
+
+## Packet receive flow
+
+```mermaid
+flowchart TD
+    A[Socket bytes\nNetwork mode] --> B[MessageTokenizer\nsrc/Network/MessageTokenizer.pm]
+    B --> C[PacketParser\nsrc/Network/PacketParser.pm]
+    C --> D[Receive dispatcher\nsrc/Network/Receive.pm]
+    D --> E[Server-type handler\nsrc/Network/Receive/*]
+    E --> F[Runtime mutation\nGlobals + Actor + Task signals]
+    F --> G[Hooks/plugins notified\nsrc/Plugins.pm]
+```
+
+Receive processing turns protocol frames into domain-level state transitions used by AI and tasks.
+
+## Packet send path (supporting context)
+- Action request sources: AI, commands, task modules, plugins/macros.
+- Encoding path: `src/Network/Send.pm` -> `src/Network/Send/*` (server-type specific structures).
+- Transport path: active mode (`DirectConnection`, `XKore`, `XKore2`, or `XKoreProxy`) in `src/Network/*.pm`.

openkore_llm_knowledge/knowledge/10_xkore_modes.md

@@ -0,0 +1,20 @@
+# XKore Modes
+
+XKore modes define how OpenKore connects to the game client/server pipeline.
+
+## Core modules
+- `src/Network/XKore.pm`
+- `src/Network/XKore2.pm`
+- `src/Network/XKoreProxy.pm`
+- `src/Network/DirectConnection.pm` (baseline comparison)
+
+## Mode summary
+- **DirectConnection**: bot connects directly to game servers.
+- **XKore**: client-assisted mode using forwarding/bridging logic.
+- **XKore2**: OpenKore hosts local account/char/map proxy endpoints (`src/Network/XKore2/*`) and relays traffic.
+- **XKoreProxy**: proxy-style mediation path for packet bridging.
+
+## Architectural impact
+- All modes reuse packet parsing/dispatch and send modules (`src/Network/{Receive,Send}.pm`).
+- Mode choice primarily changes transport/session orchestration and how packets are sourced/sinked.
+- AI, tasks, actor state, plugins, and macro systems remain mode-agnostic above the network abstraction.