chore: cleanup AI instructions

Author: Nerivec

.github/copilot-instructions.md

@@ -16,21 +16,25 @@ This project uses the following exact technology versions:
 
 ### Core Technologies
 
-- **Node.js**: `^20.19.0 || >=22.12.0` (prefer 22.12.0+)
-- **TypeScript**: `^5.9.2`
+- **Node.js** (prefer v24)
+- **TypeScript**
   - Target: esnext
   - Module: NodeNext
   - Module Resolution: NodeNext
   - Strict mode enabled
-- **Package Manager**: npm (10.8.2+)
+- **Package Manager**: npm
+
+Refer to [../package.json](../package.json) for versions.
 
 ### Development Dependencies
 
-- **@biomejs/biome**: `^2.2.4` (linting and formatting)
-- **@types/node**: `^24.5.2`
-- **vitest**: `^3.0.8` (testing framework)
-- **@vitest/coverage-v8**: `^3.2.4` (coverage provider)
-- **serialport**: `^13.0.0` (dev dependency only)
+- **@biomejs/biome**: linting and formatting
+- **vitest**: testing framework
+- **@vitest/coverage-v8**: coverage provider
+- **serialport**: dev dependency only
+- **@types/node**: typing
+
+Refer to [../package.json](../package.json) for versions.
 
 ### Critical Version Constraints
 
@@ -42,58 +46,7 @@ This project uses the following exact technology versions:
 
 ### Layered Architecture
 
