Merge pull request #6 from ngrok/joelhans/lesson-00-and-diary

add diary+lesson 00: Two Pis, connected—can they just... talk?

Author: joelhans

.gitignore

@@ -1,3 +1,6 @@
 # Python bytecode (from running the tools/* scripts)
 __pycache__/
 *.py[cod]
+
+# macOS
+.DS_Store

AGENTS.md

@@ -0,0 +1,88 @@
+# Agent guide
+
+This repo teaches networking by pairing story, runnable lessons, and Raspberry
+Pi image tooling. If you are a coding agent asked to guide someone through it,
+act as a tutor and lab operator: explain what each command is proving, run only
+the mode that matches the user's environment, and stop for physical actions.
+
+## Start here
+
+Read these in order before making changes or walking a user through the lab:
+
+1. `README.md` for the project shape and phases.
+2. `diaries/00_two-pis-one-cable.md` for the story behind lesson 00.
+3. `lessons/00/README.md` for the hands-on run path.
+4. `lessons/00/manifest.json` for the machine-readable lesson beats, expected
+   observations, and recovery commands.
+
+Use `rg --files` to inspect the repo. The `.context/` directory is private
+workspace scratch space; do not assume external users or future agents can see
+it.
+
+## Teaching modes
+
+- Read-only tutoring: use the diary, lesson README, and manifest to explain the
+  lesson without running commands. This works from any machine.
+- Virtual lab: run lesson 00 in Linux with network namespaces. This is the best
+  mode when there is no hardware. From `lessons/00`, use
+  `sudo env NO_COLOR=1 ./scripts/run.sh --virtual`.
+- Hardware lab: drive two real Pis over SSH. Confirm the user has two nodes
+  flashed with `image/`, an Ethernet cable between their `eth0` ports, and SSH
+  access over Wi-Fi before running scripts.
+
+## Commands and safety
+
+Lesson 00 scripts live in `lessons/00/scripts/`.
+
+- `./scripts/check.sh --hardware` checks SSH access, required tools, sudo
+  readiness, and whether `eth0` already has lesson state.
+- `sudo ./scripts/check.sh --virtual` checks the Linux namespace lab
+  prerequisites.
+- `./scripts/run.sh` walks the hardware lesson over SSH.
+- `sudo ./scripts/run.sh --virtual` creates, runs, and tears down the namespace
+  lab.
+- `./scripts/reset.sh` deletes the lesson's `eth` NetworkManager profile on
+  both hardware nodes, returning `eth0` to a blank lab wire.
+- `sudo ./scripts/virtual/lab-down.sh` removes the virtual namespaces if a
+  virtual run is interrupted.
+
+Do not run hardware scripts without confirming `A_HOST` and `B_HOST`; they
+default to `pi@pi-foo-01.local` and `pi@pi-foo-02.local`. Do not run image build
+or flashing commands unless explicitly asked; those can take a long time and can
+write to disks if misused.
+
+When scripting or capturing output for another agent, prefer:
+
+```bash
+NO_COLOR=1 ./scripts/<step>.sh
+```
+
+The scripts pause only when stdin is a terminal, so noninteractive runs continue
+through prompts automatically. Hardware runs may still need SSH and sudo access.
+
+## Human handoffs
+
+Stop and ask the user to perform physical work when the lesson requires it:
+
+- Unplug or seat the Ethernet cable.
+- Check link lights.
+- Flash or move microSD cards.
+- Confirm the correct SD card device before any `dd` command.
+
+The agent can interpret output and troubleshoot, but it cannot verify physical
+state directly.
+
+## Expected lesson 00 arc
+
+The lesson answers three questions:
+
+- Layer 1: a real cable changes `eth0` from `NO-CARRIER` / `DOWN` to
+  `LOWER_UP` / `UP`, with speed and duplex negotiated.
+- Layer 2: the link emits frames immediately, including IPv6 neighbor discovery,
+  multicast listener reports, router solicitation, and on real Pis often mDNS
+  and DHCP discovery.
+- Layer 3: `ping 10.10.0.2` fails until both ends receive IPv4 identities on
+  `eth0`; then ARP maps the typed IP address to the peer's MAC address.
+
+If the virtual lab is unavailable on macOS or Windows, tell the user to run it
+inside a Linux VM or use read-only tutoring mode.

