@@ -116,6 +116,21 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
+      - name: Tracked text files are LF in the index
+        # .gitattributes declares `text=auto eol=lf`; this holds the line.
+        # A CRLF file sneaking into the index breaks `#!` shebangs on Linux
+        # and produces whole-file whitespace diffs. `git ls-files --eol`
+        # reports the INDEX encoding (i/...), independent of the runner's OS.
+        working-directory: .
+        run: |
+          bad=$(git ls-files --eol | grep -E '^i/(crlf|mixed)' || true)
+          if [ -n "$bad" ]; then
+            echo "::error::tracked files with CRLF/mixed line endings in the index:"
+            echo "$bad"
+            exit 1
+          fi
+          echo "index is LF-clean ($(git ls-files --eol | grep -c '^i/lf') text files)"
+
       - name: Install uv
         uses: astral-sh/setup-uv@v5
         with:
 
@@ -5,6 +5,9 @@ here. Strike through or delete when done; the LOG records what happened.
 
 ## Hardware (the gate everything else waits on)
 
+- [ ] **Run `uv run pytest -m hardware tests/test_hardware_rx_smoke.py -v`
+      on the bench.** Written 2026-10-24 without a board; the first run is
+      its validation. Set `SDR_DSP_TEST_FM_HZ` to a local station.
 - [ ] **Wired one-way TX bench test** of the FSK packet chain
       (`examples/two_station_link.py`). Everything digital, TX and protocol
       is software-only until this runs (REFERENCE §12).
@@ -37,8 +40,8 @@ here. Strike through or delete when done; the LOG records what happened.
       are unannotated (~350 errors under `disallow_untyped_defs`). Enable the
       strict flags per module as each is annotated; until then the marker
       overpromises, exactly the hackrfpy pre-1.1.0 situation.
-- [ ] Line-ending normalization: `.gitattributes` is committed, the
-      `git add --renormalize .` commit has not been made. Do it alone.
+- [x] Line-ending normalization: the index was already LF-clean
+      (`git ls-files --eol`); CI now guards it. No renormalize commit needed.
 
 ## Repo hygiene
 
 
@@ -38,7 +38,18 @@
 )
 from .sources import IQSource, ArraySource, FileSource
 
-__version__ = "0.1.0"
+# Resolved from the installed package metadata (pyproject.toml is the single
+# source of truth), with a fallback for an uninstalled checkout. A hard-coded
+# string here had drifted to 0.1.0 while pyproject said 0.2.0.
+try:
+    from importlib.metadata import version as _pkg_version, PackageNotFoundError
+    try:
+        __version__ = _pkg_version("sdr_dsp")
+    except PackageNotFoundError:          # pragma: no cover - uninstalled tree
+        __version__ = "0.0.0+unknown"
+    del _pkg_version, PackageNotFoundError
+except ImportError:                       # pragma: no cover
+    __version__ = "0.0.0+unknown"
 
 # io, sinks, stream, link and Pipeline are imported LAZILY (PEP 562) so that importing
 # the package -- or a submodule like `from sdr_dsp.core import demod` -- never
 
