[schreck61]

What

docs/architecture.md describes how Intersection Lab 0.5.1 is put together:

• Sections 1–5: what the program is, how the code is split into layers, the boundary between ground truth and what controllers see, the crate layout and build targets, module dependencies and the order of one simulation step.
• Section 6: each file in src/sim/: the engine, the road network for every layout, signals, sensors, demand, vehicle classes, statistics, determinism, corridors and the cooperative crossing.
• Sections 7–8: the controller contract, what the simulation does with a controller's request, each controller and the learning code: inputs, the safety shield, the reward, training and model selection, network size and the weights files.
• Section 9: the app's files, its frame loop, the comparison twin and an illustrated tour of the window, panel by panel, including corridors and the cooperative crossing.
• Sections 10–13: entry points, studies and tests; the build, CI and release pipeline; design principles; where to change the code to add a controller, a layout or a sensor.
• Appendix A: how every screenshot was made, so they can be remade when the app changes.

It has 21 Mermaid diagrams, which share one color legend, and 40 screenshots and three figures in docs/images/architecture/. The README and CONTRIBUTING.md link to it.

Also in this change:

• Scripted screenshots: the app accepts TS_OVERLAYS, TS_SELECT, TS_BENCH and TS_SCROLL_LEFT, which the screenshots needed. A scripted screenshot now stops the clock at TS_SHOT_AFTER and waits 600 ms for the panels to catch up, so every capture of a run shows the same moment. None of this does anything unless the variables are set.
• American spelling: "T-junction" is now "T-intersection" everywhere, including the layout's name in the app, and .gitattributes says "Normalize".

Checking the document against the code turned up a few bugs in 0.5.1, which will be fixed in separate pull requests. The document describes 0.5.1 as it is, so §8.7 records one of them: the Hybrid's Save weights writes a file that doesn't load.

Why

Contributors need a map of the code before they change it, and the README only describes the modules briefly. This also covers the documentation_architecture criterion of the OpenSSF Best Practices silver badge.

Testing

• The document was checked claim by claim against the code.
• Every diagram renders without errors in light and dark themes and fits GitHub's page width.
• Every relative link, anchor and image path in the changed files resolves.
• cargo clippy --locked --release --all-targets -- -D warnings, its wasm32 counterpart and cargo test --locked --release pass.