-This project follows a strict layered architecture:
-
-```
-┌─────────────────────────────────────────────────┐
-│         Drivers (src/drivers/)                   │
-│  - OTRCPDriver (main adapter)                   │
-│  - OTRCPParser (frame parsing)                  │
-│  - OTRCPWriter (frame writing)                  │
-│  - Descriptors (device descriptors)             │
-└─────────────────────────────────────────────────┘
-                      ↓
-┌─────────────────────────────────────────────────┐
-│      Zigbee Stack Handlers (src/zigbee-stack/)  │
-│  - MACHandler (MAC layer operations)            │
-│  - NWKHandler (Network layer operations)        │
-│  - NWKGPHandler (Green Power operations)        │
-│  - APSHandler (Application Support layer)       │
-│  - StackContext (shared state)                  │
-└─────────────────────────────────────────────────┘
-                      ↓
-┌─────────────────────────────────────────────────┐
-│   Zigbee Protocol Utilities (src/zigbee/)       │
-│  - MAC (IEEE 802.15.4)                          │
-│  - NWK (Network Layer)                          │
-│  - NWK GP (Green Power)                         │
-│  - APS (Application Support)                    │
-│  - Core utilities (zigbee.ts)                   │
-└─────────────────────────────────────────────────┘
-                      ↓
-┌─────────────────────────────────────────────────┐
-│        Spinel Protocol (src/spinel/)             │
-│  - Core protocol (spinel.ts)                    │
-│  - HDLC framing (hdlc.ts)                       │
-│  - Properties (properties.ts)                   │
-│  - Commands, Statuses                           │
-└─────────────────────────────────────────────────┘
-                      ↓
-┌─────────────────────────────────────────────────┐
-│          Utilities (src/utils/)                  │
-│  - Logger (logger.ts)                           │
-└─────────────────────────────────────────────────┘
-```
-
-### Directory Structure Rules
-
-- **src/drivers/**: RCP communication and main adapter logic
-- **src/zigbee-stack/**: Zigbee stack handlers (MAC, NWK, APS, GP, context)
-- **src/spinel/**: Spinel protocol implementation (OpenThread RCP)
-- **src/zigbee/**: Zigbee protocol utilities (frame encoding/decoding)
-- **src/utils/**: Shared utilities (minimal)
-- **src/dev/**: Development tools (excluded from production builds)
-- **test/**: Test files matching source structure
+This project follows a strict layered architecture. Refer to [../docs/architecture.md](../docs/architecture.md)
 
 ### Build Configurations
 
@@ -766,6 +719,13 @@ const enum SaveConsts {
 }
 ```
 
+### Routing Feedback Loop (keep MAC/NWK changes in sync)
+
+- `MACHandler.sendFrameDirect()` **must** clear `StackContext.macNoACKs` and call `NWKHandler.markRouteSuccess()` when a unicast ACK succeeds, and increment `macNoACKs` plus call `markRouteFailure()` when a NO_ACK error occurs.
+- `StackContext.sourceRouteTable` stores **multiple** `SourceRouteTableEntry` objects per destination; `NWKHandler.findBestSourceRoute()` re-sorts them on every lookup using: path cost + staleness penalty + failure penalty − recency bonus, and filters out relays whose `macNoACKs` entry exceeds `CONFIG_NWK_CONCENTRATOR_DELIVERY_FAILURE_THRESHOLD`.
+- Whenever all routes are purged (expired/blacklisted) the NWK handler must immediately trigger `sendPeriodicManyToOneRouteRequest()` so the coordinator refreshes routes.
+- Link-status frames reuse the computed path costs so any tweak to the heuristic must stay consistent across `sendPeriodicZigbeeNWKLinkStatus()` and the source-route scorer.
+
 ### Wireshark Compatibility
 
 ```typescript

AGENTS.md

@@ -7,49 +7,21 @@ Zigbee on Host is an open-source Zigbee stack designed to run on a host and comm
 **Architecture:**
 - **Host-based Zigbee stack** with RCP communication
 - **Language:** TypeScript (~7,000 lines of source code)
-- **Runtime:** Node.js ^20.19.0 || >=22.12.0
+- **Runtime:** Node.js
 - **License:** GPL-3.0-or-later
 - **Module system:** NodeNext (ES modules)
 - **Zero production dependencies** - lightweight core
-- **Protocol Layers:**
-  - **Spinel Protocol (`src/spinel/`):**
-    - `spinel.ts` - Core protocol (~400 lines)
-    - `hdlc.ts` - HDLC framing
-    - `properties.ts` - Spinel properties (2,800 lines)
-    - `commands.ts` - Spinel commands
-    - `statuses.ts` - Status codes
- - **Zigbee Protocol Utilities (`src/zigbee/`):**
-    - `mac.ts` - IEEE 802.15.4 MAC layer utilities
-    - `zigbee-nwk.ts` - Network layer utilities
-    - `zigbee-aps.ts` - Application Support layer utilities
-    - `zigbee-nwkgp.ts` - Green Power utilities
-    - `zigbee.ts` - Main Zigbee utilities
-  - **Zigbee Stack Handlers (`src/zigbee-stack/`):**
-    - `stack-context.ts` - Shared state and context
-    - `mac-handler.ts` - MAC layer handler
-    - `nwk-handler.ts` - Network layer handler
-    - `nwk-gp-handler.ts` - Green Power handler
-    - `aps-handler.ts` - Application Support layer handler
-  - **Driver (`src/drivers/`):**
-    - `ot-rcp-driver.ts` - Main RCP driver (4,700 lines)
-    - `ot-rcp-parser.ts` - Frame parsing
-    - `ot-rcp-writer.ts` - Frame writing
-    - `descriptors.ts` - Device descriptors
-    - `wip.ts` - Work in progress features** with RCP communication
-
-**Key Components:**
-- `src/drivers/` - RCP communication drivers (main: `ot-rcp-driver.ts`)
-- `src/zigbee-stack/` - Zigbee protocol stack handlers (MAC, NWK, APS, Green Power, context)
-- `src/spinel/` - Spinel protocol implementation (HDLC framing, properties)
-- `src/zigbee/` - Zigbee protocol utilities (frame encoding/decoding)
-- `src/dev/` - Development tools (excluded from production builds)
-- `src/utils/` - Shared utilities (logging framework)
+- **Protocol Layers:** Refer to [./docs/architecture.md](./docs/architecture.md)
+
+Refer to [./package.json](./package.json) for versions.
 
 ## Setup Commands
 
 **Prerequisites:**
-- Node.js version >=22.12.0 (also supports ^20.19.0)
-- npm 10.8.2+
+- Node.js (prefer v24)
+- npm
+
+Refer to [./package.json](./package.json) for versions.
 
 **Initial setup:**
 ```bash
@@ -126,10 +98,8 @@ npm run test:cov        # Run tests with coverage report (~2.5s)
 ```
 
 **Coverage requirements:**
-- Statements: 85%+
-- Functions: 85%+
-- Branches: 80%+
-- Lines: 85%+
+
+Refer to [./test/vitest.config.mts](./test/vitest.config.mts)
 
 **Coverage details:**
 - Provider: v8
@@ -372,6 +342,7 @@ docker compose -f docker-dev/compose.yaml down
 - ✅ Nested device support
 - ✅ Indirect transmission mechanism
 - ✅ Source routing
+- ✅ Host-guided routing heuristics (multi-path scoring + MAC NO_ACK integration + automatic MTORR refresh)
 - ✅ Coordinator LQI/Routing tables
 - ✅ LQI reporting
 - ✅ Install code validation and Trust Center enforcement for initial joins
@@ -467,7 +438,7 @@ docker compose -f docker-dev/compose.yaml down
 
 - **Repository:** https://github.com/Nerivec/zigbee-on-host
 - **npm package:** zigbee-on-host
-- **Version:** 0.2.0 (work in progress, expect breaking changes)
+- **Version:** 0.2.3 (work in progress, expect breaking changes)
 - **Author:** Nerivec
 
 ### Key Files

docs/architecture.md

@@ -1,7 +1,7 @@
 # Zigbee on Host - Architecture Documentation
 
-**Document Version:** 1.1
-**Last Updated:** November 2, 2025
+**Document Version:** 1.2
+**Last Updated:** November 27, 2025
 **Maintainer:** Nerivec
 **License:** GPL-3.0-or-later
 
@@ -25,6 +25,7 @@ Zigbee on Host is a host-based Zigbee stack implementation that communicates wit
 3. **Single Source of Truth** - StackContext owns all shared state
 4. **Zero Production Dependencies** - Only Node.js built-in modules
 5. **TypeScript Zero-Cost Abstractions** - Interfaces, const enums, type aliases
+6. **Host-Guided Routing Heuristics** - Routing decisions leverage host-only scoring (LQA, staleness, MAC feedback) to keep concentrator behavior deterministic
 
 ### Technology Stack
 
@@ -199,6 +200,7 @@ export async function processFrame(
 - Handle data requests
 - Maintain indirect transmission queue
 - Process MAC commands
+- Update per-destination NO_ACK counters (`StackContext.macNoACKs`) to feed NWK routing heuristics
 
 **Key Methods:**
 ```typescript
@@ -240,6 +242,9 @@ interface MACHandlerCallbacks {
 - Implement many-to-one routing
 - Process route record frames
 - Handle all NWK commands
+- Score candidate routes with host-only heuristics (path cost, staleness penalty, MAC NO_ACK counters, recency bonus)
+
+The handler now keeps multiple source-route entries per destination and ranks them every time `findBestSourceRoute` runs. Expired or blacklisted paths are purged eagerly, remaining entries are sorted by a composite score (path cost + penalties + recency bonus), and any relay that has accumulated too many MAC NO_ACK events is skipped entirely. When no usable path is left the handler immediately triggers a concentrator (many-to-one) refresh so the coordinator can rebuild routing knowledge.
 
 **Key Methods:**
 ```typescript
@@ -345,11 +350,13 @@ interface APSHandlerCallbacks {
 - Device table (device entries with capabilities, LQA tracking, authorization)
 - Address mappings (16-bit ↔ 64-bit)
 - Routing tables (source routes)
+- Source route table entries with timestamps + failure counts (multiple per destination allowed)
 - Application link key table (pair-wise TC/app link keys)
 - Install code metadata and derived link keys
 - Key frame counters
 - Pending network key staging (pre-SWITCH_KEY activate)
 - End-device timeout metadata and runtime NWK frame counters
+- MAC NO_ACK counters (per-destination delivery health used by NWK heuristics)
 - Trust center policies (join policies, key policies)
 - Coordinator configuration attributes
 - Pending associations (awaiting DATA_RQ from device)
@@ -486,7 +493,9 @@ Application API Call
     │
 [MACHandler.sendFrameDirect()]
     ├─ Build Spinel STREAM_RAW property (MAC frame)
-    └─ Call callbacks.onSendFrame()
+    ├─ Call callbacks.onSendFrame()
+    ├─ ACK success → clear `macNoACKs` entry + `NWKHandler.markRouteSuccess()`
+    └─ NO_ACK error → increment `macNoACKs` + `NWKHandler.markRouteFailure()`
         ↓
 [OTRCPDriver.setProperty()]
     ├─ Encode as Spinel frame
@@ -499,6 +508,17 @@ Application API Call
 Serial Port → RCP Firmware → Radio Transmission
 ```
 
+### Routing Feedback Loop (Extra Pass Focus)
+
+Recent refactors introduced a closed-loop routing controller that keeps concentrator behavior stable even when radio quality fluctuates:
+
+1. **MAC delivery feedback** – Every unicast tracks whether the RCP reported an ACK. Success clears the destination entry in `StackContext.macNoACKs`, while a NO_ACK increments it and immediately calls `NWKHandler.markRouteFailure()`.
+2. **Source-route scoring** – `NWKHandler.findBestSourceRoute()` re-sorts all candidate paths on every lookup. The score combines hop count, staleness penalty, failure penalty, a recency bonus, and a hard filter that rejects any relay currently above the NO_ACK threshold.
+3. **Automatic recovery** – When the handler purges all routes (expired, blacklisted, or unhealthy relays), it schedules a many-to-one route discovery so the coordinator re-advertises itself and rebuilds source routes.
+4. **Link status integration** – Periodic link-status frames piggyback the same computed path costs so neighbors receive up-to-date metrics derived from LQA + routing penalties.
+
+Together these steps ensure routing decisions remain deterministic and reflect the host's richer telemetry without waiting for devices to age routes out on their own.
+
 ## State Management
 
 ### State Persistence