diff --git a/openkore_llm_knowledge/knowledge/01_llm_context.md b/openkore_llm_knowledge/knowledge/01_llm_context.md
new file mode 100644
index 0000000000..cf85d00779
--- /dev/null
+++ b/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/*`
diff --git a/openkore_llm_knowledge/knowledge/02_architecture_overview.md b/openkore_llm_knowledge/knowledge/02_architecture_overview.md
new file mode 100644
index 0000000000..6bfe238247
--- /dev/null
+++ b/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.
diff --git a/openkore_llm_knowledge/knowledge/03_system_architecture_map.md b/openkore_llm_knowledge/knowledge/03_system_architecture_map.md
new file mode 100644
index 0000000000..3181b0647f
--- /dev/null
+++ b/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
diff --git a/openkore_llm_knowledge/knowledge/04_core_subsystems.md b/openkore_llm_knowledge/knowledge/04_core_subsystems.md
new file mode 100644
index 0000000000..9621268ac6
--- /dev/null
+++ b/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.
diff --git a/openkore_llm_knowledge/knowledge/05_module_dependency_map.md b/openkore_llm_knowledge/knowledge/05_module_dependency_map.md
new file mode 100644
index 0000000000..35f8eb23cf
--- /dev/null
+++ b/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).
diff --git a/openkore_llm_knowledge/knowledge/06_execution_flows.md b/openkore_llm_knowledge/knowledge/06_execution_flows.md
new file mode 100644
index 0000000000..cac52ed2b0
--- /dev/null
+++ b/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.
diff --git a/openkore_llm_knowledge/knowledge/07_npc_interaction_flow.md b/openkore_llm_knowledge/knowledge/07_npc_interaction_flow.md
new file mode 100644
index 0000000000..48d5f80007
--- /dev/null
+++ b/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.
diff --git a/openkore_llm_knowledge/knowledge/08_routing_and_movement.md b/openkore_llm_knowledge/knowledge/08_routing_and_movement.md
new file mode 100644
index 0000000000..a1e0b0cf5f
--- /dev/null
+++ b/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.
diff --git a/openkore_llm_knowledge/knowledge/09_networking_packets.md b/openkore_llm_knowledge/knowledge/09_networking_packets.md
new file mode 100644
index 0000000000..a72e17de20
--- /dev/null
+++ b/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`.
diff --git a/openkore_llm_knowledge/knowledge/10_xkore_modes.md b/openkore_llm_knowledge/knowledge/10_xkore_modes.md
new file mode 100644
index 0000000000..4f0d773936
--- /dev/null
+++ b/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.
diff --git a/openkore_llm_knowledge/knowledge/15_debugging_playbook.md b/openkore_llm_knowledge/knowledge/15_debugging_playbook.md
new file mode 100644
index 0000000000..c826ebf7c4
--- /dev/null
+++ b/openkore_llm_knowledge/knowledge/15_debugging_playbook.md
@@ -0,0 +1,185 @@
+# Debugging Playbook
+
+This playbook maps common OpenKore runtime failures to likely causes, inspection points, and step-by-step troubleshooting.
+
+---
+
+## 1) Bot not moving
+- **Likely subsystem**: AI + Task + Routing + Network Send
+- **Possible causes**:
+  - AI state blocked (attack/dialog/task lock)
+  - Route task never created or immediately failing
+  - Movement packets not being sent or rejected
+  - Movement-related config prevents walking
+- **Files to inspect**:
+  - `src/AI.pm`, `src/AI/CoreLogic.pm`
+  - `src/TaskManager.pm`, `src/Task/Move.pm`, `src/Task/Route.pm`
+  - `src/Network/Send.pm`, `src/Network/Receive.pm`
+- **Config to inspect**:
+  - `control/config.txt` (movement/lockMap/route-related options)
+  - `control/mon_control.txt` (behavior that can pin combat state)
+- **Debugging steps**:
+  1. Confirm AI is ticking and not paused/stuck in a higher-priority state.
+  2. Check whether `Task::Route`/`Task::Move` is queued in task manager.
+  3. Validate that move packets are emitted by send path.
+  4. Confirm receive updates are acknowledging position changes.
+  5. Reduce constraints in config (lock-only behavior, avoid lists) and retest.
+
+## 2) Routing failure
+- **Likely subsystem**: Routing + Field data + Task
+- **Possible causes**:
+  - Missing/incorrect field data
+  - Blocked cells/portal transitions not resolved
+  - Route recomputation loops without progress
+- **Files to inspect**:
+  - `src/Task/Route.pm`, `src/Task/Move.pm`, `src/Field.pm`
+- **Config to inspect**:
+  - `control/config.txt` (route/move flags)
+  - `fields/*` (map walkability data)
+- **Debugging steps**:
+  1. Verify map field exists and corresponds to current map.
+  2. Check route generation result (empty path or oscillating path).
+  3. Confirm position updates are fresh (no stale coordinates).
+  4. Test shorter route segments to isolate failing region.
+  5. Re-check portal/map transition assumptions.
+
+## 3) NPC interaction failure
+- **Likely subsystem**: Task + Network Receive/Send + Actor/NPC state
+- **Possible causes**:
+  - Wrong NPC coordinates or stale actor reference
+  - Dialogue step mismatch with server response
+  - Talk packets not sent or incorrect sequence
+- **Files to inspect**:
+  - `src/Task/TalkNPC.pm`
+  - `src/Network/Send.pm`, `src/Network/Receive.pm`, `src/Network/Receive/*`
+  - `src/ActorList.pm`
+- **Config to inspect**:
+  - `control/config.txt` (npc interaction directives/scripts)
+- **Debugging steps**:
+  1. Confirm NPC exists in actor list at expected coordinates.
+  2. Trace talk packet send sequence against expected dialogue steps.
+  3. Verify receive handlers parse response packet IDs correctly for server type.
+  4. Reproduce with minimal NPC script/task to reduce branching.
+
+## 4) Plugin not loading
+- **Likely subsystem**: Plugin system + startup/module loading
+- **Possible causes**:
+  - Syntax/runtime error in plugin file
+  - Incorrect plugin path/name
+  - Missing dependency module used by plugin
+- **Files to inspect**:
+  - `src/Plugins.pm`, `src/Modules.pm`
+  - `plugins/<plugin_name>/*.pl`
+- **Config to inspect**:
+  - `control/config.txt` (plugin enable/load entries)
+- **Debugging steps**:
+  1. Check startup logs for plugin load exceptions.
+  2. Validate plugin registers with `Plugins::register`.
+  3. Confirm plugin path and filename match expected loader behavior.
+  4. Remove optional dependency imports to isolate failing require/use.
+
+## 5) Plugin hook not firing
+- **Likely subsystem**: Plugin hooks + event dispatch
+- **Possible causes**:
+  - Hook registered with wrong event name
+  - Hook callback blocked by guard condition
+  - Expected event never emitted in current runtime path
+- **Files to inspect**:
+  - `src/Plugins.pm`, `src/functions.pl`
+  - Plugin file defining `Plugins::addHooks`
+- **Config to inspect**:
+  - `control/config.txt` (conditions controlling event generation)
+- **Debugging steps**:
+  1. List hooks registered by plugin after load.
+  2. Add lightweight logging at callback entry.
+  3. Verify event name spelling and payload assumptions.
+  4. Trigger event manually through a minimal reproduction path.
+
+## 6) Macro not triggering
+- **Likely subsystem**: Macro plugin + command/hook bridge
+- **Possible causes**:
+  - Macro file not loaded
+  - Automacro condition never true
+  - Macro command blocked by runtime state
+- **Files to inspect**:
+  - `plugins/macro/macro.pl`, `plugins/macro/Macro/*`
+  - `src/Commands.pm`, `src/Plugins.pm`
+- **Config to inspect**:
+  - `control/config.txt` (`macro_file` and related keys)
+  - macro definition file referenced by config
+- **Debugging steps**:
+  1. Confirm macro plugin loaded and macro file parsed.
+  2. Validate automacro conditions against live state.
+  3. Execute macro manually to separate trigger vs action issues.
+  4. Inspect command dispatch path for blocked/invalid command.
+
+## 7) eventMacro issues
+- **Likely subsystem**: eventMacro plugin + event parser/runner
+- **Possible causes**:
+  - Invalid eventMacro syntax
+  - Trigger conditions not matching event payload
+  - Runner stalled by previous action/wait state
+- **Files to inspect**:
+  - `plugins/eventMacro/eventMacro.pl`
+  - `plugins/eventMacro/eventMacro/{Core,Runner,Automacro,FileParser}.pm`
+- **Config to inspect**:
+  - `control/config.txt` (`eventMacro_file`)
+  - eventMacro script file
+- **Debugging steps**:
+  1. Validate eventMacro file parsing with minimal script.
+  2. Log trigger evaluation for target automacro.
+  3. Check runner queue and pending wait/time gates.
+  4. Reduce script to one trigger + one action and retest.
+
+## 8) Packet desync
+- **Likely subsystem**: Networking receive/parser + server-type mappings
+- **Possible causes**:
+  - Wrong server type packet tables
+  - Opcode map mismatch after server update
+  - Packet boundary/tokenization errors
+- **Files to inspect**:
+  - `src/Network/MessageTokenizer.pm`, `src/Network/PacketParser.pm`
+  - `src/Network/Receive.pm`, `src/Network/Receive/*`
+  - `src/Network/Send.pm`, `src/Network/Send/*`
+- **Config to inspect**:
+  - `control/config.txt` (serverType/recvpackets settings)
+  - `tables/*` packet definition files for the target server
+- **Debugging steps**:
+  1. Confirm selected serverType and recvpackets data.
+  2. Compare failing opcode decode against current server packet definitions.
+  3. Capture raw packet sequence around first desync point.
+  4. Verify both receive and send side use compatible packet maps.
+
+## 9) XKore sync issues
+- **Likely subsystem**: XKore transport/session bridging
+- **Possible causes**:
+  - Client-proxy handshake mismatch
+  - Account/char/map relay state divergence
+  - Timing/forwarding issues in XKore mode
+- **Files to inspect**:
+  - `src/Network/XKore.pm`, `src/Network/XKore2.pm`, `src/Network/XKoreProxy.pm`
+  - `src/Network/XKore2/{AccountServer,CharServer,MapServer}.pm`
+- **Config to inspect**:
+  - `control/config.txt` (XKore mode and connection settings)
+- **Debugging steps**:
+  1. Confirm active mode (Direct vs XKore/XKore2/XKoreProxy).
+  2. Trace handshake/login flow across account->char->map stages.
+  3. Check for asymmetric forwarding (client sees state that bot does not, or inverse).
+  4. Validate mode-specific ports/bind settings and restart cleanly.
+
+## 10) Visual client state not updating
+- **Likely subsystem**: XKore bridge + packet forwarding + actor sync
+- **Possible causes**:
+  - Forwarded packets not reaching client
+  - Actor state updated in bot but not mirrored to client channel
+  - Client session stuck after map transition
+- **Files to inspect**:
+  - `src/Network/XKore*.pm`
+  - `src/Network/Receive.pm`, `src/ActorList.pm`
+- **Config to inspect**:
+  - `control/config.txt` (XKore forwarding/session config)
+- **Debugging steps**:
+  1. Verify bot-side state is changing (position/actors) first.
+  2. Confirm corresponding packets are forwarded to client path.
+  3. Re-check session phase (account/char/map) for stuck transition.
+  4. Reconnect client through same mode to re-establish synchronization.
diff --git a/openkore_llm_knowledge/knowledge/16_debug_decision_trees.md b/openkore_llm_knowledge/knowledge/16_debug_decision_trees.md
new file mode 100644
index 0000000000..8869941f85
--- /dev/null
+++ b/openkore_llm_knowledge/knowledge/16_debug_decision_trees.md
@@ -0,0 +1,90 @@
+# Debug Decision Trees
+
+These trees provide fast triage paths for recurring OpenKore failures.
+
+## A) Bot not moving / Routing failure
+
+```mermaid
+flowchart TD
+    A[Bot not moving] --> B{AI ticking?}
+    B -- No --> B1[Inspect src/AI.pm and main loop in src/functions.pl]
+    B -- Yes --> C{Task::Route or Task::Move queued?}
+    C -- No --> C1[Inspect AI decisions in src/AI/CoreLogic.pm and config gates]
+    C -- Yes --> D{Move packets sent?}
+    D -- No --> D1[Inspect src/Network/Send.pm and command/task path]
+    D -- Yes --> E{Position updates received?}
+    E -- No --> E1[Inspect src/Network/Receive.pm and packet mapping]
+    E -- Yes --> F{Path valid in fields data?}
+    F -- No --> F1[Inspect src/Field.pm + fields/*]
+    F -- Yes --> G[Check blockers/lock settings in control/config.txt]
+```
+
+Use this when movement appears frozen or route tasks fail repeatedly.
+
+## B) NPC interaction failure
+
+```mermaid
+flowchart TD
+    A[NPC interaction fails] --> B{NPC present in ActorList?}
+    B -- No --> B1[Inspect src/ActorList.pm updates from receive handlers]
+    B -- Yes --> C{TalkNPC task created?}
+    C -- No --> C1[Inspect trigger path in AI/commands/plugins]
+    C -- Yes --> D{Talk packets emitted?}
+    D -- No --> D1[Inspect src/Task/TalkNPC.pm + src/Network/Send.pm]
+    D -- Yes --> E{Expected response packet decoded?}
+    E -- No --> E1[Inspect src/Network/Receive/* serverType handlers]
+    E -- Yes --> F[Validate dialogue sequence assumptions in task script]
+```
+
+Use this when NPC talks stop, loop, or complete with wrong branch.
+
+## C) Plugin not loading / Hook not firing
+
+```mermaid
+flowchart TD
+    A[Plugin issue] --> B{Plugin loads successfully?}
+    B -- No --> B1[Check syntax/dependencies + src/Plugins.pm loader logs]
+    B -- Yes --> C{Hook registered via Plugins::addHooks?}
+    C -- No --> C1[Fix registration block in plugin file]
+    C -- Yes --> D{Event emitted at runtime?}
+    D -- No --> D1[Inspect event source in src/functions.pl / network paths]
+    D -- Yes --> E{Callback guard conditions pass?}
+    E -- No --> E1[Log callback inputs and config-dependent guards]
+    E -- Yes --> F[Inspect side effects via Commands/TaskManager]
+```
+
+Use this for both plugin boot failures and silent hooks.
+
+## D) Macro/eventMacro not triggering
+
+```mermaid
+flowchart TD
+    A[Macro/eventMacro not triggering] --> B{Plugin loaded?}
+    B -- No --> B1[Inspect plugins/macro or plugins/eventMacro load path]
+    B -- Yes --> C{Script file parsed?}
+    C -- No --> C1[Validate macro_file/eventMacro_file in control/config.txt]
+    C -- Yes --> D{Trigger condition true in live state?}
+    D -- No --> D1[Log variables/events used by automacro]
+    D -- Yes --> E{Action executes manually?}
+    E -- No --> E1[Inspect command path in src/Commands.pm]
+    E -- Yes --> F[Investigate scheduler/wait constraints in runner]
+```
+
+Use this to isolate parser issues from trigger logic and action execution.
+
+## E) Packet desync / XKore sync / visual client desync
+
+```mermaid
+flowchart TD
+    A[Desync observed] --> B{Wrong serverType/packet table?}
+    B -- Yes --> B1[Fix control/config.txt + tables/* packet mappings]
+    B -- No --> C{Receive decode errors?}
+    C -- Yes --> C1[Inspect MessageTokenizer/PacketParser/Receive handlers]
+    C -- No --> D{Only in XKore mode?}
+    D -- No --> D1[Inspect send/receive parity and opcode updates]
+    D -- Yes --> E{Client and bot state diverge?}
+    E -- Yes --> E1[Inspect src/Network/XKore*.pm forwarding/session state]
+    E -- No --> F[Inspect map-transition/session phase sync]
+```
+
+Use this for protocol mismatches and client-bridge synchronization drift.
diff --git a/openkore_llm_knowledge/knowledge/17_code_recipes.md b/openkore_llm_knowledge/knowledge/17_code_recipes.md
new file mode 100644
index 0000000000..ba7d8fa816
--- /dev/null
+++ b/openkore_llm_knowledge/knowledge/17_code_recipes.md
@@ -0,0 +1,147 @@
+# Code Recipes
+
+Practical snippets for common OpenKore development tasks.
+
+## 1) Minimal plugin skeleton
+```perl
+package myPlugin;
+
+use strict;
+use Plugins;
+use Log qw(message warning error);
+
+my $hooks = [];
+
+Plugins::register('myPlugin', 'Minimal plugin skeleton', \&on_unload);
+$hooks = Plugins::addHooks(
+    ['start3', \&on_start],
+    ['AI_pre', \&on_ai_pre],
+);
+
+sub on_start {
+    message "[myPlugin] started\n", 'info';
+}
+
+sub on_ai_pre {
+    my ($hookName, $args) = @_;
+    # lightweight periodic logic
+}
+
+sub on_unload {
+    Plugins::delHooks($hooks);
+    message "[myPlugin] unloaded\n", 'info';
+}
+
+1;
+```
+
+## 2) Hook registration pattern
+```perl
+my $hooks = Plugins::addHooks(
+    ['packet_pre/actor_moved', \&on_actor_moved],
+    ['packet/map_changed', \&on_map_changed],
+    ['configModify', \&on_config_modify],
+);
+
+sub on_actor_moved {
+    my ($hook, $args) = @_;
+    # inspect $args->{ID}, $args->{coords}
+}
+```
+
+## 3) Command registration
+```perl
+Commands::register(
+    ['mycmd', 'run custom action', \&cmd_mycmd]
+);
+
+sub cmd_mycmd {
+    my (undef, $args) = @_;
+    message "[myPlugin] mycmd args: $args\n", 'info';
+}
+
+# on unload:
+Commands::unregister('mycmd');
+```
+
+## 4) Packet hook example
+```perl
+my $hooks = Plugins::addHooks(
+    ['packet_pre/login_error', \&on_login_error],
+    ['packet/map_changed', \&on_map_changed],
+);
+
+sub on_login_error {
+    my ($hook, $args) = @_;
+    warning "Login error packet received: $args->{type}\n";
+}
+```
+
+## 5) Macro example (`macros.txt`)
+```txt
+automacro autoHeal {
+    hp < 40%
+    timeout 1
+    call {
+        do ss 28
+    }
+}
+
+macro goTown {
+    do move prontera
+}
+```
+
+## 6) eventMacro example
+```txt
+automacro checkWeight {
+    InLockMap 1
+    weight > 85%
+    call {
+        do conf itemsTakeAuto 0
+        do ai clear
+    }
+}
+
+automacro greetOnMap {
+    map prontera
+    run-once 1
+    call {
+        do c Hello from OpenKore
+    }
+}
+```
+
+## 7) Configuration examples (`control/config.txt`)
+```txt
+lockMap prontera
+saveMap prontera
+route_randomWalk 1
+teleportAuto_hp 25
+itemsTakeAuto 2
+attackAuto 2
+macro_file macros.txt
+eventMacro_file eventMacros.txt
+```
+
+## 8) Debugging snippets
+### 8.1 Print current map and coordinates
+```perl
+use Globals qw($field %char);
+message sprintf("Map=%s x=%d y=%d\n", $field->baseName, $char{pos_to}{x}, $char{pos_to}{y}), 'debug';
+```
+
+### 8.2 Trace command callback entry
+```perl
+sub cmd_mycmd {
+    my (undef, $args) = @_;
+    message "[TRACE] cmd_mycmd called with '$args'\n", 'debug';
+}
+```
+
+### 8.3 Check task queue state quickly
+```perl
+use TaskManager;
+my $task = TaskManager::getTaskManager()->activeTask;
+message "Active task: " . ($task ? ref($task) : 'none') . "\n", 'debug';
+```
diff --git a/openkore_llm_knowledge/knowledge/18_openkore_faq.md b/openkore_llm_knowledge/knowledge/18_openkore_faq.md
new file mode 100644
index 0000000000..c3a6760545
--- /dev/null
+++ b/openkore_llm_knowledge/knowledge/18_openkore_faq.md
@@ -0,0 +1,147 @@
+# OpenKore Technical FAQ
+
+## Architecture
+1. **Q:** What is OpenKore's main runtime entry point?  
+   **A:** `src/functions.pl` initializes modules and runs the main loop.
+2. **Q:** Where is global runtime state stored?  
+   **A:** Mostly in `src/Globals.pm` and shared structures.
+3. **Q:** Which module runs AI logic?  
+   **A:** `src/AI.pm` coordinates AI and calls `src/AI/CoreLogic.pm`.
+4. **Q:** How are game entities represented?  
+   **A:** Through `src/Actor.pm` and `src/ActorList.pm`.
+5. **Q:** What handles tasks?  
+   **A:** `src/Task.pm` defines tasks and `src/TaskManager.pm` schedules them.
+6. **Q:** Where does command parsing happen?  
+   **A:** In `src/Commands.pm`.
+7. **Q:** How are plugins managed?  
+   **A:** Via `src/Plugins.pm` lifecycle and hooks API.
+8. **Q:** Why is architecture loop-based?  
+   **A:** To repeatedly process receive->state->AI->tasks->send cycles.
+
+## Debugging
+9. **Q:** First check when bot freezes?  
+   **A:** Confirm AI tick and active task state.
+10. **Q:** How to distinguish route vs movement failure?  
+    **A:** Check if a route exists, then confirm move packets and position updates.
+11. **Q:** Why log packet IDs during failures?  
+    **A:** To detect serverType/recvpackets mismatch quickly.
+12. **Q:** Best way to debug plugin hooks?  
+    **A:** Log both hook registration and callback entry.
+13. **Q:** Why test with minimal config?  
+    **A:** To remove config side effects masking root causes.
+14. **Q:** What indicates desync risk?  
+    **A:** Decode errors, unknown packets, or stale actor updates.
+15. **Q:** How to verify task deadlock?  
+    **A:** Inspect active task and queued tasks in task manager.
+16. **Q:** Should I debug with all plugins enabled?  
+    **A:** No, isolate with minimal plugin set first.
+
+## Plugins
+17. **Q:** Minimum plugin requirements?  
+    **A:** `Plugins::register`, optional hooks, and clean unload.
+18. **Q:** How to add a custom command?  
+    **A:** Use `Commands::register` and unregister on unload.
+19. **Q:** Why might plugin load fail silently?  
+    **A:** Early syntax/runtime errors or missing dependencies.
+20. **Q:** Can plugins alter AI behavior?  
+    **A:** Yes, via commands, hooks, and task interactions.
+21. **Q:** Where are community plugins stored?  
+    **A:** Under `plugins/`.
+22. **Q:** How to avoid hook performance issues?  
+    **A:** Keep callbacks lightweight and defer heavy work.
+23. **Q:** Can multiple plugins share hook names?  
+    **A:** Yes, each callback runs if registered correctly.
+24. **Q:** Why unregister hooks on unload?  
+    **A:** To prevent stale callbacks and inconsistent state.
+
+## Macros / eventMacro
+25. **Q:** Difference between macro and eventMacro?  
+    **A:** Macro is classic command script flow; eventMacro is event/condition-driven automation.
+26. **Q:** Where to set macro file path?  
+    **A:** `control/config.txt` via `macro_file`.
+27. **Q:** Where to set eventMacro file path?  
+    **A:** `control/config.txt` via `eventMacro_file`.
+28. **Q:** Why automacro never triggers?  
+    **A:** Condition false, plugin not loaded, or parse issue.
+29. **Q:** How to test macro trigger quickly?  
+    **A:** Manually run equivalent command and compare behavior.
+30. **Q:** Why use run-once in eventMacro?  
+    **A:** To avoid repeated firing for one-time actions.
+31. **Q:** Can macros execute OpenKore commands?  
+    **A:** Yes, via `do <command>`.
+32. **Q:** How to debug eventMacro parser issues?  
+    **A:** Reduce to one trigger + one action and rebuild incrementally.
+
+## Routing / movement
+33. **Q:** Which files control routing logic?  
+    **A:** `src/Task/Route.pm`, `src/Task/Move.pm`, and `src/Field.pm`.
+34. **Q:** What is walkability?  
+    **A:** Whether a map cell is traversable based on field data.
+35. **Q:** Why does route loop occur?  
+    **A:** Stale position updates, blocked transitions, or invalid field assumptions.
+36. **Q:** What is lockMap effect?  
+    **A:** Restricts behavior to a preferred map scope.
+37. **Q:** How to validate map data?  
+    **A:** Ensure map exists in `fields/*` and coordinates are valid.
+38. **Q:** Why movement works manually but not AI?  
+    **A:** AI priorities/config may override movement intents.
+39. **Q:** Can aggressive combat stop movement?  
+    **A:** Yes, combat states can continuously preempt route tasks.
+40. **Q:** Best first movement test?  
+    **A:** Short route on same map with minimal automation enabled.
+
+## Networking
+41. **Q:** Which module tokenizes incoming packets?  
+    **A:** `src/Network/MessageTokenizer.pm`.
+42. **Q:** Which module decodes packet structures?  
+    **A:** `src/Network/PacketParser.pm` and receive handlers.
+43. **Q:** Where is receive dispatch done?  
+    **A:** `src/Network/Receive.pm`.
+44. **Q:** Where are server-specific packet handlers?  
+    **A:** `src/Network/Receive/*` and `src/Network/Send/*`.
+45. **Q:** Why packet errors after server patch?  
+    **A:** Opcode/table changes requiring updated mappings.
+46. **Q:** Can wrong serverType break everything?  
+    **A:** Yes, it causes systematic decode/encode mismatch.
+47. **Q:** What causes partial desync?  
+    **A:** Some packets map correctly while others fail for changed opcodes.
+48. **Q:** How to isolate receive vs send bug?  
+    **A:** Compare inbound decode logs and outbound packet construction separately.
+
+## NPC interaction
+49. **Q:** Which task handles NPC dialogues?  
+    **A:** `src/Task/TalkNPC.pm`.
+50. **Q:** Why NPC script stalls mid-dialogue?  
+    **A:** Response packet mismatch or wrong expected step sequence.
+51. **Q:** Must NPC be in actor list first?  
+    **A:** Yes, reliable interaction depends on valid actor presence and position.
+52. **Q:** Why wrong NPC gets targeted?  
+    **A:** Incorrect coordinates or stale target selection.
+53. **Q:** What to inspect first in NPC failure?  
+    **A:** Talk packet sequence and corresponding receive responses.
+54. **Q:** Can plugins interfere with NPC flow?  
+    **A:** Yes, if they alter commands/tasks concurrently.
+
+## Config behavior
+55. **Q:** Where are core behavior settings?  
+    **A:** `control/config.txt`.
+56. **Q:** What file controls monster behavior rules?  
+    **A:** `control/mon_control.txt`.
+57. **Q:** Why config changes seem ignored?  
+    **A:** Reload needed, wrong key, or overridden by plugin automation.
+58. **Q:** How to keep config deterministic?  
+    **A:** Use minimal explicit settings and disable conflicting automation.
+59. **Q:** What is saveMap used for?  
+    **A:** Preferred return/safety map behavior.
+60. **Q:** Why document config with code changes?  
+    **A:** Behavior is policy-driven; docs prevent invisible config regressions.
+
+## XKore / client sync
+61. **Q:** What is XKore2 role?  
+    **A:** Local proxy/relay flow for account/char/map sessions.
+62. **Q:** Why client view stale but bot state updates?  
+    **A:** Forwarding/session sync issue in XKore bridge path.
+63. **Q:** Is debugging Direct and XKore identical?  
+    **A:** No, transport/session layers differ significantly.
+64. **Q:** First step for XKore sync bugs?  
+    **A:** Confirm active mode and trace handshake phase transitions.
diff --git a/openkore_llm_knowledge/knowledge/19_glossary.md b/openkore_llm_knowledge/knowledge/19_glossary.md
new file mode 100644
index 0000000000..abf1c04be5
--- /dev/null
+++ b/openkore_llm_knowledge/knowledge/19_glossary.md
@@ -0,0 +1,27 @@
+# Glossary
+
+- **Actor**: Runtime entity abstraction (player, monster, NPC, portal) managed via `Actor` modules.
+- **AI queue**: Ordered AI intention/state processing that decides which action/task should run next.
+- **Task**: Executable unit with lifecycle (start/process/finish), e.g., move, route, NPC interaction.
+- **Plugin hook**: Callback registration point triggered by runtime events (`Plugins::addHooks`).
+- **Command handler**: Function bound to a command name through `Commands::register`.
+- **Packet handler**: Receive/send routine that decodes or encodes specific protocol packets.
+- **Route**: Planned path between coordinates/maps, later executed stepwise by movement tasks.
+- **Automacro**: Conditional automation rule that triggers scripted actions when conditions match.
+- **eventMacro**: Event/condition-driven macro framework with parser, runner, and trigger model.
+- **lockMap**: Configuration policy limiting movement/behavior to a designated map.
+- **saveMap**: Preferred map used for return/recovery behavior.
+- **Walkability**: Whether map cells are traversable according to field data and routing constraints.
+- **Client sync**: Consistency between bot internal state and visual game client state (important in XKore).
+- **Server packet**: Protocol message exchanged with the game server; parsed/encoded by network modules.
+- **ServerType**: Packet profile selection controlling opcode and packet layout mapping.
+- **Receive dispatch**: Mechanism mapping inbound opcode frames to concrete handler methods.
+- **Send pipeline**: Path from action intent to serialized outbound packet.
+- **XKore mode**: Bridged/proxy connection model variants (`XKore`, `XKore2`, `XKoreProxy`).
+- **Main loop tick**: One full iteration of runtime processing in `functions.pl`.
+- **Field data**: Map walkability/cell data used by route calculations.
+- **Desync**: Divergence between expected protocol/state and observed runtime behavior.
+- **Hook event**: Named runtime signal emitted for plugin subscribers.
+- **Task manager**: Scheduler coordinating active/pending tasks and transitions.
+- **Packet desync**: Failure mode where packet mappings no longer align with server behavior.
+- **Control files**: Operator-facing config files under `control/` that drive runtime policy.
diff --git a/openkore_llm_knowledge/knowledge/20_code_index.md b/openkore_llm_knowledge/knowledge/20_code_index.md
new file mode 100644
index 0000000000..d0b179e3f4
--- /dev/null
+++ b/openkore_llm_knowledge/knowledge/20_code_index.md
@@ -0,0 +1,46 @@
+# Code Index (Architecture-Oriented)
+
+## Runtime entry and orchestration
+- `src/functions.pl` — startup sequence and main loop
+- `src/Modules.pm` — module loading registry
+- `src/Globals.pm` — shared runtime state container
+
+## AI
+- `src/AI.pm` — AI framework and queue/state management
+- `src/AI/CoreLogic.pm` — core decision routines
+
+## Actor and world model
+- `src/Actor.pm` — actor base model
+- `src/ActorList.pm` — actor collections/indexing
+- `src/Actor/*` — actor specializations
+- `src/Field.pm` — map/field representation
+
+## Task execution
+- `src/Task.pm` — task abstraction
+- `src/TaskManager.pm` — scheduler/executor
+- `src/Task/Route.pm` — route planning/execution wrapper
+- `src/Task/Move.pm` — movement task
+- `src/Task/TalkNPC.pm` — NPC dialogue workflow
+- `src/Task/UseSkill.pm` — skill-use workflows
+
+## Networking and packets
+- `src/Network.pm` — network facade and state
+- `src/Network/DirectConnection.pm` — direct server mode
+- `src/Network/XKore.pm`, `src/Network/XKore2.pm`, `src/Network/XKoreProxy.pm` — proxy/bridge modes
+- `src/Network/MessageTokenizer.pm` — packet frame/token extraction
+- `src/Network/PacketParser.pm` — packet definition parsing
+- `src/Network/Receive.pm` + `src/Network/Receive/*` — inbound packet dispatch/handlers
+- `src/Network/Send.pm` + `src/Network/Send/*` — outbound packet builders
+
+## Commands, plugins, and automation
+- `src/Commands.pm` — command parser/dispatcher
+- `src/Plugins.pm` — plugin lifecycle and hook API
+- `plugins/macro/macro.pl` + `plugins/macro/Macro/*` — legacy macro automation
+- `plugins/eventMacro/eventMacro.pl` + `plugins/eventMacro/eventMacro/*` — event-driven macro automation
+
+## Configuration and data sources
+- `src/Settings.pm` — config path and file registration
+- `src/FileParsers.pm` — config/table parsing
+- `control/*` — user behavior policies and runtime options
+- `tables/*` — server/data tables
+- `fields/*` — map grids for routing/navigation
diff --git a/openkore_llm_knowledge/knowledge/22_common_pitfalls.md b/openkore_llm_knowledge/knowledge/22_common_pitfalls.md
new file mode 100644
index 0000000000..66dbbe6238
--- /dev/null
+++ b/openkore_llm_knowledge/knowledge/22_common_pitfalls.md
@@ -0,0 +1,49 @@
+# Common Pitfalls
+
+Concise checklist of high-frequency debugging traps in OpenKore architecture and operations.
+
+## 1) Assuming movement issues are only routing bugs
+- AI state locks, command overrides, or task queue starvation can mimic routing failures.
+- Check AI/task state before editing route logic.
+
+## 2) Ignoring serverType/packet table drift
+- Packet desync often starts after server updates when recvpackets/opcodes change.
+- Keep `control/config.txt` server settings aligned with `tables/*` packet definitions.
+
+## 3) Debugging plugin hooks without proving event emission
+- A hook can be correct but never run if the event is not emitted in the current flow.
+- Verify both registration and actual event source path.
+
+## 4) Treating macro trigger failures as parser failures
+- Many cases are valid parse + false trigger conditions.
+- Separate: plugin load -> file parse -> trigger true -> action execution.
+
+## 5) Overlooking config-side constraints
+- `control/config.txt`, `mon_control.txt`, and related files can disable or redirect behavior.
+- Always test with minimal, known-good config for reproduction.
+
+## 6) Mixing XKore and DirectConnection assumptions
+- Transport/session behavior differs; debugging steps are mode-specific.
+- Confirm active mode first before tracing packet/session paths.
+
+## 7) Trusting visual client state over bot internal state
+- In XKore scenarios, client view may lag/diverge from bot state.
+- Compare bot-side actor/position updates with forwarded client packets.
+
+## 8) Investigating deep modules before reproducing minimally
+- Large automation stacks (AI + plugin + macro + eventMacro) hide root causes.
+- Reproduce with minimal script/task/command to localize fault domain.
+
+## Fast isolation matrix
+| Symptom | First subsystem to verify | Primary files |
+|---|---|---|
+| Bot not moving | AI/Task | `src/AI.pm`, `src/TaskManager.pm` |
+| Route fails | Routing/Field | `src/Task/Route.pm`, `src/Field.pm` |
+| NPC fails | Task + Receive | `src/Task/TalkNPC.pm`, `src/Network/Receive.pm` |
+| Plugin not loading | Plugin loader | `src/Plugins.pm`, plugin file |
+| Hook silent | Event dispatch | `src/Plugins.pm`, event source module |
+| Macro not triggering | Macro pipeline | `plugins/macro/*`, `src/Commands.pm` |
+| eventMacro issues | eventMacro runner | `plugins/eventMacro/eventMacro/*` |
+| Packet desync | Packet mapping | `src/Network/PacketParser.pm`, `tables/*` |
+| XKore sync issues | XKore bridge | `src/Network/XKore*.pm` |
+| Client view stale | XKore forwarding | `src/Network/XKore*.pm`, `src/ActorList.pm` |
diff --git a/openkore_llm_knowledge/knowledge/24_learning_path.md b/openkore_llm_knowledge/knowledge/24_learning_path.md
new file mode 100644
index 0000000000..f9c988b0e1
--- /dev/null
+++ b/openkore_llm_knowledge/knowledge/24_learning_path.md
@@ -0,0 +1,49 @@
+# Learning Path for New OpenKore Developers
+
+## Stage 0: Orientation (Day 1)
+- Read `01_llm_context.md`, `02_architecture_overview.md`, `03_system_architecture_map.md`.
+- Goal: understand receive->state->AI->task->send loop and key directories.
+
+## Stage 1: Runtime core comprehension (Days 2-3)
+- Study `src/functions.pl`, `src/Globals.pm`, `src/Modules.pm`.
+- Track one full startup + one main-loop tick.
+- Exercise: write a short note describing what runs each tick.
+
+## Stage 2: Network + actor model (Days 4-5)
+- Study `src/Network.pm`, `src/Network/Receive.pm`, `src/Network/Send.pm`, `src/ActorList.pm`.
+- Exercise: trace one incoming packet to a world-state mutation.
+- Exercise: trace one outgoing action from command/task to send packet.
+
+## Stage 3: AI and task flow (Days 6-7)
+- Study `src/AI.pm`, `src/AI/CoreLogic.pm`, `src/TaskManager.pm`, `src/Task/Route.pm`, `src/Task/TalkNPC.pm`.
+- Exercise: map how AI chooses a task and how task completion feeds back.
+
+## Stage 4: Plugins and automation (Week 2)
+- Study `src/Plugins.pm`, `src/Commands.pm`, `plugins/macro/*`, `plugins/eventMacro/*`.
+- Build a minimal plugin with one hook and one command.
+- Add one macro and one eventMacro automation rule.
+
+## Stage 5: Config-driven behavior (Week 2)
+- Study `control/config.txt`, `control/mon_control.txt`, relevant table files.
+- Exercise: change one behavior via config only and document impact.
+
+## Stage 6: Debugging proficiency (Week 3)
+- Use `15_debugging_playbook.md`, `16_debug_decision_trees.md`, `22_common_pitfalls.md`.
+- Reproduce and fix one issue in each category:
+  - movement/routing
+  - plugin/hook
+  - macro/eventMacro
+  - packet/XKore sync
+
+## Stage 7: Advanced protocol + XKore (Week 3+)
+- Study `09_networking_packets.md`, `10_xkore_modes.md`.
+- Compare DirectConnection vs XKore2 flow and identify mode-specific risks.
+
+## Suggested competency checklist
+- [ ] Explain OpenKore runtime architecture from memory.
+- [ ] Trace packet receive and send paths.
+- [ ] Implement and unload a safe plugin.
+- [ ] Diagnose macro and eventMacro trigger failures.
+- [ ] Diagnose route and movement failures.
+- [ ] Diagnose basic packet/serverType desync.
+- [ ] Explain XKore sync failure patterns.
diff --git a/openkore_llm_knowledge/knowledge/26_architecture_diagrams.md b/openkore_llm_knowledge/knowledge/26_architecture_diagrams.md
new file mode 100644
index 0000000000..54654be8e2
--- /dev/null
+++ b/openkore_llm_knowledge/knowledge/26_architecture_diagrams.md
@@ -0,0 +1,17 @@
+# Architecture Diagrams (Mermaid)
+
+This file indexes the runtime diagrams for OpenKore subsystem interactions.
+
+## Included diagrams
+1. **AI execution loop** — `06_execution_flows.md`
+2. **Packet receive flow** — `09_networking_packets.md`
+3. **NPC interaction flow** — `07_npc_interaction_flow.md`
+4. **Plugin hook execution** — `27_system_flows.md`
+5. **Routing and movement flow** — `08_routing_and_movement.md`
+6. **Command execution flow** — `27_system_flows.md`
+
+## Reading guidance
+- Start with `06_execution_flows.md` for the main runtime cycle.
+- Use `09_networking_packets.md` and `10_xkore_modes.md` for transport/protocol context.
+- Use `07_npc_interaction_flow.md` and `08_routing_and_movement.md` for task-level behavioral flows.
+- Use `27_system_flows.md` for extension and control-plane flows.
diff --git a/openkore_llm_knowledge/knowledge/27_system_flows.md b/openkore_llm_knowledge/knowledge/27_system_flows.md
new file mode 100644
index 0000000000..61357e961e
--- /dev/null
+++ b/openkore_llm_knowledge/knowledge/27_system_flows.md
@@ -0,0 +1,35 @@
+# System Flows
+
+## Plugin hook execution flow
+Plugins extend runtime behavior through hook callbacks registered in `src/Plugins.pm` and commonly invoke `src/Commands.pm` or task APIs.
+
+```mermaid
+flowchart TD
+    A[Plugin load\nplugins/*.pl] --> B[Plugins::register]
+    B --> C[Plugins::addHooks]
+    C --> D[Runtime event\nloop/packet/config]
+    D --> E[Plugin callback]
+    E --> F{Action needed?}
+    F -- No --> G[Return]
+    F -- Yes --> H[Execute command\nsrc/Commands.pm]
+    H --> I[Task/Network side effects]
+    I --> G
+```
+
+Hook callbacks are event-driven and should remain lightweight; heavy operations are usually delegated to commands/tasks.
+
+## Command execution flow
+
+```mermaid
+flowchart TD
+    A[Input source\nconsole/plugin/macro] --> B[Commands::run]
+    B --> C[Command parser\nsrc/Commands.pm]
+    C --> D{Built-in or plugin cmd?}
+    D -- Built-in --> E[Built-in handler]
+    D -- Plugin --> F[Plugin command callback]
+    E --> G[Update state / queue task / send packet]
+    F --> G
+    G --> H[Feedback to interface/log]
+```
+
+Commands are a shared control surface across manual operations, plugins, and macro automation.
diff --git a/openkore_llm_knowledge/knowledge/29_prompt_examples_for_users.md b/openkore_llm_knowledge/knowledge/29_prompt_examples_for_users.md
new file mode 100644
index 0000000000..ba46ebe919
--- /dev/null
+++ b/openkore_llm_knowledge/knowledge/29_prompt_examples_for_users.md
@@ -0,0 +1,49 @@
+# Prompt Examples for Users
+
+Realistic prompts users can ask an OpenKore-focused GPT assistant.
+
+## Architecture and code navigation
+1. "Explain how `src/functions.pl` orchestrates the OpenKore main loop."
+2. "Map the dependency chain between AI, TaskManager, and Network::Send."
+3. "Which modules should I read first to understand actor updates from packets?"
+4. "Summarize how plugin hooks interact with command execution."
+
+## Debugging
+5. "My bot stopped moving. Give me a step-by-step diagnosis plan with files to inspect."
+6. "How do I distinguish packet desync from route calculation failure?"
+7. "Generate a troubleshooting checklist for NPC dialogue failures."
+8. "Why are my plugin hooks not firing even though plugin loads fine?"
+9. "Help me debug eventMacro that parses but never triggers."
+10. "Create a minimal reproduction plan for XKore client sync issues."
+
+## Plugins
+11. "Create a minimal plugin skeleton with register, hooks, and unload cleanup."
+12. "Add a custom command `farmstatus` that prints current map and task."
+13. "Show best practices for lightweight hook callbacks in OpenKore plugins."
+14. "How do I instrument a plugin with debug logs without spamming output?"
+
+## Macro / eventMacro
+15. "Write an automacro that pauses looting above 85% weight."
+16. "Create eventMacro rules to send a chat message only once when entering Prontera."
+17. "Compare macro and eventMacro for reactive combat behavior."
+18. "How can I test whether a macro trigger condition is actually true at runtime?"
+
+## Routing and movement
+19. "Explain why route tasks can oscillate and how to debug it."
+20. "Show a script strategy to test short movement segments before full routes."
+21. "What configs can block movement even if route exists?"
+
+## Networking and packets
+22. "How do I verify that serverType and recvpackets are correctly configured?"
+23. "Trace one incoming movement packet from socket bytes to Actor update."
+24. "What logs should I capture when packet decode errors start after a patch?"
+25. "Explain where to add temporary logging for packet send construction."
+
+## Configuration
+26. "Review my config goals and suggest a minimal stable `config.txt` baseline."
+27. "Which `mon_control.txt` settings commonly interfere with movement tasks?"
+28. "How do lockMap and saveMap influence AI behavior?"
+
+## Learning and onboarding
+29. "Build me a 2-week learning plan to become productive in OpenKore development."
+30. "Give me a study order for networking, AI, tasks, plugins, and macros with exercises."
diff --git a/openkore_llm_knowledge/knowledge/30_dataset_summary.md b/openkore_llm_knowledge/knowledge/30_dataset_summary.md
new file mode 100644
index 0000000000..91cb53f8a1
--- /dev/null
+++ b/openkore_llm_knowledge/knowledge/30_dataset_summary.md
@@ -0,0 +1,37 @@
+# Dataset Summary
+
+## Purpose
+This dataset provides an LLM-oriented knowledge layer for OpenKore architecture, runtime flow, debugging, and practical usage.
+
+## Coverage areas
+- **Architecture core**: context, subsystem boundaries, dependency map, code index.
+- **Runtime flows**: AI loop, packet receive flow, NPC interaction, routing/movement, command and plugin hook flows.
+- **Networking**: packet pipeline and XKore mode behavior.
+- **Debugging**: playbook, decision trees, and common pitfalls.
+- **Practical usage**: code recipes, FAQ, glossary, learning path, and user prompt examples.
+
+## Main artifact groups
+1. **Foundational architecture docs** (`01`-`05`, `20`)
+2. **Flow/diagram docs** (`06`-`10`, `26`, `27`)
+3. **Troubleshooting docs** (`15`, `16`, `22`)
+4. **Developer enablement docs** (`17`, `18`, `19`, `24`, `29`)
+
+## Intended users
+- Developers onboarding to OpenKore internals.
+- Maintainers debugging runtime and packet issues.
+- LLM assistants that need stable structural context for responses.
+
+## Strengths
+- Grounded in likely module and directory references from the repository.
+- Organized by numbered, task-oriented documents.
+- Includes actionable diagnostics and reusable snippet patterns.
+
+## Known limits
+- Documentation is descriptive and may lag upstream implementation changes.
+- Server-specific packet behavior can change rapidly after game updates.
+- Mermaid diagrams prioritize clarity over exhaustive edge-case detail.
+
+## Maintenance recommendations
+- Re-validate packet/XKore docs after serverType or recvpackets updates.
+- Update recipe snippets when plugin/hook APIs evolve.
+- Keep FAQ and pitfalls synced with recurring issue reports.