@@ -49,6 +49,7 @@ def __init__(self, iq: np.ndarray, sample_rate: float,
         self.block_size = int(block_size)
 
     def blocks(self) -> Iterator[np.ndarray]:
+        """Yield the array in consecutive ``block_size`` slices (last may be short)."""
         n = len(self.iq)
         for start in range(0, n, self.block_size):
             yield self.iq[start:start + self.block_size]
 
@@ -76,6 +76,7 @@ def __init__(self, taps):
         self._tail: np.ndarray | None = None
 
     def reset(self) -> None:
+        """Forget all carried history, e.g. after a retune or a stream restart."""
         self._tail = None
 
     def __call__(self, block):
@@ -107,6 +108,7 @@ def __init__(self, factor):
         self._skip = 0           # samples to drop at the start of the next block
 
     def reset(self) -> None:
+        """Forget all carried history, e.g. after a retune or a stream restart."""
         self._skip = 0
 
     def __call__(self, block):
@@ -137,6 +139,7 @@ def __init__(self, shift_hz, sample_rate):
         self._n0 = 0
 
     def reset(self) -> None:
+        """Forget all carried history, e.g. after a retune or a stream restart."""
         self._n0 = 0
 
     def __call__(self, block):
@@ -174,6 +177,7 @@ def __init__(self, deviation_hz=None, sample_rate=None):
         self._prev: np.ndarray | None = None
 
     def reset(self) -> None:
+        """Forget all carried history, e.g. after a retune or a stream restart."""
         self._prev = None
 
     def __call__(self, block):
@@ -234,6 +238,7 @@ def latency_samples(self) -> int:
         return self.ahead
 
     def reset(self) -> None:
+        """Forget all carried history, e.g. after a retune or a stream restart."""
         self._buf = None
         self._started = False
 
@@ -305,6 +310,7 @@ def __init__(self, sample_rate, tau_us=75.0):
         self._y_prev = 0.0
 
     def reset(self) -> None:
+        """Forget all carried history, e.g. after a retune or a stream restart."""
         self._y_prev = 0.0
 
     def __call__(self, block):
 
@@ -0,0 +1,185 @@
+"""Run every file-mode and synthetic example's main() end to end.
+
+test_examples_smoke.py proves each example PARSES and IMPORTS. About half of
+them had nothing beyond that: argparse surfaces, file loading, the pipeline
+glue, and the output writers of am_receiver, ook_decoder, inspect_capture,
+iq_basics, waterfall and friends never executed under test. This runs each one
+as a subprocess the way a user would, with the smallest arguments that still
+exercise the real path:
+
+* file-based examples get a short synthetic SigMF capture written by this test
+  (an FM station, an OOK burst train, an AM carrier), so no sample_data or
+  hardware is needed;
+* plotting examples run with MPLBACKEND=Agg, where plt.show() is a no-op, so
+  figures are built but never block;
+* anything that needs a radio is excluded by name -- the stub-radio adapter
+  tests cover that seam.
+
+A non-zero exit, a traceback, or a 120 s timeout fails the example. These are
+smoke tests: they assert the run completed and produced its declared output,
+not the DSP (the core tests and test_examples_demods do that).
+"""
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+import numpy as np
+import pytest
+
+from sdr_dsp.io import save_iq
+from sdr_dsp.core import ook_modulate
+
+EXAMPLES = Path(__file__).resolve().parent.parent / "examples"
+TIMEOUT = 120
+
+# Examples that need a radio, a sound device, or an interactive window loop
+# with no non-interactive mode. Each is covered elsewhere or by name here so
+# the list is explicit, not a silent omission.
+NEEDS_HARDWARE = {
+    "hackrf_capture.py",       # adapter: tests/test_hackrf_adapter_stub.py
+    "hackrf_sink.py",          # TX adapter: tests/test_tx_sink.py
+    "live_433_capture.py", "live_spectrum.py", "live_fm_listen.py",
+    "collect_sample_data.py",  # tests/test_collect_sample_data.py
+    "fm_band_explorer.py",     # interactive UI; tests/test_fm_band_explorer.py
+    "sdr_adapter_template.py", # a template, exercised by tests/test_modularity.py
+}
+
+
+# ---------------------------------------------------------------------------
+# synthetic captures (cf32 SigMF, which load_iq reads like any capture)
+# ---------------------------------------------------------------------------
+
+@pytest.fixture(scope="module")
+def captures(tmp_path_factory):
+    d = tmp_path_factory.mktemp("captures")
+    rng = np.random.default_rng(0)
+
+    # FM: 1 kHz tone, 75 kHz deviation, 2 Msps, 0.25 s, a touch of noise
+    fs = 2_000_000
+    n = fs // 4
+    t = np.arange(n) / fs
+    msg = np.sin(2 * np.pi * 1000 * t)
+    fm = 0.5 * np.exp(1j * 2 * np.pi * 75e3 * np.cumsum(msg) / fs)
+    fm += 0.005 * (rng.standard_normal(n) + 1j * rng.standard_normal(n))
+    fm_path = d / "fm.sigmf-data"
+    save_iq(fm_path, fm.astype(np.complex64), fs, center_freq=100e6)
+
+    # OOK: a few bursts of a 1 kbaud pattern at 250 ksps
+    fs_ook = 250_000
+    sps = 250
+    bits = np.array([1, 0, 1, 1, 0, 0, 1, 0] * 4)
+    burst = ook_modulate(bits, sps)
+    gap = np.zeros(20 * sps, dtype=np.complex64)
+    ook = np.concatenate([gap, burst, gap, burst, gap]).astype(np.complex64)
+    ook += 0.01 * (rng.standard_normal(len(ook))
+                   + 1j * rng.standard_normal(len(ook))).astype(np.complex64)
+    ook_path = d / "ook.sigmf-data"
+    save_iq(ook_path, ook, fs_ook, center_freq=433.92e6)
+
+    # AM: carrier at +50 kHz offset, 60% modulation by a 700 Hz tone
+    fs_am = 500_000
+    n = fs_am // 2
+    t = np.arange(n) / fs_am
+    am = (1 + 0.6 * np.sin(2 * np.pi * 700 * t)) * np.exp(1j * 2 * np.pi * 50e3 * t)
+    am = 0.4 * am + 0.005 * (rng.standard_normal(n) + 1j * rng.standard_normal(n))
+    am_path = d / "am.sigmf-data"
+    save_iq(am_path, am.astype(np.complex64), fs_am, center_freq=1e6)
+
+    return {"fm": str(fm_path), "ook": str(ook_path), "am": str(am_path),
+            "dir": d}
+
+
+# ---------------------------------------------------------------------------
+# the table: example -> argv (callables receive the captures dict)
+# ---------------------------------------------------------------------------
+
+CASES = {
+    # file-based receivers / inspectors
+    "am_receiver.py": lambda c: [c["am"], "--tune", "50000", "--out",
+                                 str(c["dir"] / "am.wav")],
+    "fm_receiver.py": lambda c: [c["fm"], "--out", str(c["dir"] / "fm.wav")],
+    "ook_decoder.py": lambda c: [c["ook"]],
+    "inspect_capture.py": lambda c: [c["fm"], "--max-samples", "200000"],
+    "signal_survey.py": lambda c: [c["fm"], c["ook"]],
+    "spectrum_analyzer.py": lambda c: [c["fm"], "--no-plot"],
+    "waterfall.py": lambda c: [c["fm"], "--max-samples", "200000"],
+    "burst_detector.py": lambda c: [c["ook"]],
+    "annotate_bursts.py": lambda c: [c["ook"], "--out",
+                                     str(c["dir"] / "annotated.sigmf-data")],
+    "channelizer.py": lambda c: [c["fm"]],
+    "channel_sweep.py": lambda c: ["--scheme", "fsk", "--msg", "HI"],
+    "power_calibration.py": lambda c: ["--save", str(c["dir"] / "cal.json")],
+    "live_pipeline_fm.py": lambda c: [c["fm"], "--block", "50000"],
+    "cfo_demo.py": lambda c: [c["fm"], "--correct"],
+    "dc_offset_demo.py": lambda c: [c["fm"]],
+    "filter_explorer.py": lambda c: [c["fm"]],
+    "iq_basics.py": lambda c: [c["fm"], "--samples", "500"],
+    # synthetic / teaching demos (no file)
+    "constellation_recovery.py": lambda c: ["--nsym", "300"],
+    "decimation_stages.py": lambda c: ["--n", "100000"],
+    "impairment_extraction.py": lambda c: [],
+    "matched_filter_demo.py": lambda c: ["--total", "2000"],
+    "nyquist_aliasing_demo.py": lambda c: [],
+    "resampler_benchmark.py": lambda c: ["--n", "50000"],
+    "spectrogram_chirp.py": lambda c: ["--dur", "0.02"],
+    "windowing_demo.py": lambda c: [],
+    "agc_demo.py": lambda c: [],
+    "modulate_demo.py": lambda c: [],
+    "differential_psk_demo.py": lambda c: [],
+    "dsss_demo.py": lambda c: [],
+    "fhss_visualizer.py": lambda c: [],
+    "cw_decoder.py": lambda c: [],
+    "fsk_decoder.py": lambda c: [],
+    "nask_decoder.py": lambda c: [],
+    "ssb_receiver.py": lambda c: [],
+    "dsb_sc_demo.py": lambda c: [],
+    "packet_loopback.py": lambda c: [],
+    "two_station_link.py": lambda c: [],
+    "transmit_examples.py": lambda c: [],
+}
+
+
+def test_every_example_is_either_run_or_explicitly_excluded():
+    """No example may fall through the cracks: each is in CASES or in
+    NEEDS_HARDWARE with a reason. Adding an example without deciding which is
+    a failure, on purpose."""
+    names = {p.name for p in EXAMPLES.glob("*.py")}
+    covered = set(CASES) | NEEDS_HARDWARE
+    missing = sorted(names - covered)
+    assert not missing, f"examples with no run test and no exclusion: {missing}"
+    stale = sorted(covered - names)
+    assert not stale, f"CASES/NEEDS_HARDWARE name files that do not exist: {stale}"
+
+
+def _run(path, argv, cwd):
+    env = dict(os.environ, MPLBACKEND="Agg", PYTHONUNBUFFERED="1")
+    env.pop("DISPLAY", None)
+    return subprocess.run([sys.executable, str(path), *argv], cwd=cwd,
+                          capture_output=True, text=True, timeout=TIMEOUT,
+                          env=env)
+
+
+@pytest.mark.parametrize("name", sorted(CASES), ids=lambda n: n)
+def test_example_runs_to_completion(name, captures, tmp_path):
+    path = EXAMPLES / name
+    argv = CASES[name](captures)
+    if "matplotlib" in path.read_text() and not pytest.importorskip("matplotlib"):
+        pytest.skip("matplotlib not installed")
+    try:
+        r = _run(path, argv, cwd=tmp_path)
+    except subprocess.TimeoutExpired:
+        pytest.fail(f"{name} did not finish in {TIMEOUT}s with args {argv}")
+    if r.returncode != 0:
+        tail = "\n".join((r.stderr or r.stdout).strip().splitlines()[-12:])
+        pytest.fail(f"{name} exited {r.returncode} with args {argv}:\n{tail}")
+    assert "Traceback" not in r.stderr, r.stderr[-800:]
+
+
+def test_am_receiver_wrote_audio(captures):
+    out = captures["dir"] / "am.wav"
+    if not out.exists():        # the run test for am_receiver.py creates it
+        _run(EXAMPLES / "am_receiver.py", CASES["am_receiver.py"](captures),
+             cwd=captures["dir"])
+    assert out.exists() and out.stat().st_size > 1000
@@ -7,11 +7,17 @@
 the hackrfpy stream path underneath all run for real, with no hardware.
 
 The ramp has I even and Q odd, and the stub writes it in deliberately
-odd-sized flushed pieces, so a single dropped byte anywhere shows up as every
+odd-sized flushed pieces with a pause after each, so the parent's read1() sees
+the odd piece on its own and a single dropped byte anywhere shows up as every
 later sample having I and Q exchanged -- a capture whose power statistics look
 fine while its phase is garbage. hackrfpy < 1.1.1 does exactly that in
-``PersistentReceiver.blocks()``; the xfail flips to a hard failure (strict)
-when the fixed hackrfpy is installed, which is the signal to delete the mark.
+``PersistentReceiver.blocks()``.
+
+Whether the old code actually misbehaves on a given run depends on how the OS
+delivers pipe writes (macOS coalesced them in CI and the bug never fired), so
+the alignment assertion is SKIPPED, not xfailed, on the old hackrfpy: a
+timing-dependent bug trigger must not be a strict expectation. Once the dev
+group pins hackrfpy >= 1.1.1 the skip disappears and the assertion runs.
 """
 
 import os
@@ -39,6 +45,8 @@
     n = sizes[k % len(sizes)]; k += 1
     sys.stdout.buffer.write(raw[pos:pos + n]); pos += n
     sys.stdout.buffer.flush()
+    if n % 2:
+        time.sleep(0.02)   # let the parent read the odd piece by itself
 time.sleep(10)        # stay alive until the parent interrupts us
 '''
 
@@ -82,29 +90,29 @@ def _version_tuple(v):
         return (0, 0, 0)
 
 
-needs_fixed_hackrfpy = pytest.mark.xfail(
-    _version_tuple(hackrfpy.__version__) < (1, 1, 1), strict=True,
+needs_fixed_hackrfpy = pytest.mark.skipif(
+    _version_tuple(hackrfpy.__version__) < (1, 1, 1),
     reason="hackrfpy < 1.1.1: PersistentReceiver.blocks() drops an odd byte "
-           "and swaps I/Q for the rest of the stream")
+           "and swaps I/Q for the rest of the stream (fixed in 1.1.1)")
 
 
 def test_adapter_satisfies_iqsource(stub_tools_dir, HackRFCapture):
     from sdr_dsp.sources.base import IQSource
-    src = HackRFCapture(100e6, 2e6, tools_dir=stub_tools_dir)
+    src = HackRFCapture(100e6, 8e6, tools_dir=stub_tools_dir)
     assert isinstance(src, IQSource)
-    assert src.sample_rate == 2e6 and src.center_freq == 100e6
+    assert src.sample_rate == 8e6 and src.center_freq == 100e6
 
 
 def test_adapter_requires_context_manager(stub_tools_dir, HackRFCapture):
-    src = HackRFCapture(100e6, 2e6, tools_dir=stub_tools_dir)
+    src = HackRFCapture(100e6, 8e6, tools_dir=stub_tools_dir)
     with pytest.raises(RuntimeError):
         next(src.blocks())
     with pytest.raises(RuntimeError):
         src.read(10)
 
 
 def test_adapter_read_is_exact_and_pair_aligned(stub_tools_dir, HackRFCapture):
-    with HackRFCapture(100e6, 2e6, tools_dir=stub_tools_dir) as src:
+    with HackRFCapture(100e6, 8e6, tools_dir=stub_tools_dir) as src:
         a = src.read(1000)
         b = src.read(70_000)
     assert len(a) == 1000 and len(b) == 70_000
@@ -116,7 +124,7 @@ def test_adapter_read_is_exact_and_pair_aligned(stub_tools_dir, HackRFCapture):
 def test_adapter_blocks_are_pair_aligned_across_odd_pipe_chunks(stub_tools_dir,
                                                                  HackRFCapture):
     got = []
-    with HackRFCapture(100e6, 2e6, tools_dir=stub_tools_dir) as src:
+    with HackRFCapture(100e6, 8e6, tools_dir=stub_tools_dir) as src:
         for blk in src.blocks():
             assert blk.dtype == np.complex64
             got.append(blk)
@@ -126,7 +134,7 @@ def test_adapter_blocks_are_pair_aligned_across_odd_pipe_chunks(stub_tools_dir,
 
 
 def test_adapter_capture_array_convenience(stub_tools_dir, HackRFCapture):
-    src = HackRFCapture(100e6, 2e6, tools_dir=stub_tools_dir)
+    src = HackRFCapture(100e6, 8e6, tools_dir=stub_tools_dir)
     x = src.capture_array(5000)
     assert len(x) == 5000
     _check_ramp(x)
@@ -140,7 +148,7 @@ def test_adapter_drives_a_streaming_pipeline(stub_tools_dir, HackRFCapture):
     from sdr_dsp.stream import StreamingFIR
     taps = design_lowpass(200e3, 2e6, num_taps=33)
     seen = []
-    with HackRFCapture(100e6, 2e6, tools_dir=stub_tools_dir, block_size=4096) as src:
+    with HackRFCapture(100e6, 8e6, tools_dir=stub_tools_dir, block_size=4096) as src:
         class _Bounded:
             sample_rate, center_freq = src.sample_rate, src.center_freq
             def blocks(self):