[Theauxm]

The README explains what Trax is for before it shows any code

Background

Most people meet Trax on the GitHub repository page, not the docs. Until now the README was
kept minimal: badges, the template commands, a train snippet, the folder table, the colour key.
That suited someone who already knew what a train was, but it left a newcomer with no idea what
problem Trax solves or which part of the work is theirs.

Problem

⬛ The first screen doesn't say what Trax is for
It opens with badges and dotnet new. The one-line pitch is there, but nothing shows a client
sending a move and the server deciding.

⬛ The example shows a train and nothing else
RecalculateLeaderboardTrain is a chain of two junctions. It doesn't show a state machine,
a rule, a guard or a refusal, which is the part that sets Trax apart from a job runner.

⬛ There's no list of what it does
The folder table says where things live, not what you get. The samples, which are the
quickest way to see Trax working, are a single link.

Example

What a visitor sees, top to bottom:

Before	After
Title and five badges	Centred logo, tagline, nav links (Quick start, Trax in five minutes, Docs, the book, Samples), badges
One-line pitch	The figure of how a move is checked, then a paragraph on what Trax is
Install	Quick start: the template commands plus dotnet run and the URLs it serves
	What you write, and what Trax does: the table from the intro
A two-junction train	The book's checkout rules and its PlaceOrderTrain, then what a client gets back: NO_TRANSITION, FORBIDDEN, GUARD_FAILED with "Choose how to pay."
	Features: eight bold one-liners, each checked against the docs
Link to Trax.Samples	StateMachine and Recovery screenshots, and a line each for Board, ChatService, Scheduling and DistributedWorkers
Where this fits, colour key	Where this fits unchanged; the colour key collapsed into a <details>
Sponsors, Contributing, License	Unchanged

How this solves it

⬛ Lead with the idea, then the split, then the code
The figure and the paragraph say what Trax is for. The table says which parts the reader
writes. The example shows that code and what Trax does with it. Everything below that is
reference material for someone who's already interested.

flowchart TD
    H["Header: logo, tagline, links"] --> F["Figure: how a move is checked"]
    F --> Q["Quick start"]
    Q --> S["You write / Trax does"]
    S --> E["Example: checkout rules + PlaceOrder train"]
    E --> Feat["Features"]
    Feat --> Sam["Samples"]
    Sam --> W["Where this fits"]
    class H,F,Q,S,E,Feat,Sam,W tooling
    classDef tooling fill:#334155,stroke:#0f172a,color:#fff

Loading

⬛ Nothing in it is new code
The logo is the site's icon, the figure comes from the docs, the screenshots come from the
samples and the snippets are trimmed from the book's Shopfront. Every relative link was
checked against the branch.

Architectural hinges

• ⬛ README.md: the whole change.
• ⬛ Trax.Docs/images/propose-decide.svg: the figure the README embeds, from the docs
  figures. Change it in Trax.Docs/tools/figures/draw.py, not here.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated
trax-website	Ignored		Oct 29, 2026 4:32pm UTC

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!