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? | getting-started/README.md |
| How do I run my first build? | getting-started/README.md |
| How do I deploy or monitor for the first time? | getting-started/README.md |
What does platformio.ini need to contain? |
reference/platformio-ini.md |
| What CLI commands and options exist? | reference/cli.md |
How do I use fbuild build / deploy / monitor / test-emu? |
reference/cli.md |
| How do I use the emulator (QEMU / avr8js / simavr)? | guides/emulator-testing.md |
| What is fbuild's PlatformIO compatibility policy? | reference/platformio-compatibility.md |
Why does fbuild strip .eh_frame on some builds? |
reference/platformio-compatibility.md#eh_frame-strip-policy |
| Why does fbuild exist? | WHY.md |
| What are fbuild's key benefits and performance numbers? | WHY.md |
| Is my board supported? | BOARD_STATUS.md |
| Where is the canonical board/platform matrix? | BOARD_STATUS.md |
| How do I add a new board? | BOARD_STATUS.md |
| What's the crate dependency graph? | ../crates/CLAUDE.md |
| How does fbuild's architecture fit together? | architecture/overview.md |
| How does the daemon work? | architecture/runtime.md |
| How does the serial / monitor subsystem work? | architecture/serial.md |
| How do the PyO3 Python bindings work? | architecture/pyo3-bindings.md |
| How does deploy preemption work? | architecture/deploy-preemption.md |
| What are the cross-platform portability constraints? | architecture/portability.md |
| How does library selection (LDF) work in fbuild? | architecture/library-selection.md |
| Why was my library wrongly compiled (#204) / not found (#202)? | architecture/library-selection.md |
| Why did we choose X over Y? | DESIGN_DECISIONS.md |
| What's on the implementation roadmap? | ROADMAP.md |
| How do I run tests / lint / fmt? | development/README.md |
| Why is my build failing? | DEVELOPMENT.md |
| What CI cache block should consumers copy? | CI_CACHE.md |
| What cache keys and invalidation pattern should CI use? | CI_CACHE.md |
| How do I cache fbuild across CI runs? | CI_CACHING.md |
| What's safe to cache in GitHub Actions? | CI_CACHING.md |
| Why does warm-pass build take ~30 s per sketch? (#91) | PERF_WARM_BUILD.md |
What does FBUILD_PERF_LOG=1 do? |
PERF_WARM_BUILD.md |
| Does warm rebuild + deploy + monitor land under 4 s? (#114) | PERF_WARM_DEPLOY.md |
How fast is soldr when building fbuild itself? |
SOLDR_BUILD_PERF.md |
How can a user override ESP-IDF CONFIG_* / sdkconfig settings? |
sdkconfig.md |
Where does the framework's pre-baked sdkconfig.h come from? |
sdkconfig.md |
What's the precedence chain for CONFIG_* overrides? |
sdkconfig.md |
| Where do end-to-end perf benchmarks live (FastLED matrix, P-01)? | ../bench/fastled-examples/README.md |
| What architecture docs should I read for a given crate? | CLAUDE.md |
- The top-level
README.mdis 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.mdremains the canonical board-status and per-board CI badge document.CLAUDE.mdat the repo root is the LLM-entry file;docs/CLAUDE.mdis 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.mdfiles are enforced by a pre-commit hook; every directory with files needs one.
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.