# Knowledge Index — Embedded Agent Bridge

> Progressive disclosure routing table. Agents read this first, then load ONLY what they need.
> Never load everything — load what the current task requires.

---

## Core Docs (load for any task)

| Doc | What it contains | Load when |
|-----|-----------------|-----------|
| `docs/SYSTEM.md` | What's live vs dormant, deploy targets, tech stack, DO NOT FIX list | Any task — read first |
| `docs/SEVERITY.md` | P0-P3 rubric, hardware safety, dormant code cap rule | Triaging issues, writing bug reports |
| `CLAUDE.md` | eabctl command reference, critical rules, hardware support matrix | Any EAB work |

---

## Architecture & Design

| Doc | What it contains | Load when |
|-----|-----------------|-----------|
| `AGENT_GUIDE.md` | Full eabctl command reference, workflows, event stream, data streaming | Agent integration, CLI usage |
| `DEBUGGING.md` | Memory inspection, fault analysis, variable reading, profiling, RTT | Debugging embedded targets |
| `PROTOCOL.md` | Binary framing protocol spec for high-throughput firmware | Custom firmware, binary framing |
| `docs/FEATURE_ROADMAP.md` | Planned features and roadmap | Planning sessions |
| `.agent/handoff.md` | Key knowledge, gotchas, handoff notes | Starting work on EAB |

---

## Hardware-Specific

| Doc | What it contains | Load when |
|-----|-----------------|-----------|
| `docs/usb-port-mapping.md` | USB port mapping, re-enumeration behavior | Flashing, port issues |
| `docs/macos-flash-troubleshooting.md` | macOS-specific flash issues (ST-Link V3, etc.) | Flash failures on macOS |
| `docs/stm32n6-sram-boot.md` | STM32N6 SRAM boot procedure via GDB | STM32N6 work |
| `docs/stm32n6-flash-debug.md` | STM32N6 external flash loader debugging | STM32N6 flash issues |
| `docs/mcxn947-macos-setup.md` | NXP MCX N947 setup on macOS | MCX N947 work |
| `docs/ble-guide.md` | BLE integration guide | BLE-related work |
| `docs/rtt-signature-mismatch.md` | RTT control block debugging case study | RTT issues |

---

## Testing & Debug

| Doc | What it contains | Load when |
|-----|-----------------|-----------|
| `docs/regression.md` | YAML-driven hardware-in-the-loop regression tests | Writing or running HW tests |
| `docs/probe-rs-rtt-status.md` | probe-rs RTT transport status | probe-rs RTT debugging |
| `docs/probe-rs-test-results.md` | probe-rs transport test results | probe-rs validation |
| `docs/gdb_script_generators.md` | GDB script generation patterns | GDB automation |
| `docs/mcp-setup.md` | MCP tool server setup | MCP integration |

---

## Benchmarks & Results

| Doc | What it contains | Load when |
|-----|-----------------|-----------|
| `docs/ml-bench-results.md` | ML benchmark results | Performance analysis |
| `docs/ml-benchmark-comparison.md` | ML benchmark comparisons across devices | Cross-device analysis |
| `docs/npu-benchmark-results.md` | NPU benchmark results | NPU performance work |

---

## Source Code

| Path | What it contains | Load when |
|------|-----------------|-----------|
| `eab/` | Python package (daemon, CLI, MCP, RTT, fault analysis) | Python changes |
| `eab-probe-rs/` | Rust native extension (probe-rs PyO3 binding) | Rust/probe-rs changes |
| `scripts/` | Test scripts, device detection, validation | CI/test changes |
| `tests/` | CLI integration tests | Test changes |
| `eab/tests/` | Unit tests | Test changes |
| `examples/` | Example firmware and test projects | Example/demo work |

---

## How to Use This Index

1. Read `docs/SYSTEM.md` — understand what's live vs dormant before touching any code
2. Check `.agent/handoff.md` — known gotchas and key knowledge
3. Load only the domain docs relevant to your task
4. After completing work: update relevant docs and add new discoveries

**Never load everything at once.** Context is finite — load only what the task needs.
