# Changelog

All notable changes to the **Adsum IoT Coder** extension will be documented in this file.

## [0.1.8] - 2026-07-07

3-layer debug lands (app, HCI, and radio), alongside a hardening pass for the CRA Readiness Check driven by real field runs on Windows and macOS.

### 3-layer debug

Adsum now debugs across all three layers of a BLE connection: the application log, the HCI host↔controller bus, and the over-the-air radio, correlated to show where a flow actually broke. It builds on the HCI decoding shipped in 0.1.7 (parsing Host Controller Interface event streams into human-readable BLE protocol events). The guided **HCI + Sniffer sample run** promised in 0.1.7 is now the on-ramp: a walkthrough of a real one-directional BLE bug that lands on the one-line fix and bridges into the CRA readiness check. It runs on a bundled sample with no hardware needed, and the same debugging works on your own nRF boards.

### CRA runs don't dead-end anymore

- **A CRA run now rests on an open question, never a "task complete" box.** No more dead-end endings or "I'll continue later" traps, the run always offers concrete forward actions (triage this CVE, start closing this gap), and you leave simply by moving on. The old completion scorecards (with pass/fail glyphs) are blocked at the source.
- **Knowledge-loading is self-healing.** A transient network blip on a knowledge fetch now retries silently; a mistyped knowledge path auto-corrects when the catalog has exactly one match (a real run dead-ended on `cra/rules/core.md` vs `cra/core.md`, that class of failure is gone). Error messages now say precisely what failed: transient fetch vs not-in-catalog vs registry unreachable.
- **The readiness-report integrity guard is fairer and clearer.** It no longer misreads honest phrasing like "62 total packages: 10 queryable" as a wrong count (a correct report was rejected 3× for this), and every rejection now quotes the exact line it objected to, so a rewrite lands in one attempt.

### Honesty & safety hardening (from real run reviews)

