feat(ide): add a Zed-based Arduino IDE experience behind fbuild ide [meta]

[zackees]

Context

Add an umbrella fbuild ide feature that turns fbuild into a complete, local-first embedded development environment combining:

• Zed’s editing experience.
• clangd code intelligence.
• fbuild’s build, deploy, device, dependency, and serial backends.
• The approachable workflow of Arduino IDE.

The goal is not a pixel-for-pixel Arduino IDE copy. The goal is a modern replacement for its core local workflows: open a sketch, select an environment and device, write code with accurate navigation, compile, deploy, and monitor without manually configuring toolchains or dependencies.

fbuild already provides much of the backend:

• fbuild build, deploy, monitor, reset, device, and sync.
• compile_commands.json generation.
• fbuild clangd-config.
• Cross-toolchain discovery and framework installation.
• LDF-style library selection.
• Device discovery, leases, and bootloader port recovery.
• Build, deploy, status, log, and serial WebSocket APIs through fbuild-daemon.

The missing layer is a cohesive IDE launch and UI experience.

Zed constraint

The current public Zed extension API supports languages, language servers, debuggers, themes, snippets, and MCP servers, but does not support arbitrary custom toolbars and panels.

This feature should therefore be delivered in phases:

1. Launch and configure stock Zed using generated settings, tasks, clangd configuration, and fbuild commands.
2. Build or maintain a Zed/GPUI application or fork that provides the full embedded UI.

References:

• https://zed.dev/docs/languages/cpp
• https://zed.dev/docs/extensions/developing-extensions
• https://docs.arduino.cc/software/ide/
• https://docs.arduino.cc/arduino-cli/

Arduino Cloud synchronization is explicitly deferred.

Proposal

Introduce:

fbuild ide [project_dir] [-e <environment>]

The command should prepare the project and launch the supported Zed-based IDE.

Startup lifecycle

On launch:

1. Locate and parse platformio.ini.
2. Resolve the requested or default environment.
3. Resolve and install the selected platform, framework, toolchain, and declared libraries.
4. Generate required framework and board configuration headers.
5. Generate or refresh compile_commands.json.
6. Generate Zed and clangd configuration.
7. Launch the workspace.
8. Watch dependency and environment changes.
9. Refresh the compile database and restart/reload clangd when configuration changes.

Editor and clangd

The editing experience must provide:

• Completion and signature help.
• Live diagnostics.
• Jump to declaration.
• Jump to definition and implementation.
• Find references.
• Rename and symbol search.
• Header/source switching.
• Formatting.
• Board- and environment-aware preprocessor state.
• Navigation into framework, core, variant, toolchain, and library sources.
• Correct diagnostic mapping from generated C++ back to the original .ino sketch.

clangd configuration must reflect the real embedded build:

• Cross-compiler and target.
• Board-specific defines.
• Architecture and ABI flags.
• Framework, variant, core, library, and toolchain include paths.
• Generated headers.
• Selected libraries only.
• Cross-compiler builtin include directories.

Automatic dependency installation

When a project or environment is opened:

• Install declared platform, framework, toolchain, and library dependencies.
• Reuse fbuild’s managed caches and locks.
• Install the complete framework/library source when available so navigation can reach implementations.
• Index system and standard-library headers.
• Retain generated sources and headers where clangd can inspect them.
• Explain when implementation source is unavailable because a dependency is proprietary or precompiled.

For unresolved includes:

• Automatically install an unambiguous compatible provider.
• Show a picker when multiple libraries provide the same header.
• Never silently choose an ambiguous dependency.
• Explain architecture incompatibilities.
• Persist selections in project configuration and platformio.lock.
• Support offline/cache-only operation.

Primary UI

The full Zed/GPUI phase should provide:

Toolbar

• Verify/Compile.
• Deploy/Upload.
• Deploy and Monitor.
• Stop/cancel.
• Reset board.
• Open Serial Monitor.
• Open Serial Plotter.

Selectors

Keep these concepts separate:

• Environment selector: platform, board, framework, flags, and dependencies.
• Board selector: compile identity and board options.
• Device/port selector: the physical deployment and monitoring target.
• Programmer selector where supported.

The active environment and its persisted project configuration must remain the source of truth. UI state must not silently diverge from platformio.ini and platformio.lock.

Left project pane

Show:

