diff --git a/AGENTS.md b/AGENTS.md
index d2f3f6b..3f4d2da 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -244,6 +244,19 @@ implementation agents.
     though en dashes inside numeric ranges keep their normal meaning.
     Hyphens in compound words (`wasm-clean`, `tty-wire`) are untouched.
 
+16. **Doc examples must be compile-checked, never `ignore`.** rustdoc
+    marks ` ```ignore ` blocks with an untested badge that docs.rs
+    surfaces on the crate page (an ⓘ icon with the tooltip "This
+    example is not tested"); `no_run` blocks get no badge, because
+    doctests still compile them. So: prefer a fully tested doctest;
+    otherwise `no_run`. For an example whose body needs a feature, gate
+    the body with hidden cfg lines instead of ignoring the block:
+    `# #[cfg(feature = "local")]` then `# {` and `# }`, so the example
+    compiles (as an empty body) under default features and
+    compile-checks under `--all-features`. Verify with `cargo test`
+    (the doctest run) in both feature configurations; the crate-root
+    assembly example in `src/lib.rs` is the reference pattern.
+
 ## Verification Commands
 
 Run these before committing. All must pass.
diff --git a/src/lib.rs b/src/lib.rs
index 9e15c80..ccbd8cd 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -36,7 +36,9 @@
 //!
 //! # Assembly pattern
 //!
-//! ```ignore
+//! ```no_run
+//! # #[cfg(feature = "local")]
+//! # {
 //! let mut backends = std::collections::HashMap::new();
 //! backends.insert(
 //!     "local".into(),
@@ -44,6 +46,7 @@
 //!         as std::sync::Arc<dyn alktty::TtyBackend>,
 //! );
 //! let tty_adapter = alktty::TtyAdapter::new(backends);
+//! # }
 //! ```
 //!
 //! # Crate-root surface