rf-primer: time-distribution chapter + chain animation; land the bf-constellation GIF

[josephnef]

Docs + animations, two threads:

rf-primer §10 — "One clock for many radios"

A zero-background walk through the time-sync machinery, in the primer's picture-book voice:

• why crystals disagree (ppm → milliseconds within minutes) and what breaks
• the core reframe: sync is a timestamping problem — software notes wobble by hundreds of µs; the whole game is hardware taking the notes at the wire/antenna
• the chain, link by link: PTP over Ethernet (PHY timestamps, the PHC as "GPS over the LAN") → the Wi-Fi TSF servoed to the wire (~290 ns, its own 1 µs floor) → hardware beacons (stamped at the antenna, latched at arrival, both in silicon → ~0.3 µs station lock from listening alone) → the TBTT pin (why the schedule needs its own actuator, and why it must not jump the clock it serves — ~1 µs held)
• the honest end-to-end budget and links into time-distribution.md for every number

New animation (tools/timesync_chain_gif.py → docs/img/timesync_chain.gif, house monitor style): a four-act loop over three clock lanes — free-running drift, PTP pulses pulling the AP comb onto the wire grid, beacons dragging the station in (with a ghosted software-stamp scatter as the counter-example), and the pin snapping the beacon flags onto the disciplined grid while all three counters converge. A red→amber→green residual sparkline runs underneath. Chosen from a brainstorm of four concepts; the runners-up (software-vs-hardware histogram, the "pin slides the flag vs cuts the tape" close-up) are folded in as act-3's ghost scatter and act-4's pin moment.

The strayed beamforming constellation lands

tools/bf_constellation_gif.py → docs/img/bf_constellation.gif finds its natural home in docs/beamforming-self-sounding.md, immediately after the SU report-decode section it visualizes: per-subcarrier h_B/h_A on the complex plane (unit circle = TX antennas balanced, arc = the channel's frequency signature, per-tone sweep readout), with a caption tying it to the decode math and noting what a multipath channel would do to the arc.

Doc-only + tools; ctest 17/17.

🤖 Generated with Claude Code

[josephnef]

Reworked the animation per feedback: the AP and STATION lanes now open up to the Wi-Fi MAC internals on the radio hop — TSF COUNTER → TBTT COMPARE (TSF % interval == off → fire) → RSVD PAGE beacon with the TS field visibly written at egress → antenna, and station-side the tsfl LATCH freezing the local clock at arrival, feeding the (beacon TS, tsfl) pairs into the fit. Act 4 shows the pin as the hardware sees it: the comparator offset walking to zero while the TSF counter runs unbroken (all three lane counters end up reading the same second). Canvas grew to 920×700; primer caption updated.