# Understanding [topic]

> Explanation – the "why" document, Diataxis style. It deepens
> understanding; it does not teach a task or list facts. Both live
> elsewhere and get linked.

## The idea

[What this thing is and why it exists, in plain terms. Anchor it to
something the reader already knows.]

## How it works

[Mechanism at the right altitude: components and their relationships.
A diagram earns its place here.]

```mermaid
flowchart LR
    A[Concept A] --> B[Concept B]
    B --> C[Concept C]
```

## Design decisions and trade-offs

| Decision | Alternative rejected | Why |
|----------|----------------------|-----|
| [choice made] | [alternative] | [reasoning] |

## When you care vs when you don't

- **You care when**: [conditions where this matters operationally]
- **Safe to ignore when**: [conditions where the default is fine]

## Limits and edge cases

[Where the model breaks down, common misconceptions, honest limits.]

## History / context (optional)

[How we got here – often explains odd corners that look arbitrary.]

## See also

- Task version: [how-to link]
- Facts: [reference link]
- Learning path: [tutorial link]