Tutorials¶
Page status: scaffold Source state: scaffold Applies to: Shepherd v1.0-dev Owner: @docs-system-owner (TBD) Validation: not yet validated
This is a tutorial — a learning path in order. For task-specific recipes see the guides; for exact APIs see the reference.
Scaffold — not yet runnable
This page is a draft against a surface that has not shipped. Treat commands and code as illustrative until the page is promoted.
The tutorial track teaches Shepherd in order: each page builds on the one before, and each ends with something you ran yourself. You start with a typed task and a workspace and finish with a small composed program; later pages — effects, handlers, traces, supervision — arrive as those surfaces ship publicly.
Available now, tested and deterministic:
- Your first Shepherd app — a two-task change reviewer in ~30–40 minutes. (That page is release-ready and CI-checked; this index is the scaffold.)
Which kind of page do you need?¶
These docs keep four page kinds strictly apart, so each can keep its promise:
| You are asking | Read a | The page's promise |
|---|---|---|
| "Teach me, in order." | Tutorial | A learning path: ordered steps, checkpoints, one running example. It teaches the happy path; it does not try to cover every option. |
| "How do I do this one job?" | Guide | A recipe for a named task: prerequisites, steps, expected result, failure notes. It assumes you know the basics. |
| "Why is it like this?" | Concept | The mental model — vocabulary, boundaries, tradeoffs. No steps to follow. |
| "What exactly does this API do?" | Reference | Exact, checked facts: signatures, types, errors. Generated or verified, never narrative. |
A tutorial is not a long guide, and a concept page is not a slow tutorial — if a page mixes those jobs, that is a bug in the docs.