Docs carry spec weight; marketing shows happy paths
Decision. Marketing pages show happy paths. /docs must enumerate every
screen and every state — empty, error, permissions, edge cases —
reference-style.
Why. This split is what prevents the beautiful-facade failure mode: a gorgeous site describing a product nobody actually specced. If a feature’s states aren’t written down, the dreaming isn’t done; it’s decorated.