Diagrams and a table of contents for the README

[mspinola]

The README had grown to 493 lines with zero diagrams, and the density is not evenly spread: ## Environment alone is 154 lines, 31% of the file, because it absorbed the whole Windows producer topology.

Four diagrams

Each replaces something a reader currently has to assemble from prose.

1. Producer/consumer orientation, at the top. The store is the seam: everything above it is vendor- and box-specific, everything below is identical everywhere.
2. The tier model, previously spread across three sections. Read the arrows as "can be computed from" and the asymmetry is immediate: one arrow into each equity tier, two into propadj. That one picture is the reason futures grew a tier component in the store path, and the reason the producer writes both tiers or fails the symbol.
3. Nightly producer topology, showing what the prose states but does not make obvious: where the retry lives differs per task. Futures retry via a repeating trigger because the gate defers cheaply; equities retry inside the wrapper because they have no cheap defer to fall through to.
4. The finals gate as a loop, with the counterintuitive conclusion called out: a healthy night ends on a non-zero exit, so Last Result is not a health signal.

A worked roll

Real stored values, HE April to June 2025:

                                        Fri 11 Apr   Mon 14 Apr        the day's move
  front contract                            202504       202506
  unadj      as traded                       85.43        95.12    +9.70    +11.35%
  backadj    spread removed, SHIFTED         76.00        77.80    +1.80     +2.37%
  propadj    spread removed, SCALED          77.24        78.73    +1.49     +1.93%

The unadj row is an eleven percent overnight move nobody made. Both adjusted rows remove it and differ in how: backadj subtracts the spread and keeps the point move honest, propadj divides it out and keeps the percentage honest.

Newly measured over HE's full history and stated in the section: the three tiers disagree only on the 2.7% of bars that are roll days. On the other 97.3%, propadj percent returns are identical to as-traded (to 6e-8, float32 storage precision), while backadj is off by a median 0.894 percentage points per day.

Also

A table of contents, since 610 lines is past the point where scrolling to find a section is reasonable.

Mermaid safety

Labels deliberately avoid <b>/<i> and CLI flag text: the former depend on htmlLabels being enabled, and a -- pair inside a label can confuse the lexer. Only <br/> is used.

Verified on the pushed branch that GitHub classifies all four blocks as data-type="mermaid" and creates renderer iframes for them. I could not confirm the final visual render, because the browser pane I have available does not display GitHub reliably. Worth a quick eyeball before merge.

Not done

The structural fix is still available and is probably the bigger win: docs/LINUX_SCHEDULING.md already exists, so Windows scheduling sitting inline in the README is the inconsistency. Extracting it to docs/WINDOWS_SCHEDULING.md would cut roughly 120 lines from the README and match a convention the repo already has. Left alone here because it moves content rather than adding to it.

🤖 Generated with Claude Code