Clarify docs, examples, and integration notes

Update documentation and small API docs to clarify integration and example policy:

- Mark publishability roadmap as completed and add detailed progress/remaining notes (PUBLISHABILITY_ROADMAP.md).
- Explain that examples are repo-only due to Xtensa flashing/toolchain requirements (README.md).
- Add DHCP link troubleshooting guidance to examples README (apps/examples/README.md).
- Tweak module doc comments to reference feature-gated esp-hal/integration facades (src/boards/mod.rs, src/driver/mod.rs).

These changes improve discoverability and reduce confusion about example packaging and integration feature flags.

Author: swgiacomelli

PUBLISHABILITY_ROADMAP.md

@@ -111,9 +111,11 @@ Last updated: 2026-02-08
 
 **Goal**: Present a clear, minimal integration story with current examples and docs.
 
+**Status**: ✅ Completed
+
 **Work items**
 - **Root documentation pass**
-  - Add “happy path” snippets for esp-hal (WT32-ETH01), embassy-net, and smoltcp.
+  - Add “happy path” snippets for esp-hal (WT32-ETH01) and esp-hal async.
   - Add a concise **feature-flag matrix** (what each flag unlocks).
   - Add a **memory/footprint** section (DMA descriptor counts, buffer sizes, defaults).
   - Ensure all docs use the correct crate name and current API (no legacy references).
@@ -125,6 +127,20 @@ Last updated: 2026-02-08
   - Document the decision to keep examples repo-only (or spin out a separate examples crate).
   - If repo-only, add a short “why” and link from the root README.
 
+**Progress**
+- Rebuilt the root README around the esp-hal happy path (sync + async) and added a memory sizing section.
+- Added a docs index (`docs/README.md`) and rewrote `/docs` to the current standards.
+- Normalized crate name references across docs and module-level rustdocs.
+- Updated `apps/examples/README.md`, `apps/qa-runner/README.md`, `apps/README.md`, and `xtask/README.md`.
+- Updated CI fmt/doc to target the root manifest only (avoids non-crate apps/ issues).
+- Added a short “repo-only examples” rationale to the root README.
+- Added a DHCP/link troubleshooting note to the examples README.
+- Confirmed `cargo doc --no-deps` builds cleanly.
+- Kept embassy-net/smoltcp snippets in the example docs (not in the root README).
+
+**Work remaining**
+- None.
+
 **Exit criteria**
 - Docs build cleanly with `cargo doc --no-deps`.
 - Example and integration-test READMEs are accurate, minimal, and up-to-date.

README.md

@@ -136,6 +136,8 @@ See [xtask/README.md](xtask/README.md) for details.
 
 Examples are provided as a **separate crate** in this repository and are not
 packaged with the published library crate.
+They require the Xtensa toolchain and flashing setup, so they are kept repo-only
+to avoid pulling those requirements into crates.io consumers.
 
 See [apps/examples/README.md](apps/examples/README.md) for build and run
 instructions.

apps/examples/README.md

@@ -56,6 +56,12 @@ $env:ESPFLASH_BAUD = "921600"
 All examples default to the WT32-ETH01 board (LAN8720A, external 50 MHz clock).
 If you use different hardware, adjust the constants at the top of the example.
 
+## Troubleshooting
+
+- **DHCP takes too long or never assigns**: confirm link is up, give it 10–30s,
+  and ensure your network allows broadcast/multicast. If still stuck, power-cycle
+  the board and retry.
+
 ## Related
 
 - `apps/qa-runner/` for hardware QA runs

src/boards/mod.rs

@@ -15,7 +15,7 @@
 //!
 //! # See Also
 //!
-//! - [`crate::integration::esp_hal`] - esp-hal facade helpers
+//! - esp-hal facade helpers (feature-gated `esp-hal` module at crate root)
 
 #[cfg(feature = "esp32")]
 #[cfg_attr(docsrs, doc(cfg(feature = "esp32")))]

src/driver/mod.rs

@@ -25,7 +25,7 @@
 //!
 //! # See Also
 //!
-//! - [`crate::integration`] - stack and runtime facades
+//! - Integration facades (feature-gated modules under `integration`)
 
 // Submodules
 pub mod config;