- **Never weakens your project to make a scan work.** New hard rules: the agent must never disable your security features (secure boot, flash encryption, signed OTA) to force a build, must never edit your SDK/toolchain installation (a run had patched a script inside `C:\ncs\`, now banned), and if an earlier scan run left your config modified, the posture check detects it and offers a restore instead of counting those as *your* gaps.
- **ESP SBOM generation fixed for IDF 5.x.** The documented `--output-file` flag is used, and `idf.py sbom-create --spdx-file` (absent on IDF 5.5.4) is version-checked before use instead of failing.
- **Silent commands aren't "failures" anymore.** Commands that legitimately produce no output (`mkdir`, `cp`, …) no longer report a scary "technical issue", the agent is told plainly: silent success, verify state directly if it matters.

### Windows reliability

- **The terminal just works on a fresh Windows install.** New Windows machines ship PowerShell locked down (Restricted execution policy), which silently blocks VS Code's shell integration so the agent can't read command output. The extension now detects and repairs this in the background at startup, sets the execution policy to RemoteSigned (current-user scope), selects a working default terminal profile, and restarts stale terminals, with a dismissible note of what changed. Group Policy-managed machines are left untouched.

### Compact input area

- The input stack is dramatically slimmer: one-line input that grows as you type, auto-approve as a compact ⚡ chip next to **@**, and the wide Cancel/Resume buttons replaced by a Claude-style **send ↔ stop** morphing icon (brand cyan, instant tooltips). The chat input glows cyan on focus.
- The "What's new" card icon is now theme-consistent (no more OS-style emoji).

## [0.1.7] - 2026-06-24

### CRA Readiness Check: get CRA-ready as you build

A new one-click **CRA Readiness Check** helps you prepare for the EU Cyber Resilience Act, on **both nRF and ESP**. It's a readiness snapshot to help you prepare, not a conformity assessment, and not legal advice.

- **SBOM from your real build.** A machine-readable software bill of materials (SPDX), the CRA's named artifact, generated from the actual build, not a guess.
- **Secure-by-design posture.** A checklist against your build's real configuration (secure boot, signed updates, debug-port lock, secure pairing, secure storage, and more), each item evidence-grounded (the literal config fact, not a generic assertion), ordered so prerequisites come first.
- **Advisories for your SDK version.** Surfaced with links to review, never an automatic verdict.
- **Help you start.** The agent offers to begin closing the top gap (e.g. add a secure bootloader), routing into the normal add-feature flow.
- Writes a `compliance/` folder: a human-readable report, a machine-readable JSON companion, and the SBOM. Run it on your project, or try it on a bundled sample with nothing open.

It also tells you which CRA date applies to you up front, whether you're getting a head start on the Dec 2027 essential requirements, or already in scope for the Sep 2026 reporting duty.

### HCI deep-debug: three layers for BLE projects

When a BLE project is open (`CONFIG_BT=y` detected), the welcome screen now surfaces a one-line shortcut to the full debug stack:

> **app logs · HCI · radio sniffer** *(soon)*

The HCI layer is new: the extension can now parse Host Controller Interface (HCI) event streams and decode them to human-readable BLE protocol events, helping you see exactly what's happening at the controller level, not just the application log.

A guided **HCI + Sniffer sample run**, a three-layer walkthrough (app log → HCI bus → over-the-air) that lands on the one-line fix and bridges to the CRA readiness check, is coming in a follow-up release.

### nRF terminal: self-contained, version-aware

The nRF terminal now detects which NCS version your build uses and executes commands against that SDK automatically, no manual path wrangling. When you have multiple NCS installs (e.g. v3.2.1 and v3.3.1), the agent follows the build directory's version, not whichever was compiled most recently.

### ESP reliability

- **Multi-board builds.** When multiple ESP-IDF versions are installed, the extension now shows all of them, not just the first, removing the "ambiguous forever" state where a project pinned to a different version than the global install.
- **Version detection on git-clone installs.** ESP-IDF git checkouts have no `version.txt`; the extension now reads `tools/cmake/version.cmake` as a reliable fallback, so the platform strip always shows the correct IDF version regardless of install method.

### Welcome screen: adaptive, not static

- **"Try it on a sample" picker.** A new inline picker lists available demos (BLE bug, CRA readiness check, and more). Appears when no project is open; becomes a re-run link once you've tried one.
- **CRA nudge for BLE projects.** When a BLE project is open but has no `compliance/` folder yet, a dismissible note surfaces: "A connected product likely falls under the EU CRA, preview your secure-by-design posture." Evidence-grounded, never a verdict.
- **Compact platform status.** The nRF/ESP detection panel collapses to a one-line summary per detected platform (e.g. `nRF · NCS 3.2.1 · nRF5340 DK`). Click to expand for full detail.

### Diagrams that match your theme

Mermaid diagrams in chat now follow your VS Code light/dark theme and the Adsum palette, previously they used a fixed dark theme that was hard to read in light mode.

### Honesty hardening

The agent's CRA output is now verified against a 108-fixture scanner before it leaves the model. New rules added this release: the agent can no longer produce numeric readiness scores, "non-compliant" verdicts, or citations to CRA articles that don't exist. All posture items are evidence-mode only, literal config facts, with "verify" always the next step.

### Legal

- `NOTICE` file added (Apache 2.0 §4c attribution).
- `iot-knowledge/LICENSE` makes the open k-bits' license explicit.
- README updated: open-core model, AI limitations, trademark notices.

## [0.1.6] - 2026-06-16

### One extension: now for ESP32, too

Adsum IoT Coder now speaks **Espressif ESP32 / ESP-IDF** as well as Nordic nRF, in a single install. It reads what's on your desk and in your workspace and shows the right tools, workflows, and guidance for each platform, nothing to switch.

- **ESP32 / ESP-IDF support.** Build, flash, monitor, and test ESP-IDF firmware with the same guided agent workflows you already use for nRF, `idf.py`/`esptool`-driven, with chip, flash, and PSRAM detection and serial-log capture built in.
- **Automatic platform detection.** The home screen recognizes whether your workspace is nRF, ESP, both, or a fresh start, and routes every workflow card and the agent's expertise to the right platform automatically.
- **Prototyping for both platforms.** *Start a prototype* now scaffolds complete ESP-IDF projects too, it sets the target chip, lays out the project, and gets you to a first build, the same way it already does for nRF.
- **Always-current knowledge, leaner install.** Platform expertise is delivered on demand and cached locally, so the extension stays small and the guidance stays up to date without waiting for a new release.

### Reliability & cross-platform

- **Stronger Windows support.** Board and toolchain detection now handle the full range of real-world install layouts on Windows, nRF boards and NCS versions surface correctly, ESP-IDF is found wherever it's installed, and serial-log capture runs cleanly. Verified on real nRF and ESP hardware.
- **Smarter ESP toolchain selection.** When more than one ESP-IDF version is installed, the agent uses the one your project pins, and asks you when it's genuinely ambiguous instead of guessing.
- **Steadier file editing.** Edits now apply cleanly even on large, streamed changes.
- **Cleaner diagrams.** Architecture and sequence diagrams render reliably across models.

### Notes

- Existing nRF projects are unaffected, same workflows, same behavior.

## [0.1.5] - 2026-06-08

### A full UI redesign: rebuilt around how you start

Early users told us the hardest part wasn't the agent, it was the cold start. So we rebuilt the entire first-run experience: see it work *before* any setup, land on something useful immediately, and always have a clear next step.

- **See it debug a real bug, in 30 seconds, before you set anything up.** A new first-run demo debugs a real BLE bug on firmware bundled with the extension, capture → analyze → fix on a genuine failure, with no board, API key, or project of your own required. Run it on your own firmware right after.
- **Zero-config first run.** Fresh installs land directly on a working home screen, no provider-selection gate before you can try the agent. The free tier is on by default; bring your own key anytime.
- **A home screen that guides the next step.** With a project open, the agent reads what it is and offers one-click **workflow cards**, *Build, flash & debug*, *Add a feature*, *Test & validate*, with *SDK migration* and *board bring-up* on the way. With no project open, it points you to *start a prototype* or *open your nRF project*. After any task finishes, it suggests where to go next instead of leaving a blank prompt.

### Notes

- The previous two-button home (*Analyze Logs* / *Generate Logging Code*) is replaced by the demo + context-aware workflow cards above; the same capabilities are reachable through *Build, flash & debug*.

### Reliability

- **Free-tier "tokens left" counter is now accurate.** It decrements by each request's real usage and shows **0** the moment the quota is exhausted, fixing the prior behavior where the chip could plateau (e.g. "~20k left") even after the free tier ran out. Resolves the 0.1.3 known issue.
- **Token counter shows on first launch.** The free-tier balance now appears immediately on a fresh install, instead of only after switching providers and back.
- **Invite codes.** Redeem a code in the free-tier panel (or the quota-exhausted card) for extra free-tier tokens.
- **Windows: better nRF tooling detection.** `nrfutil` is now found in more install locations (`NRFUTIL_HOME` and common Windows paths), fixing a spurious "nrfutil not found".
- **"What's new" re-appears on updates.** Patch releases (e.g. 0.1.3 → 0.1.5) now show the what's-new note to existing users, not only fresh installs.

### Smarter workflows behind the cards

The one-click workflow cards now hold up across platforms and harder projects:

- **Test & validate works on Windows and macOS, not just Linux.** It picks the right path for your machine: a host simulator where one fits, or running the **same tests on your connected board** with no extra install. It's also honest about what a simulator can and can't prove (logic vs. real radio, sensor, and timing), and walks you through the one-time QEMU setup only when you actually need board-free runs.
- **Prototyping handles two-device and sensor builds.** Ask for a central ↔ peripheral system and it scaffolds **both** apps from the matching Nordic samples and flashes each to its own board; ask for an I²C sensor and it wires the devicetree overlay correctly, the parts that usually trip people up. It builds the files for you instead of pointing you at a sample to open, and sketches the architecture (and a two-device timeline) first.
- **Debug a board that's already running, no reflash.** *Build, flash & debug* can now skip straight to capturing and analyzing logs when your device is already running the firmware you want to inspect.

## [0.1.3] - 2026-06-01

### Free tier: zero-friction onboarding

- **Run the agent without an API key.** New built-in free tier backed by a managed model hosted by Adsum Networks, no key, account, or card to evaluate the tool. Acted on the most-requested item from the previous release.
- **Instant BYOK switchover.** Adding your own key swaps the provider on the live task, no restart, the in-flight session continues.
- **Quota conversion card.** When the free quota runs out, a single-click prompt routes you to add a key and resumes the same task on your provider, instead of failing with a raw error.

### Reliability

- Quota exhaustion (HTTP 402) is handled cleanly, no spurious auto-retries or "Invalid API Response" noise.
- Rate-limit (429) responses surface a readable message instead of raw JSON.
- Free-tier usage telemetry corrected: funnel-entry fires once per install (was firing on every step), and the BYOK-conversion event now fires on the code path the settings form actually uses.

### Known issues

- Free-tier "tokens left" chip can briefly show a stale value until the next prompt; balance is backend-authoritative and harmless. See README → Limitations. *(Fixed in 0.1.5, the chip now decrements live and shows 0 on exhaustion.)*

## [0.1.2] - 2026-05-31

### Fixed

- Toolbar and chat icons showed as blank squares, and the chat send button was missing on Linux. Icons now render correctly on macOS, Windows, and Linux.

### Changed

- Reduced the extension download size by ~6 MB.
- Improved Marketplace search keywords (nRF52/53/54, Zephyr, BLE, RTT, J-Link).

## [0.1.0] - 2026-05-26

The first release built around the **skill-first architecture**: domain expertise lives in versioned Markdown modules (workflows, actions, rules, board specs) that are loaded into the system prompt on demand based on what the agent detects in your workspace, not baked into a fixed prompt. Same model, smaller context, fewer wrong turns. Backed by an open hardware-in-the-loop benchmark.

### Architecture: `iot-knowledge/` skill library

- **New `iot-knowledge/` tree.** Every piece of nRF/Zephyr expertise the agent uses is now a Markdown file under `iot-knowledge/`, organized as `rules/`, `platforms/nrf/{rules,boards,sdks,workflows,actions}/`. Author once, ship as part of the extension, regenerate snapshots when changed. Adding a new SoC, protocol, or debug procedure is a Markdown PR, not a code change.
- **Workflows are entry points, Actions are subroutines.** Three primary workflows ship: `log-analyzer.md`, `log-generator.md`, `debug-loop.md`. Four atomic actions: `build.md`, `flash.md`, `capture-logs.md`, `analyze-logs.md`. The agent is hard-prohibited from loading an Action as the first read of a task, it must enter through a Workflow, which then pulls Actions via `MANDATORY SKILL LOAD` directives. This is enforced by `platforms/nrf/rules/skill-loading.md`.
- **Operation-Gating Principle.** Before performing any complex hardware operation (build / flash / capture / analyze / inject logs) the agent must `read_file` the matching Workflow first, regardless of how it arrived at that decision. Closes the failure mode where smaller models would skip the workflow load and improvise from pre-training.
- **Dynamic context loading.** `iot_context.ts` reads `prj.conf`, scans for `build_info.yml` in every build directory, and only injects the modules that match: BLE protocol guide when `CONFIG_BT=y`, the matching board file (nRF52832/52840/5340) for each detected build target, NCS SDK reference always. The system prompt fits what your project actually is.
- **Scope Gate + Context Budget Protection.** `AGENT.md` refuses non-NCS work in-extension (politely redirects), and `rules/core.md` Rule 9 forbids speculative reads outside the workspace and outside the NCS file pattern. No more agents wandering into `~/Documents` to "understand the workspace".
- **Device-Identity rule loaded by default.** `platforms/nrf/rules/device-identity.md` was listed mandatory in `PLATFORM.md` but never actually loaded in 0.0.x; now it is. Multi-device captures use generic `device1`/`device2` labels until role is confirmed by config or logs, no more guessing Central vs Peripheral from board type.
- **`platforms/nrf/PLATFORM.md`** rewritten as a proper directory index with full `triggerNordicAction` documentation, board-target → board-file map, and the skill library index.
- **Board Target Resolution Protocol** in `actions/build.md`: decision matrix that cross-references `build_info.yml` history with live `nrfutil device device-info --serial-number` output instead of guessing.

### Agent reliability: works across "any model"

- **Tool-call parsing hardened against four real-world failure modes**: DeepSeek DSML token stream (`<｜｜DSML｜｜...>`), Markdown code fences wrapping tool XML, literal template mimicry from small models (emitting `<tool_name>read_file</tool_name>` instead of substituting), and mid-task model switches that cross the native-tools ↔ XML-tools boundary. New `normalize-assistant-message.ts` stream-safe rewriter, +30 unit tests.
- **Model-family detection broadened**: DeepSeek V4-class included in native-tools allowlist; Anthropic `-latest` aliases recognized as Claude 4+; new `getToolCallReliabilityTier()` so the UI can warn once when a low-tier model fails to produce tool calls three turns in a row.
- **Windows process-cleanup fix.** The `taskkill /F /IM JLink.exe & taskkill /F /IM nrfutil.exe` form silently failed under PowerShell (`&` is reserved). Now emitted as `cmd /c "..."` from three sources, the action manuals and the tool's `TECHNICAL_REFERENCE`, so it works in PowerShell, bash, and `cmd.exe` identically.
- **Cross-platform J-Link binary resolution (RTT Plan B).** `connectRTTPlanB` previously hardcoded `/bin/bash` and `JLinkExe`. New `jlinkResolver.ts` walks deterministic SEGGER install paths, versioned `JLink_V*` dirs, and `PATH`, fails loudly with a useful error instead of silently launching a broken terminal. 33 unit tests cover Win32 / macOS Apple Silicon / Linux.
- **Read-file error guidance.** Missing `logs/<transport>/*.log` files now return a structured "run capture first" hint instead of raw `ENOENT`, and the analyze workflow is required to `list_files` on the logs directory before reading.

### Hardware-in-the-loop benchmark: IoT-FirmwareDebugBench v0.1

- **Published the first open benchmark for AI agents on embedded IoT firmware.** Six BLE-focused tasks across three difficulty levels, run on real nRF52840 DK and nRF52832 DK boards with NCS v3.2.1, same model on both sides (Claude Haiku 4.5). Full report under `docs/benchmarks/v0.1-report.md` with regenerable SVG figures and a stdlib-only `generate_figures.py` script.
- **Headline result:** Adsum IoT Coder resolved 5/6 tasks vs the general-agent baseline's 3/6, at 3.8× lower token cost. Architecture is the only variable.

### UI / UX

- **Welcome & home screen redesigned** with the new Adsum brand: coral logo, two prominent entry-point cards ("Debug Live Device Logs" promoted to first with brighter border), recent task cards on the home screen, brand orange (`#d76947`) on the focus-chain progress bar with green retained for success states.
- **Claude Code-style `ThinkingBlock`** replaces `ThinkingRow`: italic "Thought for Xs" label, animated dots while streaming, grid-rows collapse animation, auto-collapse when the response begins, expandable on demand. +21 unit tests covering label states, duration formatting, and expand/collapse.
- **Codicons + code font now load reliably in the installed extension.** Vite was emitting absolute `@font-face` URLs that 404'd silently under the webview's `vscode-resource://` scheme; fixed by setting `base: "./"` and dropping a redundant `<link>` to `node_modules/@vscode/codicons/`.
- **Mode icons rendered as base64 PNGs** (CSP-safe), with a theme-aware CSS filter (white in dark mode, black in light mode) via a new `useVSCodeTheme` hook that no longer misidentifies high-contrast light as dark.

### Telemetry: own project, real opt-out

- **Own PostHog project**, separate from upstream Cline. `ADSUM_TELEMETRY_SERVICE_API_KEY` injected at build time; `esbuild.mjs` auto-loads `.env` so `F5` and `npm run package` both work.
- **Opt-out setting** (`adsum-iot-coder.telemetry.enabled`) AND-combined with VS Code's global `telemetry.telemetryLevel`, either being off stops all collection.
- **Fork-attribution fields** on every event (`extension_name`, `extension_publisher`, `is_fork`, `upstream`, `arch`) so upstream-vs-fork usage is unambiguous in analytics.
- New `extension_installed` (once) and `extension_activated` (every session) lifecycle events for clean DAU/install tracking.
- User-facing privacy document: [TELEMETRY.md](./TELEMETRY.md).

### Rebrand

- Display name and UI now **Adsum IoT Coder – for nRF**; activity-bar icon, sidebar logo, welcome screen, social cards, hero GIF all updated. Marketplace identity (`AdsumNetwork.nrf-ai-debugger`) preserved to keep installs intact.
- All command, view, and config keys migrated to the `adsum-iot-coder.*` namespace.
- README rewritten around the AI-agent positioning, the skill-first architecture, and the v0.1 benchmark; supported SoCs broadened from "nRF52840" to **nRF52 / nRF53 / nRF54**.

### Other fixes

- macOS symlink resolution in `iot-knowledge` auto-approval allowlist.
- Onboarding reset button restored in About section; terminal icon fixed.
- Chat freeze on certain large reasoning streams resolved.
- DeepSeek reasoning content now passes through the OpenAI-compatible provider correctly.
- `build-proto.mjs` no longer breaks on macOS paths containing spaces.

## [0.0.4] - 2026-03-23

### Changed
- **Major Rebrand:** Extension renamed from "nRF AI Debugger" to **Adsum IoT Coder – for nRF**.
- **Repository Move:** All internal links and configuration updated to point to the new repository at [https://github.com/adsumnetworks/SoC-AI-Debugger](https://github.com/adsumnetworks/SoC-AI-Debugger).

### Added
- **PostHog Analytics:** Integrated PostHog to track anonymous usage data and Nordic toolchain errors, helping us identify missing dependencies or environmental issues automatically.
- **Compliance:** Added official trademark disclaimer for nRF and Nordic Semiconductor compliance.

### Fixed
- **Log Analyzer Reliability:** Significant improvements to cross-platform UART and RTT log capture stability.
- **Terminal Routing:** Fixed a bug where named terminals (nRF Connect) were incorrectly routed to hidden `cmd.exe` processes in background execution mode.

## [0.0.2] - 2026-03-02

### Fixed
- **Terminal Warning Suppression:** Removed the annoying "Shell Integration Unavailable" warning for nRF Connect terminals.
- **Background Execution:** Fixed a critical bug where named terminals (e.g., nRF Connect) were routed to hidden `cmd.exe` processes instead of the proper PowerShell terminal when the terminal execution mode was set to "Background Exec". This ensures `nrfutil` and `west` commands work reliably.
- **Terminal Timeout:** Increased the shell integration timeout to ensure slower PCs (e.g., Windows 10) have enough time to initialize the nRF Connect SDK environment before executing commands.

## [0.0.1] - Initial Release

### Added
- Initial release of Adsum IoT Coder!
- Seamless integration with the nRF Connect SDK terminal in VS Code.
- AI-powered assistant for Zephyr-based projects capable of automatically analyzing UAR/RTT logs, executing Nordic toolchain commands, and debugging code.