Diagrams

Diagrams are committed as source + rendered SVG, so they diff, version, and rebuild in CI — unlike a binary format such as Visio's .vsdx (which was considered and rejected: Windows-only, paid, doesn't render on GitHub, no clean diff). The repo-friendly toolchain is three layers:

Layer	Tool	Where it's used
Baseline	Mermaid (inline in Markdown)	every doc — renders natively on GitHub
Technical	C4 model via D2 → SVG	svg/c4-*.svg
Plain/friendly	D2 sketch mode → SVG	svg/plain-flow.svg

The C4 set (technical track)

C4 teaches architecture in zoom levels — the standard for docs that explain a system:

• c4-context.svg — Level 1: WorkWingman and the outside world.
• c4-container.svg — Level 2: the Electron shell, Angular renderer, loopback API, vault, store, and automation browser.
• c4-component.svg — Level 3: inside the API — controllers, core interfaces, services, Flurl/Polly clients, automation, vault, and the dependency doctor.

Overnight build-out diagrams (technical track)

Added alongside the making-of chapter on the overnight multi-agent session:

• hybrid-automation.svg — the hybrid automation flow: Playwright drives (navigation, iframes, fills, the never-submit guard), and on ambiguity consults the IPageAdvisor seam to a Claude-driven PageAgent for a ranked hint, still pausing for the user below the confidence threshold. See architecture.md.
• overnight-orchestration.svg — the multi-agent fan-out: one orchestrator spawning agents across two compute pools (Claude + Codex) into isolated worktrees, every branch through the Codex-review gate, then batched merges to master.

Rebuilding

Install D2 at the version in .d2-version (reproducible output), then:

bash build.sh       # renders all src/*.d2 into svg/

Edit the .d2 source, re-run build.sh, and commit the source and the regenerated SVG together. CI re-renders and fails if a committed SVG is stale (see the diagrams job in .github/workflows/ci.yml).

Source ↔ output

Source	Output	Track
src/c4-context.d2	svg/c4-context.svg	technical
src/c4-container.d2	svg/c4-container.svg	technical
src/c4-component.d2	svg/c4-component.svg	technical
src/hybrid-automation.d2	svg/hybrid-automation.svg	technical
src/overnight-orchestration.d2	svg/overnight-orchestration.svg	technical
src/plain-flow.d2	svg/plain-flow.svg	plain