Start here — route by intent¶

Every other entry surface on this site is organised by what a document is: the normative specification, the descriptive reference suite, the C++ API reference, the worked examples. This page is organised by what a reader is trying to do. Its only job is to hand you one first page and the short ordered route after it.

Audience: a reader who has decided libtracer is possibly relevant and now needs the one page that answers their question. This page explains nothing twice — every row below is a pointer, and where a lane rests on a commitment, the document that records that commitment is named rather than paraphrased.

Two rules govern it:

One intent, one first page. Where two lanes share a destination, the lane says what to read it for; the destination is never re-explained here.
Nothing here is normative. When this page and the specification disagree, the specification wins — as it does against every other informative document (spec index §what is normative).

Pick the lane¶

I want to…	Start at	Then	Target scale
Move data between two boards	Getting started §5	lane 1	NARROW → MID
Let a browser see robot state	Reference 16 — WebSocket session authentication	lane 2	MID
Implement the wire protocol myself	The specification	lane 3	any
Embed a node on an MCU	Reference 12 — deployment profiles	lane 4	NARROW
Decide whether it fits at all	Performance & conformance	other doors	any
Build a device other vendors integrate with	Interoperability	other doors	NARROW → WIDE
Extend or embed the C++ core in a host application	C++ API reference	other doors	MID → WIDE
Understand the model before choosing any of the above	Reference 00 — core overview	the reference suite’s own reading paths	any

Target scale is the deployment the lane is written for, and that is the only thing these three words mean: NARROW = a constrained node with tens of KB of RAM, MID = a gateway or SBC process, WIDE = a many-core host — the spectrum ADR-0082 §reason 2 draws on when it calls the single-upstream MCU “the common NARROW deployment”. They once doubled as the names of the three allocation-store compositions in ADR-0079 — with the mapping inverted, so that reading collided with this one; that spelling is retired (ADR-0079’s 2026-08-20 amendment) and the compositions are now folded / per-plane / per-thread. Target scale is a reading hint, not a conformance statement — the protocol is one model at every scale (Reference 12, opening).

Lane 1 — Move data between two boards¶

Two nodes, one link, a value produced on one and observed on the other.

Getting started §5 — two nodes over a wire — the build, then the smallest end-to-end exchange.
Two nodes over a wire — FWD delivery — the same thing as a program CI builds and runs on every change.
Reference 07 — host embedding — what a route is. A remote endpoint is addressed by its full path from your own root, walking through transport vertices; each hop strips its whole mount run and forwards the rest (Reference 00 §conformance, item 6).
Reference 13 — network formation — who issues the writes that create the link and bind the flow, and why the party that issues them can then leave.
Transport module and connection configuration — the reference implementation’s own surface and its config keys.

What the lane asks you to accept before the API makes sense:

There is no connect and no subscribe primitive. The data API is read / write / await; subscribing is a write into the producer’s :subscribers[] (ADR-0006, ADR-0026).
A connection is a vertex, created by an ordinary write to a creator endpoint — not by a transport-specific call (ADR-0027, ADR-0059, RFC-0014).
Routing is explicit source-routing, so a peer reachable two ways is two addresses — there is no automatic multipath or failover (ADR-0040).

Not yet written as one article: the single narrative that joins path-as-route, mounting and network composition. It is article 1 of #1382; until it lands the story is distributed across reference 03, 07 and 13.

Lane 2 — Let a browser see robot state¶

A browser tab is an ordinary peer, not a client tier (CONTEXT.md §peer / peer symmetry).

Reference 16 — WebSocket session authentication — start here rather than at a transport page, because the browser constraint is the thing that shapes the design: a browser cannot present a header on the opening GET, and the credential must not ride the URL.
Reference 13 — network formation — the web UI joins as an ephemeral peer with delegated admin, creates and binds, then departs; the devices keep talking. Read it for what the UI must not do: it must not proxy the data.
TypeScript binding (see bindings/README.md) — a native TypeScript codec plus a client SDK and WebSocket / WebTransport transports. All four npm packages are published; the client SDK describes itself as experimental, which is a surface-stability caveat (ADR-0034 erratum).
Capability matrix — what the TypeScript core actually covers today, generated from CI evidence rather than hand-maintained.

Rationale worth reading once, in the repository: direct browser-to-robot binding and WebTransport (ADR-0031), and why WebSocket is the first transport with QUIC deferred per link (ADR-0029).

The bindings have no home in this doc tree yet — their READMEs live in the repository. That is article 3 of #1382.

Lane 3 — Implement the wire protocol myself¶

A second implementation, in any language, that interoperates byte-for-byte.

