diff --git a/docs-site/src/content/docs/guides/idf-workflow.mdx b/docs-site/src/content/docs/guides/idf-workflow.mdx
new file mode 100644
index 0000000..8e4ca97
--- /dev/null
+++ b/docs-site/src/content/docs/guides/idf-workflow.mdx
@@ -0,0 +1,223 @@
+---
+title: IDF Project Workflows
+description: Build, flash, and monitor ESP-IDF projects through MCP tools
+sidebar:
+  order: 8
+---
+
+import { Steps, Aside, Tabs, TabItem, LinkCard } from '@astrojs/starlight/components';
+
+mcesptool wraps ESP-IDF's toolchain management and project build system as MCP tools. This guide walks through the full development cycle: checking your environment, setting up toolchains for a target chip, building, flashing, and monitoring. Each section is self-contained -- jump to the step you need.
+
+## Check your environment
+
+Before building anything, confirm that ESP-IDF is detected and see which toolchains are installed.
+
+<Steps>
+
+1. Get the ESP-IDF path, version, and environment variables:
+
+   ```python
+   result = await client.call_tool("idf_env_info", {})
+   ```
+
+   The response includes `idf_path`, `idf_version`, and the `PATH` additions that ESP-IDF exports. If `success` is `false`, ESP-IDF is not installed or not on the system path.
+
+2. Check which tools are installed vs missing:
+
+   ```python
+   result = await client.call_tool("idf_tools_check", {})
+   ```
+
+   The response lists every tool with its install status. The `installed_count` and `missing_count` fields give a quick summary.
+
+</Steps>
+
+<Aside type="tip">
+You can also read the `esp://idf/status` resource for a quick overview that includes per-target readiness without calling any tools.
+</Aside>
+
+## Set up a new target chip
+
+When you need to build for a chip you have not used before (say, an ESP32-P4), some toolchains may be missing. The RISC-V targets need the `riscv32-esp-elf` toolchain; Xtensa targets need `xtensa-esp-elf`.
+
+<Steps>
+
+1. Check readiness for the specific target:
+
+   ```python
+   result = await client.call_tool("idf_tools_check", {
+       "target": "esp32p4"
+   })
+   ```
+
+   Look at the `target_ready` field. If it is `false`, the `missing_for_target` array tells you exactly which tools are needed.
+
+2. Install the missing tools:
+
+   ```python
+   result = await client.call_tool("idf_tools_install", {
+       "targets": ["esp32p4"]
+   })
+   ```
+
+   This downloads and installs only the tools required for the specified targets. You can pass multiple targets at once (e.g. `["esp32p4", "esp32c6"]`) to install everything in a single operation.
+
+3. Verify the installation:
+
+   ```python
+   result = await client.call_tool("idf_tools_check", {
+       "target": "esp32p4"
+   })
+   # result["target_ready"] should now be true
+   ```
+
+</Steps>
+
+<Aside type="caution">
+Toolchain downloads can be large -- 100MB or more per architecture. The install operation has a 10-minute timeout. On slow connections, install one target at a time.
+</Aside>
+
+## Build a project
+
+With the toolchain in place, build an ESP-IDF project for your target.
+
+```python
+result = await client.call_tool("idf_build_project", {
+    "project_path": "/home/user/esp/my-project",
+    "target": "esp32p4"
+})
+```
+
+The `project_path` must point to a directory containing a `CMakeLists.txt`. The tool runs `idf.py set-target` followed by `idf.py build`.
+
+<Tabs>
+  <TabItem label="Incremental build">
+    The default behavior is an incremental build. CMake only recompiles files that changed since the last build.
+
+    ```python
+    result = await client.call_tool("idf_build_project", {
+        "project_path": "/home/user/esp/my-project",
+        "target": "esp32s3"
+    })
+    ```
+  </TabItem>
+  <TabItem label="Clean build">
+    If you are switching targets or need to start fresh, set `clean` to `true`. This runs `idf.py fullclean` before building.
+
+    ```python
+    result = await client.call_tool("idf_build_project", {
+        "project_path": "/home/user/esp/my-project",
+        "target": "esp32s3",
+        "clean": True
+    })
+    ```
+
+    A clean build is also useful when you see stale object files causing link errors after changing `sdkconfig` options.
+  </TabItem>
+</Tabs>
+
+## Flash to device
+
+Once the build completes, flash it to a connected device.
+
+```python
+result = await client.call_tool("idf_flash_project", {
+    "project_path": "/home/user/esp/my-project",
+    "port": "/dev/ttyUSB0"
+})
+```
+
+The tool runs `idf.py flash` using the build artifacts already in the project's `build/` directory. It flashes the bootloader, partition table, and application binary in one operation.
+
+<Aside type="tip">
+The default baud rate is 460800. If you experience frequent flash failures, drop to a lower rate:
+
+```python
+result = await client.call_tool("idf_flash_project", {
+    "project_path": "/home/user/esp/my-project",
+    "port": "/dev/ttyUSB0",
+    "baud": 115200
+})
+```
+</Aside>
+
+## Monitor output
+
+After flashing, capture the device's serial output to verify it booted correctly.
+
+```python
+result = await client.call_tool("idf_monitor", {
+    "port": "/dev/ttyUSB0",
+    "duration": 15
+})
+```
+
+The tool captures serial output for the specified duration (default 10 seconds, max 60) and returns it as text.
+
+### ELF-based crash decoding
+
+When you provide the `project_path`, IDF monitor uses the built ELF file to decode crash backtraces into source file names and line numbers.
+
+```python
+result = await client.call_tool("idf_monitor", {
+    "port": "/dev/ttyUSB0",
+    "project_path": "/home/user/esp/my-project",
+    "duration": 20
+})
+```
+
+Without `project_path`, backtrace addresses appear as raw hex values. With it, you get output like `app_main.c:42` instead of `0x400d1234`.
+
+## Troubleshoot
+
+### ESP-IDF not detected
+
+If `idf_env_info` returns `success: false`, the IDF path is not set. Common causes:
+
+- ESP-IDF is not installed. Follow the [ESP-IDF Get Started guide](https://docs.espressif.com/projects/esp-idf/en/stable/esp32/get-started/) to install it.
+- The `IDF_PATH` environment variable is not set in the shell where the MCP server runs. Make sure `export.sh` (or `export.bat` on Windows) has been sourced before starting the server.
+
+### Tier 2 tools report "environment not available"
+
+The build, flash, and monitor tools require a fully configured IDF environment. If they fail with this error:
+
+<Steps>
+
+1. Run `idf_tools_check` to see what is missing.
+
+2. Run `idf_tools_install` with the appropriate targets.
+
+3. Restart the MCP server so the updated PATH takes effect.
+
+</Steps>
+
+### Missing tools for a target
+
+When `idf_tools_check` shows `target_ready: false`, the specific toolchain for that chip architecture is not installed. RISC-V targets (esp32c2, esp32c3, esp32c5, esp32c6, esp32c61, esp32h2, esp32p4) need `riscv32-esp-elf`. Xtensa targets (esp32, esp32s2, esp32s3) need `xtensa-esp-elf`. Run `idf_tools_install` with the target name and the correct toolchain is resolved automatically.
+
+### Build failures after switching targets
+
+If you change the `target` parameter without cleaning the build directory, CMake may fail with configuration errors. Use a clean build:
+
+```python
+result = await client.call_tool("idf_build_project", {
+    "project_path": "/home/user/esp/my-project",
+    "target": "esp32c6",
+    "clean": True
+})
+```
+
+### Flash connection failures
+
+If flashing fails with a connection timeout:
+
+- Confirm the device is in download mode. Most dev boards enter download mode automatically, but some require holding the BOOT button during reset.
+- Check the serial port path. Use `esp_detect_ports` to list connected devices.
+- Try a lower baud rate. Long USB cables or cheap adapters may not sustain 460800 baud reliably.
+
+<LinkCard
+  title="IDF Integration Reference"
+  description="Full parameter details for all IDF toolchain and project workflow tools."
+  href="/reference/idf-integration/"
+/>