[Theauxm]

A newcomer can learn what Trax is for from the docs, in pictures, before any code

Background

The docs are typed by kind (tutorial, how-to, explanation, reference), and the home page,
index.md, routes into them. Pages are CommonMark rendered by the site; until now no page used an
image, so every diagram was an ASCII fence.

Problem

⬛ The docs home explains the mechanism before the purpose
Its first two paragraphs name trains, junctions, the mediator, the scheduler, workers, GraphQL
and the console, then hand the reader a sixteen-item reading list and a forty-link directory.
People shown Trax go to /docs to find out what it is, and get the parts list first.

⬛ Nothing in the docs can show a picture
sync-docs.sh copies only *.md, so a figure had nowhere to live, and the one diagram on
What Trax does is ASCII art.

Example

A reader opens /docs knowing only that Trax is "a .NET framework".

	Before	After
First sentence	"Trax .NET is a framework for .NET business logic you can call, schedule, serve as an API, or move to workers…"	"Trax makes sure a process happens in the right order, by the right people, with nothing skipped, whether a person, a script or an AI agent is doing the work."
First picture	none	a browser, a script and an agent propose a move; the server checks it three ways and saves it or refuses it with a typed error
Where to start	sixteen links in order	New here? → Trax in five minutes, then one of four short paths: deciding, building in .NET, AI agents, production

The new page walks the book's checkout from end to end in eleven figures, for example:

How this solves it

⬛ An explanation page, "Trax in five minutes"
introduction.md, at the top of the sidebar above Quick start. In order: many clients touch one
process; the idea; what a state machine is (a traffic light); the railway picture (stations,
tracks, signals as guards, trains, junctions); the PlaceOrder train; how states and trains work
together; the checkout as a map and a From/Move/To table; the book's checkout machine in C#, as a
from= excerpt of the sample; how the server checks a move (NO_TRANSITION, FORBIDDEN,
INVALID_INPUT, GUARD_FAILED); the clients that drive it; where Trax sits around an AI agent;
the Board sample and the refusals an agent gets back; what a run records; one-line explanations
for different readers. It claims only what the published pages and samples already show.

⬛ The docs home leads with it
index.md opens with the one-line pitch, the propose/decide figure and a link to the page. The
sixteen-item list becomes four paths of four links each. The directory below is unchanged. What
Trax does points to the page and draws its diagram as a figure, and the landing hero's second
link goes to the page.

⬛ Figures are files in the docs, served by the site
An SVG in Trax.Docs/images/, 768px wide, shown with an ordinary markdown image. All of them are
drawn by Trax.Docs/tools/figures/draw.py with one colour per idea (teal states, lavender moves,
amber guards, blue trains, pink junctions, orange failures), so they stay consistent. The sanitizer and the Content-Security-Policy already allowed same-origin
images, so the site needed only the copy and a wrapper for narrow screens.

flowchart LR
  F["Trax.Docs/images/*.svg"] -->|sync-docs.sh| P["public/docs-images/"]
  M["page.md: ![alt](/docs-images/x.svg)"] -->|rehype-sanitize keeps img| R["MdxComponents img"]
  P --> R
  R -->|"min 640px, scrolls in its own box"| S["/docs/introduction"]
  T["ImagesResolveTests"] -.checks.-> F
  T -.checks.-> M
  class F,M,T tooling
  class P,R,S surface
  classDef surface fill:#3b82f6,stroke:#1d4ed8,color:#fff
  classDef tooling fill:#334155,stroke:#0f172a,color:#fff

Loading

ImagesResolveTests fails on an image outside /docs-images/, a file that is not in images/,
empty alt text, or a figure no page shows. writing-docs.md gains a Figures section with the
convention.

Architectural hinges

• ⬛ Trax.Docs/introduction.md: the page itself; every figure is drawn for it.
• ⬛ Trax.Docs/index.md: the reading paths that replace the old start list.
• ⬛ Trax.Docs/tools/figures/draw.py: every figure, and the colour key they share.
• ⬛ Trax.Website/scripts/sync-docs.sh: copies images/ to public/docs-images/, which git
  ignores, so the site shows the figures of the commit it was built from.
• ⬛ Trax.Website/src/components/mdx/MdxComponents.tsx (img): a /docs-images/ figure keeps
  a readable width on a phone and scrolls sideways instead of shrinking.
• ⬛ Trax.Docs/tests/Trax.Docs.Tests/Tests/ImagesResolveTests.cs: keeps references, files and
  alt text in step.

[vercel]

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

1 Skipped Deployment

Project	Deployment	Actions	Updated
trax-website	Ignored	Preview	Oct 27, 2026 6:29pm UTC