Blue is a deterministic document model for typed content, content identity, timeline-driven processing, and document-owned workflow logic.
That sentence is dense because Blue connects ideas that are often split across several systems. A normal application might keep its schema in code, its state in a database, its event history in a queue, its business rules in service handlers, its payment state in a provider dashboard, and its audit trail in logs. Blue gives you a way to put the explainable part of that model into documents: the state, the type references, the accepted timeline evidence, the operations, the workflows, the BEX programs that compute patches, and the emitted events.
The docs are intentionally small, but the pages are not meant to be thin. Read them in order the first time. After that, use the two examples as anchors: Counter for the smallest complete loop, Weekend package checkout for the real-world shape.
| Step | Page | What you should understand after reading it |
|---|---|---|
| 1 | What is Blue? | Why Blue exists and how documents, types, identity, timelines, contracts, and BEX fit together. |
| 2 | Documents and types | How Blue content is structured, how types are ordinary Blue nodes, how extension works, and how schema constraints accumulate. |
| 3 | BlueId | Why identity is based on canonical content and meaning rather than file paths, row ids, or raw YAML text. |
| 4 | Blue directive | How source documents can use authoring conveniences while still producing portable identity-bearing content. |
| 5 | Timelines and contracts | How delivered evidence is accepted by channels, matched by operations, processed by workflows, and recorded by checkpoints. |
| 6 | BEX in contracts | How document-owned deterministic logic returns values, changesets, events, gas, and metrics without external side effects. |
| 7 | Counter | A complete processing loop with one state field, one operation, one Compute step, one emitted event, and a checkpoint. |
| 8 | Weekend package checkout | A realistic offer-to-order flow with an embedded PayNote, merchant order snapshots, confirmation gates, and idempotent BEX guards. |
These docs are explanatory. They are not the normative specification. The source of truth for the Blue Language, Contracts and Processor, BEX, Coordination, and PayNote specifications is the public bluecontract/blue-spec repository.
These docs are also not an exhaustive registry. They show the smallest useful example and one serious example. That is deliberate. Adding five more toy examples would make the docs feel larger while teaching less. Counter teaches the processing loop. Weekend package checkout teaches how the same loop scales to a real business document.
Counter and Weekend package checkout look very different on the surface.
Counter is tiny:
1name: Counter2counter: 03contracts:4 ownerChannel:5 type: Coordination/Timeline Channel6 timelineId: counter-demo
The weekend package is large. It has an offer, a package order template, checkout state, an embedded PayNote, embedded hotel and restaurant orders, component status, payment status, and workflow contracts.
The same processing model applies to both:
1current Blue document2+ delivered timeline entry or lifecycle event3+ matching channel/operation/workflow contracts4+ deterministic BEX Compute steps5= new canonical document + emitted events + gas + checkpoints
That is the most important thing to carry through the docs. Blue is not magic because the YAML is clever. Blue is useful because the state transition can be represented, inspected, replayed, and addressed as Blue content.
Use the reference overview for links to the specification repository, implementation repositories, and the full weekend package source embedded in these docs. The docs should explain enough that you do not need to read the specification first. The specification should be used when you need normative wording, edge cases, conformance behavior, or implementation details.