• Primary .ino sketch.
• Additional .ino files.
• Project headers and C/C++ sources.
• src/, include/, lib/, and data/.
• Framework, core, variant, and dependency sources.
• Built-in, platform, and library examples.

Dependency sources should be visibly distinguished from user-editable project files.

Bottom panel

Provide:

• Build and deployment logs.
• Structured problems and clickable diagnostics.
• Serial Monitor.
• Serial Plotter.
• Flash and RAM usage.
• Operation progress and cancellation.
• clangd and toolchain health.

Build and deployment

Compile must support:

• Incremental and clean builds.
• Progress and cancellation.
• Clickable compiler diagnostics.
• Flash and RAM usage.
• Artifact locations.
• Optional verbose commands.
• Automatic clangd refresh after configuration changes.

Deploy must support:

• Automatic device detection.
• Explicit port selection and override.
• Bootloader re-enumeration and changed-port recovery.
• Upload progress and verification.
• Automatic monitor reconnection.
• Serial, USB, debug-probe, network, and OTA deployment where supported.
• Upload Using Programmer.
• Burn Bootloader.

Serial Monitor and Plotter

Serial Monitor should support:

• Board-aware baud rate and control-line behavior.
• Line-ending selection.
• Text and raw-byte transmission.
• Timestamps.
• Autoscroll and pause.
• Clear, copy, search, and save.
• Automatic reconnect after reset or deployment.
• Port ownership/conflict diagnostics.
• Multiple readers through the existing daemon serial manager.

Serial Plotter should support:

• Multiple numeric channels.
• Labels and legends.
• Configurable ranges and history.
• Pause, clear, and export.
• Reconnection with the same device identity.

Managers

Library manager

• Search by name, header, category, and architecture.
• Install, remove, upgrade, downgrade, and pin.
• Show metadata, dependencies, compatibility, examples, and source links.
• Install from registry, Git, archive, or local path.
• Update project configuration and lock state.

Platform and board manager

• Search platforms and boards.
• Install, remove, upgrade, downgrade, and pin package versions.
• Support additional package registries.
• Display installation progress and disk usage.
• Configure board-specific menus such as CPU frequency, flash layout, USB mode, and partition scheme.

Project and sketch management

Provide:

• New sketch.
• Open, save, rename, duplicate, archive, and recent projects.
• Sketchbook browsing.
• Built-in, framework, platform, and library examples.
• Import library or sketch archives.
• Crash recovery for unsaved changes.
• Multi-environment workspaces.
• Formatting preferences and keybindings.

Debugging

Long-term Arduino IDE parity includes:

• Supported-probe detection.
• Breakpoints.
• Continue, pause, and stepping.
• Variables and watches.
• Call stack.
• Registers and disassembly.
• Board-specific debug configuration.
• J-Link, CMSIS-DAP, Atmel-ICE, and other supported adapters.

Suggested child issues

This meta issue should be decomposed into independently closable child issues:

• Define fbuild ide CLI contract and architecture.
• Implement stock-Zed discovery, configuration, and launch.
• Generate .zed/settings.json, tasks, and environment configuration.
• Make compile-database and clangd refresh environment-aware.
• Install missing platform, framework, toolchain, and declared dependencies on open.
• Add safe include-to-library resolution and ambiguous-provider picker.
• Decide and implement the Zed fork/GPUI distribution strategy.
• Add embedded build/deploy toolbar and operation progress.
• Add environment, board, device, port, and programmer selectors.
• Add the sketch/project/dependency source tree.
• Add integrated Serial Monitor.
• Add Serial Plotter.
• Add library manager.
• Add platform and board manager.
• Add examples and sketchbook workflows.
• Add programmer upload and bootloader operations.
• Add debugger integration.
• Add cross-platform packaging, updates, and first-run onboarding.
• Add end-to-end tests for representative AVR, ESP32, ARM, and RP2040 projects.

Child issues should link back to this issue and be added to the checklist as they are created.

Acceptance criteria

This meta issue is complete when:

