Feat/v5

.github/FUNDING.yml

@@ -0,0 +1,15 @@
+# These are supported funding model platforms
+
+github: [mcodex]
+patreon: # Replace with a single Patreon username
+open_collective: # Replace with a single Open Collective username
+ko_fi: # Replace with a single Ko-fi username
+tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
+community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
+liberapay: # Replace with a single Liberapay username
+issuehunt: # Replace with a single IssueHunt username
+lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
+polar: # Replace with a single Polar username
+buy_me_a_coffee: # Replace with a single Buy Me a Coffee username
+thanks_dev: # Replace with a single thanks.dev username
+custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']

.gitignore

@@ -1,3 +1,5 @@
 *configs
 storage/
-private/
+private/
+.tokensave
+node_modules/

.luacheckrc

@@ -5,7 +5,8 @@ max_line_length = 120
 read_globals = {
   -- OTClient core
   "g_game", "g_map", "g_ui", "g_things", "g_clock", "g_resources", "g_platform", "g_http", "HTTP",
-  "modules", "macro", "schedule", "dofile", "periodic",
+  "modules", "macro", "schedule", "dofile", "periodic", "g_items",
+  "now", "autoWalk",
 
   -- Player accessors
   "pos", "target", "player", "mana", "hppercent", "manapercent",
@@ -23,6 +24,7 @@ read_globals = {
   -- Native callback registration (all optional, may not exist)
   "onCreatureAppear", "onCreatureDisappear", "onCreatureHealthPercentChange",
   "onPlayerPositionChange", "onManaChange", "onHealthChange",
+  "onPlayerZChange", "onPlayerWalkError",
   "onContainerOpen", "onContainerClose", "onContainerUpdateItem",
   "onAttackingCreatureChange", "onTextMessage", "onTalk",
   "onAddThing", "onRemoveThing", "onWalk", "onTurn", "onMissle",
@@ -51,6 +53,8 @@ globals = {
   "ZChangeGuard", "KillTracker",
   "AttackData", "AttackAnalytics", "AttackConfig", "CombatExecutor",
   "HealConfig", "SpellResolver", "HealAnalytics",
+  "Supplies", "BotDB", "AttackFSM", "MovementCoordinator",
+  "IntelligenceBotDoctor", "IntelligenceUiPresenter",
   "storage", "info", "warn",
 }
 

.superpowers/sdd/route-safety-report.md

@@ -0,0 +1,70 @@
+# Route Safety Report
+
+## Scope
+
+Implemented the wall-traversal route-safety slice only. Unrelated UI, combat,
+and existing user worktree changes were not modified.
+
+## Findings Fixed
+
+- `StepValidator.canMergeDiagonal` checked only the traversed cardinal tile and
+  diagonal destination. It now checks both orthogonal corner tiles.
+- `PathStrategy.findPath` accepted malformed or wall-crossing native direction
+  arrays. Every returned direction is now structurally and geometrically
+  validated, including diagonal corners and destination walkability.
+- `PathStrategy.nativePathIsSafe` stopped checking after an invalid direction
+  and could dereference missing tile helpers. It now fails closed.
+- CaveBot's field loop called raw `walk(d)`. It now validates each exact step
+  and dispatches through `PathStrategy.walkStep`.
+- CaveBot used keyboard nudge and relaxed searches after strict path failure.
+  Those unsafe fallback paths were removed; strict failure returns `false`.
+- The OTBR adapter dropped `maxSteps` and shifted the options argument. Its
+  `autoWalk(destination, maxSteps, options)` forwarding now matches callers.
+
+## TDD Evidence
+
+Failing focused run before implementation:
+
+```text
+15 successes / 5 failures / 0 errors / 0 pending
+```
+
+Failures covered diagonal corner rejection, native path validation, raw field
+walking, and OTBR argument forwarding.
+
+Passing focused run after implementation:
+
+```text
+38 successes / 0 failures / 0 errors / 0 pending
+```
+
+Command:
+
+```text
+busted tests/unit/navigation/step_validator_spec.lua \
+  tests/unit/navigation/route_safety_spec.lua \
+  tests/unit/navigation/path_planner_spec.lua \
+  tests/unit/navigation/obstacles_spec.lua
+```
+
+`git diff --check` passed.
+
+## Verification Limitation
+
+The focused `luacheck` command could not start because the installed Luacheck
+1.2.0 loader is incompatible with the installed Lua 5.5 runtime:
+
+```text
+luacheck/standards.lua:134: attempt to assign to const variable 'field_name'
+```
+
+No code lint result is claimed from that command.
+
+## Changed Files
+
+- `cavebot/walking.lua`
+- `utils/path_strategy.lua`
+- `core/acl/adapters/opentibiabr.lua`
+- `navigation/step_validator.lua`
+- `tests/unit/navigation/step_validator_spec.lua`
+- `tests/unit/navigation/route_safety_spec.lua`

.superpowers/sdd/task-5-report.md

@@ -0,0 +1,58 @@
+# Task 5 Report
+
+## Result
+
+Implemented attack synchronization and lifecycle recovery without changing UI,
+navigation, CaveBot, or the legacy `AttackStateMachine`.
+
+## Root cause
+
+`AttackFSM` treated `pcall` success as a successful native attack, so a native
+`attack()` returning `false` was accepted. Same-target requests also returned
+success without dispatch, and `LOCKED` refreshed confirmation from the stale
+red-square selection on every tick. Disappearance had no authoritative FSM
+path and could be counted as a kill by the active attack flow.
+
+## Changes
+
+- `targetbot/application/attack_fsm.lua`
+  - Separates selected target, command dispatch, client confirmation, and health progress evidence.
+  - Rejects explicit false native attack returns.
+  - Re-dispatches same targets after connection-generation invalidation.
+  - Adds `isProgressing()` and `onConnectionGeneration()`.
+  - Adds bounded `STALLED` recovery at 200 ms, 1 s, and 3 s, then releases.
+  - Adds disappearance and health-progress event entry points.
+  - Keeps disappearance from incrementing kill statistics.
+- `targetbot/target_events.lua`
+  - Routes target disappearance and health progress to the authoritative FSM.
+- `targetbot/target_coordinator.lua`
+  - Wires game/login/logout and recovery-pause generations to FSM invalidation.
+- `tests/unit/domain/attack_fsm_spec.lua`
+  - Adds regression coverage for false returns, reconnect recovery, stale selection, progress evidence, bounded retries, and disappearance.
+
+## TDD evidence
+
+Initial focused run before implementation:
+
+```text
+23 successes / 2 failures / 2 errors
+```
+
+The failures were the expected missing behaviors: false attack accepted,
+missing `onConnectionGeneration`, missing `isProgressing`, and stale state
+transitions.
+
+Final focused run:
+
+```text
+busted tests/unit/domain/attack_fsm_spec.lua tests/integration/combat_pipeline_spec.lua tests/integration/target_abandonment_spec.lua
+29 successes / 0 failures / 0 errors / 0 pending
+```
+
+## Self-review
+
+- No files outside the requested target files, listed tests, and report were staged.
+- `core/client_lifecycle.lua` was unchanged because its existing generation callback contract was sufficient.
+- Native confirmation is no longer refreshed merely because the red square remains selected.
+- Recovery is timer-bounded and does not retry on every tick.
+- Unrelated pre-existing UI, navigation, and CaveBot changes remain untouched.

README.md

@@ -1,6 +1,6 @@
 # nExBot
 
-![Version](https://img.shields.io/badge/version-4.0.0-blue)
+![Version](https://img.shields.io/badge/version-5.1.0-blue)
 ![License](https://img.shields.io/badge/license-MIT-green)
 ![Lua](https://img.shields.io/badge/Lua-5.1-purple)
 
@@ -16,19 +16,67 @@ Install paths:
 - **vBot:** `%APPDATA%/OTClientV8/<ServerName>/bot/nExBot`
 - **OTCR:** `~/.local/share/<otcr-data>/<ServerName>/bot/nExBot`
 
+## v5.1.0 — Tactical Intelligence, Profile Reconnect & Character-Bound State Remediation
+
+This release delivers a comprehensive remediation of state management, persistence, and tactical intelligence:
+
+- **Atomic profile switching** — CaveBot/TargetBot profile changes preserve desired ON/OFF state, commit in single transaction
+- **Character-bound state** — Per-character, per-root-profile UnifiedStorage files (schema v6), full isolation
+- **Tactical Intelligence crash safety** — `next = nil` sandbox handled, section isolation, incremental projections
+- **Analytics contract separation** — `TelemetryClient` (outbound), `HuntMetrics` (local), `ClientTelemetry` (OTClient signals)
+- **Desired vs Effective state** — Explicit inhibitors, runtime state never overwrites user preference
+- **Explicit origins** — Every mutation carries `USER`/`INITIAL_RESTORE`/`RECONNECT_RESTORE`/etc.
+- **Silent restoration** — UI restores without triggering persistence callbacks
+- **Control registry** — All toggles declaratively registered with explicit scopes
+- **Lifecycle adapter** — `onGameStart`/`onGameEnd` drive state coordinator, generation guards on all async work
+- **Performance** — ≥70% Tactical CPU reduction target, no-change projection p95 <2ms
+
+## v5 UI Platform
+
+nExBot v5 introduces a unified product interface built on one design system,
+one navigation shell, and one shared component library.
+
+- **BotShell** — replaces the client's left bot bar with a compact cockpit
+  containing engine controls, telemetry, attention state, and a footer.
+  Single instance, generation-guarded lifecycle, auto-attaches to the host
+  left panel at startup.
+- **ModuleRegistry** — secondary-page navigation and ordering.
+- **Design system** — semantic color/spacing/typography/density/status tokens
+  (`ui/design_system/`), frozen against mutation.
+- **Icons** — native Tibia item sprites through `UIItem`; no asset toolchain.
+- **Components** — shared widget library (`ui/components/`).
+- **View models** — embedded workflows expose versioned projections
+  (`schemaVersion, revision, state, header, sections, actions`); widgets never
+  mutate domain globals directly.
+
+The shell replaces the legacy tab-fill left bar.
+
 ## Modules
 
 | Module | Function |
 |--------|----------|
 | **HealBot** | Spell/potion healing at configurable HP thresholds. 75ms response. |
 | **AttackBot** | Attack spell/rune rotation with AoE optimization |
 | **CaveBot** | Waypoint navigation, floor-change safety, supply refills, 50+ pre-built routes |
-| **TargetBot** | 9-stage priority targeting, Monster Insights AI, movement coordination |
-| **Hunt Analyzer** | Session analytics — kills/hr, XP/hr, profit, Hunt Score |
-| **Containers** | Event-driven BFS, O(1) operations, generation tracking, quiver management 🎒 |
+| **TargetBot** | 9-stage priority targeting, Tactical Intelligence integration, movement coordination |
+| **Tactical Intelligence** | Unified session analytics, monster intelligence, targeting history, resources, routes |
+| **Containers** | Event-driven BFS, O(1) operations, generation tracking, reconnect recovery coordinator, multi-level readiness, quiver management 🎒 |
 | **Follow Player** | Party hunt — stays near leader while attacking |
 | **Extras** | Anti-RS, alarms, equipment swap, combo system, push max |
 
+## Adaptive Intelligence
+
+nExBot shares combat and navigation context through one bounded intelligence runtime:
+
+- TargetBot evaluates candidates through deterministic proposal arbitration and a hard safety envelope.
+- Dynamic Lure, Pull, and wave avoidance use explicit state machines.
+- CaveBot preserves route intent across combat pauses, path failures, and recovery.
+- Twelve local models learn in `SHADOW` mode without changing actions.
+- Replay, calibration, resource tracking, learned navigation costs, and Bot Doctor diagnostics use bounded storage.
+- Adaptive tick rates reduce background work while combat and safety paths keep their priority.
+
+Open **More → Analytics → AI Intelligence** to inspect lifecycle, targeting, routes, models, replay, resources, and diagnostics.
+
 ## Architecture
 
 ```
@@ -37,17 +85,23 @@ Install paths:
 ├── EventBus (event-driven communication)
 ├── UnifiedTick (single 50ms master timer)
 ├── UnifiedStorage (per-character JSON persistence)
+├── Adaptive Intelligence
+│   ├── immutable world snapshot + feature pipeline
+│   ├── proposal arbitration + hard safety envelope
+│   ├── bounded SHADOW models, replay, calibration, and diagnostics
+│   └── adaptive tick and optional-work budgets
 │
 ├── Containers 🎒
-│   ├── identity (physical container identity)
+│   ├── identity (physical container identity — generation+path+slot+type)
 │   ├── queue (head/tail FIFO, O(1) dequeue)
-│   ├── state_machine (13 states, generation tracking)
-│   ├── registry (O(1) lookups, incremental item index)
-│   ├── bfs (event-driven traversal)
-│   ├── scheduler (UnifiedTick integration)
-│   ├── readiness (derived snapshots)
-│   ├── quiver (paladin ownership)
-│   └── discovery (orchestrator)
+│   ├── state_machine (23 states, generation tracking, transition log)
+│   ├── registry (O(1) lookups, slot-level item index, role assignments)
+│   ├── bfs (event-driven traversal, retry counting, deduplication)
+│   ├── scheduler (priority queue, ack timeout, exhaustion backoff)
+│   ├── readiness (10-level derived snapshots)
+│   ├── client_adapter (OTClient/vBot abstraction)
+│   ├── quiver (paladin ownership, fixed slot detection)
+│   └── discovery (orchestrator + reconnect recovery coordinator)
 │
 ├── HealBot ←── player:health events
 │   └── spell_resolver (conversion functions)
@@ -57,33 +111,13 @@ Install paths:
 ├── CaveBot ←─── 250ms waypoint engine
 ├── TargetBot ←─ creature events + Monster AI
 │   ├── AttackStateMachine (sole attack issuer)
-│   ├── Monster Insights (12 AI modules)
-│   └── MovementCoordinator (intent voting)
-│
-└── Hunt Analyzer ←─ passive analytics
+│   └── Tactical Intelligence ←─ unified analytics + learning
 ```
 
-## Documentation
-
-| Guide | Description |
-|-------|-------------|
-| [Installing](docs/INSTALLING.md) | Installation for vBot and OTCR |
-| [HealBot](docs/HEALBOT.md) | Healing spells, potions, conditions |
-| [AttackBot](docs/ATTACKBOT.md) | Attack spells, runes, AoE optimization |
-| [CaveBot](docs/CAVEBOT.md) | Navigation, waypoints, supply management |
-| [TargetBot](docs/TARGETBOT.md) | Combat AI, Monster Insights, movement |
-| [Follow Player](docs/FOLLOW.md) | Party hunt companion |
-| [Containers](docs/CONTAINERS.md) | Container management, quiver system |
-| [Hunt Analyzer](docs/SMARTHUNT.md) | Session analytics |
-| [Extras](docs/EXTRAS.md) | Safety, equipment, utilities |
-| [Architecture](docs/ARCHITECTURE.md) | Technical design |
-| [Performance](docs/PERFORMANCE.md) | Optimization and tuning |
-| [FAQ](docs/FAQ.md) | Troubleshooting |
-
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md). Run `make check` before submitting. Follow existing Lua style (2-space indentation).
 
 ## License
 
-[MIT License](LICENSE)
+MIT License.