README.md

@@ -7,17 +7,25 @@ Networking is one of the most global and durable technologies you'll ever touch.
 Its fundamentals are going nowhere, and when you make all those invisible layers
 of the internet visible and intuitive to you, you become a better developer.
 
+Everything here is meant to be **reproduced**. The bill of materials, the OS
+image tooling, and the lesson scripts all live in this repo so you can build
+your own little internet and follow along.
+
 _And have some fun along the way._
 
 ## How I'm rolling out the little internet
 
-We start with a single network, then two networks, and then a working facsimile
-of the internet you know and love. Each phase comes with lessons as technical
-write-ups ([ngrok blog](https://ngrok.com/blog)), YouTube videos
-([ngrok @ YouTube](https://www.youtube.com/@ngrokHQ)), and follow-along scripts
-in this repo.
+I'm going from single network, then two networks, and then a working facsimile
+of the internet you know and love.
+
+As I go, I'll write [diaries](./diaries/) that track questions I'm asking about
+the little internet and the paths I've taken to unpuzzle and understand them.
+Each of those gets a hands-on [lesson](./lessons) you can run yourself. I'll
+also peel off particularly tasty deep-dives on different protocols over to the
+[ngrok blog](https://ngrok.com/blog) and
+[YouTube](https://www.youtube.com/@ngrokHQ).
 
-Each phase includes just enough hardware to make the next set of ideas tangible.
+Here's the whole big picture:
 
 - **Phase 1: a network.** Two Pis and a managed switch. How do devices on the
   same network find and talk to each other? _ARP, MAC addresses, broadcast
@@ -30,16 +38,18 @@ Each phase includes just enough hardware to make the next set of ideas tangible.
   advertise their reachability to one another. _Autonomous systems, BGP, path
   selection, convergence_, plus side quests like DNS, TLS, and Pi-hole.
 
-## Want to build your own?
+## Want to build your own little internet?
 
 1. Gather the hardware. See [`BOM.md`](./BOM.md) for the full parts list by
    phase.
 2. Download a prebuilt image from [Releases](../../releases), or build your own.
    Either way, see [`image/`](./image/) for getting the Raspberry Pi OS image
    (built with [pi-gen](https://github.com/RPi-Distro/pi-gen)) and flashing it
    to your microSD cards.
-3. Follow the lessons. (Coming soon. Start with lesson 00, "why can't these two
-   Pis just talk to each other?")
+3. Follow the lessons. Start with [`lesson 00`](./lessons/00/), "two Pis, one
+   cable: can they just talk?"
+4. Read the diaries for the story behind it all. They're the running build log
+   of putting this together, in the order each piece came to life.
 
 ## Repo layout
 
@@ -49,10 +59,22 @@ Each phase includes just enough hardware to make the next set of ideas tangible.
 ├── BOM.md        Bill of materials — every part, by phase, with vendors.
 ├── image/        pi-gen config that builds the Raspberry Pi OS image the
 │                 nodes run, plus instructions for building and flashing it.
-└── lessons/      (coming soon) One directory per lesson: an explainer, the
-                  scripts to run it yourself, and recorded packet captures.
+├── diaries/      Running build log of how the network came together, one
+│                 prose file per session, in the order things happened.
+├── lessons/      One directory per lesson: an explainer, the scripts to run
+│                 it yourself, and recorded packet captures. Start with
+│                 lessons/00.
+└── AGENTS.md     Guidance for coding agents that teach or operate the labs.
 ```
 
+## Using a coding agent
+
+Coding agents can teach from the docs, run the Linux virtual lab, or drive real
+Pis over SSH while you handle the cable and hardware. Point them at
+[`AGENTS.md`](./AGENTS.md) first; lesson 00 also has a machine-readable
+[`manifest.json`](./lessons/00/manifest.json) with beats, commands, expected
+observations, and recovery steps.
+
 ## Contributing
 
 Want to help? Open an issue or email me at joel@ngrok.com.