• All required child issues have been created, linked, and completed.
• fbuild ide [project_dir] [-e <environment>] works on Windows, macOS, and Linux.
• A fresh supported project can be opened without manually installing its toolchain, framework, or declared libraries.
• clangd completion, diagnostics, declaration, definition, implementation, and reference navigation work for project, framework, and library code.
• Changing environments refreshes dependencies, compile configuration, and clangd.
• The IDE exposes compile, deploy, reset, monitor, and cancellation controls.
• Environment, board, and physical-device selection remain distinct and are persisted correctly.
• Serial Monitor reconnects across deploy/reset and port re-enumeration.
• Serial Plotter supports multiple numeric streams.
• Library and platform managers can search, install, remove, upgrade, and pin packages.
• Ambiguous missing-header providers require an explicit user selection.
• Build and deployment errors are clickable and map to project source.
• Representative AVR, ESP32, ARM, and RP2040 projects pass end-to-end IDE tests.
• First-run setup and troubleshooting are documented.

Non-goals

• Pixel-for-pixel replication of Arduino IDE.
• Arduino Cloud sketch synchronization in the initial scope.
• Guaranteeing implementation navigation for proprietary or binary-only dependencies.
• Hiding platformio.ini or creating a second conflicting project configuration model.

Open questions

Child issues should resolve:

• How the Zed/GPUI application or fork is built, distributed, updated, and kept synchronized with upstream Zed.
• Whether generated Zed configuration is project-owned, fbuild-owned, or layered without modifying user files.
• How UI edits to boards, environments, and libraries are persisted atomically.
• Which board-specific configuration menus are required for the initial supported platform set.
• Which debugger adapters and hardware probes form the first supported debugging milestone.

Related issues

Existing foundations:

• feat: generate clangd header configuration for the default platformio.ini env so go-to-definition works #533 — generated clangd configuration and go-to-definition support.
• feat: add fbuild sync and JSON platformio.lock #618 — fbuild sync and deterministic platformio.lock.
• feat(library-selection): Rust-native LDF-style transitive header scanner, zccache-backed #205 — Rust-native library selection and transitive header scanning.

[zackees]

Research follow-up (2026-07-15): assumption audit + corrected implementation guide

I researched every load-bearing assumption in this proposal against the current Zed codebase/docs (Zed 1.11.3, released today), the fbuild source tree, and the Arduino/clangd ecosystem. Several assumptions are wrong or stale — including two in our own code — and a couple of the proposed requirements are architecturally the wrong shape. This comment is the corrected, authoritative implementation guide. Nothing below edits the original body; treat this as the errata + plan of record.

---

Part 1 — Assumption audit

1.1 Zed extension API: confirmed, and it's worse than stated — plan for it permanently

The body says the extension API "does not support arbitrary custom toolbars and panels." Confirmed, and the trend is narrowing, not widening:

