Turn architecture, code walkthrough, and subsystem docs into a code-anchored repository map

[szTheory]

Goal

Make the documentation function like a programmer-oriented table of contents for the entire GUI app: readers should be able to skim from architecture → code walkthrough → subsystem deep dives, recognize important code shapes, understand where behavior lives, and then enter the source with useful bearings.

The point is not to duplicate every source file. It is to help a human contributor or AI workflow effectively "download the codebase map" before reading implementation details individually.

Scope

Apply this consistently across:

• the high-level architecture walkthrough;
• the code walkthrough;
• every subsystem document;
• links and transitions between those layers.

Documentation approach

• Use progressive disclosure: high-level system map first, then important flows, then targeted subsystem detail.
• Include compact, representative code snippets for the most important classes, functions, interfaces/types, commands, adapters, IPC contracts, state shapes, and orchestration paths.
• Prefer snippets that reveal data shape, ownership boundaries, call direction, and transformation flow.
• Attach every snippet/concept to its real source path and symbol so readers can jump directly into implementation.
• Reuse recognizable snippets or signatures across layers when that repetition helps readers connect the dots ("I have seen this shape before; this is where it fits").
• Explain why each excerpt matters immediately around the code block.
• Keep excerpts selective and durable; do not turn docs into a source dump or copy entire implementations.
• Add diagrams/tables only where they materially clarify cross-subsystem flow, dependencies, or ownership.

Acceptance criteria

• Architecture docs provide a skimmable system map and point to the code walkthrough and subsystem deep dives.
• The code walkthrough shows representative code blocks for the primary end-to-end flows and core data shapes.
• Every subsystem doc includes enough representative code to identify its entry points, important types/functions/classes, dependencies, outputs, and failure boundaries.
• Cross-links let readers move from high-level concepts to the exact subsystem, source file, and symbol without searching blindly.
• A contributor can answer "where does this live, what shape does the data have, and what calls what?" for each major subsystem after skimming the docs.
• Code blocks render well on desktop/mobile with useful syntax highlighting and wrapping.
• Documentation verification detects stale source paths/symbol references so the map stays useful as code changes.
• The finished set is useful both for contributor onboarding and for AI development workflows loading targeted codebase context.