BOOK: 01: Add mdBook scaffold for the Shuttle book

[sarsko]

Sarek here, AI under the ----split

I'm adding a book. The writing of the book is heavily AI-assisted, but I don't want it to be AI-y so I have forked Shuttle and I'm reviewing each chapter there and having Claude/Codex respond to my comments. Once a PR is merged there it'll be put up here for review by others. I'll probably also fully write certain sections myself. I expect certain sections like the ones that for now are under "advanced", like how to do reftesting to require more input from me.

I don't expect the book to be superb, but to be better than the nothing we have currently. I also expect it to require a bit of editing in terms of moving stuff around and changing how things are presented, but I think some of that'll come in a pass after the initial version of the book has been made.

I won't bother with PR description and commit message for any BOOK pr in this initial batch and I'll just take whatever the LLM generates. Once I start doing edits there might be something in the PR description.

---

First commit of a documentation series: an mdBook at book/ that grows into a guide to testing concurrent code with Shuttle. This PR is scaffolding only — book.toml, the table of contents, placeholder chapter pages, and CI. The chapters themselves follow as separate PRs so each can be reviewed on its own.

What is here

• book/book.toml — mdBook config. runnable = false for the playground, since the samples need shuttle linked and the playground cannot provide it.
• book/src/SUMMARY.md — the table of contents, in three parts: getting started, using Shuttle, understanding Shuttle.
• book/src/*.md — one placeholder per planned chapter, each a heading plus a <!-- TODO --> marker, so SUMMARY.md resolves and the book builds from this commit onward.
• .github/workflows/book.yml — builds the book on every PR, runs mdbook test against the samples, and deploys to GitHub Pages from main only.
• README.md — a Documentation section pointing at the book and at docs.rs.
• .gitignore — ignores the book/book/ build output.

Why a book

The rustdoc is good on individual APIs but there is no single place that explains the workflow — randomize to find a failure, replay to debug it — or the determinism rules a test body has to follow for replay to work at all. Those are the questions that come up repeatedly, and they do not belong on any one API page.

Two things worth flagging

mdbook test needs -L, not the playground. The workflow runs cargo build --tests --workspace and then mdbook test book -L target/debug/deps. Because mdBook passes only -L and never --extern, every Rust sample that names shuttle needs a hidden # extern crate shuttle; line or it fails to resolve the crate. The chapter PRs follow that convention throughout.

Pages needs enabling before the deploy job can work. The deploy job uses actions/deploy-pages@v4, which requires the repository to have Pages configured with GitHub Actions as the source. Until a maintainer does that, the build job passes and deploy fails on main. The README link to https://awslabs.github.io/shuttle/ is likewise dead until then. Happy to drop the deploy job from this PR and add it separately once Pages is set up — say the word.

Verification

mdbook build book and mdbook test book both pass on this commit (mdBook 0.5.4, the version the workflow pins).

Note on process

CONTRIBUTING.md asks for an issue before significant work. I did not open one first — the book was drafted before I read that, and the content is already written and reviewed on a fork. I am happy to open a tracking issue for the series if that is useful for coordination; tell me and I will file it. If you would rather review the book as fewer, larger PRs than one-per-chapter, that is easy to reshape too.