Mental Models

Draft. This piece is scaffolded from the roadmap. The outline below is the shape the finished article will take — headings are real, prose is not.

In one sentence

The model users already hold, and the cost of every place your interface contradicts it.

Why it matters

Where this sits in a production system, what breaks without it, and the class of bug it exists to prevent. Written for someone who has shipped software before but is new to synthesis & modelling.

How it works

The mechanism, from the outside in — the API surface first, then the behaviour underneath it, then the parts you only need when something goes wrong.

// A minimal, runnable example lands here.

In practice

The decisions you actually face: defaults worth keeping, the two or three knobs that matter, and the numbers to reach for when you have nothing to go on.

Common pitfalls

• The mistake almost everyone makes on their first attempt.
• The one that only shows up under production load.
• The one that looks like a model problem but is a data problem.

Further reading

Primary sources — provider docs, papers, and reference implementations — rather than a link farm.