📌 Issue: Clarify Role of `lib.rs` in EMBP and Export Strategies

### 📌 Issue: Clarify Role of `lib.rs` in EMBP and Export Strategies

**Summary:**
The current Explicit Module Boundary Pattern (EMBP) documentation is excellent, but does not clearly address the specific role of `lib.rs` in crate architecture. In practice, `lib.rs` acts as the top-level `mod.rs`, and the decision between `pub mod xyz;` vs `mod xyz; pub use ...` is nuanced and worth formalizing.

---

### ✅ Proposal

Update the EMBP guide to include:

#### 1. **Explicit treatment of `lib.rs` as a crate-wide gateway**

* Equivalent to `mod.rs` at the crate root
* All crate-level public exports should be managed here

#### 2. **Guidance on `pub mod xyz;` vs `pub use xyz::...;`**

* `pub mod xyz;` → Use when you want to preserve a feature boundary (`crate::metrics::init_metrics()`)
* `pub use xyz::...;` → Use when you want to flatten crate API (`crate::init_metrics()`)

#### 3. **When to hoist vs preserve submodule namespaces**

* Hoist: core API or ergonomic primitives
* Preserve: feature modules, subsystems

#### 4. **Implications for binary crates using the library**

* Clarify how `pub mod xyz;` enables `main.rs` or integration tests to use internal modules cleanly

---

### ✍️ Suggested Section Title:

> 📚 `lib.rs` as a Crate-Level Gateway (EMBP Root Pattern)