docs: remove the two remaining em dashes from Cargo.toml comments

- new scripts/docs-check.sh, the pre-publish docs gate:
  rustdoc build with -D warnings (broken intra-doc links and doc lints
  fail locally, docs.rs does not fail on warnings, so this is stricter
  than production), doctests in both feature configurations with a hard
  zero-ignored-assertion (ignored = uncompiled = untested, convention
  16), and a badge scan over the rendered HTML for the stable
  'example-wrap ignore' markup class (tooltip wording varies across
  rustdoc versions, the class does not)
- verified both directions: green on the current tree; a temporary
  scratch ignore block fails the gate at the doctests step
- Cargo.toml exclude gains scripts/ so the helper never ships in the
  package; AGENTS.md verification commands and convention 16 reference
  the gate

AGENTS.md

@@ -244,6 +244,21 @@ 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. The
+    `scripts/docs-check.sh` docs gate automates the whole rule (see
+    below) and also fails on any `ignore` block it finds.
+
 ## Verification Commands
 
 Run these before committing. All must pass.
@@ -258,6 +273,7 @@ cargo test --manifest-path fuzz/shared/Cargo.toml    # fuzz corpus replay: the s
 cargo check --target wasm32-unknown-unknown       # the default crate stays wasm-clean
 cargo clippy --target wasm32-unknown-unknown -- -D warnings
 cargo publish --dry-run --allow-dirty             # before a release
+./scripts/docs-check.sh                           # docs gate: rustdoc -D warnings, zero ignored doctests, no untested badges
 ```
 
 The wasm check is the structural guard for the "default crate is

Cargo.toml

@@ -9,7 +9,7 @@ repository = "https://git.alk.dev/alkdev/alktty"
 readme = "README.md"
 keywords = ["tty", "terminal", "pty", "channels", "alkcall"]
 categories = ["network-programming", "asynchronous"]
-exclude = [".opencode/", "AGENTS.md", "docs/reviews/", "docs/plans/", "docs/sdd_process.md", "fuzz/"]
+exclude = [".opencode/", "AGENTS.md", "scripts/", "docs/reviews/", "docs/plans/", "docs/sdd_process.md", "fuzz/"]
 
 [workspace]
 members = ["."]
@@ -22,7 +22,7 @@ name = "alktty"
 default = []
 # `local` is inherently non-wasm (portable-pty + tokio::process need a real
 # OS). The default crate (no features) targets `wasm32-unknown-unknown`;
-# enabling `local` on wasm is a build error by design — use a real OS for
+# enabling `local` on wasm is a build error by design: use a real OS for
 # the local-process backend. The protocol crate (wire, negotiation,
 # control, backend trait, adapter, session, channels) stays wasm-clean so
 # downstream TS/Python adapters can compile it in a sandbox.
@@ -31,8 +31,8 @@ local = ["dep:portable-pty", "dep:tokio-util", "tokio/process", "tokio/rt-multi-
 [dependencies]
 alkcall = "0.10.1"
 # Minimal, wasm-clean tokio features. `local` adds `process` +
-# `rt-multi-thread` (non-wasm). Do NOT use `features = ["full"]` — it
+# `rt-multi-thread` (non-wasm). Do NOT use `features = ["full"]` (it
-# pulls in `signal`/`fs`/`net` which break `wasm32-unknown-unknown`.
+# pulls in `signal`/`fs`/`net` which break `wasm32-unknown-unknown`).
 tokio = { version = "1", default-features = false, features = ["rt", "sync", "io-util", "macros"] }
 bytes = "1"
 futures = "0.3"

scripts/docs-check.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+# Docs sanity gate: run before a publish (AGENTS.md convention 16).
+# Catches what `cargo doc` alone does not: ignore-marked doc examples,
+# which rustdoc renders with the untested badge that docs.rs surfaces on
+# the crate page (the tooltip "This example is not tested"; the wording
+# varies by rustdoc version, so we grep the stable `example-wrap ignore`
+# markup class instead).
+#
+# 1. rustdoc build with warnings as errors: broken intra-doc links,
+#    broken anchors, and doc lints fail here instead of surfacing on
+#    docs.rs (docs.rs does not fail on warnings, so the local gate is
+#    stricter than production).
+# 2. doctests in both feature configurations, with the rule that zero
+#    doctests are ignored (ignored = uncompiled = untested). The lib
+#    doctest count is expected: 1 compiled (the assembly example), 0
+#    ignored. Feature-gated example bodies compile as empty under
+#    default features and fully under --all-features.
+# 3. badge scan over the rendered HTML: no `example-wrap ignore` markup
+#    and no "example is ... tested" tooltip text anywhere in target/doc.
+set -euo pipefail
+root="$(git rev-parse --show-toplevel)"
+cd "$root"
+
+echo "== rustdoc build, warnings as errors (default features)"
+RUSTDOCFLAGS="-D warnings" cargo doc --no-deps
+
+ignored_count() {
+    echo "$1" | grep -o '[0-9]* ignored' | awk '{s += $1} END {print s + 0}'
+}
+
+for cfg in "" "--all-features"; do
+    label="default features"
+    [ -n "$cfg" ] && label="--all-features"
+    echo "== doctests ($label)"
+    out="$(cargo test --doc $cfg 2>&1)"
+    echo "$out" | grep -E '^test result' | sed "s/^/  $label: /"
+    ignored="$(ignored_count "$out")"
+    if [ "$ignored" != "0" ]; then
+        echo "FAIL: $ignored ignored doctest(s) ($label); convention 16:" \
+             "examples are tested or no_run, never ignore" >&2
+        exit 1
+    fi
+done
+
+echo "== untested-badge scan over target/doc"
+badges="$(grep -rlE 'example-wrap[ "]?ignore|This example is (not |un)?tested' \
+    target/doc/alktty/*.html 2>/dev/null || true)"
+if [ -n "$badges" ]; then
+    echo "FAIL: untested-documentation badge(s) in the rendered docs:" >&2
+    echo "$badges" | sed 's/^/  /' >&2
+    exit 1
+fi
+
+echo "docs-check: ok"

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