Tutorials

The tutorials are one rail, not a menu. Each page opens with the problem the last one left you holding, ends at a working checkpoint, and hands off to the next. Every command and its output is real, and so is the agent: the rail assumes a GitHub Copilot subscription, which a fresh keelson defaults to. (Driving Claude, Codex, or Pi instead changes nothing but the sign-in; the configuration guide covers it.)

Ride it in order. Each stop uses the harness for something real and leaves you ready for the next. The first five need keelson alone and close on a multi-model build; the last two bolt on two ribs and turn the same app into a software factory run.

One caution before you start: real means not reproducible. The outputs printed on these pages show you the shape of what a stop produces, but a live agent will not match them word for word, and the builds at stops 5 and 7 will give you a different app than they gave us. That is the point, not a defect. Treat each stop as a lab, not a script: run the step, read what actually came back, and when a page says “try it”, try your own variation before moving on.

The whole rail is seven stops:

Figure 1. The tutorial rail. Stops 1 to 5 need only the harness: install and run, talk to the agent three ways, make a task repeatable, make it remember, then build an app on many models. Stops 6 and 7 add the beads and swarm ribs and build the same app again as a factory.

1. Your first runInstall the harness, read its health sweep, sign in to Copilot, and push one chat turn through the whole loop.

2. Talk to the agentWork the agent three ways (the browser Chat surface, the interactive terminal, and a scriptable one-shot), all backed by one persisted store.

3. Run and author a workflowRun the bundled smoke-test, then author a four-node YAML DAG, let validation catch a broken reference, and watch the engine execute it.

4. Make it rememberGive a project a notebook and a governed memory, then watch a fresh session recall what an earlier one learned, only after you approve it.

5. One workflow, many modelsThe field exercise: clone a template project, run a real app build that routes each phase to a different model, then swap one and compare.

6. Plan the backlog with beadsInstall the beads rib, seed the Cosmos build as eleven beads with real dependencies, and read the board that says what can start now.

7. Run the software factoryInstall the swarm rib and let a Fleet of agents drain the board in dependency order, with a design critic on every page and a reviewer on every merge.

Two shapes of the same build

Stops 5 and 7 build the same app from the same spec, on purpose. Stop 5 is a pipeline: one model writes a plan, and every later phase trusts it in a straight line. Stop 7 is a factory: the work is a graph of small, reviewable units, agents pick up whatever is ready, and nothing lands without a second agent reading it. Stop 7 does not need stop 5, and running both is the cleanest way to see which shape fits which kind of work.