FastLED · zackees · Jun 9, 2026 · Jun 9, 2026
diff --git a/README.md b/README.md
diff --git a/crates/fbuild-build/src/nxplpc/orchestrator.rs b/crates/fbuild-build/src/nxplpc/orchestrator.rs
@@ -184,9 +184,7 @@ impl BuildOrchestrator for NxpLpcOrchestrator {
         let src_dir = crate::compiler::absolute_from_cwd(&ctx.src_dir);
         let project_dir_abs = crate::compiler::absolute_from_cwd(&params.project_dir);
         let mut include_dirs: Vec<PathBuf> = Vec::with_capacity(8);
-        let project_variant_dir = project_dir_abs
-            .join("variants")
-            .join(&ctx.board.variant);
+        let project_variant_dir = project_dir_abs.join("variants").join(&ctx.board.variant);
         if project_variant_dir.join("pins_arduino.h").is_file() {
             tracing::info!(
                 "nxplpc: using project-local variant include {}",

diff --git a/docs/BOARD_STATUS.md b/docs/BOARD_STATUS.md
@@ -1,6 +1,9 @@
 # Board Status
 
-Live per-platform CI status and supported-board reference for fbuild.
+Live per-platform CI status and supported-board reference for fbuild. This is
+the canonical board/platform status document; the root README keeps only a
+short platform summary so per-board badges and support notes do not drift
+between files.
 
 ## Per-platform CI badges
 

diff --git a/docs/INDEX.md b/docs/INDEX.md
@@ -1,52 +1,68 @@
 # Documentation Index
 
-A grep-friendly FAQ that maps common questions to the file that answers them. Both humans and LLM agents should use this table as the entry point into the fbuild docs.
+A grep-friendly FAQ that maps common questions to the file that answers them.
+Both humans and LLM agents should use this table as the entry point into the
+fbuild docs.
 
-| Question                                                  | File                                                       |
-|-----------------------------------------------------------|------------------------------------------------------------|
-| How do I install fbuild?                                  | [../README.md](../README.md#installation)                  |
-| How do I run my first build / deploy / monitor?           | [../README.md](../README.md#quick-start)                   |
-| What does `platformio.ini` need to contain?               | [../README.md](../README.md#configuration)                 |
-| Why does fbuild exist?                                    | [WHY.md](WHY.md)                                           |
-| What are fbuild's key benefits and performance numbers?   | [WHY.md](WHY.md#key-benefits)                              |
-| Is my board supported?                                    | [BOARD_STATUS.md](BOARD_STATUS.md)                         |
-| How do I add a new board?                                  | [BOARD_STATUS.md](BOARD_STATUS.md#adding-a-new-board)      |
-| What's the crate dependency graph?                        | [../crates/CLAUDE.md](../crates/CLAUDE.md)                 |
-| How does fbuild's architecture fit together?              | [architecture/overview.md](architecture/overview.md)       |
-| How does the daemon work?                                 | [architecture/runtime.md](architecture/runtime.md)         |
-| How does the serial / monitor subsystem work?             | [architecture/serial.md](architecture/serial.md)           |
-| How do the PyO3 Python bindings work?                     | [architecture/pyo3-bindings.md](architecture/pyo3-bindings.md) |
-| How does deploy preemption work?                          | [architecture/deploy-preemption.md](architecture/deploy-preemption.md) |
-| What are the cross-platform portability constraints?      | [architecture/portability.md](architecture/portability.md) |
-| How does library selection (LDF) work in fbuild?          | [architecture/library-selection.md](architecture/library-selection.md) |
+| Question | File |
+|---|---|
+| How do I install fbuild? | [getting-started/README.md](getting-started/README.md#install) |
+| How do I run my first build? | [getting-started/README.md](getting-started/README.md#first-project) |
+| How do I deploy or monitor for the first time? | [getting-started/README.md](getting-started/README.md#first-deploy-and-monitor) |
+| What does `platformio.ini` need to contain? | [reference/platformio-ini.md](reference/platformio-ini.md) |
+| What CLI commands and options exist? | [reference/cli.md](reference/cli.md) |
+| How do I use `fbuild build` / `deploy` / `monitor` / `test-emu`? | [reference/cli.md](reference/cli.md#core-workflows) |
+| How do I use the emulator (QEMU / avr8js / simavr)? | [guides/emulator-testing.md](guides/emulator-testing.md) |
+| What is fbuild's PlatformIO compatibility policy? | [reference/platformio-compatibility.md](reference/platformio-compatibility.md) |
+| Why does fbuild strip `.eh_frame` on some builds? | [reference/platformio-compatibility.md#eh_frame-strip-policy](reference/platformio-compatibility.md#eh_frame-strip-policy) |
+| Why does fbuild exist? | [WHY.md](WHY.md) |
+| What are fbuild's key benefits and performance numbers? | [WHY.md](WHY.md#key-benefits) |
+| Is my board supported? | [BOARD_STATUS.md](BOARD_STATUS.md) |
+| Where is the canonical board/platform matrix? | [BOARD_STATUS.md](BOARD_STATUS.md#supported-platforms-and-boards) |
+| How do I add a new board? | [BOARD_STATUS.md](BOARD_STATUS.md#adding-a-new-board) |
+| What's the crate dependency graph? | [../crates/CLAUDE.md](../crates/CLAUDE.md) |
+| How does fbuild's architecture fit together? | [architecture/overview.md](architecture/overview.md) |
+| How does the daemon work? | [architecture/runtime.md](architecture/runtime.md) |
+| How does the serial / monitor subsystem work? | [architecture/serial.md](architecture/serial.md) |
+| How do the PyO3 Python bindings work? | [architecture/pyo3-bindings.md](architecture/pyo3-bindings.md) |
+| How does deploy preemption work? | [architecture/deploy-preemption.md](architecture/deploy-preemption.md) |
+| What are the cross-platform portability constraints? | [architecture/portability.md](architecture/portability.md) |
+| How does library selection (LDF) work in fbuild? | [architecture/library-selection.md](architecture/library-selection.md) |
 | Why was my library wrongly compiled (#204) / not found (#202)? | [architecture/library-selection.md](architecture/library-selection.md#why) |
-| Why did we choose X over Y?                               | [DESIGN_DECISIONS.md](DESIGN_DECISIONS.md)                 |
-| What's on the implementation roadmap?                     | [ROADMAP.md](ROADMAP.md)                                   |
-| How do I run tests / lint / fmt?                          | [DEVELOPMENT.md](DEVELOPMENT.md#testing)                   |
-| Why is my build failing?                                  | [DEVELOPMENT.md](DEVELOPMENT.md#troubleshooting)           |
-| How do I use the emulator (QEMU / avr8js / simavr)?       | [../README.md](../README.md#emulator-testing)              |
-| What CI cache block should consumers copy?                | [CI_CACHE.md](CI_CACHE.md#copy-paste-github-actions-block) |
-| What cache keys and invalidation pattern should CI use?   | [CI_CACHE.md](CI_CACHE.md#key-composition)                 |
-| How do I cache fbuild across CI runs?                     | [CI_CACHING.md](CI_CACHING.md)                             |
-| What's safe to cache in GitHub Actions?                   | [CI_CACHING.md](CI_CACHING.md#what-the-cache-holds)        |
-| Why does warm-pass build take ~30 s per sketch? (#91)     | [PERF_WARM_BUILD.md](PERF_WARM_BUILD.md)                   |
-| What does `FBUILD_PERF_LOG=1` do?                          | [PERF_WARM_BUILD.md](PERF_WARM_BUILD.md#instrumentation)   |
-| Does warm rebuild + deploy + monitor land under 4 s? (#114) | [PERF_WARM_DEPLOY.md](PERF_WARM_DEPLOY.md)                 |
-| How fast is `soldr` when building fbuild itself?            | [SOLDR_BUILD_PERF.md](SOLDR_BUILD_PERF.md)                 |
-| How can a user override ESP-IDF `CONFIG_*` / `sdkconfig` settings? | [sdkconfig.md](sdkconfig.md)                          |
-| Where does the framework's pre-baked `sdkconfig.h` come from? | [sdkconfig.md](sdkconfig.md#whats-there-today)            |
-| What's the precedence chain for `CONFIG_*` overrides?       | [sdkconfig.md](sdkconfig.md#tldr)                          |
+| Why did we choose X over Y? | [DESIGN_DECISIONS.md](DESIGN_DECISIONS.md) |
+| What's on the implementation roadmap? | [ROADMAP.md](ROADMAP.md) |
+| How do I run tests / lint / fmt? | [development/README.md](development/README.md) |
+| Why is my build failing? | [DEVELOPMENT.md](DEVELOPMENT.md#troubleshooting) |
+| What CI cache block should consumers copy? | [CI_CACHE.md](CI_CACHE.md#copy-paste-github-actions-block) |
+| What cache keys and invalidation pattern should CI use? | [CI_CACHE.md](CI_CACHE.md#key-composition) |
+| How do I cache fbuild across CI runs? | [CI_CACHING.md](CI_CACHING.md) |
+| What's safe to cache in GitHub Actions? | [CI_CACHING.md](CI_CACHING.md#what-the-cache-holds) |
+| Why does warm-pass build take ~30 s per sketch? (#91) | [PERF_WARM_BUILD.md](PERF_WARM_BUILD.md) |
+| What does `FBUILD_PERF_LOG=1` do? | [PERF_WARM_BUILD.md](PERF_WARM_BUILD.md#instrumentation) |
+| Does warm rebuild + deploy + monitor land under 4 s? (#114) | [PERF_WARM_DEPLOY.md](PERF_WARM_DEPLOY.md) |
+| How fast is `soldr` when building fbuild itself? | [SOLDR_BUILD_PERF.md](SOLDR_BUILD_PERF.md) |
+| How can a user override ESP-IDF `CONFIG_*` / `sdkconfig` settings? | [sdkconfig.md](sdkconfig.md) |
+| Where does the framework's pre-baked `sdkconfig.h` come from? | [sdkconfig.md](sdkconfig.md#whats-there-today) |
+| What's the precedence chain for `CONFIG_*` overrides? | [sdkconfig.md](sdkconfig.md#tldr) |
 | Where do end-to-end perf benchmarks live (FastLED matrix, P-01)? | [../bench/fastled-examples/README.md](../bench/fastled-examples/README.md) |
-| What architecture docs should I read for a given crate?   | [CLAUDE.md](CLAUDE.md)                                     |
+| What architecture docs should I read for a given crate? | [CLAUDE.md](CLAUDE.md) |
 
 ## Conventions
 
-- The top-level `README.md` is the install + Quick Start entry point for humans.
-- `CLAUDE.md` at the repo root is the LLM-entry file; `docs/CLAUDE.md` is the LLM map into architecture docs.
+- The top-level `README.md` is the concise project front door for humans.
+- `docs/getting-started/` owns first-run workflows.
+- `docs/guides/` owns task-oriented workflows.
+- `docs/reference/` owns stable user references such as CLI and configuration.
+- `docs/platforms/` routes platform questions; `BOARD_STATUS.md` remains the
+  canonical board-status and per-board CI badge document.
+- `CLAUDE.md` at the repo root is the LLM-entry file; `docs/CLAUDE.md` is the
+  LLM map into architecture docs.
 - Architecture docs live under `docs/architecture/`, one file per subsystem.
 - ADR-style decisions go in `docs/DESIGN_DECISIONS.md`.
-- Per-directory `README.md` files are enforced by a pre-commit hook — every directory with files needs one.
+- Per-directory `README.md` files are enforced by a pre-commit hook; every
+  directory with files needs one.
 
-## Keeping this index current
+## Keeping This Index Current
 
-When a new doc is added under `docs/`, add a row to the table above. Prefer one FAQ-style question per row so readers can grep for the question they have.
+When a new doc is added under `docs/`, add a row to the table above. Prefer one
+FAQ-style question per row so readers can grep for the question they have.
diff --git a/docs/README.md b/docs/README.md
@@ -1,18 +1,34 @@
 # Documentation
 
-Architecture and design documentation for the fbuild project.
+Documentation is organized by reader intent. Start with
+[`INDEX.md`](INDEX.md) when you have a specific question.
 
-## Contents
+## User Docs
 
-- **`INDEX.md`** -- FAQ-style index mapping questions to files (start here)
-- **`ARCHITECTURE.md`** -- Index of all architecture documents
-- **`CLAUDE.md`** -- Guide mapping crates to relevant architecture docs
-- **`WHY.md`** -- Why fbuild exists, key benefits, performance benchmarks
-- **`BOARD_STATUS.md`** -- Per-platform CI badges and supported boards
-- **`DEVELOPMENT.md`** -- Testing, troubleshooting, local development setup
-- **`CI_CACHE.md`** -- Consumer-facing cross-run CI cache strategy
-- **`CI_CACHING.md`** -- How to save/restore fbuild's cache across CI runs
-- **`SOLDR_BUILD_PERF.md`** -- Local soldr build benchmark for the Rust workspace
+- **`getting-started/`** -- install, first build, first deploy, first emulator run
+- **`guides/`** -- task workflows such as emulator testing and CI caching
+- **`reference/`** -- CLI, `platformio.ini`, compatibility, and other stable references
+- **`platforms/`** -- board/platform support routing
+- **`BOARD_STATUS.md`** -- canonical per-platform CI badges and supported boards
+- **`WHY.md`** -- why fbuild exists, key benefits, performance benchmarks
+
+## Contributor And Internal Docs
+
+- **`development/`** -- human entry point for working on fbuild itself
+- **`DEVELOPMENT.md`** -- testing, troubleshooting, local development setup
+- **`ARCHITECTURE.md`** -- index of all architecture documents
+- **`architecture/`** -- subsystem-specific architecture documents
+- **`CLAUDE.md`** -- guide mapping crates to relevant architecture docs
 - **`DESIGN_DECISIONS.md`** -- ADR-style decisions with rationale
-- **`ROADMAP.md`** -- Implementation phases for the Rust port
-- **`architecture/`** -- Subsystem-specific architecture documents
+- **`ROADMAP.md`** -- implementation phases for the Rust port
+- **`RELEASING.md`** -- release workflow
+
+## Operations And Performance
+
+- **`CI_CACHE.md`** -- consumer-facing cross-run CI cache strategy
+- **`CI_CACHING.md`** -- detailed save/restore design for CI runners
+- **`PERF_WARM_BUILD.md`** -- warm-pass build performance investigation
+- **`PERF_WARM_DEPLOY.md`** -- warm deploy and monitor timing results
+- **`SOLDR_BUILD_PERF.md`** -- local soldr build benchmark for the Rust workspace
+- **`symbols.md`** -- per-symbol bloat analysis reference
+- **`sdkconfig.md`** -- ESP `sdkconfig` user-override design
diff --git a/docs/development/README.md b/docs/development/README.md
@@ -0,0 +1,29 @@
+# Development
+
+This directory is the human-facing entry point for working on fbuild itself.
+
+## Start Here
+
+The existing project-wide development guide remains in
+[`../DEVELOPMENT.md`](../DEVELOPMENT.md). It covers:
+
+- Test commands.
+- Troubleshooting.
+- Local setup on Windows and other hosts.
+- Linting and formatting.
+- Distribution and release notes.
+- Python / PyO3 extension builds.
+- Enforced hooks.
+
+## Troubleshooting
+
+Troubleshooting content currently lives in
+[`../DEVELOPMENT.md#troubleshooting`](../DEVELOPMENT.md#troubleshooting).
+
+## Related Docs
+
+- Architecture overview: [`../architecture/overview.md`](../architecture/overview.md)
+- Crate dependency graph: [`../../crates/CLAUDE.md`](../../crates/CLAUDE.md)
+- Design decisions: [`../DESIGN_DECISIONS.md`](../DESIGN_DECISIONS.md)
+- Releasing: [`../RELEASING.md`](../RELEASING.md)
+- Roadmap: [`../ROADMAP.md`](../ROADMAP.md)
diff --git a/docs/getting-started/README.md b/docs/getting-started/README.md
@@ -0,0 +1,106 @@
+# Getting Started
+
+Use this guide when you want to install fbuild, compile a first sketch, and
+understand what happens on the first run.
+
+## Install
+
+Install the published Python package:
+
+```bash
+pip install fbuild
+```
+
+Or install from a local checkout:
+
+```bash
+git clone https://github.com/fastled/fbuild.git
+cd fbuild
+pip install -e .
+```
+
+## First Project
+
+Create a project with a PlatformIO-compatible layout:
+
+```bash
+mkdir my-project
+cd my-project
+mkdir src
+```
+
+Create `platformio.ini`:
+
+```ini
+[env:uno]
+platform = atmelavr
+board = uno
+framework = arduino
+```
+
+Create `src/main.ino`:
+
+```cpp
+void setup() {
+  pinMode(LED_BUILTIN, OUTPUT);
+}
+
+void loop() {
+  digitalWrite(LED_BUILTIN, HIGH);
+  delay(1000);
+  digitalWrite(LED_BUILTIN, LOW);
+  delay(1000);
+}
+```
+
+Build it:
+
+```bash
+fbuild build
+```
+
+The first build downloads the AVR-GCC toolchain and Arduino AVR core, then
+caches them. Later builds reuse the cache and write firmware under
+`.fbuild/build/<env>/`.
+
+## First Deploy And Monitor
+
+Deploy to a connected board:
+
+```bash
+fbuild deploy -e uno
+```
+
+Deploy and attach the serial monitor:
+
+```bash
+fbuild deploy -e uno --monitor
+```
+
+Run the monitor by itself:
+
+```bash
+fbuild monitor -e uno --timeout 60
+```
+
+Serial monitoring uses pyserial and follows the same general port-selection
+model as PlatformIO. You can pass `--port COM3` or `--port /dev/ttyUSB0` when
+auto-detection is not enough.
+
+## First Emulator Run
+
+Run a build in the default emulator for the board:
+
+```bash
+fbuild test-emu . -e uno --timeout 10
+```
+
+See the [emulator testing guide](../guides/emulator-testing.md) for backend
+selection, QEMU notes, and CI-friendly halt conditions.
+
+## Next Steps
+
+- CLI commands and options: [reference/cli.md](../reference/cli.md)
+- `platformio.ini` keys: [reference/platformio-ini.md](../reference/platformio-ini.md)
+- Supported boards: [BOARD_STATUS.md](../BOARD_STATUS.md)
+- Troubleshooting: [development/README.md](../development/README.md)
diff --git a/docs/guides/README.md b/docs/guides/README.md
@@ -0,0 +1,14 @@
+# Guides
+
+Task-oriented docs for using fbuild in real workflows.
+
+## Contents
+
+- [Emulator testing](emulator-testing.md) - run firmware under avr8js, simavr,
+  or QEMU without physical hardware.
+- [CI cache strategy](../CI_CACHE.md) - copy-paste setup for consumer GitHub
+  Actions workflows.
+- [CI caching internals](../CI_CACHING.md) - detailed save/restore behavior for
+  fbuild and zccache.
+- [Troubleshooting](../development/README.md#troubleshooting) - local setup and
+  common failure modes.