blueprint-authoringlisted

# Blueprint Authoring A blueprint is the **whole product's desired end state as a technical contract** — detailed enough that `plan` and `execute` *decide* instead of asking or assuming. It is organized around **flows** (the primary unit, under `docs/blueprint/flows/`), which carry the process — steps, screens, jobs, and acceptance. Entities (`docs/blueprint/entities/`) are supporting data contracts (an `index.md` + an authoritative `schema.yaml`), and each service's API is one authoritative OpenAPI file under `docs/blueprint/apis/`. The traceability spine runs product goal → flow (`Serves:`) → entity (`Used by:`, transitively). The bar: a blueprint records every decision that has **more than one reasonable answer** AND is **true regardless of how the code is written today**. Everything else belongs to `plan` (code-aware realization) or `execute` (mechanical). Read **Contract vs realization** first — it is the line the whole skill turns on. Two bars, not one. Completeness asks *"is this decided?"* and can only ask for more; **Density** asks *"does this line change what gets built?"* and is the only thing that asks for less. A doc fails review for being long exactly as it fails for being thin. Every audience for these docs is an agent that re-reads them on every turn — write for that reader, not for a human skimming a spec. | Topic | When to read