• Extensions today provide: languages/LSP wiring, debug adapters (DAP), themes, icon themes, snippets, MCP servers. No panels, no toolbars, no webviews, no status-bar items. (developing-extensions)
• Extension-provided slash commands were removed from Zed, and MCP-server extensions are being deprecated toward the MCP registry — the API surface has shrunk since 2025.
• The Visual Extension API RFC got an official maintainer response on 2026-05-21: "not something we're likely to get to in the near future, but very much on our radar" (zed#53403; see also zed#21208).
• Zed tasks cannot prompt for user input — there is no VS Code-style inputs mechanism; maintainer-confirmed and still true (zed#10823).
• There is no external control API: the zed CLI has no "restart language server" / "reload" verb, and no IPC socket. The only external lever is rewriting watched config files.

Correction: Phase 1 (stock Zed) is not a stopgap before a "real UI" — it is the product for the foreseeable future. Design the whole workflow to be excellent inside the constraints: terminal tasks, LSP config, DAP config, and daemon-served web pages (§1.6).

1.2 The "Zed fork" half of Phase 2 should be dropped

• Zed relicensed in May 2026: AGPL was removed entirely; all first-party code is now GPL-3.0-or-later, with gpui and marked components staying Apache-2.0 (zed#57948, merged 2026-05-28).
• A fork is legal — fbuild (MIT OR Apache-2.0) can stay out-of-process, and separate programs communicating over CLI/HTTP are not derivative works — but the fork binary itself is GPL, must be rebranded (trademark), and must track a very large Rust workspace shipping weekly stable releases. The two real-world precedents are instructive: Gram (hard fork, 1.0 in 2026-03) is a multi-maintainer effort, and Zedless gave up on conventional forking and maintains patch scripts against upstream instead. That's the maintenance bill we'd be signing up for, alone, for a build tool's side feature.
• If a native companion app is ever justified, the clean path is GPUI directly (Apache-2.0, permissive) plus longbridge/gpui-component (60+ components incl. dockable panels, powers a commercial app) — a new small app, not a fork of the editor.

Correction: strike "or fork" from Phase 2. The realistic ladder is: stock Zed → daemon-served web UI (§1.6) → maybe a GPUI companion app → maybe Zed's Visual Extension API if it ever ships.

1.3 ".ino diagnostic mapping from generated C++" is the wrong architecture — feed the raw .ino to clangd instead

The requirement "Correct diagnostic mapping from generated C++ back to the original .ino sketch" describes the arduino-language-server design (Arduino IDE 2.x's Go LSP proxy with a position-translating sourcemapper). We cannot and should not take that path: it is AGPL-3.0, requires arduino-cli + FQBN (not platformio.ini), its own README says main is not stable, and rebuilding an LSP position-mapping proxy from scratch is a project bigger than everything else in this issue combined.

What actually works (the approach used by clangd+Arduino users in Helix/Neovim, and what PlatformIO effectively recommends):

1. Compile-DB entry for the raw .ino itself. Today fbuild concatenates .ino files, injects #include <Arduino.h>, generates prototypes, and writes <build_dir>/<stem>.ino.cpp (crates/fbuild-build-engine/src/source_scanner.rs:292-352) — and compile_commands.json records only the generated .ino.cpp, never the file the user edits. So today, the sketch itself gets zero IntelliSense. Fix: when emitting the IDE-flavored DB, replace the .ino.cpp entry with an entry for the raw .ino using the same flags plus -x c++ -include Arduino.h (replace, not add — two TUs covering the same code duplicates every symbol in clangd's index and makes go-to-definition offer both).
2. Editor-side language mapping. Zed: "file_types": {"C++": ["ino"]} in .zed/settings.json — documented and sufficient to start clangd on .ino buffers.
3. The auto-prototype wart, honestly. clangd sees the raw sketch without Arduino's generated forward declarations, so use-before-declaration draws spurious "use of undeclared identifier" squiggles on code the real build accepts. We already extract prototypes with tree-sitter (source_scanner.rs:666, extract_function_prototypes) — we can optionally emit <build_dir>/<stem>.ino.prototypes.h and add a second -include after Arduino.h. Caveat that no one solves cleanly (not even arduino-cli — see arduino-cli#1800): prototypes referencing types defined later in the sketch still fail. Document "declare before use" as the escape hatch and move on.
4. Multi-tab sketches (multiple .ino concatenated): per-tab TUs won't see symbols from sibling tabs. Single-sketch projects — the overwhelmingly common case — work perfectly; multi-tab gets a documented limitation and a follow-up child issue. (Also note: .ino preprocessing is skipped entirely when a main.cpp exists, source_scanner.rs:179.)

Correction: rewrite the acceptance criterion from "diagnostics map from generated C++ back to .ino" to "raw .ino files get first-class clangd IntelliSense via direct-as-C++ compile entries, with the prototype limitation documented."

1.4 fbuild clangd-config exists (#533 → PR #539) but is broken for this feature's purposes — fix it first

Three concrete findings from the source:

• The --query-driver machinery is effectively dead code. clangd_config.rs:151-153 documents that arguments[0] in compile_commands.json is "the real GCC/G++ binary (not a cache wrapper)". That is false: pipeline/compile.rs:159 unconditionally runs translate_for_clang, which rewrites arguments[0] to bare clang/clang++ and inserts --target=<triple> (unit-tested at compile_database/tests/clang.rs:201-213). So extract_compiler_path returns "clang++", compiler_query_driver_glob degenerates to ./*, and the generated .clangd pins Compiler: clang++. The cross-toolchain's builtin include dirs are never exposed via the driver.
  • Fix (preferred): drop query-driver entirely and bake the cross-GCC builtin include dirs into each DB entry as -isystem during translation — fbuild_packages::toolchain::clang::find_gcc_builtin_include_dirs() already exists and is already used by run_iwyu. This is also the robust choice on Windows, where query-driver has a known breakage class around .exe-suffix mismatches (cf. arduino-cli#1286) and requires clangd to execute the driver.
  • Either way, fix the stale doc comment.
• Staleness. clangd-config only regenerates the DB if the file is missing (clangd_config.rs:31-50); a plain fbuild build never refreshes it (DB generation is gated behind -t compiledb / FBUILD_COMPILEDB — docs/DESIGN_DECISIONS.md:63 ("generate after every build") is aspirational, not what the code does). fbuild ide must own freshness explicitly: regenerate on open, on env switch, and after builds it launches.
• Everything except .clangd is VS Code-shaped (.vscode/settings.json with ${workspaceFolder}, MS C/C++ extension keys, .vscode/extensions.json). The .clangd writer, env resolution (resolve_env_name), atomic writes, and the merge-don't-clobber settings writer (merge_vscode_settings, clangd_config.rs:230) are all reusable — refactor into an editor-neutral core with per-editor emitters.

1.5 Zed on Windows / CLI / config: assumptions hold, with useful specifics

• Windows is stable since 2025-10-15 (blog); install via winget install -e --id ZedIndustries.Zed; Zed is at 1.11.3 (2026-07-15), x64 + ARM64. Hard requirement: DirectX-11-capable GPU — which means CI runners cannot launch Zed; see §3 for what that does to the e2e acceptance criteria.
• The zed CLI exists on all three platforms (-w/--wait, -n/--new, -a/--add, file:line:col, --user-data-dir) (CLI reference). On Windows it ships with the app but may need PATH setup — fbuild ide should also probe known install locations rather than trusting PATH.
• Project config surface is exactly what we need: .zed/settings.json (lsp.clangd.binary.{path,arguments}, file_types), .zed/tasks.json (with $ZED_WORKTREE_ROOT etc.), .zed/debug.json. Zed manages its own clangd binary by default, so we don't have to distribute clangd. Prefer putting CompilationDatabase/compiler config in the project-root .clangd file (editor-neutral, relative paths) and keep .zed/settings.json minimal and portable — Zed's lsp arguments have no ${workspaceFolder}-style variable, so absolute paths there would make the file machine-specific.
• Refresh lifecycle, honestly: Zed hot-reloads .zed/settings.json on change (regular files only — symlinks don't reload, zed#38936); clangd itself hot-reloads compile_commands.json (stat-throttled ~5 s, clangd ≥ 12); but already-open buffers may not re-parse until the user runs editor: restart language server, and no external process can trigger that. The body's startup-lifecycle step 9 ("restart/reload clangd when configuration changes") must be reworded to "regenerate configs and rely on hot-reload; a manual language-server restart is occasionally required" — we cannot promise automation Zed doesn't expose.

1.6 Serial Monitor is already solved; Serial Plotter should be daemon-served web UI

• Monitor: fbuild monitor already routes through the daemon's SharedSerialManager (broadcast multi-reader, exclusive writer, deploy-preemption pause/auto-reconnect — crates/fbuild-serial/src/manager.rs). In stock Zed it's simply a task in the terminal panel. Reconnect-across-deploy is the existing preemption contract, not new work.
• Plotter: needs real UI Zed can't host. The resolution that costs nearly nothing: fbuild-daemon already runs axum, already exposes /ws/serial-monitor, and already serves HTML/JS pages (the avr8js emulator pages, crates/fbuild-daemon/src/handlers/emulator/). Serve a plotter page from the daemon; the "Open Serial Plotter" Zed task opens the browser. Same pattern later hosts build progress, library/board managers, and flash/RAM visualizations. CORS is already localhost-only.

1.7 The missing-include → provider picker is a much bigger project than one checklist line

Nothing resembling it exists: fbuild-library-select attributes includes strictly by path-prefix and only reports unresolved includes (Selection.unresolved); /api/install-deps installs declared deps only; fbuild sync is Phase 1 (source classification into platformio.lock — no network resolution, no installation). A "which library provides <header>" feature requires a header→package index across the PlatformIO registry and Arduino library index, plus ranking and architecture filtering. Keep the child issue, but scope it as its own multi-phase project and do not gate the IDE MVP on it.

1.8 Debugging: milestone 1 is probe-rs targets only

Zed's debugger is DAP-native, supports arbitrary adapters via extensions and tcp_connection attach in .zed/debug.json (debugger docs). Reality check for embedded:

• probe-rs ships a DAP server (probe-rs dap-server, what its VS Code extension uses) → ARM Cortex-M + RP2040 over CMSIS-DAP/J-Link is achievable with a generated .zed/debug.json and no Zed extension at all. That's milestone 1.
• OpenOCD speaks the GDB remote protocol, not DAP — driving it needs a DAP↔GDB adapter; there is no cortex-debug equivalent for Zed, and no SVD/peripheral/RTT views exist. ESP32 (openocd-esp32) and AVR debugging are far out. Don't put them in the first debugging milestone.

---

Part 2 — Corrected implementation plan

Phase 0 — Foundations (do these before any fbuild ide code; each is independently shippable)

1. Fix the compile DB for clangd (§1.4): bake find_gcc_builtin_include_dirs() output into translated entries as -isystem; delete the degenerate query-driver path or make it real; fix the stale doc at clangd_config.rs:151.
2. Raw-.ino compile entries (§1.3): replace the .ino.cpp entry with a raw-.ino entry (-x c++ -include Arduino.h, optional generated prototypes header) when emitting for IDE use.
3. Freshness: make DB regeneration a first-class, cheap operation fbuild ide can invoke on open/env-switch/build (today: only -t compiledb/FBUILD_COMPILEDB).
4. Refactor clangd_config.rs into an editor-neutral core + emitters (--editor vscode|zed), keeping current behavior as the VS Code emitter. The non-destructive merge pattern (merge_vscode_settings) carries over to .zed/settings.json.

Phase 1 — fbuild ide MVP on stock Zed

CLI wiring (template: ClangdConfig): Commands::Ide variant in crates/fbuild-cli/src/cli/args.rs (~:442), "ide" in KNOWN_SUBCOMMANDS (args.rs:888 — required for the fbuild <dir> ide arg-rewrite), pub mod ide; in cli/mod.rs, dispatch arm in cli/dispatch.rs.

Startup lifecycle maps almost 1:1 onto existing calls:

Step	Existing machinery
Parse platformio.ini, resolve env	PlatformIOConfig::from_path, get_default_environment / resolve_env_name
Install platform/toolchain/libs	daemon POST /api/install-deps (declared deps)
Generate/refresh compile DB	run_build(target=Some("compiledb")) + Phase 0 fixes
Emit clangd config	.clangd writer (keep DB discovery relative here, §1.5)
Emit Zed config	new: .zed/settings.json (file_types ino→C++, minimal lsp.clangd), .zed/tasks.json
Launch	probe PATH + known install dirs for zed/zed.exe; zed <project_dir>; print winget/brew/instructions if absent

Generated tasks (all just fbuild invocations, so they render progress in Zed's terminal panel and file:line diagnostics are clickable there): Build, Build (clean), Deploy, Deploy + Monitor, Monitor, Reset, Select environment — the selector problem (§1.1, no task input prompts) is solved by making selection fbuild's job: an interactive terminal picker (fbuild ide select) that persists the choice and regenerates configs, plus optional static per-env task variants.

Config ownership (answers the open question): layered, merge-don't-clobber — fbuild owns specific keys inside .zed/settings.json/.zed/tasks.json and .clangd, never touches others, and files are regenerable at any time. Recommend gitignoring compile_commands.json (absolute paths, machine-specific); .zed/ contents as emitted are portable and committable.

Phase 2 — Panel-grade UX without forking anything

Daemon-served pages (precedent: avr8js): Serial Plotter over /ws/serial-monitor, then build progress, library/board managers (backed by new daemon endpoints), flash/RAM usage. Zed tasks open them in the browser.

Phase 3 — Debugging, milestone 1 = probe-rs DAP attach (§1.8)

Generate .zed/debug.json with a tcp_connection attach to probe-rs dap-server for ARM/RP2040 boards fbuild can already identify. Everything else (OpenOCD/ESP32/AVR, peripheral views) is explicitly out of milestone 1.

Phase 4 — Re-scoped "full UI" decision

Default: stock Zed + daemon web UI is the end state. If a native companion is ever justified: GPUI (Apache-2.0) + gpui-component standalone app — not a Zed fork (§1.2). Revisit only if Zed ships the Visual Extension API (zed#53403).

---

Part 3 — Acceptance-criteria corrections

• "Diagnostic mapping from generated C++ back to .ino" → raw .ino gets clangd IntelliSense directly as C++; prototype/multi-tab limitations documented.
• "Representative projects pass end-to-end IDE tests" → CI cannot launch Zed (hard DX11 GPU requirement; headless runners). Test the contract instead: assert generated .clangd/.zed/*/DB contents, and run clangd --check=<file> (headless, no editor) against representative AVR/ESP32/ARM/RP2040 projects asserting zero unexpected diagnostics — this exercises the exact include/define/target correctness the IDE depends on.
• "Changing environments refreshes … clangd" → regenerates configs; clangd hot-reloads the DB (~5 s); open buffers may require a manual editor: restart language server (§1.5).
• "Debugger integration" acceptance for milestone 1 → probe-rs-supported targets only.
• Selectors: environment/board persisted in platformio.ini-adjacent state via fbuild picker tasks; "port selector" remains fbuild's device lease machinery (already daemon-owned).

Part 4 — Child-issue list adjustments

Adjustments to the suggested decomposition (others stand as written):

1. Add (new, first): Phase-0 foundations — builtin-include baking + query-driver fix; raw-.ino DB entries; DB freshness; clangd_config.rs editor-neutral refactor. These fix real bugs that also improve today's VS Code flow (feat: generate clangd header configuration for the default platformio.ini env so go-to-definition works #533's original goal).
2. "Decide and implement the Zed fork/GPUI distribution strategy" → re-title: "Decide Phase-4 native-UI strategy (GPUI companion app vs. wait for Zed Visual Extension API)" — fork option removed with rationale (§1.2).
3. "Add safe include-to-library resolution and ambiguous-provider picker" → re-scope as a standalone multi-phase project (header→package index across PlatformIO/Arduino registries); not an MVP gate (§1.7).
4. "Add integrated Serial Monitor" → mostly done (daemon multi-reader + preemption); the child issue is just the generated task + docs.
5. "Add Serial Plotter" → daemon-served web plotter over /ws/serial-monitor (§1.6).
6. "Add debugger integration" → split: milestone 1 probe-rs DAP attach; follow-ups for OpenOCD-bridge/ESP32/AVR.
7. Add (new): multi-tab .ino IntelliSense limitation + prototypes-header option (§1.3.4).
8. Note for "toolbar/selectors/source-tree" issues: blocked on Zed UI extensibility that officially will not arrive "in the near future" — implement their Phase-1 equivalents as tasks/pickers/web pages instead, and keep the original issues parked against the Zed RFC.

Key sources

• Zed extension surface & no-UI status: developing-extensions, Visual Extension API RFC + official response, webview request, no task inputs
• Zed Windows GA: zed.dev/blog/zed-for-windows-is-here · CLI reference · C++/clangd docs · debugger
• Zed relicense (AGPL removed, GPL-3.0-or-later; gpui Apache-2.0): zed#57948
• Fork precedents: Gram (LWN), Zedless, gpui-component
• .ino/clangd ecosystem: arduino-language-server (AGPL), arduino-cli#1800 (prototype gaps), PlatformIO ino-to-cpp FAQ, clangd CDB hot-reload, open-buffer reparse caveat
• fbuild internals: crates/fbuild-cli/src/cli/clangd_config.rs, crates/fbuild-build-engine/src/pipeline/compile.rs:159, crates/fbuild-build-engine/src/compile_database/clang.rs:44, crates/fbuild-build-engine/src/source_scanner.rs:292-352,666, crates/fbuild-serial/src/manager.rs, crates/fbuild-daemon/src/main.rs:140-190

(Researched with Claude Code; repo claims verified against source at main today.)

[zackees]

Direction update (2026-07-15): use the converter's .ino.cpp output for clangd IntelliSense

(Rewritten for clarity.)

Decision from @zackees: fbuild already converts .ino → .cpp with full prototype generation (preprocess_ino_files in crates/fbuild-build-engine/src/source_scanner.rs). Use that converter's output as the basis for clangd IntelliSense. This replaces §1.3 of the previous comment (which fed the raw .ino to clangd and accepted fake "undeclared identifier" errors as a known wart).

The problem in one paragraph

The build never compiles your sketch.ino directly. The converter first generates build/sketch.ino.cpp = a machine-written header (Arduino include + prototypes) followed by a copy of your sketch text, and that file is what gets compiled — and what compile_commands.json points at. But clangd only gives IntelliSense for a file when that file has an entry in compile_commands.json. Your sketch.ino has none, so the file you actually edit gets nothing. And we can't just tell the editor "use the generated file's entry" — clangd analyzes the live text of the file open in your editor, so an entry that names the generated file means your unsaved edits are invisible and every error points into a file you're not looking at.

The fix in one sentence

The generated file is just [machine-written header] + [your sketch text, unchanged] — so save the machine-written header as its own file, and add a compile_commands.json entry that says: "when compiling sketch.ino, treat it as C++ and paste that header in front first" (that's what the compiler flag -include does).

Worked example

Your sketch.ino — note blink() is called before it's defined, which is legal in Arduino only because of generated prototypes:

void loop() { blink(3); }
void blink(int n) { /* ... */ }

What the converter already generates today (build/sketch.ino.cpp):

#include <Arduino.h>
// Auto-generated function prototypes
void loop();
void blink(int n);

#line 1 "sketch.ino"
void loop() { blink(3); }
void blink(int n) { /* ... */ }

New step 1 — the converter also writes the top half to build/sketch.ino.prelude.h (it already has these strings in hand at source_scanner.rs:311-328; use the existing write_if_changed):

#include <Arduino.h>
void loop();
void blink(int n);

New step 2 — the IDE-flavored compile_commands.json gets an entry for the real sketch.ino (same flags as the generated file's entry, two additions), and the generated file's entry is removed so every symbol isn't indexed twice:

{
  "file": "/path/to/sketch.ino",
  "arguments": ["clang++", "--target=xtensa-esp32-elf", "<...same flags...>",
                "-x", "c++", "-include", "build/sketch.ino.prelude.h",
                "-c", "/path/to/sketch.ino"]
}

Result: when you open sketch.ino, clangd compiles exactly what the real build compiles — Arduino.h + prototypes + your code. blink(3) resolves, there are no fake errors, every diagnostic lands on the line you're looking at, and nothing ever asks you to open a generated file. If the prototype generator ever misses a function, the editor and the build fail on the same line — which is exactly what an IDE should do.

Details that matter

• Keeping the prelude fresh: adding a new function means its prototype must appear in the prelude. The fbuild ide file watcher (startup-lifecycle step 8) regenerates it on save; clangd notices the changed header and re-checks automatically. Between your keystroke and the watcher firing there can be a brief moment where a new call-above-definition shows an error — same latency class as the compile-DB reload caveats already noted.
• Multi-tab sketches (was "documented limitation", now solved): the build concatenates primary sketch first, then tabs alphabetically, with prototypes extracted from the whole set. Each tab's prelude = Arduino include + all prototypes + the text of the tabs that come before it in that order. A tab then sees exactly what it would see in the real concatenated build — no more, no less. Minor side effect: symbols from early tabs are indexed via several entries, so go-to-definition can offer two candidates.
• main.cpp present: the converter skips .ino preprocessing entirely (source_scanner.rs:179) — those .ino files aren't in the build, so the IDE emits no entries for them and shows the existing warning.

Two converter bugs found while verifying this (worth their own child issues — they affect builds today, IDE aside)

1. Only the first file gets a #line directive. preprocess_ino_files computes line offsets for every tab but only emits the first (source_scanner.rs:298-336) — compile errors in a secondary tab are reported against the primary sketch's filename with wrong line numbers. Fix: emit #line 1 "<tab>" at each tab boundary.
2. Prototypes are inserted above the user's own #includes and type definitions (source_scanner.rs:314-328). A sketch defining struct MyStruct and a function void draw(MyStruct s) gets a prototype that references MyStruct before it exists — compile error. arduino-cli avoids this by inserting prototypes after the include block. Because editor and build share the artifact, this hits both identically (so IntelliSense stays truthful), but it will bite real sketches.

Plan deltas

• Previous comment §1.3 → replaced by the above. Multi-tab upgraded from limitation to solved.
• Phase 0 item 2 → "converter emits per-sketch/per-tab prelude headers; IDE DB swaps generated-file entries for raw-.ino entries with -x c++ -include <prelude>."
• Acceptance criterion → clangd --check=<sketch.ino> reports the same diagnostics as compiling the generated .ino.cpp — a parity check that runs headlessly in CI.
• Child issues → add the two converter bugs; re-scope the multi-tab issue to per-tab prelude generation.