Initial scaffold: book.toml, SUMMARY, deploy workflow, preface, intro, chapter stubs

DavidLiedle · claude · DavidLiedle · commit 3dbd1e3c2f56 · 2026-05-06T13:49:08.000-06:00
Co-Authored-By: Claude Opus 4.7 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
@@ -0,0 +1,49 @@
+name: Deploy mdBook to GitHub Pages
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup mdBook
+        uses: peaceiris/actions-mdbook@v2
+        with:
+          mdbook-version: 'latest'
+
+      - name: Build book
+        run: mdbook build
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./book
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
diff --git a/README.md b/README.md
@@ -0,0 +1,36 @@
+# Mesh Networking for Mortals
+
+**A 2026 survey of mesh networking, scoped for the working engineer.**
+
+**[Read online at cloudstreet-dev.github.io/Mesh-Networking-for-Mortals](https://cloudstreet-dev.github.io/Mesh-Networking-for-Mortals/)**
+
+## About This Book
+
+The available literature on mesh networking splits into two unhelpful piles: academic papers that assume you've read every prior academic paper, and project-website pitches that assume you're already sold. There is almost nothing in between for the engineer who has heard of half these projects, doesn't know how they compare, and wants an honest survey before they commit a weekend to playing with one.
+
+This book is that survey, scoped to 2026.
+
+The reader is a competent developer who has shipped real products. They know what TCP/IP is. They've maybe heard of Meshtastic from a maker friend, vaguely remember that cjdns was a thing in the 2010s, use Tailscale at work, and aren't sure whether any of those are actually the same kind of thing. They want to know which projects are alive in 2026, what each one is structurally good at, what it gets wrong, and which one to install on a Raspberry Pi this weekend if they want to actually feel mesh networking in their hands.
+
+## About CloudStreet
+
+CloudStreet is a catalog of short, opinionated technical books on topics that working engineers ought to understand and mostly don't. Each book is written to be read in a weekend and to leave the reader more dangerous than they were on Friday.
+
+## AI Authorship
+
+This book is written by Claude Opus 4.7 (Anthropic), with editorial direction and project management from the CloudStreet team. The byline is the model's own. We disclose this plainly because the alternative is dishonest, and because the work is good enough to defend on its merits.
+
+## Building Locally
+
+```sh
+cargo install mdbook
+mdbook serve --open
+```
+
+## Deploying
+
+Pushes to `main` build the book and deploy to GitHub Pages via the workflow at `.github/workflows/deploy.yml` (peaceiris/actions-mdbook + actions/deploy-pages).
+
+## License
+
+CC0 1.0 Universal — public domain dedication. Take it, fork it, ship it, claim it as your own. See [LICENSE](LICENSE).
diff --git a/book.toml b/book.toml
@@ -0,0 +1,31 @@
+[book]
+title = "Mesh Networking for Mortals"
+authors = ["Claude Opus 4.7"]
+description = "A 2026 survey of mesh networking that doesn't expect you to have read every academic paper. Reticulum, Meshtastic, MeshCore, Yggdrasil, cjdns, Scuttlebutt, Briar, and the mesh VPNs — what each is good for, what it gets wrong, which are worth your weekend."
+language = "en"
+src = "src"
+
+[build]
+build-dir = "book"
+
+[output.html]
+git-repository-url = "https://github.com/cloudstreet-dev/Mesh-Networking-for-Mortals"
+edit-url-template = "https://github.com/cloudstreet-dev/Mesh-Networking-for-Mortals/edit/main/{path}"
+site-url = "/Mesh-Networking-for-Mortals/"
+default-theme = "navy"
+preferred-dark-theme = "navy"
+
+[output.html.fold]
+enable = true
+level = 0
+
+[output.html.search]
+enable = true
+limit-results = 30
+teaser-word-count = 30
+use-boolean-and = true
+boost-title = 2
+boost-hierarchy = 1
+boost-paragraph = 1
+expand = true
+heading-split-level = 3
diff --git a/src/SUMMARY.md b/src/SUMMARY.md
@@ -0,0 +1,38 @@
+# Summary
+
+[Preface](preface.md)
+[Introduction](introduction.md)
+
+---
+
+# Part I: Orientation
+
+- [What "Mesh Networking" Even Means](ch01-what-mesh-even-means.md)
+- [The Physical Layer Decides A Lot](ch02-physical-layer.md)
+- [The Routing Problem](ch03-routing-problem.md)
+
+# Part II: The LoRa Family
+
+- [Meshtastic](ch04-meshtastic.md)
+- [MeshCore](ch05-meshcore.md)
+- [Reticulum](ch06-reticulum.md)
+
+# Part III: IP-Layer Meshes
+
+- [Yggdrasil](ch07-yggdrasil.md)
+- [The Hyperboria Story](ch08-hyperboria.md)
+
+# Part IV: Adjacent Shapes
+
+- [Scuttlebutt and the Gossip Family](ch09-scuttlebutt.md)
+- [Briar, Bitchat, and the Bluetooth Family](ch10-briar-bitchat.md)
+- [Mesh VPNs Are A Different Thing](ch11-mesh-vpns.md)
+
+# Part V: Practice
+
+- [Pick One This Weekend](ch12-pick-one.md)
+
+---
+
+[Acknowledgments](acknowledgments.md)
+[License](license.md)
diff --git a/src/acknowledgments.md b/src/acknowledgments.md
@@ -0,0 +1,3 @@
+# Acknowledgments
+
+Thanks to **Georgiy Treyvus**, the CloudStreet PM who keeps the backlog and who decided this book belonged on it.
diff --git a/src/ch01-what-mesh-even-means.md b/src/ch01-what-mesh-even-means.md
@@ -0,0 +1,3 @@
+# what mesh even means
+
+*Coming soon.*
diff --git a/src/ch02-physical-layer.md b/src/ch02-physical-layer.md
@@ -0,0 +1,3 @@
+# physical layer
+
+*Coming soon.*
diff --git a/src/ch03-routing-problem.md b/src/ch03-routing-problem.md
@@ -0,0 +1,3 @@
+# routing problem
+
+*Coming soon.*
diff --git a/src/ch04-meshtastic.md b/src/ch04-meshtastic.md
@@ -0,0 +1,3 @@
+# meshtastic
+
+*Coming soon.*
diff --git a/src/ch05-meshcore.md b/src/ch05-meshcore.md
@@ -0,0 +1,3 @@
+# meshcore
+
+*Coming soon.*
diff --git a/src/ch06-reticulum.md b/src/ch06-reticulum.md
@@ -0,0 +1,3 @@
+# reticulum
+
+*Coming soon.*
diff --git a/src/ch07-yggdrasil.md b/src/ch07-yggdrasil.md
@@ -0,0 +1,3 @@
+# yggdrasil
+
+*Coming soon.*
diff --git a/src/ch08-hyperboria.md b/src/ch08-hyperboria.md
@@ -0,0 +1,3 @@
+# hyperboria
+
+*Coming soon.*
diff --git a/src/ch09-scuttlebutt.md b/src/ch09-scuttlebutt.md
@@ -0,0 +1,3 @@
+# scuttlebutt
+
+*Coming soon.*
diff --git a/src/ch10-briar-bitchat.md b/src/ch10-briar-bitchat.md
@@ -0,0 +1,3 @@
+# briar bitchat
+
+*Coming soon.*
diff --git a/src/ch11-mesh-vpns.md b/src/ch11-mesh-vpns.md
@@ -0,0 +1,3 @@
+# mesh vpns
+
+*Coming soon.*
diff --git a/src/ch12-pick-one.md b/src/ch12-pick-one.md
@@ -0,0 +1,3 @@
+# pick one
+
+*Coming soon.*
diff --git a/src/introduction.md b/src/introduction.md
@@ -0,0 +1,56 @@
+# Introduction
+
+There is a certain kind of conversation that happens at hacker meetups every few months. Someone mentions Meshtastic. Someone else mentions Tailscale. A third person, helpfully, says "oh, like cjdns?" and a fourth person, less helpfully, says "isn't that just LoRa?" Within ninety seconds the word *mesh* has been used to refer to four mutually incompatible things and nobody has the energy to untangle which is which.
+
+This book is the untangling.
+
+## The premise
+
+Mesh networking is a topic where the available literature splits into two unhelpful piles.
+
+The first pile is academic: SIGCOMM papers, IETF drafts, dissertations on mobile ad-hoc routing. They are, on the whole, excellent — and they assume you have read every prior paper they cite, which means you have not read them, because nobody has time to read every prior paper. They are not for you.
+
+The second pile is project marketing. The Reticulum landing page. The Meshtastic homepage. The Tailscale "How it works" diagram. They are, on the whole, well-produced — and they assume you have already decided to use the project in question. They are not surveys. They cannot tell you whether to choose this project or a different one, because every one of them is the project they're selling.
+
+There is almost nothing in between.
+
+This book aims to fill that gap, for one specific reader: a working engineer who has heard of half these projects, doesn't know how they compare, and wants an honest survey before committing a weekend to one of them. If you are looking for an academic treatment, the bibliography points outward. If you are looking for a tutorial for one particular tool, the project's own documentation will serve you better than this book ever could. What this book offers is the thing the existing literature does not: the comparative map.
+
+## What we mean by 2026
+
+The mesh networking field has been through several waves. The early 2010s wave — Hyperboria, the cjdns-curious, the radio-mesh-as-political-act communities — is largely over, and pretending otherwise would waste your time. The mid-2010s consumer-mesh wave (the Eero/Plume "buy three boxes for your house" definition of mesh) is alive but is a different category of object than what most of this book is about. The 2020s wave — Meshtastic going mainstream, Reticulum maturing, mesh VPNs becoming infrastructure — is the wave you are sitting in the middle of as you read this.
+
+Scoping to 2026 means: the projects discussed are the ones a reader can actually engage with right now. Where a project is dormant, the book says so. Where a project is thriving, the book says so. Where a project's status is genuinely ambiguous — and a few of them are — the book says that too, and points at the most recent meaningful activity rather than pretending to certainty it doesn't have.
+
+## What you will get out of this
+
+By the end of the book you will be able to:
+
+- Distinguish the four things "mesh" gets used to mean, and call out vendors using the word as marketing rather than description.
+- Reason about why physical layer choice cascades through everything else — range, throughput, regulatory limits, who can join.
+- Hold the routing problem in your head clearly enough to understand why flooding-based meshes (Meshtastic) degrade above ~100 nodes and what the alternatives are doing differently.
+- Have an opinion about which project to install on a Raspberry Pi this weekend, indexed by what you actually want to feel.
+
+## What you will not get out of this
+
+You will not become an expert on any of these projects. You will not be qualified to operate a regional mesh deployment, audit Reticulum's cryptography, or contribute to Yggdrasil's routing core. Those are jobs that take longer than a weekend, and the people doing them have written better material than this book ever will once you know which doors to walk through.
+
+What you will get is: which doors to walk through.
+
+## How the book is organized
+
+**Part I (chapters 1–3)** does the foundational work. What "mesh networking" actually means once you tease apart the four uses of the word. Why physical layer choice cascades through every other decision. Why routing is the hard part and how the major approaches differ.
+
+**Part II (chapters 4–6)** is the LoRa family. Meshtastic is the entry point, MeshCore is the engineered alternative, Reticulum is the project that takes the whole stack seriously. Each gets an honest assessment of what it does well, what it does badly, and what shape of user it serves.
+
+**Part III (chapters 7–8)** moves to IP-layer meshes. Yggdrasil is alive and worth running. cjdns and Hyperboria are largely historical, but the lessons they left are real and worth honoring.
+
+**Part IV (chapters 9–11)** covers the adjacent shapes. Scuttlebutt and the gossip family — mesh-adjacent, useful as contrast. Briar, Bitchat, and short-range Bluetooth-mesh messaging. And mesh VPNs (Tailscale, Nebula, ZeroTier, Headscale) — which legitimately use the word *mesh* but solve a completely different problem.
+
+**Part V (chapter 12)** is the punchline. Indexed by what you want, here is what to install this weekend, what hardware to buy, and what an evening with it looks like.
+
+## A note on tone
+
+This book will occasionally be blunt about projects that did not pan out. That is not disrespect — those projects were attempts at something hard, and the people who built them deserve credit for the attempt regardless of the outcome. But the book is written for a reader who is about to spend a weekend on something, and softening "this network is a ghost town" into "this network has a small but dedicated community" would be a disservice. The reader can handle "this didn't work and here is what we learned." So the book treats them that way.
+
+Let's begin.
diff --git a/src/license.md b/src/license.md
@@ -0,0 +1,7 @@
+# License
+
+This book is dedicated to the public domain under [CC0 1.0 Universal](https://creativecommons.org/publicdomain/zero/1.0/).
+
+To the extent possible under law, the authors have waived all copyright and related or neighboring rights to this work.
+
+You can copy, modify, distribute, and use the work, even for commercial purposes, all without asking permission. You do not need to credit the authors. You do not need to ask first. The full legal text is in the [LICENSE](https://github.com/cloudstreet-dev/Mesh-Networking-for-Mortals/blob/main/LICENSE) file at the repository root.
diff --git a/src/preface.md b/src/preface.md
@@ -0,0 +1,11 @@
+# Preface
+
+This book was written by Claude Opus 4.7, an AI system built by Anthropic, working from a brief drafted by the CloudStreet editorial team. The byline is the model's own — not as a stylistic flourish, but because pretending otherwise would be dishonest, and dishonesty is a poor foundation for a book that asks the reader to trust its survey of a noisy field.
+
+What that means for you, the reader: every claim of fact in this book — every range figure, every project status, every license, every link — was generated by a language model and is, in principle, capable of being wrong in the way language models are wrong. The book has been edited and the structurally important claims cross-checked. But the mesh networking landscape moves, and 2026 will become 2027, and a project that was alive when this was written may have gone quiet by the time you read it. Where the book leans on a contested or volatile claim, it tries to say so. Where it does not, treat the load-bearing claims as you would treat any survey: directionally correct, individually verifiable, and worth a quick check before you commit hardware money to a recommendation.
+
+The structural argument of the book — that physical layer cascades through everything, that routing is the dominant constraint, that "mesh" is doing four jobs in one word, that you should start with Meshtastic and invest in Reticulum — is not the kind of thing that goes stale in a year. The specific URLs and version numbers are.
+
+What this book is not: a tutorial, a comprehensive technical reference, a defense of any particular project, or a polemic against the existing Internet. It is a survey written for one specific reader — the engineer who has heard of half these projects and doesn't know how they compare — and you should put it down the moment it stops being useful to you.
+
+— Claude Opus 4.7

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# Acknowledgments`
	`2`	`+`
	`3`	`+Thanks to Georgiy Treyvus, the CloudStreet PM who keeps the backlog and who decided this book belonged on it.`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# what mesh even means`
	`2`	`+`
	`3`	`+Coming soon.`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# physical layer`
	`2`	`+`
	`3`	`+Coming soon.`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# routing problem`
	`2`	`+`
	`3`	`+Coming soon.`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# meshtastic`
	`2`	`+`
	`3`	`+Coming soon.`