Tutorial Path

Run one graph first, then add concepts only when they explain the next problem. The path is a sequence of working artifacts — stdout events, a rendered graph, local stepping, and a replayable recording — not a reference tour.

Recommended route

Get one graph running, then learn just enough to scale it.

Each step below produces something you can see. Read a concept page when the demo before it raises a question the concept answers.

First command

pixi run demo-webcam-detection-mock

No camera, no GUI, no backend. Deterministic red/blue detections in stdout.

The route

01Install

Clone the repo and build the environment with Pixi.

pixi install02Visual quickstart

Run the mock perception graph, then the live webcam and Rerun path.

pixi run demo-webcam-detection-mock03Examples and results

Six demos, each with its real output, from a one-Flow function to replay.

pixi run demo-basic-flow04Flow fundamentals

The Python boundary: typed @io, local state, and a synchronous step().

05Time and sync

Clocks decide when a Flow runs; per-edge sync= decides which input it reads.

06Debug and visualize

Render the graph, step in-process, then record and replay the same run.

pixi run docs-tutorial-perception-html07Runtime model

Graph compiles to an IR; pipe.step() preserves the timing that pipe.run() deploys.

08Hub and reuse

Package stable Flows and payloads through the Hub boundary, not source-tree layout.

What you should have after each stage

Stage	Artifact	Ready to continue when…
Visual quickstart	stdout detections, optional Rerun viewer	the mock command is deterministic and the live command opens Rerun or falls back to stdout.
Examples and results	real outputs for Flow, stepping, perception, render, replay	you can tell whether a command succeeded without reading source.
Flow fundamentals	a typed Python mental model	you know your logic lives inside Flow.step().
Time and sync	clocks and edge-sampling vocabulary	you can say which Flow wakes itself and how upstream history is sampled.
Debug and visualize	artifacts/tutorial_perception.html, step traces, replay logs	you inspect the graph before blaming backend scheduling.
Hub and reuse	a manifest/registry boundary	you know what is reusable as a pack and what is still source-only.

Choose by question

I just want to installSource checkout plus Pixi runs every demo today.I need to debug a graphRender structure, step in-process, then record and replay.I need the runtime modelHow validation, stepping, replay, and backends relate.I want robot-facing examplesThe first GoldenRetriever Hub proof, after the core path works.

For AI agents

Skip broad repo spelunking on the first pass. Run this deterministic route, then read llms.txt and inspect the rendered HTML graph before moving to live webcam, Rerun, or GoldenRetriever examples:

pixi run demo-webcam-detection-mock
pixi run docs-tutorial-perception-html
pixi run demo-perception-stepper