From faa1c9ba10280b5c908718579b33af447737aa93 Mon Sep 17 00:00:00 2001
From: "glm-5.3-flash" <glm-5.3-flash@alk.dev>
Date: Mon, 2 Nov 2026 17:51:46 +0000
Subject: [PATCH] docs(lib): assembly example compiles as no_run, not ignore;
 convention 16

- the crate-root assembly example was a ```ignore block, which rustdoc
  renders with the untested badge docs.rs surfaces on the crate page
  (the tooltip 'This example is not tested'); ```no_run blocks are
  compile-checked by doctests and get no badge
- the example body is gated with hidden cfg lines (#[cfg(feature =
  "local")] around a hidden block): empty under default features,
  compile-checked under --all-features; the doctest now passes in both
  cargo test configurations instead of being skipped
- AGENTS.md convention 16 records the rule: doc examples are tested or
  no_run, never ignore; feature-gated bodies via hidden cfg lines

Verification: cargo test (doctest src/lib.rs line 39 now compile-... ok
in default and --all-features); cargo doc --no-deps (no untested badge
in the rendered HTML); clippy --all-targets --all-features -D warnings;
fmt --check; wasm check; fuzz/shared corpus replay (9).
---
 AGENTS.md  | 13 +++++++++++++
 src/lib.rs |  5 ++++-
 2 files changed, 17 insertions(+), 1 deletion(-)

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