feat(architecture): open ARCHITECTURE.md with a 3-second Overview

[cheneeheng]

What

ARCHITECTURE.md now opens with a 3-second Overview — one domain sentence plus one linear 3-6 node flow — and the Components diagram is named as that Overview expanded, with the rules and worked example it was missing. Ships as v5.0.3.

Why

The doc began at the diagram set, which answers how a system is built before anything answers what it is. Two follow-on questions drove the rest: whether a fuller "how the whole thing works" diagram was a missing type (it was not — it was the Components diagram drawn thinly), and whether document-architecture being absent from the SessionStart hook was deliberate (it was not — the doc-sync rule fires on implicit mid-turn decisions, which is the hook's own selection rule).

How

No sixth diagram type was added. Adding one would have produced two diagrams with the same nodes and no rule for which carries the detail, so the detail rules went into the existing Components slot instead: label every edge with what crosses it, draw the trust boundary as a subgraph, put stack names on nodes, branch freely. The Overview/Components contrast is stated outright — the Overview is a spine by rule, Components branches wherever the real system does.

That exposed an older overlap between System context and Components, both claiming the externals; System context now earns a separate diagram only when the externals outgrow Components.

A simulation pass over two systems (the shop the examples use, and this repo — no users, no DB, no state machine) broke the skill on the small-system case and added three written-down cases: a system too small for Components, a doc predating the Overview, and a non-user-facing audience. Three rules stated twice each were cut to one statement.

Testing

python tools/validate-plugins/validate.py green. check-semver.py CHANGELOG.md green. The hook payload was round-tripped through json.load to confirm it is still valid single-line JSON after the new block.

Not tested: the Mermaid examples are unrendered — rendering needs a chromium install I did not run. No behavioral eval was run against the skill.

Checklist

• All CI checks pass
• Tests added or updated for new behavior — n/a, docs/skills repo; both validators run
• No any / @ts-ignore / # type: ignore introduced
• No secrets or credentials in code
• Migrations (if any) are backward-compatible — n/a
• ARCHITECTURE.md Key Decisions updated (if a durable decision was made) — n/a, this repo has no ARCHITECTURE.md
• Attribution included if AI tooling assisted

Generated with Claude Code by CEH