The specification — read this before v1.md. Normative status is not a property of a directory: v1.md incorporates three reference documents as normative annexes, and a reader of v1.md alone never sees the frame layout.
Protocol v1 — scope, terminology, the conformance procedure, the static path-handle requirements (§3.1).
The three annexes, in this order: 01 — data format (frame layout, the opt bits, the trailer), 05 — protocol-defined TLVs (the type-code registry and each payload layout), 03 — addressing §path syntax.
Conformance vectors — the language-agnostic test vectors every core is gated against; the C++ core is golden (ADR-0028).
Capability matrix — how far the Rust and TypeScript cores have got, so you know which vector categories are already exercised.
Implementation registry — where to list yours.

Two things to know before you start:

The wire format is draft and not yet stable; pin to a specific commit if you depend on it today — the specification says so on its own first line (Protocol v1 §status).
If you are writing only a codec or a sender, the reference suite has a section-granular route for exactly that — 01 → 03 → 05 → 06 — in its own reading paths. This page does not restate it.

Lane 4 — Embed a node on an MCU¶

NARROW: a constrained node where flash, static RAM and hot-path allocation all bind.

Reference 12 — deployment profiles — rung 1, the single-transport leaf: the exact module tree, its conformance profile, and header-elided framing, where the bus’s own identity is the path (ADR-0022). Its rung-1 flash figure is stated there as a design target for that composition, not as a measured figure — read it as such.
Protocol v1 §3.1 and Reference 03 — addressing — path handles. Every address used more than once is encoded once, into a build-time literal or one init-time allocation, and the hot path takes the handle. This is what removes snprintf and per-write allocation, and it is a conformance requirement, not an optimisation (Reference 00 §conformance, item 7). The reference suite’s reading paths name a five-section MCU route at section granularity; follow it there.
ESP32 node profile — running libtracer as a primary communication stack inside an MCU’s RAM, flash and task budget, and the sites where the bounded-reactor discipline is not yet complete.
ESP-IDF component and PlatformIO — consume a packaged integration rather than building the core directly (Getting started §2).
The configuration space — the size and policy axes that decide static RAM. They are a different kind of knob from the module set and are not visible on the integrator’s CMake line.

The footprint claim is gated, not asserted: a stripped Cortex-M0 build is measured by footprint-cortexm0.yml on every change under core/, and its budget verdict currently runs in warn mode — so take the size from that job’s own output rather than from a figure quoted elsewhere.

Other doors¶

I want to…	Read	Why this one
Decide whether it fits at all	Performance & conformance, then the capability matrix	The performance page is generated from the live harnesses in CI, and the matrix from test evidence — neither is hand-authored, so neither can drift from what ran.
Build a device other vendors integrate with	Interoperability, then building a custom interoperable device	The first says why interop here is a legibility discipline with no certification body; the second is the can / may / must-not matrix for your own device.
Extend or embed the C++ core in a host application	C++ API reference, then Reference 10 — module catalog	The module pages pair a usage narrative with declarations rendered from the headers; the catalog says which module pairs with which, and what is required versus optional.
Know what one word means	CONTEXT.md	The canonical glossary, and the vocabulary of record: where it and another page disagree, the other page is brought into line with it.
Understand why a design looks the way it does	ADRs and RFCs in the repository	Rationale and change proposals are contributor instruments and are deliberately not published on this site (spec index §how the specification is layered).
Measure the reference implementation’s own cost	Design notes	Explicitly not the standard: the measured cost of the C++23 implementation’s choices, and how cost measurement goes wrong here.

Which genre answers which question¶

A destination is easier to trust once you know which genre it belongs to. Precedence runs top to bottom.

Genre	Where	Answers	Status
Normative specification	`docs/spec/v1.md` + its three annexes	What a conforming implementation MUST do	Wins against every other document
Descriptive reference	`docs/reference/`	What the protocol is, implementation-independently	Canonical for that question; draft for v1
API reference	`docs/modules/`	What the C++23 reference implementation exposes	One implementation, not the standard
Measured evidence	Performance, capability matrix, design notes	What it costs, and what is verified	Generated from CI runs
Rationale and proposals	ADRs and RFCs, in the repository	Why it looks this way; what is being changed	Not published on this site

How this page relates to the other entry points¶

This page routes; it does not replace. The site landing page still carries its six orientation cards, Getting started still owns the ten-minute build, and the reference suite’s reading guide still owns the section-granular routes through the standard. Where their coverage overlaps this one, the overlap is recorded on #1382; folding any of them in is a separate, later change, so nothing was removed to make room for this page.