# System Reality — Embedded Agent Bridge

> Canonical source of truth. This file wins all ties. What's written here reflects what actually exists in the codebase, not what was planned.

**Last updated:** 2026-06-04

---

## Status

| Component | Status | Notes |
|-----------|--------|-------|
| eabctl CLI | Live | Primary interface — daemon control, flash, tail, fault-analyze, profiling, trace |
| EAB daemon (eab) | Live | Background serial/RTT daemon, manages device connections |
| eab-probe-rs (Rust) | Live | Native Rust extension for probe-rs RTT (PyO3 binding) |
| MCP tool server (eabmcp) | Live | MCP server exposing eabctl commands to LLM agents |
| Regression test runner | Live | YAML-driven hardware-in-the-loop tests via `eabctl regression` |
| DWT profiling | Live | J-Link DWT-based function/region performance measurement |
| Trace capture (Perfetto) | Live | RTT/serial/logfile capture to .rttbin, export to Perfetto JSON |
| C2000 support | Live | TI C2000 F28003x/F28004x via XDS110, CCS DSS transport |
| STM32N6 SRAM boot | Live | GDB-based SRAM boot procedure for STM32N6 |
| esptool wrapper | Live | System protection — intercepts direct esptool calls |
| Binary framing protocol | Dormant | PROTOCOL.md spec exists, optional for custom firmware |
| BLE integration | Planned | Docs at docs/ble-guide.md, no implementation |

**Stages:** Live = deployed + used. Dormant = code exists, not deployed or not in use. Planned = ticket exists, no code yet.

---

## Deploy Targets

| Environment | URL | Deploy trigger |
|------------|-----|----------------|
| PyPI package | `pip install embedded-agent-bridge` | Manual release |
| Local dev | `pip install -e ".[dev]"` | Developer setup |
| Mac Studio | `ssh studio` | Manual deploy |

---

## Tech Stack

| Layer | Technology | Version |
|-------|-----------|---------|
| Core language | Python | 3.9+ |
| Native extension | Rust (PyO3) | Edition 2021 |
| Debug probes | probe-rs, J-Link, OpenOCD, CMSIS-DAP | Various |
| Serial | pyserial | >=3.5 |
| Testing | pytest | >=9 |
| Linting | ruff | Latest |
| Build | setuptools | >=61.0 |
| MCP | mcp (Python) | >=1.0 |

---

## DO NOT FIX List

| Item | Reason | Owner |
|------|--------|-------|
| probe-rs RTT no background daemon | Architectural limitation — use J-Link transport for background logging | Known |
| eab/cli/serial/ shadows pyserial | Fixed via PYTHONPATH in daemon (commit 56565c9). Do not restructure. | Known |
| MCX N947 requires NXP LinkServer | probe-rs can't flash secure 0x10000000 region. Use LinkServer. | Hardware limitation |

---

## Active Constraints

- Rust extension (eab-probe-rs) depends on local probe-rs-debug build at `../../probe-rs-debug/probe-rs`
- eabctl flash for STM32 .elf requires objcopy — use .bin instead
- Zephyr SDK uses `arm-zephyr-eabi-*` not `arm-none-eabi-*`
- ST-Link V3 invisible on macOS — see docs/macos-flash-troubleshooting.md

---

## Generated Files (do not hand-edit)

| File | Generated by | When |
|------|-------------|------|
| `/tmp/eab-devices/<device>/status.json` | EAB daemon | Runtime |
| `/tmp/eab-devices/<device>/events.jsonl` | EAB daemon | Runtime |
| `/tmp/eab-devices/<device>/latest.log` | EAB daemon | Runtime |

---

## Current State

> Updated at the end of every session. Tracks what changed and what's next.

**Last session:** 2026-06-04

**What changed:**
- Applied PA starter kit tooling (commands, scripts, docs, verify gate)

**Next steps:**
- Populate expertise/ with recurring gotchas after 3-5 sessions
- Consider adding ruff check to lefthook pre-commit

**Blockers:**
- None
