diff --git a/docs/lessons/16-supervised-app-with-logs.md b/docs/lessons/16-supervised-app-with-logs.md
new file mode 100644
index 0000000..c084971
--- /dev/null
+++ b/docs/lessons/16-supervised-app-with-logs.md
@@ -0,0 +1,97 @@
+<!-- Lesson for PR #16. Teaches one concept grounded in the real diff. -->
+
+# PR #16 — Tracer: supervised app with logs
+
+> **Rust lesson:** To mutate state from an async task that outlives the function that spawned it, hand the task an `Arc<Mutex<T>>` clone — `Arc` gives shared ownership across threads, the `Mutex` makes the mutation safe.
+> **Tags:** `Arc<Mutex<T>>` · `tokio::spawn`
+> **Merged:** 2026-06-08 · +2369/−0 · [View PR](https://github.com/nonrational/adjacent/pull/16)
+
+## The situation
+
+This is the tracer-bullet PR that stood the project up: register a dev-server directory, boot it, capture its logs, and report whether it's running, stopped, or crashed. The core is a `Supervisor` that spawns a child process and then needs to know, later and asynchronously, when that child exits — and update its recorded state accordingly. The catch: the code that spawns the child returns immediately, but the exit can happen minutes later. Two different tasks end up touching the same state, and Rust will not let that happen by accident.
+
+## The Rust idea
+
+In a garbage-collected language you would capture `this` in a callback and mutate a field whenever the process exits. Nobody checks who else is touching that field at the same time.
+
+Rust makes the sharing explicit, for two reasons:
+
+1. **Lifetimes.** A task handed to `tokio::spawn` must be `'static` — it may outlive the function that created it, so it cannot borrow anything on that function's stack (including `&self`). It has to *own* what it uses.
+2. **Threads.** Tokio's default runtime is multi-threaded, so the spawned task may run on a different worker thread than the one that spawned it. Anything it captures must be safe to send and share across threads (`Send + Sync`).
+
+`Arc<Mutex<T>>` is the idiomatic answer to both:
+
+- `Arc<T>` — an **a**tomically **r**eference-**c**ounted pointer. Cloning it doesn't copy the data; it bumps a refcount and hands back a second owner of the *same* `T`. Both owners are `'static`, so both can go into spawned tasks.
+- `Mutex<T>` — guards the interior so only one task mutates at a time. `tokio::sync::Mutex::lock().await` *yields* the worker thread while waiting instead of blocking it, which is what you want inside async code.
+
+The single-threaded shortcut `Rc<RefCell<T>>` won't compile here: `Rc` isn't `Send`, so `tokio::spawn` rejects it.
+
+## In this PR
+
+The supervisor holds all app state behind one shared, locked handle:
+
+```rust
+// crates/adj/src/supervisor.rs
+#[derive(Default)]
+pub struct Supervisor {
+    inner: Arc<Mutex<Inner>>,
+}
+
+#[derive(Default)]
+struct Inner {
+    apps: HashMap<String, AppRuntime>,
+}
+```
+
+`up()` spawns the child, records it as `Running`, then detaches a task to wait for the exit:
+
+```rust
+// crates/adj/src/supervisor.rs
+pub async fn up(&self, app_dir: PathBuf, cfg: AppConfig) -> Result<u32> {
+    let name = cfg.name.clone();
+    let mut inner = self.inner.lock().await;
+    // ...
+    let mut child = command
+        .spawn()
+        .with_context(|| format!("spawning `{}`", cfg.cmd))?;
+
+    let pid = child.id().ok_or_else(|| anyhow!("spawned child has no pid"))?;
+
+    inner.apps.insert(
+        name.clone(),
+        AppRuntime { state: AppState::Running { pid }, intentional_stop: false },
+    );
+
+    // Detach the wait task so the supervisor can observe exit/crash without holding the lock.
+    let inner_handle = self.inner.clone();
+    let watch_name = name.clone();
+    tokio::spawn(async move {
+        let status = child.wait().await;
+        let mut guard = inner_handle.lock().await;
+        if let Some(rt) = guard.apps.get_mut(&watch_name) {
+            // ... record Stopped, or Crashed { exit_code }
+        }
+    });
+
+    Ok(pid)
+}
+```
+
+The load-bearing lines are the two just before `tokio::spawn`:
+
+- `let inner_handle = self.inner.clone();` clones the **`Arc`**, not the `Inner`. The new handle points at the same `Mutex<Inner>` the `Supervisor` still owns.
+- `async move { ... }` moves `inner_handle`, `watch_name`, and `child` *into* the task. Now the task owns everything it touches — no borrow of `self`, so the `'static` requirement is satisfied.
+
+When the child eventually exits, the task takes the lock (`inner_handle.lock().await`) and flips the app's `state` from `Running` to `Stopped` or `Crashed`. Meanwhile `state()`, `down()`, and the next `up()` all reach the same `HashMap` through the same `Mutex` — one writer at a time, no data race, enforced at compile time.
+
+## Why it matters
+
+Without `Arc`, you can't share the state at all: the spawned task can't borrow `self`, and moving `self.inner` into it would leave the `Supervisor` with nothing. Without the `Mutex`, two tasks writing the same `HashMap` is a data race — which in most languages is a heisenbug you find in production, and in Rust is a compile error you fix before lunch. The pattern is verbose on purpose: it forces you to name, up front, exactly which state is shared and how it's synchronized.
+
+## Related lessons
+
+- Later PRs reuse this exact `Arc<Mutex<...>>` foundation for trickier concurrency — the proxy's lazy-boot single-flight and the idle scanner's re-check-under-lock both build on the supervisor's `Inner` mutex. Those PRs are the place to teach the *variations* (single-flight, closing the request-vs-scanner race), not the base pattern taught here.
+
+## Dig deeper
+
+- [The Rust Book, ch. 16.3](https://doc.rust-lang.org/book/ch16-03-shared-state.html) — Shared-State Concurrency (`Mutex<T>` and `Arc<T>`)
diff --git a/docs/lessons/17-inject-port-into-child-env.md b/docs/lessons/17-inject-port-into-child-env.md
new file mode 100644
index 0000000..07f242a
--- /dev/null
+++ b/docs/lessons/17-inject-port-into-child-env.md
@@ -0,0 +1,87 @@
+<!-- Lesson for PR #17. Teaches one concept grounded in the real diff. -->
+
+# PR #17 — Inject PORT into supervised processes
+
+> **Rust lesson:** `tokio::process::Command` is a builder that inherits the parent process's environment by default; each `&mut self` method chains, and `.env(key, value)` layers one variable on top before `.spawn()` runs anything.
+> **Tags:** `tokio::process::Command` · `builder-pattern` · `env-vars`
+> **Merged:** 2026-06-08 · +322/−12 · [View PR](https://github.com/nonrational/adjacent/pull/17)
+
+## The situation
+
+A supervised dev server has to bind *somewhere*, and the daemon — not the app — picks the port (it allocates a free one via a `:0` bind probe). So the daemon must hand that number to the child before it starts. The classic Unix mechanism is an environment variable: inject `PORT=54321` into the child's environment, and the app reads `$PORT` and binds it. Some apps insist on a different name, so `adjacent.toml` gains a `port_env` knob to rename the injected variable.
+
+## The Rust idea
+
+Rust has no keyword arguments, no default parameters, and no function overloading. When a thing has many optional knobs and one final "go" step — spawning a process is the textbook case — the idiomatic shape is the **builder pattern**.
+
+`Command::new("sh")` returns a mutable `Command`. Every configuration method (`.arg`, `.current_dir`, `.env`, `.stdout`, `.process_group`) takes `&mut self` and returns `&mut Self`. Returning the same mutable borrow is what lets calls chain, and because nothing is *moved*, you can also configure across several statements on the same binding. Nothing actually runs until a terminal method — here `.spawn()`.
+
+The environment piece has one detail that trips people up: **a freshly built `Command` inherits the parent process's entire environment.** You start with a full copy of whatever the daemon itself was launched with. The env methods then edit that inherited set:
+
+- `.env(key, value)` — insert or **override** one entry.
+- `.envs(iter)` — the same, for many at once.
+- `.env_remove(key)` — drop one inherited entry.
+- `.env_clear()` — throw the whole inheritance away and start empty.
+
+"Inherit, then override" is a precedence decision baked into the default: a later `.env` wins over whatever the child would have inherited under the same name.
+
+## In this PR
+
+The core is a handful of chained builder calls in `up()`. The port name is resolved first, then layered onto the command:
+
+```rust
+// crates/adj/src/supervisor.rs
+let port_env = cfg.port_env.as_deref().unwrap_or("PORT");
+let mut command = Command::new("sh");
+command
+    .arg("-c")
+    .arg(&cfg.cmd)
+    .current_dir(&app_dir)
+    .env(port_env, port.to_string())
+    .stdin(Stdio::null())
+    .stdout(Stdio::from(log_file))
+    .stderr(Stdio::from(stderr_file));
+```
+
+- `cfg.port_env.as_deref().unwrap_or("PORT")` collapses `Option<String>` into a plain `&str`: `as_deref()` borrows the inner `String` as `&str` if present, and `unwrap_or("PORT")` supplies the default when it's `None`. One expression, one default, no branch.
+- `.env(port_env, port.to_string())` layers exactly one variable onto the inherited environment. The value has to be an *owned* `String` (`port` is a `u16`), because `.env` keeps the bytes for the eventual spawn — a borrowed slice tied to this stack frame wouldn't outlive it.
+
+The config field that feeds `port_env` is optional by construction:
+
+```rust
+// crates/adj/src/registry.rs
+/// Override the env var name used to inject the assigned port.
+/// When unset, Adjacent exports `PORT`. When set, it exports the named variable instead.
+#[serde(default)]
+pub port_env: Option<String>,
+```
+
+`#[serde(default)]` means an absent key deserializes to `None` instead of erroring — that's what makes `port_env` opt-in.
+
+The load-bearing proof that inheritance is the default lives in the test harness:
+
+```rust
+// crates/adj/tests/tracer.rs
+// Scrub port-related env vars from the parent shell so the daemon (and any child it
+// spawns) starts from a known-clean slate. Without this, `PORT=3000 cargo test` would
+// pass `PORT` through to the supervised child and silently break the rename test.
+c.env_remove("PORT");
+c.env_remove("BIND_PORT");
+```
+
+Read that comment as a demonstration of the semantics: because `Command` copies the parent's environment and `.env` only touches the keys you name, a stray `PORT` in the test runner's own environment flows straight through to the child. The `rename` test asserts the child sees `BIND_PORT` set and `PORT` *unset* — which is only true if the parent isn't leaking a `PORT` of its own.
+
+## Why it matters
+
+In a language where you mutate a shared, global `process.env`, injecting a variable is order-dependent and easy to leak between spawns. The `Command` builder gives you an isolated, per-child edit list assembled on a `&mut Command`, so the process can't be spawned half-configured — there's no window where the child exists but `PORT` hasn't been set yet, because `.spawn()` is the last thing you call.
+
+The trap the builder's default hides is the inheritance itself. It's convenient (the child gets `PATH`, `HOME`, and the rest for free) but it's also a silent channel: if the daemon happened to run with `PORT` in its own environment, every child would inherit it, and injection would be masking rather than setting. That's exactly why the test scrubs `PORT`/`BIND_PORT` before starting — not paranoia, but a direct consequence of "inherit, then override" being the default you signed up for.
+
+## Related lessons
+
+- PR #16 stands up the `Supervisor` and the `up()` method this `.env()` call lives inside — the `Arc<Mutex<Inner>>` state and the wait-for-exit task are the foundation this port injection slots into.
+- PR #76 generalizes this single-variable mechanic into a whole daemon-owned `ADJ_*` namespace (`ADJ_NAME`, `ADJ_HOST`, `ADJ_URL`, …) injected *after* `env_file` and `[env]` so the daemon's values win — that's where the full env-layering-and-precedence story gets taught. #17 is the one-variable version; #76 is the layered namespace.
+
+## Dig deeper
+
+- [`std::process::Command`](https://doc.rust-lang.org/std/process/struct.Command.html) — tokio's `Command` mirrors this API. The docs for `.env`, `.envs`, `.env_remove`, and `.env_clear` spell out the inherit-then-edit model, and the struct-level intro is a clean example of the builder pattern.
diff --git a/docs/lessons/19-optional-fields-with-serde.md b/docs/lessons/19-optional-fields-with-serde.md
new file mode 100644
index 0000000..8fd5632
--- /dev/null
+++ b/docs/lessons/19-optional-fields-with-serde.md
@@ -0,0 +1,101 @@
+<!-- Lesson for PR #19. Teaches one concept grounded in the real diff. -->
+
+# PR #19 — Env loading: [env] table and env_file pointer
+
+> **Rust lesson:** `Option<T>` is how a struct field says "this may be absent" — and serde's derive fills a missing `Option` field with `None` for you, while `#[serde(default)]` is what saves any *non*-`Option` field from erroring when its key is missing.
+> **Tags:** `option` · `serde` · `deserialize` · `config`
+> **Merged:** 2026-06-08 · +509/−1 · [View PR](https://github.com/nonrational/adjacent/pull/19)
+
+## The situation
+
+`adjacent.toml` grew two new, entirely optional fields: an `[env]` table of committed-safe `KEY = "value"` pairs, and `env_file`, a pointer to a dotenv file. Most apps set neither. The config struct has to parse a TOML file where these keys are usually just *not there* — and it must not treat "absent" as an error. That is a modeling question before it is a parsing one: how does a Rust struct field say "maybe nothing"?
+
+## The Rust idea
+
+Rust has no `null`. A `String` field always holds a real string; there is no back-door "empty" value that means "unset." When absence is a legitimate state, you say so in the type with `Option<T>` — an enum with exactly two variants:
+
+```rust
+enum Option<T> {
+    None,       // absent
+    Some(T),    // present, carrying a T
+}
+```
+
+The payoff is that the compiler forces every reader to handle both cases before they can touch the inner `T`. "I forgot the field might be missing" stops being a runtime surprise and becomes a compile error.
+
+serde bridges this to the data on disk. When you `#[derive(Deserialize)]`, serde generates code that walks the TOML and fills each struct field. Its default stance is strict: **a field whose key is missing from the input is an error** ("missing field `port`"). That is usually what you want — a required field that silently vanished is a bug.
+
+Two things soften that strictness, and they are easy to conflate:
+
+- `#[serde(default)]` — "if this key is missing, use the type's `Default` instead of erroring." This is what makes a field genuinely optional at the data level.
+- `Option<T>` — a *special case* serde already knows about. A missing `Option<T>` field deserializes to `None` on its own, without `#[serde(default)]`, because serde special-cases the "no value" path for options.
+
+So for the `Option` fields in this PR, the `#[serde(default)]` attribute is technically redundant — they would parse to `None` regardless. It is kept for consistency with the existing `port_env` field above them, and because the intent reads clearly at a glance. Drop `Option` for a required-but-defaulted field (say `port: u64` defaulting to `0`) and the attribute stops being optional itself: without it, a missing `port` is a hard error.
+
+## In this PR
+
+The whole change to the config type is four lines of field declarations:
+
+```rust
+// crates/adj/src/registry.rs
+pub struct AppConfig {
+    pub name: String,
+    pub cmd: String,
+    #[serde(default)]
+    pub port_env: Option<String>,
+    /// Committed-safe environment variables merged into the spawned process env.
+    /// On conflict with `env_file`, this table wins. PORT injection always wins over both.
+    #[serde(default)]
+    pub env: Option<BTreeMap<String, String>>,
+    /// Path to a dotenv-format file, resolved relative to the registered app directory.
+    /// Missing files are a startup error.
+    #[serde(default)]
+    pub env_file: Option<String>,
+}
+```
+
+`name` and `cmd` are bare `String` — required, and a manifest missing either one is rightly rejected. The two new fields are `Option`, so `None` is the normal, no-error resting state.
+
+Notice `env` is `Option<BTreeMap<String, String>>`. A TOML `[env]` table maps straight onto a map type, and serde recurses: it deserializes each `KEY = "value"` entry into a `(String, String)` pair. `BTreeMap` (not `HashMap`) keeps the keys sorted, so iterating it later to set env vars is deterministic — the same manifest always applies its overrides in the same order.
+
+The consumer side then reads these as ordinary `Option`s, and the `if let Some(...)` is the compiler-enforced "handle both cases":
+
+```rust
+// crates/adj/src/supervisor.rs
+// Resolve env layers before any port allocation so a missing `env_file` or unreadable
+// file fails fast with a clear error (and doesn't leak a port reservation).
+let env_file_values = if let Some(rel) = cfg.env_file.as_deref() {
+    let resolved = app_dir.join(rel);
+    Some(load_env_file(&resolved)?)
+} else {
+    None
+};
+```
+
+```rust
+// crates/adj/src/supervisor.rs
+if let Some(values) = &cfg.env {
+    for (k, v) in values {
+        command.env(k, v);
+    }
+}
+command.env(port_env, port.to_string());
+```
+
+`None` means "no `[env]` table, do nothing"; `Some(values)` unwraps the map so you can iterate it. There is no way to iterate the map without first proving it exists — that is `Option` doing its job.
+
+One honest footnote: `env_file` points at a *dotenv* file, which is not TOML, so serde doesn't parse its contents. The PR hand-rolls a tiny `parse_dotenv` in `crates/adj/src/env.rs`. serde's reach ends at the `adjacent.toml` boundary; the file it points to is parsed by hand.
+
+## Why it matters
+
+In a language with `null`, "this field is optional" and "I forgot to set this field" look identical at the type level — both are `null` — and the difference only shows up as a `NullPointerException` at 2am. Rust splits them: absence is `Option`, and the compiler won't let you read through it without checking. Pair that with serde's default strictness and you get a config loader where *required* fields are enforced for free (a missing `cmd` is rejected at parse time) and *optional* fields are spelled out deliberately, one `Option` at a time. The trap this avoids is the silent empty-string or zero-value that a laxer parser would hand you for a field the user never wrote.
+
+## Related lessons
+
+- PR #48 stays in this same `AppConfig` neighborhood but on the `Result` side — not swallowing a parse `Err` when a *present* field is malformed. #19 is about a field being absent; #48 is about a field being present-but-wrong.
+- PR #22 covers the mirror-image direction, serde `Serialize` for the JSON DTOs; PR #75 covers *writing* an `adjacent.toml`. This lesson stays strictly on the `Deserialize` + `Option` reading side.
+
+## Dig deeper
+
+- [The Rust Book, ch. 6.1](https://doc.rust-lang.org/book/ch06-01-defining-an-enum.html#the-option-enum-and-its-advantages-over-null-values) — the `Option` enum and its advantages over null.
+- [serde: field attributes](https://serde.rs/field-attrs.html) — `#[serde(default)]` and how missing fields are handled.
diff --git a/docs/lessons/22-serialize-wire-dto-contract.md b/docs/lessons/22-serialize-wire-dto-contract.md
new file mode 100644
index 0000000..2a59b61
--- /dev/null
+++ b/docs/lessons/22-serialize-wire-dto-contract.md
@@ -0,0 +1,125 @@
+<!-- Lesson for PR #22. Teaches one concept grounded in the real diff. -->
+
+# PR #22 — Agent JSON output on read commands
+
+> **Rust lesson:** Emit your public JSON through dedicated DTO structs, not your internal types — `#[derive(Serialize)]` when the type's natural shape already matches the contract, and hand-write `impl Serialize` when you need to pin an exact shape the derive won't give you.
+> **Tags:** `serde` · `Serialize` · `wire-contract`
+> **Merged:** 2026-06-08 · +1071/−38 · [View PR](https://github.com/nonrational/adjacent/pull/22)
+
+## The situation
+
+Every read command (`adj list`, `status`, `logs`) grew a `--json` flag, and the output is a *documented, stable* schema — `crates/adj/JSON.md` is the contract, and the test suite asserts the exact keys. The catch: the internal `AppState` enum already crosses the daemon's IPC socket as serde JSON, but the shape serde gives that enum is *not* the flat shape the public `--json` contract promises. The PR had to publish an exact documented shape without letting serde's internal enum encoding leak out as the public API.
+
+## The Rust idea
+
+`#[derive(Serialize)]` is a procedural macro. At compile time it reads a type's fields and *writes* an `impl Serialize` for you — attribute-driven code generation. You never see the generated code, but it's ordinary Rust, and `#[serde(...)]` attributes steer what it emits:
+
+- `#[serde(rename_all = "snake_case")]` — `Stdout` becomes `"stdout"` on the wire.
+- `#[serde(tag = "kind")]` on an enum — each variant serializes as an object carrying a `kind` discriminator, e.g. `{"kind":"running","pid":…,"port":…}`.
+- `#[serde(skip_serializing_if = "Option::is_none")]` — omit the field entirely when the check passes.
+
+That derived encoding is faithful and *reversible* — it round-trips cleanly back through `Deserialize`, which is exactly what you want for a type you both send and receive (the daemon's IPC). But it is welded to the type's internal structure. Rename a variant, add a field, switch the tag representation, and the JSON moves with it. That's fine for an internal wire format both ends rebuild from the same crate. It's a landmine for a *public* contract that outside `jq` scripts depend on.
+
+The discipline is a **DTO** — a data-transfer object, a struct whose only job is the wire shape, separate from the type it borrows from. Two cases:
+
+1. When the DTO's natural derived shape already equals the contract, derive it and move on.
+2. When it doesn't — you need a flat object, a hoisted field, an enum rendered as a bare string — remember `Serialize` is just a trait. The derive is one implementation; you can write your own and emit exactly the keys the contract documents.
+
+This PR does both, side by side.
+
+## In this PR
+
+The internal type is a tagged enum. It derives `Serialize`/`Deserialize` because it round-trips over IPC, and the new `started_at` is optional so old serialized state still deserializes:
+
+```rust
+// crates/adj-protocol/src/lib.rs
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(tag = "kind", rename_all = "snake_case")]
+pub enum AppState {
+    Stopped,
+    Running {
+        pid: u32,
+        port: u16,
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        started_at: Option<String>,
+    },
+    Crashed { exit_code: i32 },
+}
+```
+
+Serialized directly, an `AppState::Running` is `{"kind":"running","pid":…,"port":…}` — the `kind` tag, port nested inside the state object. But `JSON.md` documents `list` entries as *flat*: `{ "name": …, "path": …, "state": "running", "port": 53412 }`. `state` is a plain string; `port` sits at the top level and appears only when running. The derive can't produce that from `AppState` — so the PR introduces a DTO with a hand-written impl:
+
+```rust
+// crates/adj-protocol/src/lib.rs
+#[derive(Debug, Clone)]
+pub struct ListEntryDto<'a> {
+    pub name: &'a str,
+    pub path: &'a str,
+    pub state: &'a AppState,
+}
+
+impl<'a> Serialize for ListEntryDto<'a> {
+    fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
+        use serde::ser::SerializeMap;
+        let mut map = serializer.serialize_map(None)?;
+        map.serialize_entry("name", self.name)?;
+        map.serialize_entry("path", self.path)?;
+        map.serialize_entry("state", state_tag(self.state))?;
+        if let AppState::Running { port, .. } = self.state {
+            map.serialize_entry("port", port)?;
+        }
+        map.end()
+    }
+}
+```
+
+Every documented key is written by hand, in order. `state` is flattened to a bare string by a small helper instead of the enum's tagged object:
+
+```rust
+// crates/adj-protocol/src/lib.rs
+fn state_tag(state: &AppState) -> &'static str {
+    match state {
+        AppState::Stopped => "stopped",
+        AppState::Running { .. } => "running",
+        AppState::Crashed { .. } => "crashed",
+    }
+}
+```
+
+The `if let` is where "`port` present iff running" lives — it's a fact about the *contract*, expressed in the serializer, not a property serde could infer from the enum. The DTO borrows (`&'a str`, `&'a AppState`) rather than cloning, so producing the wire view costs nothing but the JSON text. `StatusDto` does the same for `status --json`, adding `pid` / `started_at` / `exit_code` per state.
+
+Contrast the log record. Its natural flat shape *is* the contract, so the derive is enough — no hand-written impl:
+
+```rust
+// crates/adj-protocol/src/lib.rs
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct LogRecord {
+    pub ts: String,
+    pub stream: LogStream,
+    pub line: String,
+}
+
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "snake_case")]
+pub enum LogStream {
+    Stdout,
+    Stderr,
+}
+```
+
+That's the whole judgment call in one file: derive `LogRecord` (shape matches, and it round-trips back off disk), hand-write `ListEntryDto` (shape doesn't match, and it's write-only).
+
+## Why it matters
+
+Slap `#[derive(Serialize)]` on `AppState` and hand it to `println!` and you've quietly published serde's `{"kind":"running",…}` nesting as your public API. It works, the tests pass, everyone's happy — until you rename a variant or restructure the enum six months later and every downstream `jq` pipeline breaks, with nothing in the type to warn you the shape was load-bearing. The DTO is the seam that decouples the contract from the type: `AppState` stays free to change, `ListEntryDto`'s impl stays pinned to `JSON.md`, and `json_output.rs` asserts the exact keys so drift shows up as a red test, not a support ticket. In a dynamically-typed language you'd assemble that dict by hand anyway; Rust's derive is convenient enough to tempt you into exposing the internal shape by accident, and the DTO is the deliberate "no, this is the wire format" boundary.
+
+## Related lessons
+
+- **PR #16** (`Arc<Mutex<T>>`) — this same PR reuses that pattern to write the JSONL: the `LogWriter` wraps the file in `Arc<Mutex<tokio::fs::File>>` so the stdout and stderr reader tasks can append `LogRecord`s without racing.
+- **PR #19** teaches the mirror image on the read side — `#[derive(Deserialize)]` and `Option` fields. Here `LogRecord` round-trips both ways; #22 is the `Serialize` half, #19 the `Deserialize` half.
+- **PR #40** (generics) — the hand-written `fn serialize<S: Serializer>` is generic over the output format; that's the trait-bound machinery #40 covers, applied to serde's serializer.
+
+## Dig deeper
+
+- [serde.rs — Using derive](https://serde.rs/derive.html) — how `#[derive(Serialize, Deserialize)]` and the `#[serde(...)]` attributes drive codegen.
+- [serde.rs — Implementing Serialize](https://serde.rs/impl-serialize.html) — writing the trait by hand with `SerializeMap`, for the shapes the derive won't give you.
diff --git a/docs/lessons/24-single-flight-boot-gate.md b/docs/lessons/24-single-flight-boot-gate.md
new file mode 100644
index 0000000..5b84b56
--- /dev/null
+++ b/docs/lessons/24-single-flight-boot-gate.md
@@ -0,0 +1,92 @@
+<!-- Lesson for PR #24. Teaches one concept grounded in the real diff. -->
+
+# PR #24 — Reverse proxy + lazy-boot + hostname routing
+
+> **Rust lesson:** To boot a resource exactly once under concurrent demand, gate it with a *per-key* lock and re-check the state after you acquire it — a short-lived map lock hands out the per-name lock, which one waiter holds across the slow work while the rest re-check and skip it.
+> **Tags:** `single-flight` · `per-key-mutex`
+> **Merged:** 2026-06-08 · +905/−0 · [View PR](https://github.com/nonrational/adjacent/pull/24)
+
+## The situation
+
+The proxy lazy-boots an app on its first request. But a browser opening a page fires many requests at once — HTML, then a dozen assets — and an agent might hit the same host in parallel too. If each first-request naively booted the app, three concurrent hits would spawn three dev servers fighting over one port. That's a *thundering herd*: N callers all racing to create the same thing. The fix is **single-flight** — one boot runs, everyone else waits for it and reuses the result.
+
+## The Rust idea
+
+Single-flight is a lock plus a **double check**. You check the state, and if the resource already exists you're done. If not, you take a lock, then check *again* — because another task may have finished the boot while you were waiting for the lock. Only if it's still missing do you do the work.
+
+Two design choices make this fast:
+
+1. **Per-key locking, not a global lock.** One `Mutex` guarding all boots would serialize *unrelated* apps: booting `site` would block the first request to `blog`. Instead we keep a `HashMap<name, Arc<Mutex<()>>>` — one lock per app name. Booting `site` and `blog` proceed independently; only concurrent boots of the *same* name serialize.
+
+2. **Two lock granularities.** The map itself needs a lock (two tasks might insert a new name at once). But you only hold the map lock long enough to look up or create the per-name lock, then you `.clone()` the `Arc` and release the map. The slow part — the actual boot — is held under the per-name lock, not the map lock. If you held the map lock across the boot, you'd be back to a global lock and lose the whole point.
+
+The `Mutex<()>` guards *nothing* — its value is the empty tuple. It's a pure mutual-exclusion token; the thing being protected is the boot side effect, not any data inside the lock.
+
+## In this PR
+
+The gate is a lock-of-locks. The map is behind one `Mutex`; each entry is an `Arc<Mutex<()>>` you can clone out and hold on its own:
+
+```rust
+// crates/adj/src/proxy.rs
+#[derive(Default)]
+pub struct BootGate {
+    locks: Mutex<HashMap<String, Arc<Mutex<()>>>>,
+}
+
+impl BootGate {
+    async fn lock_for(&self, name: &str) -> Arc<Mutex<()>> {
+        let mut map = self.locks.lock().await;
+        map.entry(name.to_string())
+            .or_insert_with(|| Arc::new(Mutex::new(())))
+            .clone()
+    }
+}
+```
+
+`lock_for` takes the map lock, gets-or-creates the per-name lock, clones the `Arc`, and returns — the map guard drops at the end of the function, so the map is free again immediately. The caller now holds a clone of the per-name lock and can hold *it* for as long as the boot takes.
+
+`ensure_running` is the double check. A fast path avoids the lock entirely when the app is already hot, then the slow path serializes and re-checks:
+
+```rust
+// crates/adj/src/proxy.rs
+async fn ensure_running(/* ... */) -> Result<u16, ProxyError> {
+    // Fast path: already running. Skip taking the per-name lock to avoid head-of-line blocking
+    // when the app is hot.
+    if let AppState::Running { port, .. } = supervisor.state(name).await {
+        return Ok(port);
+    }
+
+    // ... look up the registry entry + config once, outside the lock ...
+
+    // Single-flight: serialize concurrent boot attempts for this name. The first holder runs the
+    // boot; later holders re-check state under the lock and find Running.
+    let name_lock = gate.lock_for(name).await;
+    let _guard = name_lock.lock().await;
+
+    if let AppState::Running { port, .. } = supervisor.state(name).await {
+        return Ok(port);
+    }
+
+    supervisor
+        .up(entry.path.clone(), cfg.clone())
+        .await
+        .map_err(ProxyError::Other)?;
+    // ... then poll until the child binds its port ...
+}
+```
+
+Three requests for `flight.adj.ac` arrive together. All three miss the fast path. All three call `lock_for` and get the *same* `Arc<Mutex<()>>`. One wins `name_lock.lock().await` and boots; the other two block on `.await` (yielding their worker threads, not spinning). When the winner drops `_guard`, the next task acquires the lock, hits the re-check, sees `Running`, and returns the port without booting. The PR's integration test asserts exactly this: three concurrent first-requests, `assert_eq!(spawns, 1)`.
+
+The `let _guard = ...` binding matters. The guard is held until the end of the function scope; naming it `_guard` (not `_`) keeps it alive. Bind it to a bare `_` and Rust drops it *immediately*, releasing the lock before the boot even starts — silently defeating the whole mechanism.
+
+## Why it matters
+
+In a garbage-collected language you'd reach for a `ConcurrentHashMap.computeIfAbsent` or a library `singleflight` helper and mostly not think about the re-check. Do it by hand and the classic bug is checking state only *before* the lock: two tasks both see "stopped", both wait, both acquire the lock in turn, and both boot — the lock made them polite but didn't make the boot single. The second check, *inside* the lock, is the load-bearing line. The other trap is reaching for one global lock for simplicity, which quietly turns independent app boots into a queue. Per-key locking keeps unrelated work parallel; the double-check keeps related work single.
+
+## Related lessons
+
+- PR #16 introduces the base `Arc<Mutex<T>>` pattern this builds on — shared ownership across `tokio::spawn`ed tasks. Read that first; this lesson is the single-flight *variation* layered on top.
+
+## Dig deeper
+
+- [`tokio::sync::Mutex`](https://docs.rs/tokio/latest/tokio/sync/struct.Mutex.html) — the async mutex used here; note the docs' guidance on holding a guard across `.await`, which is exactly what the boot lock does.
diff --git a/docs/lessons/29-deadlines-and-failure-enums.md b/docs/lessons/29-deadlines-and-failure-enums.md
new file mode 100644
index 0000000..270e92b
--- /dev/null
+++ b/docs/lessons/29-deadlines-and-failure-enums.md
@@ -0,0 +1,117 @@
+<!-- Lesson for PR #29. Teaches one concept grounded in the real diff. -->
+
+# PR #29 — Readiness URL, wait-ready, and idle shutdown
+
+> **Rust lesson:** Bound async work two ways — thread a `deadline: Instant` through a poll loop, and wrap a single hang-prone `await` in `tokio::time::timeout` — then model the outcomes as a custom enum so each caller can react to *why* the wait ended, not just *that* it did.
+> **Tags:** `tokio-timeout` · `deadlines` · `error-enum`
+> **Merged:** 2026-06-08 · +1102/−56 · [View PR](https://github.com/nonrational/adjacent/pull/29)
+
+## The situation
+
+When a request arrives for a stopped app, the proxy lazy-boots it and holds the request until the app answers. That "wait until ready" is unbounded by nature: the app might take two seconds, or crash on startup, or accept the TCP connection but never write a byte. This PR pulled the wait into `readiness.rs`, added an optional `health_check_url` (poll for a 2xx instead of a bare TCP open), and shared the same code with the new `adj wait-ready` command. Both callers need the same thing: a wait that *always* ends, and an answer that says *how* it ended.
+
+## The Rust idea
+
+Two distinct tools, because there are two distinct hangs to bound.
+
+**Bounding the whole operation — a deadline.** An `Instant` is an absolute point on the monotonic clock. Compute it once (`now() + timeout`), thread it into the loop, and each pass checks `now() >= deadline`. An absolute deadline stays fixed no matter how many times you re-enter the check; a relative "time remaining" would have to be recomputed on every iteration. This bounds the *sum* of many poll attempts.
+
+**Bounding one attempt — `tokio::time::timeout`.** A single `.await` can block forever — an HTTP GET to a socket that accepts but never responds never resolves. `tokio::time::timeout(dur, fut)` races `fut` against a timer and returns `Result<T, Elapsed>`: `Ok(value)` if the future finished first, `Err(Elapsed)` if the clock won. This bounds one attempt so a single hung probe can't stall the whole poll cadence.
+
+**Modeling the outcome — a custom enum.** You could return `Result<u16, anyhow::Error>`, but then "crashed" and "timed out" are both just strings, and a caller who wants to treat them differently is stuck matching on message text. Instead, define an enum with one variant per outcome. Now the caller `match`es on the variant, and — the payoff — a crash can *short-circuit* the poll loop instead of waiting out the full deadline.
+
+## In this PR
+
+The outcome type. Note it's a plain `#[derive(Debug)]` enum — no `thiserror`, no `Display`, no `std::error::Error` impl. It never needs one: it's an internal signal that each caller matches immediately and translates into its own error surface.
+
+```rust
+// crates/adj/src/readiness.rs
+#[derive(Debug)]
+pub enum ReadinessError {
+    /// The supervisor reports the app is not running and the deadline passed before it bound
+    /// its port (or the configured health URL never returned 2xx).
+    Timeout,
+    /// The supervised process exited non-zero while we were waiting.
+    Crashed { exit_code: i32 },
+}
+```
+
+The wait itself takes the `deadline` as a parameter and polls. The `Crashed` arm returns *immediately* — that's the whole reason the enum earns its keep:
+
+```rust
+// crates/adj/src/readiness.rs
+pub async fn wait_ready(
+    name: &str,
+    supervisor: &Supervisor,
+    cfg: &AppConfig,
+    deadline: tokio::time::Instant,
+) -> Result<u16, ReadinessError> {
+    loop {
+        match supervisor.state(name).await {
+            AppState::Running { port, .. } => {
+                if probe_once(port, cfg.health_check_url.as_deref()).await {
+                    return Ok(port);
+                }
+                if tokio::time::Instant::now() >= deadline {
+                    return Err(ReadinessError::Timeout);
+                }
+                tokio::time::sleep(READY_POLL_INTERVAL).await;
+            }
+            AppState::Crashed { exit_code } => {
+                return Err(ReadinessError::Crashed { exit_code });
+            }
+            AppState::Stopped => {
+                if tokio::time::Instant::now() >= deadline {
+                    return Err(ReadinessError::Timeout);
+                }
+                tokio::time::sleep(READY_POLL_INTERVAL).await;
+            }
+        }
+    }
+}
+```
+
+Inside a single probe, `tokio::time::timeout` bounds the one `await` that could hang forever — an app that completes the TCP handshake but never writes a response:
+
+```rust
+// crates/adj/src/readiness.rs
+    tokio::time::timeout(Duration::from_millis(500), attempt)
+        .await
+        .ok()
+        .flatten()
+        .unwrap_or(false)
+```
+
+`timeout(...)` yields `Result<Option<bool>, Elapsed>`. `.ok()` drops the `Elapsed` into `Option<Option<bool>>`, `.flatten()` collapses the nesting, and `.unwrap_or(false)` maps *both* failure shapes — the timer fired, or the request errored — to "not ready, poll again." A timed-out probe is not fatal; it just means try once more before the outer deadline.
+
+The payoff lands at the callers, where the *same two variants* fan out to *different* surfaces. In the daemon's `wait-ready` handler each becomes a distinct CLI-facing message:
+
+```rust
+// crates/adj/src/daemon.rs
+    match readiness_wait(&name, supervisor.as_ref(), &cfg, deadline).await {
+        Ok(_) => Ok(Response::Ok),
+        Err(ReadinessError::Timeout) => Err(anyhow!(
+            "app `{name}` did not become ready within {timeout:?}"
+        )),
+        Err(ReadinessError::Crashed { exit_code }) => Err(anyhow!(
+            "app `{name}` crashed while waiting for ready (exit {exit_code})"
+        )),
+    }
+```
+
+The proxy's boot path matches the identical enum but maps `Timeout` to an HTTP 504 and `Crashed` to a 502. One outcome type, two error surfaces, zero string-sniffing.
+
+## Why it matters
+
+Collapse `ReadinessError` back into a single `anyhow::Error` string and two things break. First, the boot path loses the short-circuit: a crash would fall through as "still not ready," and the proxy would poll a dead process until the 60-second deadline before finally giving up — a full minute of a user staring at a hung request for an app that died in the first 200ms. The `Crashed` variant is what lets the loop bail the instant the supervisor reports the exit. Second, without either bound — the outer deadline or the inner `timeout` — a never-ready app pins the request (or the `adj wait-ready` process) forever. A language with exceptions would let you `throw` on timeout, but you'd still be hand-rolling the "which failure was it" dispatch on message strings; the enum makes the answer a type the compiler checks you handled.
+
+## Related lessons
+
+- PR #48 revisits the combinator move in this very file — `.ok().flatten().unwrap_or(false)` deliberately swallows the `Elapsed` and error cases because a failed probe is a *recovery*, not a mistake. #48 is about the opposite call: when swallowing an error is the wrong default.
+- PR #16 introduced the `Arc<Supervisor>` that `wait_ready` borrows as `&Supervisor` — the shared, lock-guarded state the poll loop reads on every pass.
+- PR #52 later hardens the inner probe: the diff here relied on hyper's drop behavior to tear down the connection after a timed-out attempt, and #52 replaces that with an explicit task `abort()` — the cancellation counterpart to this lesson's timeout.
+
+## Dig deeper
+
+- [`tokio::time::timeout`](https://docs.rs/tokio/latest/tokio/time/fn.timeout.html) — the future-vs-timer race and its `Result<T, Elapsed>` return.
+- [`thiserror`](https://docs.rs/thiserror/latest/thiserror/) — reach for it the day `ReadinessError` needs a `Display` impl to cross an API boundary; here a plain `Debug` enum matched at the call site was enough.
diff --git a/docs/lessons/34-fix-landing-page-redirect.md b/docs/lessons/34-fix-landing-page-redirect.md
new file mode 100644
index 0000000..610fc6e
--- /dev/null
+++ b/docs/lessons/34-fix-landing-page-redirect.md
@@ -0,0 +1,99 @@
+<!-- Lesson for PR #34. Teaches one concept grounded in the real diff. -->
+
+# PR #34 — Fix landing-page redirect (adj.ac/ent)
+
+> **Rust lesson:** None — this PR ships no Rust. It fixes a broken client-side redirect on the static apex page (`/cent` → `/ent/`) and teaches how a zero-config `<meta http-equiv="refresh">` bounce works, plus why the `/` in `adj.ac/ent` is a real URL path boundary rather than decoration.
+> **Tags:** `redirects` · `static-site` · `html`
+> **Merged:** 2026-06-08 · +96/−5 · [View PR](https://github.com/nonrational/adjacent/pull/34)
+
+## The situation
+
+The apex domain `adj.ac` serves a bare `index.html` whose only job is to bounce
+visitors to the real landing page. It redirected to `/cent` — a path that exists
+nowhere in the repo. One stray `c`, and the bounce dead-ended on a 404. This PR
+retargets the redirect to `/ent/` and fills in the real page underneath it.
+
+## The idea (no Rust this time)
+
+A static site has no server code at the apex to emit an HTTP `301`/`302`
+redirect — issuing a real 3xx needs host-specific config (`.htaccess`, a
+Cloudflare `_redirects` file, etc.). The option that works on *any* dumb static
+host with zero config is a **meta refresh**: a tag in the HTML `<head>` that the
+browser parses and acts on.
+
+```html
+<!-- index.html (apex) -->
+<meta http-equiv="refresh" content="0; URL='/ent/'">
+<link rel="canonical" href="https://adj.ac/ent/">
+```
+
+`content="0; URL='/ent/'"` reads as *wait 0 seconds, then navigate to `/ent/`*.
+The `0` makes it immediate. Two details carry weight:
+
+- **Root-relative, trailing slash.** The leading `/` resolves from the domain
+  root regardless of where the visitor entered. The trailing slash points at the
+  *directory* `/ent/`, whose index (`ent/index.html`) the host serves. The old
+  `/cent` was just a typo for `/ent` — but a redirect target is a plain string,
+  so nothing flagged that the path didn't exist.
+- **`rel="canonical"`.** Meta-refresh shells look like duplicate content or a
+  sneaky redirect to a crawler. The canonical link tells search engines "the
+  real address is `/ent/` — index *that*, not this empty bouncer."
+
+## The pun is load-bearing on the path
+
+`adj.ac/ent` read aloud is "adjacent." That only works because it is a *real*
+URL: `adj.ac` is the registered domain, `/` is the literal path separator, and
+`ent` is a genuine path beneath it. So the landing content has to live at
+`/ent/` for the joke to resolve — the brand depends on the file layout. The
+wordmark markup encodes the same three-part split:
+
+```html
+<!-- ent/index.html -->
+<h1 class="wordmark"><span class="a">adj.ac</span><span class="slash">/</span><span class="b">ent</span></h1>
+```
+
+Domain in paper-white, slash in rule-gray, `ent` in accent — the styling makes
+the `/` read as a boundary, not a hyphen. (CLAUDE.md locks this: the split is
+`adj.ac` + `ent`, *never* `adj` + `ac.ent`, and "the `/` is the URL path
+boundary.")
+
+## The one tooling detail
+
+`.tool-versions` gains a line:
+
+```
+# .tool-versions
+rust 1.92.0
+nodejs 26.2.0
+```
+
+The site is tooled through Node (`npx live-server`, per the `justfile`), so asdf
+pins a Node version alongside the Rust toolchain. Anyone building the landing
+page now gets the same runtime — the pin lives beside the compiler pin even
+though Cargo never touches the web frontend.
+
+## Why it matters
+
+A meta refresh is the cheapest redirect that runs on any static host — no server,
+no config file. The cost is an extra round trip (fetch the shell, then fetch the
+target) and a weaker signal to search engines than a real `301`, which the
+canonical link partially repairs.
+
+The failure this PR fixes is the one meta refresh makes easy: the target is a
+*string*, not a checked reference. `/cent` ships fine and silently dead-ends —
+nothing validates that the path exists until a human loads the page. Contrast a
+router written in code, where a route pointing at a missing handler often won't
+compile or will trip a test. A redirect string has no such safety net, so the
+typo survives all the way to production.
+
+## Related lessons
+
+- **PR #46** also ships no Rust and covers this same `ent/` landing page — but
+  from the repo-layout angle: why the site sits *beside* the Cargo workspace so
+  `cargo build` never sees it. This lesson is the redirect that *points at* that
+  directory; #46 is where the directory lives.
+
+## Dig deeper
+
+- [MDN — `<meta http-equiv>`, the `refresh` value](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta#http-equiv) — syntax, and why the spec discourages non-zero timers for accessibility.
+- [Google Search Central — Consolidate duplicate URLs (`rel=canonical`)](https://developers.google.com/search/docs/crawling-indexing/consolidate-duplicate-urls) — what the canonical link buys you on a bouncer page.
diff --git a/docs/lessons/36-docs-as-config-contract.md b/docs/lessons/36-docs-as-config-contract.md
new file mode 100644
index 0000000..e76e214
--- /dev/null
+++ b/docs/lessons/36-docs-as-config-contract.md
@@ -0,0 +1,85 @@
+<!-- Lesson for PR #36. Non-Rust: README docs; teaches doc-as-contract + Rust doctests. -->
+
+# PR #36 — Document `health_check_url`, `idle_timeout`, and `adj wait-ready` in README
+
+> **Rust lesson:** None — this PR is pure README prose (+8/−1), no Rust code. The lesson is that user-facing docs *are* the config contract, and the Rust-ecosystem angle worth knowing is **doctests**: `cargo test` compiles and runs the ```rust``` examples in your doc comments, so documented examples can't silently rot.
+> **Tags:** `docs-as-contract` · `doctests`
+> **Merged:** 2026-06-08 · +8/−1 · [View PR](https://github.com/nonrational/adjacent/pull/36)
+
+## The situation
+
+Three features already shipped — readiness probing, idle shutdown, and `adj
+wait-ready` — but the README didn't mention them. If a config key works in the
+code and isn't in the docs, nobody outside the codebase knows it exists. This PR
+closes that gap: three bullets plus two new lines in the example `adjacent.toml`.
+
+## The idea (no Rust this time)
+
+For a config-driven tool, the README *is* the contract. A user reads the example
+`adjacent.toml`, copies it, and trusts that `idle_timeout = "30m"` does what the
+comment says. The docs aren't decoration on top of the behavior — for anyone who
+doesn't read the source, they *are* the behavior.
+
+Which raises the perennial problem: prose drifts. Rename a key, change a default,
+and the README quietly lies until someone notices. Plain Markdown like this
+README has no defense against that — a human has to catch it.
+
+## In this PR
+
+The diff adds the optional fields to the example config, with defaults called out
+in comments:
+
+```toml
+# README.md
+name = "site"
+cmd = "npm run dev"           # must bind to $PORT
+
+# Optional:
+health_check_url = "/healthz" # poll for 2xx instead of TCP-open
+idle_timeout = "30m"          # stop after no requests (default "15m", or "off")
+```
+
+And a bullet stating the contract in prose:
+
+```markdown
+- Idle shutdown. Apps stop after no proxied requests for `idle_timeout`
+  (default `"15m"`, accepts `"30s"` / `"1h"` / `"off"`).
+```
+
+Nothing here is compiled or tested. If someone later changes the default from
+`"15m"` to `"20m"` in the Rust code, this Markdown keeps claiming `"15m"` and no
+tool complains.
+
+## Why it matters — the Rust angle
+
+Rust's answer to doc drift is the **doctest**. When you put a fenced ```rust```
+block in a `///` doc comment, `cargo test` extracts it, compiles it, and runs it
+as a real test:
+
+```rust
+/// Parses an idle-timeout string into a `Duration`.
+///
+/// ```
+/// # use adj::parse_timeout;
+/// assert_eq!(parse_timeout("30s").unwrap().as_secs(), 30);
+/// ```
+pub fn parse_timeout(s: &str) -> Result<Duration, ParseError> { /* ... */ }
+```
+
+If the function signature changes or the behavior drifts, that example stops
+compiling or fails its assertion, and CI goes red. The documented example
+*cannot* silently rot, because it's also a test.
+
+This README is plain Markdown, so it gets none of that — the diff doesn't
+demonstrate doctests, and honesty demands saying so. But the contrast is the
+lesson: a config table in prose is only as correct as the last human who read it;
+a doctest is correct as long as CI is green.
+
+## Related lessons
+
+- PR #16 documents the supervised-app-with-logs flow — same "docs describe a
+  contract the code enforces" shape, from the other direction.
+
+## Dig deeper
+
+- [rustdoc — Documentation tests](https://doc.rust-lang.org/rustdoc/write-documentation/documentation-tests.html) — how `cargo test` runs the examples in your docs, and the `#`-hidden-line trick shown above.
diff --git a/docs/lessons/37-signals-bypass-drop-cleanup.md b/docs/lessons/37-signals-bypass-drop-cleanup.md
new file mode 100644
index 0000000..de68eb9
--- /dev/null
+++ b/docs/lessons/37-signals-bypass-drop-cleanup.md
@@ -0,0 +1,74 @@
+<!-- Lesson for PR #37. Teaches one concept grounded in the real diff. -->
+
+# PR #37 — Handle SIGTERM in daemon socket cleanup
+
+> **Rust lesson:** `Drop` runs on normal scope exit and panic unwinding, but a process killed by a signal skips destructors entirely — so external cleanup like unlinking a Unix socket has to be done explicitly in a `tokio::signal` handler.
+> **Tags:** `tokio-signal` · `drop` · `graceful-shutdown`
+> **Merged:** 2026-06-08 · +15/−4 · [View PR](https://github.com/nonrational/adjacent/pull/37)
+
+## The situation
+
+The daemon binds a Unix socket at `~/.adjacent/sock`. That's a real file on disk, and a stale one blocks the next boot — `UnixListener::bind` fails if the path already exists. The daemon already cleaned it up on Ctrl-C. But `brew services stop` and launchd don't send Ctrl-C (SIGINT); they send **SIGTERM**. So a service-managed shutdown left the socket behind, and the next start had to notice the corpse and remove it. This PR handles SIGTERM too, so the socket goes away cleanly on the shutdown path that actually ships.
+
+## The Rust idea
+
+Rust's usual answer to "clean up a resource" is RAII: give the resource a type, put the teardown in a `Drop` impl, and the compiler runs it for you when the value leaves scope. A `File` closes itself; a `MutexGuard` unlocks itself. You don't write cleanup at every early return, because `Drop` is wired to *scope exit*.
+
+Here's the catch that trips people coming from garbage-collected or exception-based languages: **`Drop` only runs when Rust is in control of the exit.** There are exactly two paths that run destructors — a value going out of scope normally, and stack unwinding during a `panic!`. A signal is neither. When the kernel delivers SIGTERM (or SIGINT) and the process takes the default action, it just *stops*. No stack unwinds. No `Drop` fires. Whatever was living on the stack — including a `UnixListener` — is abandoned, and the OS reclaims memory and file descriptors, but it does **not** run your teardown logic or unlink a socket path you created.
+
+So RAII cannot save you here. Even if you wrote a `Drop` impl that removed the socket file, SIGTERM would walk right past it. The only way to react to a signal is to *ask* the runtime to tell you when one arrives, then do the cleanup yourself before you exit.
+
+That's what `tokio::signal` is for. Two shapes matter:
+
+- `tokio::signal::ctrl_c()` returns a **future** that resolves once, when SIGINT arrives.
+- `tokio::signal::unix::signal(SignalKind::terminate())` returns a `Result<Signal>` — a **stream** you poll with `.recv()`, because a signal can fire many times over a process's life.
+
+You want to react to *whichever* comes first, so you race them with `tokio::select!` — the async "wait on several things, wake on the first to complete" primitive.
+
+## In this PR
+
+```rust
+// crates/adj/src/daemon.rs
+
+// Best-effort cleanup of the socket on shutdown signals so subsequent boots aren't blocked.
+// SIGTERM matters specifically for `brew services stop` / launchd-driven shutdown; SIGINT
+// covers interactive Ctrl-C in the foreground. Either signal triggers the same cleanup.
+let socket_for_signal = socket.clone();
+tokio::spawn(async move {
+    let mut sigterm = match tokio::signal::unix::signal(tokio::signal::unix::SignalKind::terminate()) {
+        Ok(s) => s,
+        Err(err) => {
+            tracing::warn!("failed to install SIGTERM handler: {err}");
+            return;
+        }
+    };
+    tokio::select! {
+        _ = tokio::signal::ctrl_c() => {}
+        _ = sigterm.recv() => {}
+    }
+    let _ = std::fs::remove_file(&socket_for_signal);
+    std::process::exit(0);
+});
+```
+
+Walking the lines that matter:
+
+- **Installing the handler can fail**, so `signal(...)` returns a `Result`. The `match` binds the `Signal` on success; on failure it warns and `return`s out of the task. That's deliberately best-effort — a daemon that can't install a SIGTERM handler should still serve requests, it just won't self-clean on that signal. (See PR #48 for the "warn, don't swallow" reflex.)
+- **`tokio::select!`** races the two sources. Both arms have empty bodies (`{}`) — we don't care *which* signal woke us, only that one did. Whichever future resolves first, `select!` drops the other and control falls through to the shared cleanup below it. Without `select!` you'd `.await` one source and be deaf to the other.
+- **The cleanup is explicit and ordered**: remove the socket file first, *then* exit. `let _ =` discards the `io::Result` from `remove_file` — if the file's already gone, there's nothing to fix.
+- **`std::process::exit(0)`** is the punchline that proves the whole point. `process::exit` terminates immediately and **also does not run destructors** — it's the same "Rust isn't unwinding" situation the signal put us in. That's exactly why the `remove_file` call sits *above* it. If we were relying on `Drop` for the socket, `exit(0)` would skip it just like SIGTERM would. Cleanup has to happen by hand, before the process is gone.
+
+## Why it matters
+
+The trap is assuming RAII is a universal cleanup guarantee. In a GC language you'd reach for a shutdown hook and hit the same wall from the other side; in Rust it's tempting to think "I'll put it in `Drop`" and move on. But `Drop` is a contract about *scopes*, not about *process lifetime*. Signals, `abort()`, `std::process::exit`, and a hard `SIGKILL` (which you can't catch at all) all end the process without unwinding. Any resource that outlives the process's memory — a file on disk, a lock file, a socket path, a row in a database marked "in use" — needs an explicit teardown on the paths where `Drop` won't run. `tokio::signal` is how you get a chance to run that teardown for the signals you *can* catch.
+
+## Related lessons
+
+- **PR #52** is the exact converse of this one: it uses `Drop` deliberately, as an RAII guard that aborts a background task when a value goes out of scope. Read them together — #52 shows `Drop`'s reach (any normal scope exit, guaranteed), #37 shows its limit (a signal walks right past it).
+- **PR #16** covers the `Arc<Mutex<…>>` sharing pattern; the same `socket.clone()` + `move` closure shape shows up here to hand the path into the spawned task.
+- **PR #48** — the `match ... Err(err) => warn; return` arm is the "surface the error, don't swallow it" habit applied to handler installation.
+
+## Dig deeper
+
+- [`tokio::signal` module docs](https://docs.rs/tokio/latest/tokio/signal/index.html) — `ctrl_c`, the Unix `SignalKind` / `Signal::recv` stream API, and the caveats about async-signal-safety.
+- [The Rust Book, ch. 15.3](https://doc.rust-lang.org/book/ch15-03-drop.html) — Running Code on Cleanup with the `Drop` Trait (what `Drop` guarantees — and, by omission, what it doesn't).
diff --git a/docs/lessons/38-deterministic-async-tests.md b/docs/lessons/38-deterministic-async-tests.md
new file mode 100644
index 0000000..d1bc68e
--- /dev/null
+++ b/docs/lessons/38-deterministic-async-tests.md
@@ -0,0 +1,102 @@
+<!-- Lesson for PR #38. Teaches one concept grounded in the real diff. -->
+
+# PR #38 — Fix flaky proxy single-flight test and add CI workflow
+
+> **Rust lesson:** A deterministic async test drives real concurrency and asserts on *observable state* you can count, not on timing — and when such a test still flakes, the flake is a real race in the code, not test noise.
+> **Tags:** `#[tokio::test]` · `test-determinism`
+> **Merged:** 2026-06-08 · +45/−16 · [View PR](https://github.com/nonrational/adjacent/pull/38)
+
+## The situation
+
+A test fired three concurrent first-requests at a cold app and asserted two things:
+every request got `200`, and the app booted exactly once. It passed locally, then
+flaked in CI with a `502`. The obvious "fix" — sprinkle a `sleep`, bump a timeout —
+would have buried the problem. The real fix was one deletion in the proxy. The PR also
+added `.github/workflows/ci.yml` (build + test on every PR, toolchain pinned to 1.92.0,
+cargo cache) so flakes surface on a clean machine instead of only on someone's laptop.
+
+## The Rust idea
+
+`#[tokio::test]` is the async cousin of `#[test]`. A plain `#[test]` can't `.await`
+anything — there's no runtime to drive the futures. The macro wraps your `async fn` so
+it spins up a Tokio runtime, runs the test to completion, and tears the runtime down.
+That's all it does; the *discipline* is on you.
+
+To test concurrency deterministically, two rules:
+
+1. **Drive real concurrent work.** `tokio::task::spawn_blocking` hands each closure to a
+   real OS thread, so three of them race for genuine. Don't simulate the race — cause it.
+2. **Assert on observable state, never on timing.** A `sleep(100ms)` is a *guess* that the
+   system finished within 100ms. On a loaded CI box it didn't, and the test flakes. A
+   count of lines in a file, or an HTTP status code, is a *fact*. Assert the fact.
+
+The test already did both. It spawns three real requests, then checks a spawn-counter file:
+
+```rust
+// crates/adj/tests/proxy.rs  (existing test, unchanged by this PR)
+for h in handles {
+    let (status_line, body) = h.await.expect("join").expect("http_get");
+    assert!(status_line.contains(" 200 "), "status: {status_line}");
+}
+// ...
+assert_eq!(spawns, 1, "expected single boot, saw {spawns} spawns");
+```
+
+So why flake? Because a correctly-written deterministic test that flakes is telling you
+the *code under test* has a race. Here it did.
+
+## In this PR
+
+The proxy had a "fast path" that returned a port the instant the supervisor reported
+`Running` — skipping the readiness wait. But the supervisor flips to `Running` the moment
+it spawns the child shell, *before* the child has bound its port. A second concurrent
+request that hit the fast path in that window forwarded to a dead socket: `502`.
+
+```rust
+// crates/adj/src/proxy.rs  —  removed (the flaky fast path)
+if let AppState::Running { port, .. } = supervisor.state(name).await {
+    return Ok(port);
+}
+```
+
+The fix routes *every* request through the per-name lock and then `wait_ready`, which
+polls the app's real readiness (a TCP probe that actually connects) before returning:
+
+```rust
+// crates/adj/src/proxy.rs  —  the fix
+// We intentionally do NOT short-circuit on a Running state outside the lock. The supervisor
+// flips state to Running the moment it spawns the child — before the child has bound its
+// port. [...] would forward to a port that wasn't accepting yet and get back a spurious 502.
+let name_lock = gate.lock_for(name).await;
+let _guard = name_lock.lock().await;
+
+if !matches!(supervisor.state(name).await, AppState::Running { .. }) {
+    supervisor.up(entry.path.clone(), cfg.clone()).await.map_err(ProxyError::Other)?;
+}
+// ...falls through to wait_ready before forwarding
+```
+
+Notice the symmetry. The *test* waits on observable state (a spawn count), and the *fix*
+makes the proxy wait on observable state (a live TCP connection) instead of trusting a
+`Running` enum that leads reality by a few microseconds. Same principle on both sides:
+don't trust a signal that fires before the thing it signals is true.
+
+## Why it matters
+
+In most languages the reflex for a flaky concurrency test is to add a delay until it goes
+green. That doesn't remove the race — it just widens the window so the race loses *most*
+of the time, and the `502` returns under production load when no test is watching. Rust
+doesn't save you from this; the discipline does. Assert facts you can count, drive the
+real race, and when a deterministic test flakes, hunt the bug in the code rather than
+padding the test. The single-line deletion here is the whole fix — the test was right all
+along.
+
+## Related lessons
+
+- **PR #24** built the per-name single-flight `BootGate` this test exercises — the `lock_for(name)` + re-check pattern is the code under test here.
+- **PR #16** covers the `Arc<Mutex>` sharing that lets the supervisor state and boot gate be read from many concurrent request tasks at once.
+
+## Dig deeper
+
+- [Tokio docs — Testing](https://docs.rs/tokio/latest/tokio/attr.test.html) — what `#[tokio::test]` actually expands to, and its runtime flavors.
+- [The Rust Book, ch. 11](https://doc.rust-lang.org/book/ch11-00-testing.html) — writing and running tests.
diff --git a/docs/lessons/40-serve-https-local-ca.md b/docs/lessons/40-serve-https-local-ca.md
new file mode 100644
index 0000000..c31cc6f
--- /dev/null
+++ b/docs/lessons/40-serve-https-local-ca.md
@@ -0,0 +1,121 @@
+<!-- Lesson for PR #40. Teaches one concept grounded in the real diff. -->
+
+# PR #40 — Serve HTTPS on :8443 via opt-in local CA
+
+> **Rust lesson:** A generic function bounded by traits is compiled into a specialized copy per concrete type (monomorphization), so one serve loop drives both a plain `TcpStream` and a TLS-wrapped stream at zero runtime cost.
+> **Tags:** `generics` · `trait-bounds`
+> **Merged:** 2026-06-08 · +1242/−49 · [View PR](https://github.com/nonrational/adjacent/pull/40)
+
+## The situation
+
+The daemon already ran an HTTP reverse proxy. This PR adds an HTTPS listener on `:8443`
+that terminates TLS with a locally-issued cert, then routes requests exactly like the HTTP
+path. The two listeners differ only at accept time: one hands back a raw TCP stream, the
+other a TLS stream wrapped around one. Everything after — read the request, look up the app,
+proxy it — is identical. The problem: how do you write that shared "everything after" once
+when the two streams are different concrete types?
+
+## The Rust idea
+
+A **generic function** with **trait bounds** is Rust's answer. You write the body once against
+a type parameter `S`, and you constrain `S` to exactly the capabilities the body uses. The
+compiler then does **monomorphization**: for every concrete type you actually call the function
+with, it stamps out a separate, specialized copy with `S` replaced. `serve_plain::<TcpStream>`
+and `serve_plain::<TlsStream<TcpStream>>` become two real functions in the binary.
+
+This is *static dispatch*. In Java or Go you'd take an interface parameter and pay a vtable
+lookup on every method call through it. Rust's monomorphized copies call the concrete methods
+directly — inlinable, no indirection, no per-call cost. You trade a little binary size (two
+copies) for speed. (Rust also offers `dyn Trait` for real dynamic dispatch when you *want* one
+function and are willing to pay the vtable; here, static is the right call.)
+
+The bounds are not decoration — each one is load-bearing:
+
+- `AsyncRead + AsyncWrite` — the serve loop reads request bytes off the stream and writes the
+  response back. Without both, `hyper`'s `serve_connection` won't accept the stream.
+- `Unpin` — async I/O is poll-based and the runtime needs to move the stream around; `Unpin`
+  promises it's safe to move even after polling has begun.
+- `Send` — the connection is driven inside `tokio::spawn`, which may run it on a different
+  worker thread, so the stream must be safe to send across threads.
+- `'static` — the spawned task can outlive the stack frame that launched it, so `S` may not
+  borrow anything shorter-lived.
+
+Drop any one bound and the code that *needs* that capability fails to compile. The bound list
+is the exact contract the body demands, checked at the call site, not at runtime.
+
+## In this PR
+
+The shared loop, written once against a type parameter:
+
+```rust
+// crates/adj/src/proxy.rs
+/// Run one HTTP/1.1 connection against the proxy's per-request handler. Parameterized over the
+/// underlying stream so the HTTP and HTTPS listeners share the same serve loop — the difference
+/// between them is purely accept-time framing.
+async fn serve_plain<S>(stream: S, sup: Arc<Supervisor>, gate: Arc<BootGate>)
+where
+    S: tokio::io::AsyncRead + tokio::io::AsyncWrite + Unpin + Send + 'static,
+{
+    let io = TokioIo::new(stream);
+    let service = service_fn(move |req: Request<Incoming>| {
+        // ... clone sup + gate, dispatch to handle(req, ...)
+    });
+    if let Err(err) = server_http1::Builder::new()
+        .serve_connection(io, service)
+        .with_upgrades()
+        .await
+    {
+        tracing::debug!("proxy connection ended: {err}");
+    }
+}
+```
+
+The HTTP listener calls it with the raw accepted stream:
+
+```rust
+// crates/adj/src/proxy.rs — inside run()
+tokio::spawn(async move {
+    serve_plain(stream, sup, gate).await;   // S = TcpStream
+});
+```
+
+The HTTPS listener does the TLS handshake first, then hands the *wrapped* stream to the same
+function:
+
+```rust
+// crates/adj/src/proxy.rs — inside run_https()
+let tls_stream = match acceptor.accept(stream).await {
+    Ok(s) => s,
+    Err(err) => {
+        tracing::debug!("tls handshake failed: {err}");
+        return;
+    }
+};
+serve_plain(tls_stream, sup, gate).await;    // S = TlsStream<TcpStream>
+```
+
+Note there are no turbofish annotations at the call sites — the compiler infers `S` from the
+argument's type. The `TlsStream` that `tokio_rustls` produces already implements `AsyncRead +
+AsyncWrite + Unpin + Send`, so it satisfies the bounds and the identical body just works.
+
+## Why it matters
+
+The alternative is copy-paste: a second serve loop for the TLS stream, byte-for-byte the same
+except the parameter type. Two copies drift. A bug fix or a `with_upgrades()` tweak lands in
+one and gets forgotten in the other. Generics collapse them into a single source of truth that
+the type system re-checks against every concrete stream you feed it.
+
+A dynamically-typed language would let you pass either stream into one function and only find
+out at runtime — mid-request, on a live connection — that one of them can't do something the
+body assumed. Rust's bounds move that check to compile time: if a stream type is missing
+`Send`, the `tokio::spawn` call site refuses to build. You cannot ship the broken combination.
+
+## Related lessons
+
+- The `run_https` task is spawned best-effort (logs at `error!` and exits if the CA is missing,
+  leaving HTTP and the control plane serving) — a small lesson in fault-isolated `tokio` tasks.
+
+## Dig deeper
+
+- [The Rust Book, ch. 10.1](https://doc.rust-lang.org/book/ch10-01-syntax.html) — Generic Data Types
+- [The Rust Book, ch. 10.2](https://doc.rust-lang.org/book/ch10-02-traits.html) — Traits: Defining Shared Behavior (see "Using Trait Bounds" and the note on monomorphization in ch. 10.1)
diff --git a/docs/lessons/41-raw-string-templated-doc.md b/docs/lessons/41-raw-string-templated-doc.md
new file mode 100644
index 0000000..1700ae9
--- /dev/null
+++ b/docs/lessons/41-raw-string-templated-doc.md
@@ -0,0 +1,117 @@
+<!-- Lesson for PR #41. Teaches one concept grounded in the real diff. -->
+
+# PR #41 — Add `adj agent-instructions` command
+
+> **Rust lesson:** A raw string literal (`r#"…"#`) bakes a whole multi-line document into the binary verbatim — no escaping, no external file — and `format!`'s in-scope capture (`{name}`) splices in the dynamic fields, so the template ships *inside* the binary and only the two live values are read at run time.
+> **Tags:** `raw-string-literals` · `format-macro` · `string-templating`
+> **Merged:** 2026-06-08 · +783/−0 · [View PR](https://github.com/nonrational/adjacent/pull/41)
+
+## The situation
+
+`adj agent-instructions` prints a markdown steering doc telling a coding agent to
+drive the app through `adj` instead of running the dev command itself. The doc is
+mostly fixed prose with two holes: the app's `name` and its `cmd`, both read from
+`adjacent.toml`. The whole thing prints to stdout — no daemon, no template file on
+disk. So where does the boilerplate live, and how do the two fields get spliced in?
+
+## The Rust idea
+
+**Raw string literals.** An ordinary `"..."` string processes escapes: `\n` is a
+newline, `\t` a tab, and to put a literal `"` or `\` inside you have to escape it.
+That gets painful fast for a multi-line markdown doc full of backticks and `#`
+headers. A *raw* string turns escape processing off — `r"..."` treats every
+character between the quotes literally, backslashes and newlines included.
+
+The `#` delimiters guard the ends: `r#"..."#` only terminates at the `"#` sequence,
+so a bare `"` inside the content won't close it early. Need to embed the sequence
+`"#` itself? Add more hashes — `r##"..."##`. This is the same tool you'd reach for
+with a regex or a Windows path, here holding a page of markdown exactly as it
+renders.
+
+Because the literal is written directly in the source, it compiles into the
+binary's read-only data. The boilerplate is *self-contained* — there is no
+`template.md` to ship alongside `adj` and no file read at run time for the fixed
+text.
+
+**Templating with `format!`.** The two dynamic fields are `{name}` and `{cmd}`.
+Since Rust 2021, `format!` captures identifiers that are already in scope: `{name}`
+means "the local variable `name`," with no trailing `name = name` argument. That's
+why `render`'s parameters are *named* `name` and `cmd` to match the placeholders,
+and the `format!` call has no arguments after the string.
+
+## In this PR
+
+The template is a raw string literal; `format!` fills the two holes (trimmed):
+
+```rust
+// crates/adj/src/agent_docs.rs
+fn render(name: &str, cmd: &str) -> String {
+    format!(
+        r#"# Working with `{name}` via Adjacent
+
+This project's dev server is supervised by **Adjacent** (`adj`). The agent does not
+start the server directly — `adj` lazy-boots it on the first proxied request, captures
+stdout/stderr to `~/.adjacent/logs/{name}.log`, and stops it on idle.
+
+## Don't run the dev command yourself
+
+Don't run `{cmd}` directly. Adjacent owns the process. Running it directly
+double-binds the port and Adjacent loses visibility into the log stream.
+// ... (adj status / logs / restart / wait-ready, verify loop) ...
+"#
+    )
+}
+```
+
+The only thing read from disk at run time is the manifest, and only to pull `name`
+and `cmd` out of it — everything else is already in the binary:
+
+```rust
+// crates/adj/src/agent_docs.rs
+pub fn emit(path: Option<String>) -> Result<()> {
+    let dir: PathBuf = match path {
+        Some(p) => PathBuf::from(p),
+        None => std::env::current_dir().context("resolving current directory")?,
+    };
+    let cfg = registry::read_app_config(&dir)?;
+    print!("{}", render(&cfg.name, &cfg.cmd));
+    Ok(())
+}
+```
+
+One subtlety: `format!` still treats `{` and `}` specially even inside a raw string,
+so a *literal* brace in the doc would have to be written `{{` or `}}`. This template
+has none, which is part of why the plain `format!` stays readable.
+
+## Why it matters
+
+Reach for a run-time read instead — `std::fs::read_to_string("template.md")` — and
+the binary grows a hidden dependency: the file has to exist at the right path when
+`adj` runs. Ship the binary on its own and the command breaks at run time with a
+"file not found," not at build time. Baking the text into the source removes that
+whole failure mode: if it compiled, the content is there.
+
+The sibling technique for the *same* self-contained benefit is `include_str!`, which
+pulls an entire separate file's bytes in **at compile time** — best when the asset is
+large or edited by someone who shouldn't touch `.rs` files. This repo does exactly
+that for the dashboard HTML (`const HTML: &str = include_str!("../assets/status.html")`
+in `status.rs`). For a two-field template a few dozen lines long, an inline raw string
+keeps the text next to the one function that formats it — no second file to keep in
+sync. Same "it's in the binary" guarantee, different call on where the source text
+lives.
+
+## Related lessons
+
+- PR #48 covers the `Result` / `?` / `anyhow::Context` machinery visible in `emit`
+  here — the `.context(...)?` that turns a failed `current_dir()` into a labeled
+  error instead of a silent one.
+- The `include_str!` route to a self-contained binary — embedding a *whole file* at
+  compile time — shows up in the dashboard work (PR #45); this PR deliberately inlines
+  a literal instead, so the two make a clean before/after on "when is the asset big
+  enough to earn its own file?"
+
+## Dig deeper
+
+- [Rust Reference — Raw string literals](https://doc.rust-lang.org/reference/tokens.html#raw-string-literals) — the `r#"…"#` grammar and the multi-hash rule.
+- [`std::fmt`](https://doc.rust-lang.org/std/fmt/) — `format!` syntax, including captured identifiers (`{name}`) and escaping braces with `{{` / `}}`.
+- [`std::include_str!`](https://doc.rust-lang.org/std/macro.include_str.html) — the sibling: embed an external file's contents into the binary at compile time.
diff --git a/docs/lessons/43-trait-as-extension-point.md b/docs/lessons/43-trait-as-extension-point.md
new file mode 100644
index 0000000..dd0970f
--- /dev/null
+++ b/docs/lessons/43-trait-as-extension-point.md
@@ -0,0 +1,145 @@
+<!-- Lesson for PR #43. Teaches one concept grounded in the real diff. -->
+
+# PR #43 — Move CA private key into the macOS Keychain and add nameConstraints
+
+> **Rust lesson:** Implementing a trait a *library* defines lets you plug your own behavior into that library's machinery — here, `KeychainKey` implements rcgen's `RemoteKeyPair` so certificate signing calls out to the macOS Keychain and the private key never enters process memory.
+> **Tags:** `trait-impl` · `ffi`
+> **Merged:** 2026-06-09 · +682/−38 · [View PR](https://github.com/nonrational/adjacent/pull/43)
+
+## The situation
+
+The local CA's private key used to sit at `~/.adjacent/ca.key` — a PEM file any backup tool
+or process running as the user could copy. This PR moves the key into the macOS login keychain,
+marked non-extractable, so the bytes never leave the OS. But rcgen — the crate that builds and
+signs the CA cert — normally expects to *hold* the private key and sign with it directly. How do
+you let rcgen produce a signed certificate when it can't have the key?
+
+## The Rust idea
+
+rcgen anticipated exactly this and left a seam: a trait, `RemoteKeyPair`. A library that exposes
+a trait is saying "I don't need to own this behavior; give me anything that can do these three
+things and I'll call back into it." That's a trait used as an **extension point**. You don't
+subclass rcgen or fork it — you write a struct of your own and *implement its trait* for that
+struct. rcgen then drives your code without ever knowing what's behind it: an HSM, a cloud KMS,
+or in our case the macOS Keychain.
+
+`RemoteKeyPair` requires three methods — hand me the public key, tell me the signature
+algorithm, and sign these bytes. Fill all three and rcgen treats your type as a signer. The
+`sign` method is where the magic happens: rcgen calls it, and *your* implementation decides how
+the signature gets made. Ours forwards the request to the OS.
+
+This is the mirror image of [PR #40](40-serve-https-local-ca.md). There, a
+trait was a **bound** on a generic — "I accept any `S` that can read and write" — resolved at
+compile time into a specialized copy per type (static dispatch). Here we go the other way: we
+*implement* a trait and hand rcgen a `Box<dyn RemoteKeyPair>`, a **trait object**. rcgen holds
+one boxed value and dispatches through a vtable at runtime, because it's compiled once and must
+work with signers it's never heard of. Same feature — traits — two opposite uses: constraining a
+caller vs. supplying a plug-in.
+
+## In this PR
+
+The trait implementation. rcgen defines the three method signatures; we fill each with
+keychain-backed behavior:
+
+```rust
+// crates/adj/src/tls/keychain.rs
+impl RemoteKeyPair for KeychainKey {
+    fn public_key(&self) -> &[u8] {
+        &self.public_bytes
+    }
+
+    fn algorithm(&self) -> &'static SignatureAlgorithm {
+        &PKCS_ECDSA_P256_SHA256
+    }
+
+    fn sign(&self, msg: &[u8]) -> std::result::Result<Vec<u8>, RcgenError> {
+        self.private
+            .create_signature(Algorithm::ECDSASignatureMessageX962SHA256, msg)
+            .map_err(|cf_err| {
+                // rcgen's RemoteKeyError has no payload — log the CFError so it's not lost.
+                tracing::error!(error = %cf_err, "Keychain signing failed");
+                RcgenError::RemoteKeyError
+            })
+    }
+}
+```
+
+Note `sign` returns rcgen's `Result<Vec<u8>, RcgenError>`, not our own error type — the trait
+dictates the shape, so we `map_err` the Keychain's error into the variant rcgen expects.
+
+Handing the implementation to rcgen is one call. `Box::new(self)` puts our value on the heap as a
+trait object so rcgen can store it behind `dyn RemoteKeyPair`:
+
+```rust
+// crates/adj/src/tls/keychain.rs
+pub fn into_rcgen_keypair(self) -> Result<KeyPair> {
+    KeyPair::from_remote(Box::new(self))
+        .map_err(|e| anyhow!("constructing rcgen KeyPair from Keychain handle: {e}"))
+}
+```
+
+From rcgen's side the key is now indistinguishable from any other. The cert-building code is
+untouched — `self_signed` reaches through the trait and calls our `sign` when it needs a
+signature:
+
+```rust
+// crates/adj/src/tls.rs — generate_ca()
+let ca_handle = keychain::generate().context("creating Keychain CA key")?;
+let ca_key = ca_handle.into_rcgen_keypair()?;
+let params = build_ca_params();
+let signed = params
+    .self_signed(&ca_key)          // rcgen calls KeychainKey::sign() in here
+    .context("self-signing CA cert")?;
+```
+
+### Supporting detail: the `unsafe` FFI seam
+
+Our `sign` bottoms out in Apple's C Security framework, and generating the key does too. That
+crossing is where `unsafe` shows up. A C constant the Rust bindings didn't expose gets linked
+directly:
+
+```rust
+// crates/adj/src/tls/keychain.rs
+extern "C" {
+    static kSecAttrIsExtractable: core_foundation_sys::string::CFStringRef;
+}
+```
+
+And the raw call into the framework is wrapped in `unsafe`:
+
+```rust
+// crates/adj/src/tls/keychain.rs — create_random_key()
+let key_ref: SecKeyRef =
+    unsafe { SecKeyCreateRandomKey(params.as_concrete_TypeRef(), &mut err) };
+```
+
+`unsafe` here doesn't mean "dangerous" — it means *the compiler can't verify this*. Rust's
+guarantees (valid pointers, correct ownership, no data races) stop at the C boundary. The C
+framework might hand back a null pointer, or expect a specific retain/release discipline the
+borrow checker knows nothing about. `unsafe` is you signing off: "I've read the framework's
+contract and I'm upholding it." It marks the exact lines where that promise lives, so a reader
+knows precisely where Rust's safety net ends and manual care begins.
+
+## Why it matters
+
+The extension-point pattern is how you get library code to do something its authors never
+imagined — sign with a key they can't see — without touching their source. rcgen stays a
+dependency you pull from crates.io; the keychain integration lives entirely in your crate. The
+trait is the contract between them, and the compiler enforces that you honor it: leave out
+`sign`, or return the wrong error type, and it won't build.
+
+A language without this seam would force a worse trade. You'd either fork rcgen to teach it about
+keychains, or pull the private key into memory so rcgen could sign the ordinary way — which is
+the exact thing this PR set out to prevent. The trait lets the key stay in the OS while rcgen
+does its job none the wiser.
+
+## Related lessons
+
+- [PR #40](40-serve-https-local-ca.md) — the *other* face of traits: as a
+  **bound** on a generic (static dispatch, monomorphized per type). Read side by side with this
+  one to see constraining-a-caller vs. supplying-a-plug-in.
+
+## Dig deeper
+
+- [The Rust Book, ch. 10.2](https://doc.rust-lang.org/book/ch10-02-traits.html) — Traits: Defining Shared Behavior (implementing a trait on your own type; trait objects and `Box<dyn Trait>` are in ch. 18.2)
+- [The Rustonomicon, ch. on FFI](https://doc.rust-lang.org/nomicon/ffi.html) — calling C, `extern` blocks, and why the boundary is `unsafe`
diff --git a/docs/lessons/45-iterator-map-collect-rows.md b/docs/lessons/45-iterator-map-collect-rows.md
new file mode 100644
index 0000000..40625c3
--- /dev/null
+++ b/docs/lessons/45-iterator-map-collect-rows.md
@@ -0,0 +1,108 @@
+<!-- Lesson for PR #45. Teaches one concept grounded in the real diff. -->
+
+# PR #45 — Add built-in dashboard at status.adj.ac
+
+> **Rust lesson:** `iter().map(f).collect()` is how you turn one collection into another — a lazy pipeline that does nothing until `collect` drives it.
+> **Tags:** `iterators` · `map-collect`
+> **Merged:** 2026-06-09 · +817/−0 · [View PR](https://github.com/nonrational/adjacent/pull/45)
+
+## The situation
+
+The dashboard at `status.adj.ac` polls `GET /apps.json` and gets back one JSON
+object per registered app. The daemon holds each app as an `AppSummary` (name,
+path, live state). The handler's job: take that list and produce a list of
+wire-shaped `DashboardEntry` objects to serialize. Classic "transform a
+collection into rendered rows."
+
+## The Rust idea
+
+In many languages you'd write a `for` loop, build an empty array, and `push`
+each transformed item. Rust can do that too — but the idiomatic move is an
+**iterator chain**: `.iter()` to walk the collection, `.map(f)` to transform
+each element, `.collect()` to gather the results into a new collection.
+
+Two things make this worth learning:
+
+**Iterators are lazy.** `.map(f)` doesn't run `f` on anything. It returns a
+`Map` value that *remembers* what to do. Nothing happens until something pulls
+items through — here, `.collect()`. That's why you can chain ten adapters and
+pay for zero of them until the final consumer runs. (In a test below, `.find()`
+is a consumer that stops early — it walks only as far as the first match.)
+
+**`.collect()` builds the target type.** The type you're collecting *into*
+drives it. Annotate the binding as `Vec<DashboardEntry>` and `collect` fills a
+`Vec`. The compiler infers the rest.
+
+## In this PR
+
+The transform is one line — a pure, synchronous mapping:
+
+```rust
+// crates/adj/src/status.rs
+let dtos: Vec<DashboardEntry> = entries.iter().map(dashboard_entry).collect();
+// ... then serde_json::to_vec(&dtos) turns the Vec into the JSON body
+```
+
+`entries.iter()` yields `&AppSummary`. `dashboard_entry` takes exactly that and
+returns a `DashboardEntry`, so it drops straight in as the map function — no
+closure needed. `.collect()` gathers them into the `Vec` the annotation asks
+for. Read it left to right: "for each summary, make a dashboard entry, gather
+them up."
+
+Contrast that with the function that *builds* `entries` a few lines down:
+
+```rust
+// crates/adj/src/status.rs
+async fn snapshot(supervisor: Arc<Supervisor>) -> anyhow::Result<Vec<AppSummary>> {
+    let reg = Registry::load()?;
+    let mut entries = Vec::with_capacity(reg.apps.len());
+    for (name, entry) in &reg.apps {
+        let state = supervisor.state(name).await;
+        entries.push(AppSummary {
+            name: name.clone(),
+            path: entry.path.display().to_string(),
+            state,
+        });
+    }
+    Ok(entries)
+}
+```
+
+Why a plain `for` loop here and a `.map().collect()` there? Because this loop
+`.await`s `supervisor.state(name)` on every pass. A plain `.map()` closure can't
+`await` — its output would be a future, not a value — so an async transform
+falls back to the loop. The rule of thumb: **synchronous, side-effect-free
+transform → iterator chain; anything that awaits or fails per-item → loop.**
+The two idioms sit side by side in the same file, each used where it fits.
+
+One efficiency note in the loop: `Vec::with_capacity(reg.apps.len())`
+pre-allocates for the known count, so the `push`es never trigger a reallocation
++ copy as the vector grows.
+
+## Why it matters
+
+`.iter().map(f).collect()` reads as a single intention — "these become those" —
+where a hand-rolled loop makes you track a mutable accumulator and read three
+lines to confirm it only ever appends. The laziness means chains stay cheap: no
+intermediate collection is materialized between adapters. And because
+`dashboard_entry` returns a `DashboardEntry<'_>` that *borrows* (`&'a str`) from
+each `AppSummary` rather than cloning strings, the whole render is references
+until `serde_json::to_vec` walks them — the `entries` vector just has to outlive
+the serialize call.
+
+The trap the chain sidesteps: reaching for it when the per-item work can fail or
+await. A `.map()` that returns `Result` leaves you holding a
+`Vec<Result<T, E>>` and no clean error path; that's exactly why `snapshot` stays
+a loop with `?`. Match the tool to the shape of the work.
+
+## Related lessons
+
+- PR #41 owns `include_str!` — the static HTML shell (`const HTML`) is embedded
+  that way; this lesson is only about the *dynamic* JSON the iterator chain builds.
+- PR #16 — the `Arc<Supervisor>` threaded through `snapshot` and `handle` is the
+  `Arc<Mutex>` sharing pattern.
+
+## Dig deeper
+
+- [The Rust Book, ch. 13.2](https://doc.rust-lang.org/book/ch13-02-iterators.html) — Processing a Series of Items with Iterators (laziness, `map`, `collect`).
+- [`std::fmt::Write`](https://doc.rust-lang.org/std/fmt/trait.Write.html) — the string-building cousin: when you *do* assemble text by hand, `write!`/`writeln!` append into one `String` instead of allocating a fresh string per `format!` + `+`.
diff --git a/docs/lessons/46-revamp-landing-positioning-page.md b/docs/lessons/46-revamp-landing-positioning-page.md
new file mode 100644
index 0000000..98c8623
--- /dev/null
+++ b/docs/lessons/46-revamp-landing-positioning-page.md
@@ -0,0 +1,131 @@
+<!--
+Lesson for PR #46. Honest entry: this PR ships no Rust. It teaches how a
+single-binary Rust project carries a non-Rust web frontend alongside its crates,
+plus the one real Rust-ecosystem detail the diff does touch (dual licensing).
+-->
+
+# PR #46 — Revamp landing page into a positioning page
+
+> **Rust lesson:** None — this PR has no Rust code. It's the `ent/` landing page (HTML/CSS). The lesson is how a single-binary Rust project carries a web frontend *beside* the Cargo workspace so the two never touch, and the one Rust-ecosystem convention the diff does hit: dual `MIT OR Apache-2.0` licensing.
+> **Tags:** `repo-layout` · `web-frontend` · `dual-license`
+> **Merged:** 2026-06-09 · +341/−24 · [View PR](https://github.com/nonrational/adjacent/pull/46)
+
+## The situation
+
+Adjacent needed a real landing page — not just a wordmark, but a *positioning
+page*: hero, problem statement, the four-command flow, design principles, status.
+A "positioning page" answers "what is this and why do I care" for a first-time
+visitor, versus a "coming soon" placeholder. The whole change lives in `ent/`,
+the project's static web frontend. No crate was rebuilt.
+
+## The idea (no Rust this time)
+
+Adjacent is one Rust binary, `adj`. But the project also ships a website. The
+question every polyglot repo faces: *where do the web assets live so they don't
+leak into the build of the thing you actually compile?*
+
+Cargo's answer is the **workspace membership list**. Cargo only sees, compiles,
+and lints what `members` names. Anything else in the tree is invisible to it —
+a directory of HTML is just files on disk as far as `cargo build` is concerned.
+So the convention is: put the frontend in a **sibling directory** to `crates/`,
+and leave it out of `members`. It gets served or deployed by something else
+(here, eventually Cloudflare Pages), never bundled into the binary.
+
+## In this PR
+
+The workspace lists two crates and nothing web-facing:
+
+```toml
+# Cargo.toml
+[workspace]
+members = [
+    "crates/adj",
+    "crates/adj-protocol",
+]
+```
+
+The site lives one level up from those crates, entirely outside that list:
+
+```
+adjacent/
+├── crates/          # the Cargo workspace — what `adj` compiles
+│   ├── adj/
+│   └── adj-protocol/
+├── ent/             # the web frontend — Cargo never sees this
+│   ├── index.html
+│   └── favicon.svg
+└── index.html       # root redirect → /ent/
+```
+
+`ent/index.html` is where the 341 lines land — plain HTML with an inline
+`<style>` block, no build step. The positioning content is the new hero
+category line and the two-column problem statement:
+
+```html
+<!-- ent/index.html -->
+<p class="category">Adjacent is a local dev-server harness &mdash; one supervised
+  dev server that you and your agent share, behind a real URL.</p>
+
+<section class="statement">
+  <h2>Your dev server has two developers now.</h2>
+  <div>
+    <p>When you and your agent need the same local server, you evict each other.
+      The agent takes the process &mdash; you lose the logs. You take it back
+      &mdash; the agent can't verify its work.</p>
+    <p><strong>Adjacent supervises the server so neither of you has to own
+      it.</strong> One daemon boots, routes and watches every app; both of you
+      talk to it through the same CLI.</p>
+  </div>
+</section>
+```
+
+The root-level `index.html` is a one-line redirect so `adj.ac/` lands on the
+real page at `adj.ac/ent/` — the `/ent` path split is the brand pun (`adj.ac`
++ `ent`), enforced by URL structure:
+
+```html
+<!-- index.html -->
+<meta http-equiv="refresh" content="0; URL='/ent/'">
+<link rel="canonical" href="https://adj.ac/ent/">
+```
+
+### The one Rust-ecosystem thing in the diff
+
+`Cargo.toml` flips the license, and this *is* a Rust convention worth knowing:
+
+```toml
+# Cargo.toml — before / after
+-license = "MIT"
++license = "MIT OR Apache-2.0"
+```
+
+Rust itself, and the overwhelming majority of crates on crates.io, dual-license
+under **`MIT OR Apache-2.0`**. The SPDX `OR` means a downstream user picks
+either license — MIT for simplicity, Apache-2.0 for its explicit patent grant.
+It's the community default; publishing a crate under bare MIT reads as slightly
+off-convention. The PR added `LICENSE-MIT` and `LICENSE-APACHE` files to match,
+which is the expected on-disk layout for a dual-licensed Rust project.
+
+## Why it matters
+
+Keep the frontend out of `members` and Cargo stays fast and honest: `cargo build`
+compiles only Rust, `cargo test` runs only Rust tests, and a broken bit of CSS
+can never fail a `cargo` command. Pull the site *into* the workspace — say, as a
+crate with a `build.rs` that embeds the HTML — and now every landing-page tweak
+recompiles the binary and CI treats a copy edit like a code change. The sibling
+directory is the cheap, correct boundary.
+
+On licensing: `MIT OR Apache-2.0` isn't cosmetic. The Apache-2.0 half carries an
+explicit patent grant that bare MIT lacks, and matching the ecosystem default is
+what lets other Rust projects depend on yours without a legal review.
+
+## Related lessons
+
+- The `justfile` here also bumped `just serve` to `--port=8081` so live-server
+  wouldn't collide with the proxy's default `:8080` — a small nod to the exact
+  port-contention problem Adjacent exists to solve.
+
+## Dig deeper
+
+- [The Cargo Book — Workspaces](https://doc.rust-lang.org/cargo/reference/workspaces.html) — how `members` defines what Cargo compiles, and why a sibling directory stays invisible.
+- [Rust API Guidelines — Necessities](https://rust-lang.github.io/api-guidelines/necessities.html#crate-and-its-dependencies-have-a-permissive-license-c-permissive) — the `MIT OR Apache-2.0` dual-license convention, stated as a guideline.
diff --git a/docs/lessons/47-integration-tests-separate-crate.md b/docs/lessons/47-integration-tests-separate-crate.md
new file mode 100644
index 0000000..b0fdd76
--- /dev/null
+++ b/docs/lessons/47-integration-tests-separate-crate.md
@@ -0,0 +1,124 @@
+<!-- Lesson for PR #47. Teaches one concept grounded in the real diff. -->
+
+# PR #47 — Document and test the docker run container convention
+
+> **Rust lesson:** Every file under `crates/adj/tests/` is compiled as its *own* separate crate that links your code as an outside dependency — so it can only touch the public API, and for a binary-only crate that means driving the compiled executable via `CARGO_BIN_EXE_adj`.
+> **Tags:** `integration-tests` · `CARGO_BIN_EXE`
+> **Merged:** 2026-06-10 · +283/−0 · [View PR](https://github.com/nonrational/adjacent/pull/47)
+
+## The situation
+
+The PR is honest about being two things: a README section documenting how to run a
+containerized app under Adjacent, plus one new integration test that proves the
+convention actually works. The test — `crates/adj/tests/docker.rs` — lazy-boots
+`traefik/whoami` through the proxy, asserts a 200, checks `docker ps` sees the
+container, then runs `adj down` and confirms the container is gone. That last
+assertion is the one that would catch a signal-forwarding regression.
+
+To do all that, the test has to start a *real* `adj` daemon and talk to it exactly
+like a user would. That constraint isn't incidental — it falls straight out of how
+Rust organizes tests.
+
+## The Rust idea
+
+Rust has two places tests live, and they are not interchangeable:
+
+1. **Unit tests** — a `#[cfg(test)] mod tests { ... }` block *inside* a source file
+   (e.g. `src/supervisor.rs`). This module is compiled as part of the same crate, so
+   it can reach *private* functions, structs, and fields. Use it to test internals.
+
+2. **Integration tests** — each file in the top-level `tests/` directory. Here's the
+   part that surprises people coming from other languages: **Cargo compiles each of
+   these files as its own independent crate**, and that crate depends on yours the way
+   any outside consumer would. It can only see `pub` items. Private internals are
+   invisible to it, on purpose — an integration test proves the *public surface* works.
+
+Now the twist that makes `adj` interesting. `crates/adj` is a **binary-only** crate:
+its `Cargo.toml` declares a `[[bin]]` and there's no `lib.rs`. A binary exposes no
+library API to an external crate at all — there are no `pub fn`s to call. So the
+integration test can't link against `adj` and call functions. Instead it drives the
+compiled `adj` executable as a subprocess, the same as a shell would.
+
+Cargo makes that ergonomic: when it builds the test, it sets an environment variable
+`CARGO_BIN_EXE_<name>` to the absolute path of the compiled binary. `env!(...)` reads
+it *at compile time*, so the path is baked in — no guessing at `target/debug/`, no
+`cargo build` ordering to manage.
+
+## In this PR
+
+The test resolves the binary through that Cargo-provided variable:
+
+```rust
+// crates/adj/tests/docker.rs
+fn adj_bin() -> PathBuf {
+    PathBuf::from(env!("CARGO_BIN_EXE_adj"))
+}
+```
+
+Because it's driving a real binary, it also stands up a real daemon — sandboxed into
+a throwaway `TempDir` via `ADJACENT_HOME`, on a random port via `ADJACENT_PROXY_PORT`,
+so the test never touches your actual `~/.adjacent/`:
+
+```rust
+// crates/adj/tests/docker.rs
+fn cmd(&self) -> Command {
+    let mut c = Command::new(adj_bin());
+    c.env("ADJACENT_HOME", &self.home_path);
+    c.env("ADJACENT_PROXY_PORT", self.proxy_port.to_string());
+    c.env("RUST_LOG", "warn");
+    c.env_remove("PORT");
+    c.env_remove("BIND_PORT");
+    c
+}
+```
+
+The test itself is `async`, so it's annotated `#[tokio::test]` — the async cousin of
+`#[test]`, which spins up a Tokio runtime around the test body so you can `.await`
+inside it (here: awaiting daemon startup, subprocess output, and the container
+teardown poll):
+
+```rust
+// crates/adj/tests/docker.rs
+#[tokio::test]
+async fn docker_run_lazy_boots_and_down_stops_the_container() {
+    if !docker_ready().await {
+        eprintln!("skipping: no reachable Docker daemon (or {IMAGE} unavailable)");
+        return;
+    }
+    // ... boot through the proxy, assert 200, then `adj down` and confirm gone
+}
+```
+
+One more integration-test detail worth naming: this file uses `tempfile` and
+`tokio`, and both are available because `Cargo.toml` lists them under
+`[dev-dependencies]` — dependencies compiled only for tests and examples, never
+shipped in the release binary.
+
+## Why it matters
+
+The unit-vs-integration split is a real design decision, not boilerplate. Reaching
+into private state from a `#[cfg(test)] mod tests` is convenient, but it tests the
+code you *wrote*, not the code your users *touch*. The separate-crate rule forces the
+integration layer to go through the front door: for a library that means calling only
+`pub` items; for a binary like `adj` it means shelling out to the actual executable.
+That's why this test can honestly claim to prove the documented container convention —
+it exercises the same `adj add` / proxy / `adj down` path a developer runs by hand,
+with nothing mocked and no private shortcut.
+
+Skip the `CARGO_BIN_EXE_<name>` variable and you'd hardcode `target/debug/adj`, which
+breaks under `--release`, breaks on the CI runner's target dir, and silently runs a
+*stale* binary if you forget to rebuild. Letting Cargo hand you the path removes all
+three traps.
+
+## Related lessons
+
+- PR #38 works inside this same `tests/` directory but teaches a different axis:
+  making an async integration test *deterministic* (killing flakiness). This lesson is
+  the layout — where tests live and what they can see; #38 is how to make one reliable
+  once it's there.
+- PR #16 stood up the supervisor this test ultimately drives; the daemon it boots is
+  the `Arc<Mutex<...>>` machinery taught there, exercised end-to-end from outside.
+
+## Dig deeper
+
+- [The Rust Book, ch. 11.3](https://doc.rust-lang.org/book/ch11-03-test-organization.html) — Test Organization (the unit-vs-integration split, the `tests/` directory, and testing binary crates)
diff --git a/docs/lessons/48-warn-dont-swallow-errors.md b/docs/lessons/48-warn-dont-swallow-errors.md
new file mode 100644
index 0000000..1d8f919
--- /dev/null
+++ b/docs/lessons/48-warn-dont-swallow-errors.md
@@ -0,0 +1,80 @@
+<!-- Lesson for PR #48. Teaches one concept grounded in the real diff. -->
+
+# PR #48 — Warn instead of silently defaulting on idle_timeout parse failure
+
+> **Rust lesson:** A `Result` is a value you must consume, but combinators like `.unwrap_or(default)` let you throw the `Err` away — reach for `.unwrap_or_else(|err| …)` when the error is worth surfacing before you fall back.
+> **Tags:** `result` · `error-handling` · `combinators`
+> **Merged:** 2026-06-13 · +75/−2 · [View PR](https://github.com/nonrational/adjacent/pull/48)
+
+## The situation
+
+A bad `idle_timeout` string in `adjacent.toml` (say `"10x"`) used to fall back to the 15-minute default without a peep. `idle_timeout_for` called `.unwrap_or(Some(DEFAULT_IDLE_TIMEOUT))` on the parse `Result`, discarding the parse error. Today that path is unreachable — `read_app_config` validates eagerly — but a future caller that skips validation would turn a config typo into a silent default. This PR keeps the fallback but makes it observable.
+
+## The Rust idea
+
+Rust has no exceptions. A function that can fail returns `Result<T, E>` — an enum with two variants, `Ok(T)` and `Err(E)`. The failure is an ordinary value the caller holds in their hand, and the type system won't let you read the `T` without first acknowledging the `Err` might be there. That is the whole safety story: fallibility is visible in the signature and unavoidable at the call site.
+
+But "unavoidable" is not the same as "surfaced." The standard library ships combinators that collapse a `Result` down to a plain value, and some of them drop the error on the floor:
+
+- `.unwrap_or(default)` — returns the `Ok` value, or `default` on `Err`. The `E` is never bound to anything; it's gone.
+- `.ok()` — turns `Result<T, E>` into `Option<T>`, discarding `E`.
+- `let Ok(x) = … else { … }` — the `else` arm can't see the error either.
+
+Each one is a legitimate tool and each one silently swallows the `Err`. The compiler is happy — you *did* handle the `Result` — so the type system stops nudging you the moment you pick a combinator that ignores the payload. Swallowing an error is a code smell precisely because it looks identical to handling it.
+
+The fix is the lazy sibling: `.unwrap_or_else(|err| …)` takes a closure that receives the `Err` value. Now the error is bound to `err`, and you can log it, count it, or enrich it before returning your fallback. Same default, but the failure is no longer invisible.
+
+(`_else` also means the fallback is computed lazily — the closure only runs on `Err` — but here the real win is getting your hands on `err`.)
+
+## In this PR
+
+```rust
+// crates/adj/src/registry.rs
+
+// before:
+Some(s) => parse_idle_timeout(s).unwrap_or(Some(DEFAULT_IDLE_TIMEOUT)),
+
+// after:
+// Unreachable when callers go through `read_app_config`, which validates eagerly.
+// Warn loudly anyway so a future code path that skips validation can't turn a
+// config typo into a silent default.
+Some(s) => parse_idle_timeout(s).unwrap_or_else(|err| {
+    tracing::warn!(
+        idle_timeout = s,
+        error = %err,
+        default = ?DEFAULT_IDLE_TIMEOUT,
+        "invalid idle_timeout; falling back to default"
+    );
+    Some(DEFAULT_IDLE_TIMEOUT)
+}),
+```
+
+The signature never changed — `idle_timeout_for` still returns `Option<Duration>`, so nothing downstream in `supervisor.rs` has to grow an error path. The only difference is that the `err` from `parse_idle_timeout` now flows into the closure instead of being dropped. `%err` formats it with `Display`, `?DEFAULT_IDLE_TIMEOUT` with `Debug` — both are `tracing`'s field syntax for capturing structured values.
+
+The test pins the one observable change. Since the returned value is identical before and after, the assertion has to capture the log output:
+
+```rust
+// crates/adj/src/registry.rs
+let resolved = tracing::subscriber::with_default(subscriber, || {
+    idle_timeout_for(&cfg_with_idle_timeout(Some("10x")))
+});
+
+assert_eq!(resolved, Some(DEFAULT_IDLE_TIMEOUT));
+let logs = String::from_utf8(capture.0.lock().unwrap().clone()).unwrap();
+assert!(
+    logs.contains("invalid idle_timeout") && logs.contains("10x") && logs.contains("900s"),
+    "expected a warn naming the bad value and the default it fell back to, got: {logs}"
+);
+```
+
+## Why it matters
+
+In a language with exceptions, the equivalent bug is a bare `catch (Exception e) {}` — the swallowed-error smell everyone recognizes. Rust doesn't force you to write that; it hands you a tidy one-liner (`.unwrap_or`) that does exactly the same thing and reads as intentional. The lesson is that Rust guarantees you *considered* the `Result`, not that you *surfaced* it. When the fallback is a real recovery worth keeping quiet about, `.unwrap_or` is fine. When the `Err` means "someone made a mistake" — a config typo, a malformed input — reach for `.unwrap_or_else` and at least say so on the way down.
+
+## Related lessons
+
+- PR #49 tightens the *producer* side of this same function neighborhood: it makes `parse_idle_timeout` return a precise `Err` (rejecting zero durations with a message pointing at `off`). #48 is about not swallowing that `Err`; #49 is about making it worth reading.
+
+## Dig deeper
+
+- [The Rust Book, ch. 9](https://doc.rust-lang.org/book/ch09-00-error-handling.html) — Error Handling (`Result`, the `?` operator, and when to recover vs. propagate)
diff --git a/docs/lessons/49-parse-dont-validate-actionable-errors.md b/docs/lessons/49-parse-dont-validate-actionable-errors.md
new file mode 100644
index 0000000..7eb2b4a
--- /dev/null
+++ b/docs/lessons/49-parse-dont-validate-actionable-errors.md
@@ -0,0 +1,87 @@
+<!-- Lesson for PR #49. Teaches one concept grounded in the real diff. -->
+
+# PR #49 — Reject zero idle_timeout with a pointer to off
+
+> **Rust lesson:** Push validation *into* the parser so an invalid value can't exist downstream — and spend the extra line making the `Err` message tell the user what to do instead.
+> **Tags:** `parse-dont-validate` · `error-handling` · `result`
+> **Merged:** 2026-06-13 · +21/−0 · [View PR](https://github.com/nonrational/adjacent/pull/49)
+
+## The situation
+
+`idle_timeout = "0s"` used to parse cleanly into a zero `Duration`. That value then flowed into the idle scanner, which compares each app's idle age against its timeout every 500ms — a zero window means the app is *always* past its timeout, so it gets SIGTERM'd on the very next tick. The app quietly stops itself forever. This PR makes `parse_idle_timeout` reject zero at the door, and point the user at the thing they almost certainly meant: `"off"`.
+
+## The Rust idea
+
+**"Parse, don't validate."** There are two ways to handle an untrusted input.
+
+- *Validate:* accept it into your normal type (a `Duration`), then check `if dur.is_zero()` at each place that cares. The type says nothing — every consumer has to remember the rule, and a new call site can forget it.
+- *Parse:* do the check once, at the boundary, and return a type that *cannot represent the bad state*. Downstream code holds a value that is correct by construction.
+
+`parse_idle_timeout` returns `Result<Option<Duration>>`, and that type already encodes three distinct outcomes:
+
+- `Err(_)` — the input was malformed or nonsensical.
+- `Ok(None)` — idle shutdown is explicitly disabled (`"off"`).
+- `Ok(Some(d))` — a real, positive timeout.
+
+Before this PR, a fourth state leaked through: `Ok(Some(Duration::ZERO))`, a "valid" timeout that behaves like a self-destruct. Moving the `is_zero()` check *inside* the parser deletes that state. After the function returns `Ok(Some(d))`, every caller can trust `d` is non-zero without checking — the scanner never has to defend against a zero window, because one can't reach it.
+
+The second half of the lesson is the `Err` itself. Rust's `Result` makes failure a value you must handle, but it says nothing about the *quality* of the error. `Err(anyhow!("invalid duration"))` is technically a failure and practically useless. An actionable message names what went wrong **and** what to do instead.
+
+## In this PR
+
+The check sits at the end of the parser, right before the only `Ok(Some(...))` return:
+
+```rust
+// crates/adj/src/registry.rs
+if dur.is_zero() {
+    return Err(anyhow!(
+        "idle_timeout of zero would stop the app on every idle scan; use `off` to disable idle shutdown"
+    ));
+}
+Ok(Some(dur))
+```
+
+That message is the whole point. It has two clauses: the *consequence* ("would stop the app on every idle scan") so the user understands why zero is refused, and the *fix* ("use `off` to disable idle shutdown") so they know the exact next keystroke. `anyhow!` is the `anyhow` crate's macro for building an ad-hoc error from a format string — the same ergonomics as `format!`, but it produces an `Err` value.
+
+The doc comment is updated to explain the *why* for the next reader, not just the *what*:
+
+```rust
+// crates/adj/src/registry.rs
+/// Zero durations are rejected: a zero window would make the app a permanent shutdown
+/// candidate (stopped on every scan tick), and users writing `"0s"` almost always mean
+/// "disable" — which is what `"off"` does.
+```
+
+The test pins the contract — every zero unit is rejected, and the message steers toward `off`:
+
+```rust
+// crates/adj/src/registry.rs
+#[test]
+fn rejects_zero_and_points_at_off() {
+    for raw in ["0s", "0ms", "0m", "0h"] {
+        let err = parse_idle_timeout(raw).unwrap_err();
+        assert!(
+            err.to_string().contains("use `off`"),
+            "error for {:?} should suggest `off`, got: {}",
+            raw,
+            err
+        );
+    }
+}
+```
+
+Note what it asserts: not the whole string (brittle), but that the fix — `use `off`` — is present. The test guards the *actionable* part of the message specifically.
+
+## Why it matters
+
+Because the check lives in the parser and `read_app_config` calls it eagerly, the error surfaces at `adj add` / `adj up` time — while the user is looking at their config — instead of manifesting hours later as a server that mysteriously won't stay up. That's the payoff of parse-don't-validate: the failure appears at the boundary, with full context, once. A language that let you pass a raw `Duration` around and hope every consumer re-checks it would push that failure deep into the runtime, far from the typo that caused it.
+
+## Related lessons
+
+- **PR #48** is the mirror image — the *consumer* side of this exact function. #48 is about not *swallowing* the `Err` that `parse_idle_timeout` returns (reach for `.unwrap_or_else` over `.unwrap_or`); #49 is about making that `Err` precise and worth reading in the first place. A good error is a handshake: the producer writes something actionable, the consumer bothers to surface it.
+- **PR #29** covered error *enums* (giving failures distinct types). #49 is the complementary skill: even a stringly-typed `anyhow!` error earns its keep when the *message* tells the user what to do.
+
+## Dig deeper
+
+- [Parse, don't validate](https://lexi-lambda.github.io/blog/2019/11/05/parse-don-t-validate/) — the canonical essay. Written for Haskell, but the core move (make illegal states unrepresentable by choosing return types that exclude them) is exactly what the `Result<Option<Duration>>` signature does here.
+- [The Rust Book, ch. 9](https://doc.rust-lang.org/book/ch09-00-error-handling.html) — Error Handling: `Result`, the `?` operator, and recoverable-vs-unrecoverable failure.
diff --git a/docs/lessons/50-weak-refs-self-cleaning-map.md b/docs/lessons/50-weak-refs-self-cleaning-map.md
new file mode 100644
index 0000000..a8e6a7b
--- /dev/null
+++ b/docs/lessons/50-weak-refs-self-cleaning-map.md
@@ -0,0 +1,84 @@
+<!-- Lesson for PR #50. Teaches one concept grounded in the real diff. -->
+
+# PR #50 — Proxy follow-ups: deadline timing, BootGate GC, NAT-replacement warning
+
+> **Rust lesson:** Store `Weak` references as a map's values so the map garbage-collects itself — an entry lives only while some in-flight boot still holds the strong `Arc`, and `HashMap::retain` sweeps the dead ones in one in-place pass.
+> **Tags:** `weak-references` · `hashmap-retain`
+> **Merged:** 2026-06-13 · +48/−6 · [View PR](https://github.com/nonrational/adjacent/pull/50)
+
+## The situation
+
+The proxy's `BootGate` keeps one lock per app name so concurrent first-requests boot the app exactly once (that mechanism is PR #24). But the original map held an `Arc<Mutex<()>>` per name, and nothing ever removed entries. Every name the daemon ever routed left a permanent row in the map. The daemon is long-lived, and there is **no app-removal RPC** to hook a cleanup call onto — so the map only ever grew. A slow leak, but a leak. This PR makes the map bound itself to boots that are actually in flight.
+
+## The Rust idea
+
+`Arc<T>` is a *strong* reference: as long as one `Arc` exists, the value stays alive. `Weak<T>` is a *non-owning* reference to the same value — it points at the data but does **not** count toward keeping it alive. When the last `Arc` drops, the value is freed even if `Weak`s still point at where it used to be.
+
+Because a `Weak` might be dangling, you can't dereference it directly. You call `.upgrade()`, which returns `Option<Arc<T>>`: `Some` if the value is still alive (and hands you a fresh strong ref), `None` if it's gone. That `Option` is Rust forcing you to handle "the thing I referenced no longer exists" — there is no way to accidentally touch freed memory.
+
+Two more pieces the diff uses:
+
+- `Arc::downgrade(&arc)` mints a `Weak` from an `Arc` — that's what you store in the map.
+- `weak.strong_count()` asks how many strong `Arc`s are still out there. Zero means the value is dead and the entry is garbage.
+- `HashMap::retain(|k, v| bool)` walks every entry once and drops those where the closure returns `false`, editing the map **in place** — no rebuild, no second allocation.
+
+Put together: store `Weak` values, and an entry becomes collectable the moment its last `Arc` drops. `retain(|_, w| w.strong_count() > 0)` is the sweep.
+
+## In this PR
+
+The map's value type flips from `Arc` to `Weak`:
+
+```rust
+// crates/adj/src/proxy.rs
+#[derive(Default)]
+pub struct BootGate {
+    locks: Mutex<HashMap<String, std::sync::Weak<Mutex<()>>>>,
+}
+```
+
+And `lock_for` prunes on the way in, then either upgrades the surviving entry or mints a fresh lock:
+
+```rust
+// crates/adj/src/proxy.rs
+async fn lock_for(&self, name: &str) -> Arc<Mutex<()>> {
+    let mut map = self.locks.lock().await;
+    map.retain(|_, weak| weak.strong_count() > 0);
+    if let Some(existing) = map.get(name).and_then(std::sync::Weak::upgrade) {
+        return existing;
+    }
+    let lock = Arc::new(Mutex::new(()));
+    map.insert(name.to_string(), Arc::downgrade(&lock));
+    lock
+}
+```
+
+Trace the lifetime. `lock_for` returns an `Arc` — the caller in `ensure_running` holds it (`let name_lock = gate.lock_for(name).await;`) for the whole boot. So while a boot is in flight, at least one strong `Arc` exists, `strong_count()` is `> 0`, and the map entry survives `retain`. Concurrent requests for the *same* name `upgrade()` that same live `Weak` and get the *same* `Arc` back — single-flight identity is preserved (the new unit test asserts `Arc::ptr_eq(&lock_a, &lock_a2)`). Once the boot finishes and every caller drops its `Arc`, `strong_count()` falls to zero, and the *next* `lock_for` call sweeps the dead entry. The map is now bounded by the number of boots happening right now, not by every name ever seen.
+
+The new test spells out the whole arc — hold two locks, confirm neither is pruned while alive, drop them all, then confirm the next lookup collects them:
+
+```rust
+// crates/adj/src/proxy.rs
+drop(lock_a);
+drop(lock_a2);
+drop(lock_b);
+// All strong refs gone — the next lock_for sweeps the dead entries.
+let _lock_c = gate.lock_for("c").await;
+let map = gate.locks.lock().await;
+assert_eq!(map.len(), 1);
+assert!(map.contains_key("c"));
+```
+
+## Why it matters
+
+The trap is thinking of a map as a passive container and forgetting it's a *strong* owner. In the original code the `HashMap` held `Arc`s, so those apps could never be freed — the map itself was the reason they stayed alive. This is exactly the situation a garbage collector *can't* rescue you from either: a GC won't collect an object the map still strongly references, so a Java `HashMap` here would leak the same way. The tool for "reference it, but don't be the reason it lives" is a weak reference — `Weak<T>` in Rust, `WeakHashMap` in Java. Reaching for it turns an ever-growing map into a self-cleaning one, and the safety of `upgrade()` returning an `Option` means the "it might be gone" case is impossible to forget.
+
+## Related lessons
+
+- PR #24 owns the single-flight boot itself — the per-name lock and the double-check that make concurrent first-requests boot an app exactly once. This lesson is the follow-up that stops the lock *map* from growing forever; read #24 first for what the map is *for*.
+- Same PR, second thread (monotonic time): `ensure_running` now captures its boot deadline as `let deadline = tokio::time::Instant::now() + boot_timeout;` **before** calling `up()`, so a slow spawn counts against the boot budget instead of being added on top of it. `Instant` is a *monotonic* clock — it only moves forward and is immune to wall-clock jumps (NTP steps, DST), which is why it's the right type for a deadline. Prefer it over `SystemTime` for measuring elapsed time, and reach for `saturating_duration_since` / checked arithmetic when subtracting two `Instant`s so a reordering can't underflow.
+
+## Dig deeper
+
+- [`std::sync::Weak`](https://doc.rust-lang.org/std/sync/struct.Weak.html) — `upgrade`, `strong_count`, and the `Arc`/`Weak` ownership split.
+- [`HashMap::retain`](https://doc.rust-lang.org/std/collections/struct.HashMap.html#method.retain) — in-place filtering in a single pass.
+- [`std::time::Instant`](https://doc.rust-lang.org/std/time/struct.Instant.html) — the monotonic clock behind the deadline math.
diff --git a/docs/lessons/51-typed-http-header-values.md b/docs/lessons/51-typed-http-header-values.md
new file mode 100644
index 0000000..542ea24
--- /dev/null
+++ b/docs/lessons/51-typed-http-header-values.md
@@ -0,0 +1,77 @@
+<!-- Lesson for PR #51. Teaches one concept grounded in the real diff. -->
+
+# PR #51 — Forward X-Forwarded-* headers from the proxy
+
+> **Rust lesson:** In the `http` crate a header value is a `HeaderValue` — a validated byte-string newtype, not a `String` — so building one is fallible (`HeaderValue::from_str` returns a `Result`), and that fallibility is how the type system blocks header injection.
+> **Tags:** `newtypes` · `typed-headers` · `fallible-construction`
+> **Merged:** 2026-06-14 · +247/−13 · [View PR](https://github.com/nonrational/adjacent/pull/51)
+
+## The situation
+
+The proxy rewrites the incoming `Host` header to `127.0.0.1:<port>` so upstream dev servers with host-allowlist checks accept the request. That rewrite erases the browser's real origin. This PR restores it with the three standard reverse-proxy headers — `X-Forwarded-Host`, `X-Forwarded-For`, `X-Forwarded-Proto` — so an app can still reconstruct where the request actually came from. To set them, the code has to *construct* header values, and that is where Rust's types show up.
+
+## The Rust idea
+
+The `http` crate (re-exported through `hyper`) does not model headers as `HashMap<String, String>`. Keys are `HeaderName`, values are `HeaderValue`, and the collection is `HeaderMap`. A `HeaderValue` is a **newtype** wrapping validated bytes: a header value may not contain a carriage return, line feed, or NUL. Those are exactly the bytes an attacker would use to split one header into two — the classic header/response-injection attack. Encoding the rule in a type makes the illegal value *unrepresentable*: the only way to get a `HeaderValue` is through a constructor that checks.
+
+So **construction is fallible**. `HeaderValue::from_str(s)` returns `Result<HeaderValue, InvalidHeaderValue>` — hand it a string with a stray `\r\n` and you get `Err`, never a poisoned value. When the input is a compile-time constant you already know is legal, `HeaderValue::from_static("http")` skips the runtime check and hands back a `HeaderValue` directly (no `Result` to unwrap; it only panics if *you* wrote an illegal literal).
+
+**Reading is fallible too.** `HeaderValue::to_str()` returns a `Result`, because the wrapped bytes are opaque and aren't guaranteed to be valid UTF-8 — a `HeaderValue` is not a Rust `String`, so getting a `&str` back out can fail.
+
+Contrast a `String`-typed header map in Python, JS, or Go: nothing stops you writing a newline into a value, and the injection surfaces (if ever) as a runtime security bug. Rust makes the unsafe value impossible to build in the first place.
+
+## In this PR
+
+The whole helper, from `crates/adj/src/proxy.rs`:
+
+```rust
+// crates/adj/src/proxy.rs
+fn set_forwarded_headers(
+    headers: &mut hyper::HeaderMap,
+    original_host: &str,
+    client_ip: IpAddr,
+    proto: &'static str,
+) {
+    if let Ok(v) = hyper::header::HeaderValue::from_str(original_host) {
+        headers.insert("x-forwarded-host", v);
+    }
+    // ...
+    let mut chain: Vec<String> = headers
+        .get_all("x-forwarded-for")
+        .iter()
+        .filter_map(|v| v.to_str().ok())
+        .map(str::to_string)
+        .collect();
+    chain.push(client_ip.to_string());
+    let xff = chain.join(", ");
+    if let Ok(v) = hyper::header::HeaderValue::from_str(&xff) {
+        headers.insert("x-forwarded-for", v);
+    }
+    headers.insert(
+        "x-forwarded-proto",
+        hyper::header::HeaderValue::from_static(proto),
+    );
+}
+```
+
+Three constructions, three different type stories:
+
+- **`from_str(original_host)` is fallible**, so it's wrapped in `if let Ok(v)`. A malformed Host produces `Err`, the `insert` is skipped, and the request still forwards — the bad bytes never reach the socket.
+- **`proto` is `"http"` or `"https"`**, both compile-time-safe, so it uses `from_static` — no `Result`. That's also *why* the parameter is typed `proto: &'static str`: `from_static` demands a `&'static str`, and the accept loops thread in string literals to satisfy it.
+- **Reading the existing chain uses `.to_str().ok()`.** `to_str` is the read-side `Result`; `.ok()` inside `filter_map` drops any value that isn't valid UTF-8 instead of blowing up.
+
+One `HeaderMap` detail worth naming: `insert` *replaces* every existing value for a name, while `append` adds another line — a `HeaderMap` is a multimap that can hold several values under one key. The helper reads them all with `get_all` (not `get`, which would see only the first line), joins them, then `insert`s once to collapse the chain back to a single line.
+
+## Why it matters
+
+Header injection is the trap this avoids. Picture the string-concatenation version: `"X-Forwarded-Host: " + original_host` written straight to the socket. A Host of `evil\r\nX-Admin: true` smuggles in a whole extra header. `HeaderValue::from_str` rejects the `\r\n` before it can ever become a value, and the diff's `if let Ok(v)` turns that rejection into "quietly skip the header," never "forward the attack." Nobody had to remember to sanitize — the type simply refuses to hold the dangerous bytes.
+
+## Related lessons
+
+- PR #40 introduced the generic `serve_plain` that this PR threads `client_ip` and `proto` through — same file, same serve loop.
+- PR #48 is the same "a `Result` is a value you must handle" discipline, one layer up; here the fallible values are `HeaderValue::from_str` and `.to_str()`.
+
+## Dig deeper
+
+- [`http::HeaderMap`](https://docs.rs/http/latest/http/header/struct.HeaderMap.html) — the multimap: `insert` vs `append`, `get` vs `get_all`
+- [`http::HeaderValue`](https://docs.rs/http/latest/http/header/struct.HeaderValue.html) — `from_str` (fallible), `from_static` (infallible), `to_str` (fallible read)
diff --git a/docs/lessons/52-abort-detached-tokio-tasks.md b/docs/lessons/52-abort-detached-tokio-tasks.md
new file mode 100644
index 0000000..b4f2757
--- /dev/null
+++ b/docs/lessons/52-abort-detached-tokio-tasks.md
@@ -0,0 +1,91 @@
+<!-- Lesson for PR #52. Teaches one concept grounded in the real diff. -->
+
+# PR #52 — Abort the readiness probe's connection task when the probe resolves
+
+> **Rust lesson:** `tokio::spawn` returns a `JoinHandle`, and *dropping* that handle detaches the task so it keeps running on its own — to stop a background task once you're done with it, hold the handle and call `.abort()` (a no-op if it already finished), and for the leak-proof version let a `Drop` guard fire the abort on every exit path.
+> **Tags:** `tokio-spawn` · `join-handle-abort` · `task-cancellation`
+> **Merged:** 2026-06-14 · +86/−5 · [View PR](https://github.com/nonrational/adjacent/pull/52)
+
+## The situation
+
+The HTTP readiness probe (added in #29) opens a TCP connection to the app and speaks HTTP/1 through hyper. Hyper's client splits into two halves: a `sender` you push the request into, and a `conn` future that must be *driven* to actually pump bytes on the socket. The idiom is to `tokio::spawn` that `conn` future so it runs in the background while you await the response on `sender`.
+
+But the whole probe is wrapped in a 500ms `tokio::time::timeout`. If the timer wins, the `attempt` future is dropped mid-flight — and that spawned connection task, which owns a real TCP socket, is left running with nobody watching it. This PR keeps a handle to that task and aborts it once the probe resolves, timeout or not, so the task and its socket can't outlive the probe.
+
+## The Rust idea
+
+Two facts a newcomer needs about spawned tasks.
+
+**1. Dropping a `JoinHandle` does not stop the task — it *detaches* it.** `tokio::spawn(fut)` hands the future to the runtime and returns a `JoinHandle<T>`. Await the handle and you get the task's output. But here's the surprise if you're coming from threads, or from "a future is cancelled when you drop it": dropping the *handle* to a spawned task doesn't cancel anything. The task keeps running to completion on its own. A bare `tokio::spawn(...)` that throws the handle away is fire-and-forget — fine for work that finishes by itself, a leak for work that might not.
+
+**2. Cancellation is explicit: `JoinHandle::abort()`.** It doesn't kill the task synchronously. It flags the task so the runtime drops it at its next `.await` point (or never starts it, if it hadn't run yet). Dropping the task runs the destructors of everything it owns — here, the hyper `conn` and its TCP socket. And `abort()` on an already-finished task is a harmless no-op, so calling it unconditionally after the probe is always safe: either it reclaims a lingering task, or it does nothing.
+
+The subtle part is *guaranteeing* the abort runs. If you call it by hand, every exit path has to reach that call — every early `return`, every `?`, every panic. Miss one and the task leaks on that path. The RAII fix is the same one the language uses for locks and files: wrap the handle in a tiny struct whose `Drop` impl calls `abort()`, so the compiler runs it at scope exit on *every* path.
+
+```rust
+// Sketch — the general RAII form (not the exact shape #52 shipped; see below).
+struct AbortOnDrop(tokio::task::JoinHandle<()>);
+impl Drop for AbortOnDrop {
+    fn drop(&mut self) {
+        self.0.abort();
+    }
+}
+```
+
+`Drop` running on every normal exit is exactly what makes this leak-proof — and it's the flip side of PR #37, which is the deep dive on `Drop`'s reach *and* its one blind spot (a signal walks right past it).
+
+## In this PR
+
+The handle is parked on a slot declared *outside* both the `attempt` future and the `timeout`, so it survives even when the timer drops `attempt` mid-flight. `Option` because the spawn happens partway through `attempt` — the connect might fail with `?` before we ever spawn, so the slot is `Some` only once we got far enough to have a task.
+
+```rust
+// crates/adj/src/readiness.rs
+let mut conn_task: Option<tokio::task::JoinHandle<()>> = None;
+let attempt = async {
+    let addr = SocketAddr::from(([127, 0, 0, 1], port));
+    let stream = TcpStream::connect(addr).await.ok()?;
+    let io = TokioIo::new(stream);
+    let (mut sender, conn) = client_http1::handshake::<_, Empty<Bytes>>(io).await.ok()?;
+    conn_task = Some(tokio::spawn(async move {
+        let _ = conn.await;
+    }));
+    // ... build + send the request, read the status, drain the body ...
+    Some(status.is_success())
+};
+```
+
+Parking the handle *outside* the timed-out future is the crux: the thing that owns the task has to outlive the thing that might get cancelled. Then, once the probe has resolved one way or another, the abort fires unconditionally:
+
+```rust
+// crates/adj/src/readiness.rs
+let ready = tokio::time::timeout(Duration::from_millis(500), attempt)
+    .await
+    .ok()
+    .flatten()
+    .unwrap_or(false);
+// Abort unconditionally: a no-op once the task has finished, a cancellation (dropping the
+// socket) when the probe timed out or the probe completed while the connection lingered.
+if let Some(task) = conn_task {
+    task.abort();
+}
+ready
+```
+
+Two honest notes on the shape it actually shipped:
+
+- **It's a manual abort, not the `Drop` guard from the sketch.** That's fine *here* because `http_ready` has a single linear tail: nothing between the `timeout` resolving and the `if let ... abort()` can `return` early or `?` out, so every path reaches the abort. The day a function grows several `?` early returns between grabbing a task handle and finishing with it, that's the signal to promote this manual call into the `AbortOnDrop` guard — same story as a lock, where hand-written unlock works until someone adds an early return and the guard makes it structural.
+- **The PR couldn't even reproduce the leak.** As the author's write-up notes, hyper 1.x happens to resolve the `conn` future when `sender` is dropped, so the detached task was already exiting on its own. The explicit `abort()` converts "cancellation that works by accident, because of a dependency's internals" into "cancellation we own" — and the two new tests pin the no-lingering-socket behavior against future hyper changes.
+
+## Why it matters
+
+The trap is reading `tokio::spawn(fut)` with the handle discarded as fire-and-forget *cleanup*, when it's the opposite: the task outlives the handle. Someone from a GC language expects the task to be collected once nothing references it; someone who's learned "drop a future to cancel it" gets bitten because a *spawned* task is detached, not a bare future. One leaked socket per probe, multiplied by a poll loop, is a genuine file-descriptor leak. Holding the `JoinHandle` and aborting it — ideally from a `Drop` guard so no exit path can skip it — is how you make the background task's lifetime a strict subset of the work that needed it.
+
+## Related lessons
+
+- **PR #29** built the `tokio::time::timeout` this abort partners with. #29 bounds *how long* the probe waits; #52 cleans up *what the probe spawned* when that bound fires. Timeout + abort are the two halves of a cancel-safe async operation — the first stops waiting, the second stops the work.
+- **PR #37** is the converse-and-complement on `Drop`. #37: `Drop` runs on normal scope exit and panic unwinding, but a signal skips it. #52: *because* `Drop` runs on every normal exit path, it's the leak-proof home for an `abort()`. Read them together for the full map of what `Drop` covers and what it doesn't.
+
+## Dig deeper
+
+- [`JoinHandle::abort`](https://docs.rs/tokio/latest/tokio/task/struct.JoinHandle.html#method.abort) — the cancellation semantics, and the note that dropping a `JoinHandle` detaches (does not cancel) the task.
+- [The Rust Book, ch. 15.3](https://doc.rust-lang.org/book/ch15-03-drop.html) — Running Code on Cleanup with the `Drop` Trait, the pattern behind the `AbortOnDrop` guard.
diff --git a/docs/lessons/53-http-upgrade-stream-splicing.md b/docs/lessons/53-http-upgrade-stream-splicing.md
new file mode 100644
index 0000000..ed8a3ff
--- /dev/null
+++ b/docs/lessons/53-http-upgrade-stream-splicing.md
@@ -0,0 +1,114 @@
+<!-- Lesson for PR #53. Teaches one concept grounded in the real diff. -->
+
+# PR #53 — Propagate WebSocket upgrades through the proxy
+
+> **Rust lesson:** An HTTP `Upgrade` trades parsed HTTP framing for the raw byte stream underneath — you reserve that stream with `hyper::upgrade::on` *while you still own the request*, then splice both raw halves with `tokio::io::copy_bidirectional`.
+> **Tags:** `http-upgrade` · `copy-bidirectional` · `ownership`
+> **Merged:** 2026-06-14 · +238/−2 · [View PR](https://github.com/nonrational/adjacent/pull/53)
+
+## The situation
+
+The proxy forwarded ordinary HTTP fine, but WebSocket requests (Vite/Webpack/Next HMR)
+died at the proxy boundary. A WebSocket starts as a normal GET carrying `Upgrade: websocket`;
+the app answers `101 Switching Protocols` and from that byte onward the connection is no
+longer HTTP — it's a raw, full-duplex byte stream. The proxy has to notice the handshake,
+let it through, then get out of the way and shovel bytes both directions until someone hangs up.
+
+## The Rust idea
+
+An upgrade is a **handoff**. Normally `hyper` owns the socket and parses framed HTTP messages
+for you. After a 101 there are no more messages to parse — there's a raw TCP stream underneath
+that hyper is finished with. `hyper::upgrade::on(&mut req)` hands you a **future** (`OnUpgrade`)
+that resolves to that raw stream *once the upgrade completes*. Think of it as a claim ticket:
+you reserve the stream now and collect it later.
+
+Two Rust facts make the *timing* of that claim load-bearing:
+
+- **`send_request(req)` moves the request.** Sending it upstream consumes `req` by value, and
+  the upgrade handle lives inside the request's extension map. Once the request is moved, you
+  can never reach back in for it. So you must claim the handle *before* the move — that's the
+  only window where the server half is still yours.
+- **The downstream upgrade only resolves after you return the 101.** hyper's server loop
+  completes the client-side upgrade only once `forward` hands back the `101` response. So
+  awaiting the downstream future inline — before returning — would wait for something that
+  can't happen until you return. Deadlock. The fix is to `tokio::spawn` a detached task: return
+  the 101, and let that task collect both halves whenever they're ready.
+
+Once you hold both raw streams, `tokio::io::copy_bidirectional(&mut a, &mut b)` runs the two
+copies concurrently — `a → b` and `b → a` — and returns when both directions hit EOF. It
+replaces a hand-rolled "spawn two copy loops and coordinate the shutdown" dance with one call.
+
+## In this PR
+
+Claim the downstream handle up front, gated on the `Upgrade` header so non-upgrade requests
+pay nothing (`.then(|| …)` only runs the closure when the `bool` is `true`):
+
+```rust
+// crates/adj/src/proxy.rs
+let downstream_upgrade = req
+    .headers()
+    .contains_key(hyper::header::UPGRADE)
+    .then(|| hyper::upgrade::on(&mut req));
+```
+
+Drive the upstream client connection `with_upgrades()` so a 101 doesn't tear it down — the
+upstream's raw half has to survive past the handshake for us to claim it too:
+
+```rust
+// crates/adj/src/proxy.rs
+if let Err(err) = conn.with_upgrades().await {
+    tracing::debug!("upstream connection ended: {err}");
+}
+```
+
+On a 101, splice the two raw streams in a **detached** task:
+
+```rust
+// crates/adj/src/proxy.rs
+if resp.status() == StatusCode::SWITCHING_PROTOCOLS {
+    if let Some(downstream) = downstream_upgrade {
+        let upstream = hyper::upgrade::on(&mut resp);
+        tokio::spawn(async move {
+            let (down, up) = match tokio::join!(downstream, upstream) {
+                (Ok(d), Ok(u)) => (d, u),
+                // ...
+            };
+            let mut down = TokioIo::new(down);
+            let mut up = TokioIo::new(up);
+            if let Err(err) = tokio::io::copy_bidirectional(&mut down, &mut up).await {
+                tracing::debug!("upgraded tunnel closed: {err}");
+            }
+        });
+    }
+}
+```
+
+`tokio::join!(downstream, upstream)` awaits both claim tickets concurrently and yields a tuple
+of `Result`s; only when both raw streams are in hand does the pump start. The `TokioIo::new`
+wrappers matter: hyper's upgraded stream speaks hyper's own IO traits, but `copy_bidirectional`
+is a tokio function expecting `AsyncRead + AsyncWrite`, so `TokioIo` adapts one to the other.
+
+## Why it matters
+
+The trap is claiming the stream too late. It's natural to reach for the upgrade handle *after*
+you have the response — that's when a WebSocket "feels" established. But `send_request` already
+moved the request by then, and Rust's ownership rules make that a hard compile error, not a
+subtle runtime bug: the handle is simply gone. The type system forces you to grab it during the
+one valid window. The second trap — awaiting the downstream upgrade inline — compiles fine and
+then hangs forever; the `tokio::spawn` is what keeps it from deadlocking, and the comment in the
+diff spells out why. A garbage-collected proxy in another language would let you hold a dangling
+reference to the consumed request and discover the mistake only when the tunnel silently never
+opens.
+
+## Related lessons
+
+- **PR #40** taught the generic `serve_plain<S>` loop these connections ride on — note it already
+  calls `.with_upgrades()` on the *server* side. #53 is the client-side other half: without both,
+  the upgrade completes on neither end.
+- **PR #51** taught typed headers; the `hyper::header::UPGRADE` constant here is that same idea —
+  a typed name instead of a stringly-typed `"upgrade"` lookup.
+
+## Dig deeper
+
+- [`hyper::upgrade`](https://docs.rs/hyper/latest/hyper/upgrade/index.html) — the `on()` function and the `OnUpgrade` future, plus why `with_upgrades()` is required on the connection.
+- [`tokio::io::copy_bidirectional`](https://docs.rs/tokio/latest/tokio/io/fn.copy_bidirectional.html) — the concurrent two-way byte pump and its EOF semantics.
diff --git a/docs/lessons/55-races-beyond-the-borrow-checker.md b/docs/lessons/55-races-beyond-the-borrow-checker.md
new file mode 100644
index 0000000..3c57cee
--- /dev/null
+++ b/docs/lessons/55-races-beyond-the-borrow-checker.md
@@ -0,0 +1,92 @@
+<!-- Lesson for PR #55. Teaches one concept grounded in the real diff. -->
+
+# PR #55 — Close the test-sandbox port race behind connection-reset flakes
+
+> **Rust lesson:** `Send`/`Sync` and the borrow checker eliminate in-process *data* races, but logical races over shared OS state — a port, a file, a row in someone else's database — are still entirely on you.
+> **Tags:** `race-condition` · `TOCTOU`
+> **Merged:** 2026-06-14 · +176/−72 · [View PR](https://github.com/nonrational/adjacent/pull/55)
+
+## The situation
+
+Integration tests each spin up their own daemon in a sandbox and need a free proxy port. The old trick: bind `127.0.0.1:0`, let the kernel pick a port, read the number, close the socket, then hand that number to the daemon to re-bind. Under `cargo test` seven suites run at once, all drawing from the same kernel ephemeral-port range. Another process could claim the port in the gap between the test closing it and the daemon re-binding it. The readiness probe's bare TCP connect then hit a *foreign* listener, called it ready, and the real request landed on a stranger's socket: "Connection reset by peer". It flaked roughly 1-in-45.
+
+## The Rust idea
+
+Rust's concurrency guarantees are famous, and it's easy to over-read them. Here's the precise boundary.
+
+A **data race** is two threads touching the *same memory location* at the same time, at least one of them writing, with no synchronization. That is undefined behavior in C, a heisenbug in Go, and a *compile error* in Rust. The mechanism is two marker traits the compiler tracks for every type:
+
+- **`Send`** — safe to *move* to another thread.
+- **`Sync`** — safe to *share* by reference (`&T`) across threads.
+
+`Arc<Mutex<T>>` is `Send + Sync`; `Rc<RefCell<T>>` is neither. So `tokio::spawn` accepts the first and rejects the second, and the borrow checker won't let you reach shared memory except through the lock. Data races: gone, before the program ever runs.
+
+But note the load-bearing phrase: *the same memory location*. The guarantee is about **memory your process owns**. The moment two processes contend over something outside that model — a TCP port in the kernel's table, a file on disk, a network resource — the compiler has no view of it. No `&mut` crosses the boundary, no trait describes it, so there is nothing to check. This bug is a **TOCTOU** race — *time-of-check to time-of-use*: you check a fact (this port is free), and by the time you use it (bind it), the fact has changed. Classic, and completely invisible to `Send`/`Sync`.
+
+## In this PR
+
+The old code even confessed the race in its own doc comment:
+
+```rust
+// crates/adj/tests/proxy.rs  (deleted)
+/// Bind :0, read the assigned port, close. The kernel may reissue this number to anyone before
+/// the daemon claims it, but for a localhost test that's rare enough to accept.
+fn pick_port() -> u16 {
+    let l = std::net::TcpListener::bind("127.0.0.1:0").expect("bind :0");
+    l.local_addr().expect("local_addr").port()
+}
+```
+
+"Rare enough to accept" held until seven suites ran concurrently. The `bind → read → close → re-bind` sequence has a window, and a window is all a race needs.
+
+The fix removes the window entirely. Don't pick a port and hand it off — let the daemon bind `:0` *itself*, so the port is born bound to the right process and never freed. The daemon then publishes the actually-bound port to a file:
+
+```rust
+// crates/adj/src/proxy.rs
+let listener = TcpListener::bind(addr)
+    .await
+    .map_err(|e| anyhow!("binding proxy listener at {addr}: {e}"))?;
+let bound = listener
+    .local_addr()
+    .map_err(|e| anyhow!("reading proxy listener addr: {e}"))?
+    .port();
+report_bound_port(crate::paths::proxy_port_path(), bound);
+```
+
+The test passes `0` and learns the real port by reading that file:
+
+```rust
+// crates/adj/tests/proxy.rs
+// 0 = the daemon binds a kernel-assigned port; start_daemon learns the real port
+// from the proxy.port file. Picking a free port here and re-binding it in the
+// daemon raced concurrent test processes drawing from the same ephemeral range,
+// which flaked as "connection reset by peer" against a foreign listener.
+proxy_port: 0,
+```
+
+```rust
+// crates/adj/tests/proxy.rs
+// proxy.port is written after bind, so a parsed port means the listener is live —
+// and unambiguously ours, unlike a bare TCP connect to a guessed port.
+if self.proxy_port == 0 {
+    if let Some(p) = read_port_file(&port_file) {
+        self.proxy_port = p;
+    }
+}
+```
+
+Two races collapse into zero. There's no free-then-rebind gap because the listener that binds the port is the one that keeps it. And the readiness signal gets stronger for free: a parsed `proxy.port` file means the listener is live *and ours*, where the old bare `TcpStream::connect` couldn't tell our daemon from a squatter on the same port.
+
+## Why it matters
+
+The trap is assuming Rust's "fearless concurrency" covers all concurrency. It covers exactly one thing — shared memory inside your address space — and covers it completely. Everything with an identity outside your process is ordinary distributed-systems state, and the same discipline you'd use in any language applies: don't check-then-act across a gap where another actor can intervene. Here the fix is to eliminate the gap (bind once, keep it) rather than shrink it. Other flavors of the same lesson: hold the resource instead of releasing and reacquiring it, make the operation atomic (`O_CREAT | O_EXCL`, a `CAS`), or retry on the losing side. The borrow checker will happily let you write a textbook TOCTOU bug — it was never its job to stop you.
+
+## Related lessons
+
+- **PR #16** — the `Arc<Mutex<T>>` pattern whose guarantee this lesson bounds: it prevents data races on in-process memory, and *only* that.
+- **PR #24** — single-flight boot gate, an *in-process* logical race solved with a lock; contrast it with #55, an *OS-level* race a lock can't touch.
+- **PR #50** — GCing the per-name lock map, another case of managing shared in-process state safely.
+
+## Dig deeper
+
+- [The Rust Book, ch. 16](https://doc.rust-lang.org/book/ch16-00-concurrency.html) — Fearless Concurrency. Read it for what `Send`/`Sync` buy you, but read it knowing the chapter is about **data races** specifically; the port race in this PR is deliberately outside its scope.
diff --git a/docs/lessons/56-split-once-structured-keys.md b/docs/lessons/56-split-once-structured-keys.md
new file mode 100644
index 0000000..694f490
--- /dev/null
+++ b/docs/lessons/56-split-once-structured-keys.md
@@ -0,0 +1,90 @@
+<!-- Lesson for PR #56. Teaches one concept grounded in the real diff. -->
+
+# PR #56 — Worktree instances: per-label registry keys, remove/prune, wildcard TLS SANs
+
+> **Rust lesson:** `str::split_once` cuts a string at the *first* delimiter into two borrowed `&str` slices and returns an `Option`, so "there was no delimiter" is a case you handle instead of a bug you forget — the clean way to parse a structured key.
+> **Tags:** `string-slices` · `split-once` · `borrowing`
+> **Merged:** 2026-06-13 · +3601/−112 · [View PR](https://github.com/nonrational/adjacent/pull/56)
+
+## The situation
+
+The registry maps a key to a path. This PR lets one base app register under several keys: a bare `site` is the app itself, and `feature-x.site` is a *worktree instance* that routes at `feature-x.site.adj.ac`. The key encodes structure — one dot separates the instance label from the base name. Every routed request has to pull those two pieces back out of a `&str` key, and it has to be cheap.
+
+## The Rust idea
+
+`str::split_once(delimiter)` splits at the **first** match and hands back `Option<(&str, &str)>`. Two things are worth internalizing.
+
+**It returns `Option`, so the "no delimiter" case can't be forgotten.** In many languages you write `"feature-x.site".split(".")`, get an array, and reach for `[0]` and `[1]` — hoping there was a dot. When there isn't, `[1]` is `undefined`, an out-of-bounds panic, or a silent empty string, depending on the language. That missing-delimiter path is a landmine. `split_once` turns it into a value: `Some((before, after))` when the delimiter is present, `None` when it isn't. A bare key like `"site"` isn't an edge case to defend against — it's simply the `None` arm of a `match`.
+
+**The two pieces are borrowed slices — no allocation.** A `&str` is a pointer + length: a *window* into bytes someone else owns. The pair `split_once` returns points straight into the original string, so splitting a key costs two integer offsets, not two heap allocations. (Contrast a `String`, which owns its bytes on the heap. `&str` borrows; `String` owns.) The price of that speed is a lifetime: the slices are valid only while the input lives — which is exactly why the helper below *returns* borrows and lets the caller decide whether to `.to_string()` them.
+
+(`split_once` is the precise cousin of `split`, which returns a lazy iterator over *every* piece. When a string has a known two-part shape, you want the one that gives you exactly two.)
+
+## In this PR
+
+The parser is six lines. `split_key` maps a registry key to `(Option<label>, base)`:
+
+```rust
+// crates/adj/src/registry.rs
+/// Split a registry key into `(label, base)`. Keys are either a bare app name (`site`) or a
+/// worktree-instance key (`feature-x.site`). `add` enforces at most one dot, so `split_once`
+/// is total here.
+pub fn split_key(key: &str) -> (Option<&str>, &str) {
+    match key.split_once('.') {
+        Some((label, base)) => (Some(label), base),
+        None => (None, key),
+    }
+}
+
+/// The app name a registry key resolves config against: the part after the instance label,
+/// or the whole key when there is no label.
+pub fn base_name(key: &str) -> &str {
+    split_key(key).1
+}
+```
+
+Read the `match`: the `Some` arm is an instance key — wrap the label in `Some`, keep the base. The `None` arm is a bare app name — there's no label, and the whole key *is* the base. `base_name` just projects the second field (`.1`). Every return value is a borrow into `key`; nothing is copied.
+
+Now the load-bearing detail in that doc comment: "so `split_once` is total here." `split_once` always cuts at the *first* dot. On `"a.b.c"` it yields `("a", "b.c")` — everything after the first delimiter lands in the second slice. So if a dotted app name ever slipped through, `feature.my.app` would misparse as label `feature`, base `my.app`. The claim that "the first dot is *the* structural boundary" only holds because of an invariant enforced somewhere else: app names can't contain dots. That check lives at the point where a config enters the system:
+
+```rust
+// crates/adj/src/registry.rs
+// Dots are structural in registry keys (`<label>.<name>` is a worktree instance), so a
+// dotted app name would make `feature-x.site` ambiguous. Checked before the general
+// DNS-label check so the dot case gets its own targeted message.
+if cfg.name.contains('.') {
+    return Err(anyhow!(
+        "app name `{}` contains `.` — dots are reserved for worktree instances (`<label>.<name>`)",
+        cfg.name
+    ));
+}
+```
+
+That's the other half of the design. Splitting downstream gets to be a one-liner *because* the boundary code guarantees at most one dot per key. Reject the malformed input where it enters (see #49), and the parser never has to cope with it.
+
+The test pins both shapes — bare key and instance key — in one place:
+
+```rust
+// crates/adj/src/registry.rs
+#[test]
+fn split_key_handles_bare_and_instance_keys() {
+    assert_eq!(split_key("site"), (None, "site"));
+    assert_eq!(split_key("feature-x.site"), (Some("feature-x"), "site"));
+    assert_eq!(base_name("site"), "site");
+    assert_eq!(base_name("feature-x.site"), "site");
+}
+```
+
+## Why it matters
+
+The trap this sidesteps is the array-index split: grab `[0]`/`[1]`, forget the no-delimiter path, and ship a parser that panics or silently mangles a bare key. `split_once` makes "no dot" a branch the compiler forces you to write, and pairing it with the upstream `contains('.')` reject turns "the first dot is the only dot" from a hope into a guarantee. Because the two pieces are borrowed slices, this runs on every routed request without allocating a thing — the invariant lives in code, and reading it back out is free.
+
+## Related lessons
+
+- **PR #49** is the same file and the same move from the other end: the dotted-name reject above is a parse-don't-validate boundary check, refusing bad input at `read_app_config` so nothing downstream has to re-check it.
+- **PR #45** leans on the same borrowing trick — its `DashboardEntry<'a>` holds `&str` views into each app summary instead of cloning strings, exactly like `split_key` returns windows into `key`.
+
+## Dig deeper
+
+- [`str::split_once`](https://doc.rust-lang.org/std/primitive.str.html#method.split_once) — the signature (`Option<(&str, &str)>`), plus `rsplit_once` for splitting on the *last* delimiter instead of the first.
+- [The Rust Book, ch. 4.3](https://doc.rust-lang.org/book/ch04-03-slices.html) — The Slice Type: why a `&str` is a borrowed view, and how its lifetime is tied to the data it points into.
diff --git a/docs/lessons/60-compile-time-version-stamping.md b/docs/lessons/60-compile-time-version-stamping.md
new file mode 100644
index 0000000..d42e0e8
--- /dev/null
+++ b/docs/lessons/60-compile-time-version-stamping.md
@@ -0,0 +1,107 @@
+<!-- Lesson for PR #60. Teaches one concept grounded in the real diff. -->
+
+# PR #60 — Alpha Homebrew distribution: release CI, in-repo tap formula, version stamping
+
+> **Rust lesson:** A `build.rs` script runs *before* your crate compiles and can hand values to the compiler via `cargo:rustc-env=…` stdout directives, which `env!` (build fails if the var is missing) and `option_env!` (yields an `Option`, never fails) then bake into the binary as `&'static str` literals.
+> **Tags:** `build-scripts` · `compile-time-env` · `macros`
+> **Merged:** 2026-06-14 · +243/−1 · [View PR](https://github.com/nonrational/adjacent/pull/60)
+
+## The situation
+
+Shipping `adj` via Homebrew means `adj --version` has to report something true. A tagged release should say `0.1.0-alpha.1`; a build off a random local commit should say which commit (and whether the tree was dirty). None of that lives in the source — it lives in git and in CI env vars. This PR is mostly release plumbing (a Homebrew formula, a tag-triggered CI workflow, a `just release` target), but the one genuinely instructive Rust piece is how the binary *learns its own version* at compile time.
+
+## The Rust idea
+
+Rust has no runtime reflection for build metadata. A binary can't ask "what version am I?" from thin air — anything it knows must be baked in at compile time or read from disk at runtime. For a version string you want it baked in: a self-contained binary with no sidecar `VERSION` file to lose.
+
+Rust gives you two macros that read the *compiler's* environment:
+
+- **`env!("NAME")`** — expands to the value of environment variable `NAME` at compile time, as a `&'static str`. If `NAME` isn't set, **the build fails** with a clear error. Use it when the value must exist. Cargo always sets `CARGO_PKG_VERSION` from `Cargo.toml`, so `env!("CARGO_PKG_VERSION")` is guaranteed to compile.
+- **`option_env!("NAME")`** — same idea, but expands to `Option<&'static str>`: `Some(v)` if the var was set at compile time, `None` if not. It **never fails the build**. Use it for metadata that may or may not be there.
+
+The `!` marks these as macros, not functions. A function's argument is evaluated at runtime; these run *during compilation* and leave a string literal behind in the compiled code. That's the only way to reach the environment the compiler saw.
+
+But where does a var like `ADJ_VERSION` come from during compilation? That's what **`build.rs`** is for. Cargo compiles and runs `build.rs` before compiling the crate, and the script talks back to Cargo by printing specially-formatted lines to stdout — `cargo:rustc-env=KEY=VALUE` sets an env var that `env!`/`option_env!` can then read while the crate compiles.
+
+## In this PR
+
+The const in `main.rs` picks the git/CI-derived version when present, else the Cargo version:
+
+```rust
+// crates/adj/src/main.rs
+const VERSION: &str = match option_env!("ADJ_VERSION") {
+    Some(v) => v,
+    None => env!("CARGO_PKG_VERSION"),
+};
+```
+
+The whole expression is a `const`, so it's evaluated at compile time — `match` works in const context. `option_env!("ADJ_VERSION")` is `Some` only if the build set that var; otherwise it falls through to `env!("CARGO_PKG_VERSION")`, which can't fail because Cargo always provides it. Then clap uses it:
+
+```rust
+// crates/adj/src/main.rs
+#[command(
+    name = "adj",
+    version = VERSION,   // was: version,  (which defaults to CARGO_PKG_VERSION)
+    about = "Adjacent: supervised local dev servers"
+)]
+```
+
+The build script supplies `ADJ_VERSION`:
+
+```rust
+// crates/adj/build.rs
+fn git_describe() -> Option<String> {
+    let out = Command::new("git")
+        .args(["describe", "--tags", "--always", "--dirty", "--match", "v*"])
+        .output()
+        .ok()?;
+    if !out.status.success() {
+        return None;
+    }
+    let v = String::from_utf8(out.stdout).ok()?;
+    let v = v.trim().trim_start_matches('v').to_string();
+    (!v.is_empty()).then_some(v)
+}
+
+fn main() {
+    let version = std::env::var("ADJ_VERSION")
+        .ok()
+        .filter(|s| !s.is_empty())
+        .or_else(git_describe);
+
+    if let Some(v) = version {
+        println!("cargo:rustc-env=ADJ_VERSION={v}");
+    }
+
+    println!("cargo:rerun-if-env-changed=ADJ_VERSION");
+    // Refresh the git-describe value when HEAD moves; workspace root is two levels up from here.
+    if Path::new("../../.git/HEAD").exists() {
+        println!("cargo:rerun-if-changed=../../.git/HEAD");
+    }
+}
+```
+
+Walk the chain:
+
+1. CI sets `ADJ_VERSION` to the release tag (the workflow's `Derive version from tag` step strips the leading `v`). Locally that var is unset, so the script runs `git describe --tags --always --dirty` — which yields `0.1.0-alpha.1` on the exact tag, or an abbreviated commit like `61b2f6e` off a plain commit, with a `-dirty` suffix appended when the working tree has uncommitted changes.
+2. The script prints `cargo:rustc-env=ADJ_VERSION=<v>`, which sets that var for the crate compile that follows.
+3. `option_env!("ADJ_VERSION")` in `main.rs` sees it and bakes it into `const VERSION`.
+
+The two trailing directives are cache control. Build scripts are cached aggressively, so without a hint Cargo would keep the stale value forever. `cargo:rerun-if-env-changed=ADJ_VERSION` re-runs the script when that var changes; `cargo:rerun-if-changed=../../.git/HEAD` re-runs it when you commit (HEAD moves), so `git describe` refreshes. Build scripts run with their working directory set to the package root (`crates/adj`), which is why the repo's `.git/HEAD` is `../../` up.
+
+Note the `.ok()?` calls in `git_describe`: they intentionally throw away git's errors and return `None`, which makes the whole thing fall back to the Cargo version. That's the *legitimate* face of swallowing a `Result` (see #48) — a source build with no `.git` directory shouldn't fail to compile just because `git describe` can't run.
+
+The rest of the PR is distribution tooling, not Rust: `.github/workflows/release.yml` (tag-triggered arm64 build + GitHub prerelease), `Formula/adj.rb` and `render-formula.sh` (the in-repo Homebrew tap), and a `just release` target that tags the next alpha. Worth knowing they exist; not where the Rust lesson lives. The user-facing `brew install` / `cargo install` side is #69's subject.
+
+## Why it matters
+
+In many ecosystems you'd read the version from a file shipped next to the binary (a `package.json`, a bundled `VERSION`) or hardcode a string you forget to bump. Both drift, and the file can go missing. Compile-time stamping makes the binary self-describing with zero runtime dependencies. And the `env!` vs `option_env!` split encodes intent in the type: `env!` says "this must exist, fail the build if it doesn't" and hands you a `&str`; `option_env!` says "this might exist" and hands you an `Option<&str>` you're forced to handle. Typo `CARGO_PKG_VERSION` and the build stops immediately — you never ship a binary that reports the wrong version because a lookup silently returned empty.
+
+## Related lessons
+
+- PR #48 — *Warn instead of silently defaulting.* `build.rs` here uses `.ok()?` to deliberately drop git's errors and fall back; #48 is about the cases where that silent drop is a bug. Same combinator, opposite verdict — the difference is whether the `Err` means "someone made a mistake."
+
+## Dig deeper
+
+- [The Cargo Book — Build Scripts](https://doc.rust-lang.org/cargo/reference/build-scripts.html) — what `build.rs` can do and the full list of `cargo:` output directives (`rustc-env`, `rerun-if-changed`, `rerun-if-env-changed`).
+- [std — `env!`](https://doc.rust-lang.org/std/macro.env.html) and [`option_env!`](https://doc.rust-lang.org/std/macro.option_env.html) — the compile-time environment macros, and why one fails the build while the other returns `Option`.
diff --git a/docs/lessons/63-what-clippy-teaches.md b/docs/lessons/63-what-clippy-teaches.md
new file mode 100644
index 0000000..418e412
--- /dev/null
+++ b/docs/lessons/63-what-clippy-teaches.md
@@ -0,0 +1,108 @@
+<!-- Lesson for PR #63. Teaches one concept grounded in the real diff. -->
+
+# PR #63 — Add a fmt + clippy lint job to CI
+
+> **Rust lesson:** Clippy is a Rust teacher wearing a linter's badge — each lint names an idiom (`single_match` → `if let`) or a footgun (`await_holding_lock`, `dead_code`), and the honest reply is either to adopt the idiom or to `#[allow]` it *with a reason*.
+> **Tags:** `clippy` · `rustfmt` · `lints` · `idioms`
+> **Merged:** 2026-06-14 · +604/−248 · [View PR](https://github.com/nonrational/adjacent/pull/63)
+
+## The situation
+
+The repo had never been gated on formatting or lints. This PR adds a CI job that runs two commands and fails the build if either complains:
+
+```yaml
+# .github/workflows/ci.yml
+- run: cargo fmt --all -- --check
+- run: cargo clippy --workspace --all-targets -- -D warnings
+```
+
+To land that gate green it had to fix everything the two commands surfaced. Be honest about the split: the vast majority of the +604/−248 is one mechanical `cargo fmt --all` commit — struct literals expanded to multi-line, long calls wrapped — with no behavior change and nothing to learn. The interesting part is a tiny second commit (+46/−7) where `clippy -D warnings` forced three real changes. That's the lesson: not the formatter, but what clippy *taught*.
+
+## The Rust idea
+
+Clippy ships ~700 lints, and almost none of them are about whitespace — rustfmt owns that. Clippy is about *idiom* and *correctness*. Each lint encodes a small piece of "here's how a seasoned Rust programmer would write this, and why." Running it is less like a spell-check and more like pairing with someone who keeps saying "there's a cleaner way." `-D warnings` (deny all warnings) turns that advice into a hard gate: the build fails until you either take the advice or explicitly, in writing, decline it.
+
+Declining is a first-class move. `#[allow(clippy::some_lint)]` says "I read this lint, I understand what it's warning about, and it doesn't apply here." A clippy pass done right leaves behind a mix of both: code you improved, and a few `#[allow]`s each carrying a comment that explains the disagreement. This PR has one of each kind.
+
+## In this PR
+
+**1. `single_match` → `if let`.** Clippy's `single_match` fires when a `match` has one arm that does real work and a second arm that does nothing (`_ => {}`). Rust already has a construct for "run this code only if the value matches one pattern, otherwise skip" — that's `if let`. A two-arm match with an empty catch-all is `if let` wearing a costume, and reading it forces you to scan to the bottom to confirm the `_` really is empty.
+
+```rust
+// crates/adj/src/tls.rs — ensure_leaf
+// before:
+match (fs::read_to_string(&cert_path), fs::read_to_string(&key_path)) {
+    (Ok(cert), Ok(key)) => match leaf_covers(&cert, sans) {
+        Ok(true) => return Ok((cert, key)),
+        Ok(false) | Err(_) => {}
+    },
+    _ => {}
+}
+
+// after:
+if let (Ok(cert), Ok(key)) = (
+    fs::read_to_string(&cert_path),
+    fs::read_to_string(&key_path),
+) {
+    if let Ok(true) = leaf_covers(&cert, sans) {
+        return Ok((cert, key));
+    }
+}
+```
+
+Both matches collapse the same way. Semantics are identical — only a readable, SAN-covering cached leaf short-circuits; everything else (a read error, a parse error, a cert that doesn't cover the wanted names) falls through to re-issue. But the `if let` version *says* that: "if both files read, and the leaf covers the SANs, use it." The `_ => {}` and `Ok(false) | Err(_) => {}` filler arms are gone, so there's nothing to double-check.
+
+**2. `await_holding_lock` — the documented decline.** This lint flags holding a `std::sync::MutexGuard` across an `.await`. It's a real footgun: on a multi-threaded async runtime the task can be parked mid-await while still holding the lock, and another task on that same thread can block forever trying to acquire it — a deadlock. Clippy is right to warn by default. Here it's a false alarm, and the fix is to say so, not to restructure working test code:
+
+```rust
+// crates/adj/tests/tls.rs
+#[cfg(target_os = "macos")]
+#[tokio::test]
+// The keychain guard intentionally spans the test's awaits to serialize on LOGIN_KEYCHAIN_LOCK;
+// a current-thread tokio runtime can't deadlock on it, so the std-guard-across-await lint is moot.
+#[allow(clippy::await_holding_lock)]
+async fn install_ca_generates_files_and_prints_macos_command() {
+```
+
+The `#[allow]` is localized to the three tests that need it, not slapped on the whole crate. That matters: if the *supervisor* ever grows a real lock-across-await, the lint stays live to catch it. A repo-wide `#![allow]` would have silenced the warning everywhere and thrown away its value.
+
+**3. `dead_code` / `unused_imports` under a cross-platform gate.** The clippy job runs on `ubuntu-latest`, but the keychain code is `#[cfg(target_os = "macos")]` — it compiles to nothing on Linux. So on the CI runner, every helper that only the macOS path uses becomes genuinely dead code, and `-D warnings` promotes those warnings to errors. The fix is to `#[cfg]`-gate the now-unused items to match their only caller:
+
+```rust
+// crates/adj/src/tls.rs
+pub(crate) use keychain::delete as delete_keychain_ca;
+// Only the macOS doctor checks load a keychain handle; on other targets the re-export is unused.
+#[cfg(target_os = "macos")]
+pub(crate) use keychain::load as load_keychain_ca;
+```
+
+...and for a stub that exists only to mirror an API on the platform where it's never called, a deliberate `#[allow(dead_code)]`:
+
+```rust
+// crates/adj/src/tls/keychain.rs — the non-macOS stub
+// Mirrors the macOS KeychainKey API for symmetry; the non-macOS doctor path never calls
+// it, so it's dead on these targets.
+#[allow(dead_code)]
+pub fn sign_canary(&self) -> Result<()> {
+    Err(unsupported())
+}
+```
+
+Same test scaffolding (`with_temp_home`, `HOME_LOCK`, the `curl_available` helper) got the same `#[cfg(target_os = "macos")]` treatment.
+
+## Why it matters
+
+Two takeaways a linter-skeptic misses.
+
+First, `dead_code` under `--all-targets -D warnings` on a Linux runner is a *free cross-compilation check*. Adjacent is mostly developed on a Mac, and it's easy to leave a helper unused on platforms you never build locally. The CI job compiles the non-macOS `cfg` branches you'd otherwise never exercise, and catches the drift. The lint isn't nagging about tidiness — it's proving that every target still hangs together.
+
+Second, a green clippy run doesn't mean "no lints fired." It means "every lint that fired was either fixed or explicitly declined with a reason." That's the discipline `-D warnings` enforces: you can't ignore advice by scrolling past it. You either take it, or you write down why you didn't — and the next reader gets that reasoning for free. An `#[allow]` with a comment is worth more than clean code that silently dodged the question.
+
+## Related lessons
+
+- PR #40 shipped the HTTPS + local-CA machinery. The `ensure_leaf` match and the keychain helpers clippy is cleaning up here are exactly that code — this PR is #40's neighborhood one linter-pass later.
+- PR #48 is the same spirit in a different tool: it's about surfacing a `Result`'s `Err` instead of swallowing it. Clippy and the type system are both in the business of making the invisible visible — this PR just does it at the linter layer.
+
+## Dig deeper
+
+- [The Clippy lint index](https://rust-lang.github.io/rust-clippy/) — every lint, searchable, each with a before/after and the reasoning behind it. `single_match`, `await_holding_lock`, and the rustc `dead_code`/`unused_imports` lints all have entries worth reading.
diff --git a/docs/lessons/65-health-files-and-metadata.md b/docs/lessons/65-health-files-and-metadata.md
new file mode 100644
index 0000000..691f051
--- /dev/null
+++ b/docs/lessons/65-health-files-and-metadata.md
@@ -0,0 +1,119 @@
+<!-- Lesson for PR #65. Non-Rust: community health files; teaches OSS hygiene + Cargo.toml crates.io metadata. -->
+
+# PR #65 — Add community health files
+
+> **Rust lesson:** None — this PR is seven Markdown/YAML files under `.github/` (+160/−0), zero Rust. The lesson is open-source project hygiene, and the Rust-ecosystem analog worth knowing: the way GitHub reads your `.github/` files and renders them into the repo UI is exactly how **crates.io reads your `Cargo.toml` package metadata** — `description`, `repository`, `readme`, `keywords`, `categories`, `license`, `rust-version` — and renders it into your crate page.
+> **Tags:** `oss-hygiene` · `crates.io-metadata`
+> **Merged:** 2026-06-14 · +160/−0 · [View PR](https://github.com/nonrational/adjacent/pull/65)
+
+## The situation
+
+The repo had code and a README but none of the paperwork a public project is
+judged by: no code of conduct, no contribution guide, no security policy, no
+issue or PR templates. This PR adds the whole set — `CODE_OF_CONDUCT.md`,
+`CONTRIBUTING.md`, `SECURITY.md`, two issue templates plus a `config.yml`, and a
+`PULL_REQUEST_TEMPLATE.md` — all under `.github/`.
+
+## The idea (no Rust this time)
+
+These are **community health files**, and the reason they live in `.github/` is
+that GitHub reads them by convention and wires them into the UI. Drop
+`CONTRIBUTING.md` there and the "New pull request" screen sprouts a link to it.
+Add `ISSUE_TEMPLATE/*.md` and the "New issue" button becomes a menu of your
+templates. Add `SECURITY.md` and a "Report a vulnerability" affordance appears.
+You're not writing docs a human has to go find — you're filling in slots a
+platform already knows how to render.
+
+The trick is that the file's **location and name are the contract**. GitHub
+doesn't parse your prose; it keys off the path (`.github/SECURITY.md`) and, for
+templates, off the YAML front-matter at the top of the file. Get the path right
+and the feature lights up; get it wrong and the file is just dead Markdown.
+
+## In this PR
+
+The issue templates lead with YAML front-matter — that block *is* what GitHub
+reads to build the template menu (the `name` and `about` become the menu entry):
+
+```yaml
+# .github/ISSUE_TEMPLATE/feature_request.md
+---
+name: Feature Request
+about: Propose an enhancement or new capability for Adjacent
+labels: enhancement
+---
+```
+
+`config.yml` isn't a template — it configures the template *chooser*, keeping the
+blank-issue escape hatch open and routing open-ended questions to Discussions
+instead of the issue tracker:
+
+```yaml
+# .github/ISSUE_TEMPLATE/config.yml
+blank_issues_enabled: true
+contact_links:
+  - name: General questions
+    url: https://github.com/nonrational/adjacent/discussions
+    about: Ask questions and discuss Adjacent in Discussions
+```
+
+`SECURITY.md` states a support window and points reporters at GitHub's private
+reporting flow rather than a public issue or an email address:
+
+```markdown
+<!-- .github/SECURITY.md -->
+For security vulnerabilities, please use GitHub's [private vulnerability
+reporting feature](https://github.com/nonrational/adjacent/security/advisories/new)
+rather than opening a public issue.
+```
+
+And `CONTRIBUTING.md` closes with the standard Rust dual-license inbound clause —
+every contribution comes in under both licenses, no extra paperwork:
+
+```markdown
+<!-- .github/CONTRIBUTING.md -->
+Unless you explicitly state otherwise, any contribution intentionally submitted
+for inclusion in this work by you ... shall be dual licensed under the Apache
+License, Version 2.0 and the MIT license, without any additional terms or
+conditions.
+```
+
+That clause isn't free-floating — it matches a field already in the manifest,
+which is the bridge to the Rust angle.
+
+## Why it matters — the crates.io angle
+
+crates.io is to a published crate what GitHub's repo page is to a repo: it reads
+structured metadata and renders it. The source of that metadata is the
+`[package]` table in `Cargo.toml`. The repo's workspace manifest already carries
+two of the important fields, and the `license` here is the exact counterpart to
+the CONTRIBUTING clause above:
+
+```toml
+# Cargo.toml — [workspace.package] (already in the repo, not added by this PR)
+license = "MIT OR Apache-2.0"
+repository = "https://github.com/nonrational/adjacent"
+```
+
+If Adjacent were ever `cargo publish`ed, crates.io would surface `license` as a
+badge and `repository` as the "Repository" link — the same "platform renders
+your metadata" move as GitHub and `.github/`. But the metadata slots for a
+polished crate page go further, and they're worth knowing even before you
+publish:
+
+- **`description`** — the one-liner under the crate name in search results. Required to publish.
+- **`readme`** — path to the file crates.io renders as the crate's front page (defaults to `README.md`).
+- **`keywords`** / **`categories`** — how people find you in search and browse; `categories` must come from crates.io's fixed slug list.
+- **`rust-version`** — your MSRV (minimum supported Rust version). Cargo refuses to build with an older toolchain and prints a clear error instead of a confusing mid-compile failure.
+
+The lesson mirrors the health files exactly: don't write a paragraph telling
+people your MSRV or where to file bugs — put the value in the slot the tooling
+reads, and the tooling shows it for you, consistently, everywhere.
+
+## Related lessons
+
+- PR #46 covers the `MIT OR Apache-2.0` dual-license convention itself and the on-disk `LICENSE-*` layout — the CONTRIBUTING clause here is the inbound-contribution half of that same decision.
+- PR #36 makes the "the file's path/format *is* the contract" point from the docs side.
+
+## Dig deeper
+
+- [The Cargo Book — The Manifest Format](https://doc.rust-lang.org/cargo/reference/manifest.html) — every `[package]` field crates.io reads: `description`, `repository`, `readme`, `keywords`, `categories`, `license`, and `rust-version`.
diff --git a/docs/lessons/68-lean-agent-docs.md b/docs/lessons/68-lean-agent-docs.md
new file mode 100644
index 0000000..4af7e65
--- /dev/null
+++ b/docs/lessons/68-lean-agent-docs.md
@@ -0,0 +1,23 @@
+<!-- Lesson for PR #68. Non-Rust: pure docs deletion; modeling honesty when there's no lesson. -->
+
+# PR #68 — Remove the agent-identity section from CLAUDE.md
+
+> **Rust lesson:** None — this is a pure documentation deletion (+0/−10), no Rust and no technical concept to teach.
+> **Tags:** `docs-hygiene` · `honest-series`
+> **Merged:** 2026-06-16 · +0/−10 · [View PR](https://github.com/nonrational/adjacent/pull/68)
+
+## What happened
+
+This PR deleted the `## Agent identity` section from `CLAUDE.md` — ten lines of personal operational detail (the `nonreagent`/`nonrational` GitHub accounts, the `gh auth switch` dance, the per-commit author line) that don't belong in an open-source repo. The durable principle it encoded still lives, machine-agnostically, in each contributor's own profile:
+
+```markdown
+## Agent identity (`nonrational/adjacent` only)
+
+Agents commit, push, and self-review as the GitHub user `nonreagent` — the human reviews and merges.
+- `gh auth switch -u nonreagent` + `gh auth setup-git` before any `git push`. Inline `GH_TOKEN=...` does nothing for `git push`.
+- **Never** run `gh pr review --approve` or `gh pr merge`. Approval and merge are the human's job.
+```
+
+The meta-note worth keeping: **agent-instruction files (`CLAUDE.md`, `AGENTS.md`) earn their keep by staying lean.** Every line is context an agent re-reads on each task, and anything personal or repo-account-specific is noise for other contributors plus a small information leak. Prune aggressively.
+
+And this file is the honesty principle in action: a good teaching series says so plainly when a PR carries no lesson, rather than inventing one.
diff --git a/docs/lessons/69-distributing-a-rust-cli.md b/docs/lessons/69-distributing-a-rust-cli.md
new file mode 100644
index 0000000..6d30d58
--- /dev/null
+++ b/docs/lessons/69-distributing-a-rust-cli.md
@@ -0,0 +1,118 @@
+<!-- Lesson for PR #69. Non-Rust diff (homepage), teaches Rust-CLI install/distribution. -->
+
+# PR #69 — Add alpha install directions to the homepage
+
+> **Rust lesson:** No Rust in this diff (it's the `ent/` homepage plus a Homebrew formula rename) — but the *content* teaches the consumer side of shipping a Rust CLI: a Homebrew tap gives users a prebuilt binary with no toolchain, versus `cargo install` compiling from source into `~/.cargo/bin`, versus grabbing the release tarball by hand.
+> **Tags:** `distribution` · `homebrew` · `cargo-install`
+> **Merged:** 2026-06-21 · +46/−11 · [View PR](https://github.com/nonrational/adjacent/pull/69)
+
+## The situation
+
+The alpha was installable but the homepage still said "coming soon." This PR put
+the real install steps on the page and renamed the Homebrew package `adj → adjacent`
+so `brew install adjacent` reads naturally. The diff is HTML, bash, YAML, a Ruby
+formula, and Markdown — zero Rust. Worth teaching anyway, because "how does a
+stranger get your Rust binary onto their machine" is a real question every CLI
+project answers, and this PR answers it in public.
+
+## The idea (no Rust this time)
+
+A compiled Rust CLI is just a binary. Getting it onto a user's `PATH` has three
+common routes, and they trade off differently:
+
+1. **A package manager (Homebrew tap).** The user runs two commands, gets a
+   prebuilt binary, and never needs a Rust toolchain. Updates flow through
+   `brew upgrade`. You (the producer) do the compiling once in CI and publish the
+   artifact.
+2. **`cargo install`.** Compiles from source on the user's machine into
+   `~/.cargo/bin`. Requires them to have Rust installed, and the first build can
+   take minutes. Updates are `cargo install --force`. Great for Rust developers,
+   a non-starter for everyone else.
+3. **The prebuilt release tarball, by hand.** Download, extract, drop the binary
+   on `PATH`. No toolchain, no Homebrew — but you own every update yourself.
+
+The Homebrew route is really #3 with a manager wrapped around it: the formula
+just points at the same release tarball and automates the download-and-place.
+
+## In this PR
+
+The homepage now renders the two-command install path (`ent/index.html`):
+
+```html
+<!-- ent/index.html -->
+<section>
+  <div class="label">install &middot; alpha</div>
+  <div class="cmds">
+    <code class="cmd"><span class="prompt">$</span>brew tap nonrational/adjacent https://github.com/nonrational/adjacent<span class="note"># straight from the repo &mdash; no separate tap</span></code>
+    <code class="cmd"><span class="prompt">$</span>brew install adjacent<span class="note"># Apple Silicon, unsigned alpha build</span></code>
+  </div>
+</section>
+```
+
+Which the user runs as:
+
+```sh
+brew tap nonrational/adjacent https://github.com/nonrational/adjacent
+brew install adjacent
+```
+
+Two subtleties worth naming:
+
+**The package name and the binary name don't have to match.** `brew install
+adjacent` installs a CLI you invoke as `adj`. Homebrew's formula name is just a
+handle for the package; what lands on `PATH` is whatever the formula installs.
+This PR renamed the *package* to `adjacent` while the CLAUDE.md contract keeps the
+*binary* `adj`.
+
+**What the tap actually wraps is route #3.** The formula's source of truth points
+straight at a prebuilt release artifact (`.github/scripts/render-formula.sh`):
+
+```bash
+# .github/scripts/render-formula.sh
+url="https://github.com/${repo}/releases/download/${tag}/adj-${version}-aarch64-apple-darwin.tar.gz"
+```
+
+So the user who runs `brew install adjacent` and the user who downloads that
+`.tar.gz` by hand get byte-for-byte the same binary. Homebrew is the convenience
+layer, not a different build.
+
+For contrast, the from-source route lives in this repo's `justfile`:
+
+```make
+# justfile
+install:
+  cargo install --path crates/adj
+```
+
+That compiles the workspace and installs `adj` into `~/.cargo/bin` — the Rust
+developer's path, needing a full toolchain and a real compile, no prebuilt
+artifact involved.
+
+## Why it matters
+
+Pick the wrong default and you lose users. Lead a non-Rust audience with `cargo
+install` and you've told them to install a compiler and wait for a cold build
+before they can try your tool — most bounce. Lead with a Homebrew tap and the
+cost is on *you*: CI has to build, sign (or admit it's unsigned, as this alpha
+does), and publish the artifact, and you have to keep the formula's `url` and
+`sha256` in sync with each release. This PR even adds a `smoke` CI job that taps
+and installs from the *published* formula, so a broken install path fails the
+release instead of a user. The producer eats the complexity so the consumer's
+path stays two commands.
+
+## Related lessons
+
+- **PR #60** built the *producer* half this consumes — the release CI, the
+  in-repo tap formula, and version stamping that make `brew install adjacent`
+  resolve to a real artifact:
+  [View PR #60](https://github.com/nonrational/adjacent/pull/60). This PR is the
+  consumer-facing directions for that machinery.
+- [PR #46](46-revamp-landing-positioning-page.md) — the other side of the same
+  `ent/` homepage: how a single-binary Rust project carries a non-Rust web
+  frontend beside its Cargo workspace. Same "honest, no-Rust diff" shape as this
+  one.
+
+## Dig deeper
+
+- [The Cargo Book — `cargo install`](https://doc.rust-lang.org/cargo/commands/cargo-install.html) — installs a binary from source into `~/.cargo/bin`; the `--path`, `--force`, and `--root` flags that control where it builds from and lands.
+- [Homebrew — How to Create and Maintain a Tap](https://docs.brew.sh/How-to-Create-and-Maintain-a-Tap) — the `user/tap/formula` naming triplet and why the tap and formula sharing a name (`nonrational/adjacent` + `adjacent`) is fine.
diff --git a/docs/lessons/75-hand-render-config-to-disk.md b/docs/lessons/75-hand-render-config-to-disk.md
new file mode 100644
index 0000000..ed67c30
--- /dev/null
+++ b/docs/lessons/75-hand-render-config-to-disk.md
@@ -0,0 +1,166 @@
+<!-- Lesson for PR #75. Teaches one concept grounded in the real diff. -->
+
+# PR #75 — Scaffold a default adjacent.toml in `adj add`
+
+> **Rust lesson:** When a config file is meant for a *human* to open and edit, hand-render it as text so comments, `# TODO` placeholders, and commented-out optional fields survive — `toml::to_string(&struct)` would drop every one of them — and write it with `std::fs::write` behind a `!path.exists()` guard so you never clobber a file the user already owns.
+> **Tags:** `std::fs` · `toml` · `file-generation`
+> **Merged:** 2026-06-21 · +1552/−6 · [View PR](https://github.com/nonrational/adjacent/pull/75)
+
+## The situation
+
+`adj add .` used to dead-end when a directory had no `adjacent.toml`. This PR makes it
+*generate* a sensible default instead — filling in `name` and `cmd` when it can detect
+the stack, leaving `# TODO` guidance when it can't. The generated file's whole reason
+for existing is that a person opens it next and edits it. So two questions: how do you
+produce a config file that's friendly to a human editor, and how do you write it to disk
+without ever overwriting one the user already wrote?
+
+## The Rust idea
+
+Rust's `toml` crate can serialize a struct straight to a config string —
+`toml::to_string(&cfg)` — the write-side mirror of the `#[derive(Deserialize)]` that
+reads `adjacent.toml` back in (PR #19). It's the obvious reach, and for a machine-to-machine
+file it's the right one: faithful, round-trippable, no hand-maintained text.
+
+But `to_string` serializes **data**, and a struct holds no comments. Feed it an
+`AppConfig` and you get back exactly:
+
+```toml
+name = "myapp"
+cmd = "npm run dev"
+```
+
+No header explaining where the file came from. No `# Optional:` block showing the
+fields the user *could* set. No `# TODO` next to a value they still need to fill in.
+For a scaffold, those comments aren't decoration — they're the entire payload. The file
+is a teaching aid disguised as config.
+
+So the tool for a human-facing config file is the opposite of a serializer: you
+**render the text by hand**, comments and all, and treat the struct as something you'll
+parse the result *back* into later, not something you serialize *from*. The cost is that
+you're now responsible for producing valid TOML yourself — which the PR pins down with a
+test, below.
+
+## In this PR
+
+`render` builds the file as a string. Every line the user benefits from — the header,
+the `# TODO`s, the commented-out optional block — is text serde would never emit:
+
+```rust
+// crates/adj/src/scaffold.rs
+fn render(name: Option<&str>, cmd: Option<&str>) -> String {
+    let name_line = match name {
+        Some(n) => format!("name = \"{n}\"\n"),
+        None => "name = \"app\"  # TODO: set a name (lowercase letters, digits, `-`)\n".to_string(),
+    };
+    let cmd_line = match cmd {
+        Some(c) => format!("cmd = \"{c}\"\n"),
+        None => "cmd = \"\"  # TODO: set your dev command, e.g. \"npm run dev\"\n".to_string(),
+    };
+    format!(
+        "# Generated by `adj add` — edit and re-run if needed.\n\
+         {name_line}\
+         {cmd_line}\
+         \n\
+         # Optional:\n\
+         # port_env = \"PORT\"\n\
+         # env_file = \".env.local\"\n\
+         # idle_timeout = \"15m\"          # \"30s\" / \"1h\" / \"off\"\n\
+         # health_check_url = \"/healthz\"\n"
+    )
+}
+```
+
+The `match name` / `match cmd` is where "known value" and "placeholder with guidance"
+branch: a detected value renders as a live `name = "…"` line, an absent one renders as a
+commented `# TODO`. A serializer can't express that — there's no struct field that means
+"leave a note for the human here."
+
+Hand-rendering does put one job on you: emitting *valid* TOML. The PR's doc comment spells
+out why this particular template is safe without any escaping logic —
+
+```rust
+// crates/adj/src/scaffold.rs
+/// Render the `adjacent.toml` body. `None` fields become TODO placeholders. Detected commands
+/// come from a fixed vocabulary (none contain `"`) and `sanitize_name` guarantees `name` is
+/// `[a-z0-9-]`, so no TOML string escaping is needed here.
+```
+
+— and a unit test nails the door shut by parsing the rendered string back through the real
+`toml` crate. If a future edit ever produces something that isn't valid TOML, this goes red:
+
+```rust
+// crates/adj/src/scaffold.rs
+assert!(
+    toml::from_str::<toml::Value>(&toml).is_ok(),
+    "invalid toml: {toml}"
+);
+```
+
+That's the safety net that makes hand-rendering defensible: you give up serde's
+guaranteed-valid output, so you buy it back with a round-trip assertion.
+
+Then the write, in `client::add`. The whole thing is guarded on the file *not* already
+existing:
+
+```rust
+// crates/adj/src/client.rs
+let manifest = canon.join("adjacent.toml");
+if !manifest.exists() {
+    let scaffold = scaffold::build(&canon);
+    std::fs::write(&manifest, &scaffold.toml)
+        .with_context(|| format!("writing {}", manifest.display()))?;
+    // ... branch on detected name/cmd ...
+}
+```
+
+`std::fs::write` is the one-liner form — open (creating or truncating), write the whole
+buffer, close, all in a call. The `if !manifest.exists()` in front of it is the
+not-clobbering rule: a user who already hand-wrote an `adjacent.toml` never has it
+silently replaced by a generated one. (An integration test asserts exactly this — an
+existing manifest comes back byte-identical after `adj add`.)
+
+## Why it matters
+
+Two traps, one on each side.
+
+**Reaching for the serializer** feels like the disciplined choice and quietly produces a
+worse file. `toml::to_string(&cfg)` is faithful and valid — and strips the comments that
+were the point. The user opens a two-line file with no hint of what else they can set or
+what they still need to fill in. Knowing *when not to serialize* is the actual skill here:
+struct-to-TOML for data you'll read back by machine, hand-rendered text for a file a human
+edits next.
+
+**Skipping the existence check** is the destructive one. `std::fs::write` truncates —
+point it at a path that already holds a carefully-tuned manifest and the old contents are
+gone, no prompt, no backup. The `!exists()` guard is what keeps a convenience feature from
+eating the user's work.
+
+One honest caveat: `exists()`-then-`write()` is check-then-act, so there's a hair-thin
+window where the file could appear between the two calls. For an interactive command a
+person runs at a shell, that window doesn't matter. If you needed it to matter — a
+concurrent or hostile setting — the atomic form is
+`std::fs::OpenOptions::new().create_new(true)`, which fails outright if the file already
+exists rather than checking first. `adj add` doesn't need it; knowing the upgrade path
+exists is the point.
+
+## Related lessons
+
+- **PR #41** is the sibling technique — it also builds a document with `format!` string
+  templating, and teaches the raw-string-literal (`r#"…"#`) mechanics that make a
+  multi-line template readable. This lesson is the *decision* that sits above that
+  mechanism: why you hand-render a config at all instead of serializing a struct, plus the
+  disk write. #41 is *how* to template; #75 is *when* (and how not to clobber).
+- **PR #19** is the exact mirror: it reads `adjacent.toml` back in with
+  `#[derive(Deserialize)]` and `Option` fields. #75 writes the file #19 parses — and #19's
+  strict "missing `cmd` is an error" is what the `# TODO: set your dev command` placeholder
+  is steering the user away from tripping.
+- **PR #22** serializes DTOs to JSON *with* serde — because that output is consumed by
+  `jq`, a machine, where a stable derived shape is exactly right. Put next to #75 they're
+  the clean contrast: serialize for machines, hand-render for humans.
+
+## Dig deeper
+
+- [`std::fs::write`](https://doc.rust-lang.org/std/fs/fn.write.html) — the create-or-truncate one-shot write used here.
+- [`std::fs::OpenOptions::create_new`](https://doc.rust-lang.org/std/fs/struct.OpenOptions.html#method.create_new) — the atomic "fail if it already exists" alternative to a separate `exists()` check.
+- [The `toml` crate](https://docs.rs/toml/latest/toml/) — `toml::from_str` (used in the round-trip test) and `toml::to_string` (the serializer this PR deliberately *doesn't* use for generation, because it drops comments).
diff --git a/docs/lessons/76-derived-env-precedence-order.md b/docs/lessons/76-derived-env-precedence-order.md
new file mode 100644
index 0000000..01fa1d7
--- /dev/null
+++ b/docs/lessons/76-derived-env-precedence-order.md
@@ -0,0 +1,93 @@
+<!-- Lesson for PR #76. Teaches one concept grounded in the real diff. -->
+
+# PR #76 — Inject an ADJ_* boot environment into supervised apps
+
+> **Rust lesson:** Compute a namespace of derived values into a `Vec<(String, String)>` with `format!`, then express precedence as insertion *order* — inject that layer last so `Command::env`'s last-writer-wins overwrites anything the user set.
+> **Tags:** `format!` · `last-writer-wins` · `derived-data`
+> **Merged:** 2026-06-24 · +1303/−12 · [View PR](https://github.com/nonrational/adjacent/pull/76)
+
+## The situation
+
+PR #17 injected one variable: `$PORT`. That let an app *bind*, but not *address itself*. A dev server behind the proxy still defaults its own links to `localhost:<port>` — wrong for every URL a user clicks through `*.adj.ac`. The daemon knows the real facts (the name, the `.adj.ac` host, the listener ports); the app can't reconstruct them. So the daemon now hands the app a whole reserved namespace — `ADJ_NAME`, `ADJ_HOST`, and four base URLs — computed at boot. And because they're *authoritative*, they have to beat anything the user set in `env_file` or `[env]`.
+
+## The Rust idea
+
+Two ideas, tied together.
+
+**Deriving data with `format!`.** `format!` is `println!`'s sibling that returns instead of prints: it allocates a brand-new owned `String` from a template. `format!("https://{host}")` interpolates the `host` variable directly (Rust's inline captures — the name in the braces is a real variable in scope). Owned is the key word: the returned `String` carries its own bytes, so a function can *return* it or push it into a `Vec` without any borrow outliving the stack frame it came from. That's what makes a pure "build the values" helper possible — feed it a name and two ports, get back owned pairs, no daemon or socket required to test it.
+
+**Precedence as insertion order.** `Command::env(key, value)` inserts-or-overrides a single entry (see #17). When you apply several layers to the same command, *the order you apply them in is the precedence policy* — the last write for a given key wins. There's no merge function, no priority flag, no "if not already set" check. To make one layer authoritative, you run it last. Precedence stops being a rule buried in a helper and becomes a visible fact about the sequence of statements.
+
+## In this PR
+
+A pure helper builds the derived pairs. Note it returns `Vec<(String, String)>` — an *ordered* list of owned key/value tuples, not a map — because the caller only iterates it, and order is exactly what the precedence step needs:
+
+```rust
+// crates/adj/src/supervisor.rs
+fn adj_env(name: &str, http: Option<u16>, https: Option<u16>) -> Vec<(String, String)> {
+    let host = format!("{name}{}", crate::proxy::HOST_SUFFIX);
+    let mut vars = vec![
+        ("ADJ_NAME".to_string(), name.to_string()),
+        ("ADJ_HOST".to_string(), host.clone()),
+        ("ADJ_URL".to_string(), format!("https://{host}")),
+        ("ADJ_URL_HTTP".to_string(), format!("http://{host}")),
+    ];
+    if let Some(p) = https {
+        vars.push(("ADJ_URL_DIRECT".to_string(), format!("https://{host}:{p}")));
+    }
+    if let Some(p) = http {
+        vars.push((
+            "ADJ_URL_HTTP_DIRECT".to_string(),
+            format!("http://{host}:{p}"),
+        ));
+    }
+    vars
+}
+```
+
+- `host` is computed once, then reused. `host.clone()` hands one owned copy to the `ADJ_HOST` pair while the original stays live for the three `format!` calls below it — each of those *borrows* `host` (`&host` under the hood) to read its bytes, so `host` must still exist.
+- The four unconditional entries go in a `vec![…]` literal. The two `_DIRECT` URLs are **conditional**: `if let Some(p) = https` unwraps the port only when it resolved, and `.push`es a pair carrying it. A `None` port means that URL is simply absent — no entry pointing at a dead port. Optionality is expressed by *whether the pair exists*, not by an empty string.
+- Everything is an owned `String`. `"ADJ_NAME".to_string()` and each `format!` produce data the `Vec` owns outright, so the whole thing can be returned by value.
+
+Then `up()` applies it as the final env layer:
+
+```rust
+// crates/adj/src/supervisor.rs
+command.env(port_env, port.to_string());
+// Daemon-owned ADJ_* namespace: the app's own external identity and URLs. Injected
+// after env_file/[env] so these authoritative values win over anything a user set.
+for (k, v) in adj_env(&name, self.proxy_ports.http(), self.proxy_ports.https()) {
+    command.env(k, v);
+}
+```
+
+The full precedence chain, top to bottom, is `env_file` → `[env]` → `PORT` → `ADJ_*`. Each `command.env` call overwrites the same key from an earlier layer. The `ADJ_*` loop runs *last*, so if a user set `ADJ_HOST` in their `[env]` table, the daemon's value silently overwrites it. That's the entire enforcement of "reserved, daemon-owned namespace" — no validation, no rejection, just position in the sequence.
+
+Because `adj_env` is pure and returns plain data, the unit tests skip the daemon entirely and collect the pairs into a `HashMap` for random-access lookup by key:
+
+```rust
+// crates/adj/src/supervisor.rs
+let vars: std::collections::HashMap<String, String> =
+    adj_env("alannorton-com", Some(8080), Some(8443))
+        .into_iter()
+        .collect();
+assert_eq!(vars["ADJ_URL_DIRECT"], "https://alannorton-com.adj.ac:8443");
+```
+
+The builder returns a `Vec` (order matters, for precedence and for iteration); the test `.collect()`s it into a `HashMap` because *it* only wants "give me the value for this key." Same pairs, two container shapes, each chosen for what the code at hand does with them.
+
+## Why it matters
+
+In a language where you mutate a shared, global environment or reach for a `merge(defaults, overrides)` helper, precedence is implicit and easy to get backwards. Someone reorders two blocks, or flips an argument, and user config silently starts winning over values that were supposed to be authoritative — a bug that type-checks and passes most tests. Here the policy is one readable fact: the `ADJ_*` loop is the last thing that touches the environment before spawn, so it wins by construction. Move it above the `[env]` layer and the precedence inverts — but you'd *see* that in the diff, because it's a line order, not a hidden flag.
+
+The derived-data half pays off in testing. `format!` returning owned `String`s lets `adj_env` be a pure function of `(name, http, https)` — no I/O, no clock, no socket. Every value format, the worktree-key case, and the "port unresolved → drop the URL" rule get asserted in plain unit tests that run in microseconds, with the end-to-end test left to prove only that the wiring reaches a real child.
+
+## Related lessons
+
+- PR #17 is the one-variable version of this exact mechanic: `Command::env` as insert-or-override, and why the value must be an owned `String`. #17 injects `PORT` alone; #76 generalizes it into a computed namespace and makes the *layer order* load-bearing. Read #17 first for the builder and inheritance model; this lesson is about deriving a set of values and using order as precedence.
+- PR #45 builds rows the cousin way — `map` + `collect` into a collection — where order doesn't carry meaning the way it does here.
+
+## Dig deeper
+
+- [`std::fmt` / the `format!` macro](https://doc.rust-lang.org/std/macro.format.html) — the template syntax, inline argument captures (`{host}`), and that it returns an owned `String`.
+- [`std::collections::HashMap`](https://doc.rust-lang.org/std/collections/struct.HashMap.html) — the "Which collection?" preamble at the top of the [`std::collections`](https://doc.rust-lang.org/std/collections/index.html) module is the canonical guide to `Vec` vs `HashMap`: sequence-with-order vs lookup-by-key, exactly the choice this PR makes twice.
diff --git a/docs/lessons/README.md b/docs/lessons/README.md
new file mode 100644
index 0000000..c4b2226
--- /dev/null
+++ b/docs/lessons/README.md
@@ -0,0 +1,85 @@
+# Rust, one PR at a time
+
+A teaching series that walks Adjacent's merged pull requests in order and pulls one
+practical Rust lesson from each. The project is a real single-binary daemon — a
+process supervisor, a reverse proxy, a local CA — so the concepts show up because
+the code needed them, not because a tutorial contrived them.
+
+One file per PR. Each teaches a single idea, grounded in code that PR actually
+shipped (snippets are lifted from the real diff, not invented). Read them in number
+order to watch the codebase — and the language features it reaches for — accrete.
+
+## The honesty rule
+
+Not every PR is about Rust. Some are the landing page, some are docs, one is a
+ten-line deletion. Those are labeled plainly and teach whatever they *do* contain
+(release engineering, project hygiene, doc-as-contract) instead of a fabricated Rust
+concept. A teaching series that admits "no lesson here" is more trustworthy than one
+that forces thirty-one. Non-Rust entries are marked ◦ below.
+
+## The lessons
+
+| PR | Lesson | The one-line takeaway |
+|----|--------|-----------------------|
+| [#16](16-supervised-app-with-logs.md) | `Arc<Mutex<T>>` + `tokio::spawn` | A detached task must *own* what it touches (`'static`); clone an `Arc` to share state, a `Mutex` to mutate it safely. |
+| [#17](17-inject-port-into-child-env.md) | `Command` env injection | `Command` is a builder that inherits the parent env by default; `.env(k, v)` layers one variable on before `.spawn()`. |
+| [#19](19-optional-fields-with-serde.md) | `Option<T>` + serde `Deserialize` | `Option<T>` is how a field says "may be absent"; serde fills a missing `Option` with `None` for you. |
+| [#22](22-serialize-wire-dto-contract.md) | serde `Serialize` + wire DTOs | Emit public JSON through dedicated DTO types — derive when the shape matches, hand-write `impl Serialize` to pin an exact contract. |
+| [#24](24-single-flight-boot-gate.md) | Single-flight with a per-key lock | Boot a resource once under concurrent demand: a short map lock hands out a per-name lock, held across the boot while the rest re-check. |
+| [#29](29-deadlines-and-failure-enums.md) | Timeouts + custom error enums | Bound async work with `tokio::time::timeout` and a `deadline: Instant`; model *why* a wait ended as an enum. |
+| [#34](34-fix-landing-page-redirect.md) ◦ | Client-side redirects | How a `<meta http-equiv="refresh">` redirect works, and why the `/` in `adj.ac/ent` is a load-bearing path boundary. |
+| [#36](36-docs-as-config-contract.md) ◦ | Docs as the config contract | No Rust — but the ecosystem's answer to doc rot is doctests: `cargo test` runs the `rust` examples in your doc comments. |
+| [#37](37-signals-bypass-drop-cleanup.md) | Signals bypass `Drop` | A signal-killed process skips destructors, so external cleanup (unlink a socket) must happen in a `tokio::signal` handler. |
+| [#38](38-deterministic-async-tests.md) | Deterministic async tests | Assert on observable state you can count, never on timing — and a still-flaky test is a real race, not noise. |
+| [#40](40-serve-https-local-ca.md) | Generics + trait bounds | One `serve_plain<S>` loop, monomorphized per stream type, drives both TCP and TLS at zero runtime cost. |
+| [#41](41-raw-string-templated-doc.md) | Raw strings + `format!` | `r#"…"#` bakes a whole doc into the binary verbatim; `format!`'s `{name}` capture splices in the dynamic bits. |
+| [#43](43-trait-as-extension-point.md) | Implementing a library trait (+ FFI) | Impl rcgen's `RemoteKeyPair` so signing calls out to the Keychain — the CA key never enters process memory. |
+| [#45](45-iterator-map-collect-rows.md) | `iter().map().collect()` | Turn one collection into another with a lazy pipeline that does nothing until `collect` drives it. |
+| [#46](46-revamp-landing-positioning-page.md) ◦ | Repo layout + dual licensing | The web frontend lives *outside* the Cargo `members` list so `cargo build` never sees it; `MIT OR Apache-2.0` is the ecosystem default. |
+| [#47](47-integration-tests-separate-crate.md) | Integration test layout | Each file in `tests/` is its own crate touching only the public API; a binary-only crate drives itself via `CARGO_BIN_EXE_adj`. |
+| [#48](48-warn-dont-swallow-errors.md) | Don't swallow the `Err` | `.unwrap_or(default)` throws the error away; `.unwrap_or_else(\|err\| …)` hands it to you to surface first. |
+| [#49](49-parse-dont-validate-actionable-errors.md) | Parse, don't validate | Push the check into the parser so a bad value can't exist downstream — and spend a line making the `Err` tell the user what to do. |
+| [#50](50-weak-refs-self-cleaning-map.md) | `Weak` refs + `HashMap::retain` | Store `Weak` values so a map garbage-collects itself; `retain` sweeps the dead entries in one in-place pass. |
+| [#51](51-typed-http-header-values.md) | Typed headers as newtypes | A `HeaderValue` is a validated byte-string, not a `String`; fallible construction is how the type blocks header injection. |
+| [#52](52-abort-detached-tokio-tasks.md) | Task cancellation | Dropping a `JoinHandle` *detaches* the task; hold it and `.abort()` — ideally from a `Drop` guard so it fires on every path. |
+| [#53](53-http-upgrade-stream-splicing.md) | HTTP upgrades + `copy_bidirectional` | An `Upgrade` trades HTTP framing for the raw stream; claim it with `hyper::upgrade::on`, then splice both halves. |
+| [#55](55-races-beyond-the-borrow-checker.md) | Races the borrow checker can't catch | `Send`/`Sync` kill in-process *data* races; a TOCTOU race over a port or file is still entirely on you. |
+| [#56](56-split-once-structured-keys.md) | `str::split_once` | Cut a string at the first delimiter into two borrowed `&str` slices, returning `Option` so "no delimiter" is a case, not a bug. |
+| [#60](60-compile-time-version-stamping.md) | `build.rs` + `env!`/`option_env!` | A build script emits `cargo:rustc-env=…` before compile; `env!`/`option_env!` bake those into the binary as `&'static str`. |
+| [#63](63-what-clippy-teaches.md) | What clippy teaches | Each lint names an idiom or a footgun; the honest reply is adopt it or `#[allow]` it *with a reason*. |
+| [#65](65-health-files-and-metadata.md) ◦ | OSS hygiene + crates.io metadata | No Rust — the crates.io analog of `.github/` health files is `Cargo.toml` package metadata (`keywords`, `categories`, `rust-version`). |
+| [#68](68-lean-agent-docs.md) ◦ | Sometimes there's no lesson | A ten-line docs deletion. The honest move is to say so — that's the series' principle in action. |
+| [#69](69-distributing-a-rust-cli.md) ◦ | Distributing a Rust CLI | Homebrew tap (prebuilt, no toolchain) vs `cargo install` (compiles to `~/.cargo/bin`) vs a raw tarball — who eats the complexity. |
+| [#75](75-hand-render-config-to-disk.md) | Generating a config file | Hand-render human-editable TOML so comments survive; write with `std::fs::write` behind a `!path.exists()` guard so you never clobber. |
+| [#76](76-derived-env-precedence-order.md) | Derived data + precedence order | Compute a namespace with `format!` into a `Vec<(k, v)>`; inject it last so `Command::env`'s last-writer-wins makes it win. |
+
+◦ = little or no Rust; labeled honestly and teaching what the PR does contain.
+
+## Reading paths by theme
+
+If you'd rather follow a thread than go in order:
+
+- **Shared state & async concurrency** — [#16](16-supervised-app-with-logs.md) → [#24](24-single-flight-boot-gate.md) → [#50](50-weak-refs-self-cleaning-map.md) → [#52](52-abort-detached-tokio-tasks.md) → [#55](55-races-beyond-the-borrow-checker.md)
+- **Error handling** — [#29](29-deadlines-and-failure-enums.md) → [#48](48-warn-dont-swallow-errors.md) → [#49](49-parse-dont-validate-actionable-errors.md)
+- **Traits & generics** — [#40](40-serve-https-local-ca.md) (bounds / static dispatch) → [#43](43-trait-as-extension-point.md) (impl / dynamic dispatch)
+- **Serde, config & data** — [#19](19-optional-fields-with-serde.md) → [#22](22-serialize-wire-dto-contract.md) → [#75](75-hand-render-config-to-disk.md) → [#76](76-derived-env-precedence-order.md)
+- **The proxy stack** — [#24](24-single-flight-boot-gate.md) → [#40](40-serve-https-local-ca.md) → [#51](51-typed-http-header-values.md) → [#53](53-http-upgrade-stream-splicing.md)
+- **Process lifecycle & env** — [#17](17-inject-port-into-child-env.md) → [#37](37-signals-bypass-drop-cleanup.md) → [#76](76-derived-env-precedence-order.md)
+- **Strings & slices** — [#41](41-raw-string-templated-doc.md) → [#45](45-iterator-map-collect-rows.md) → [#56](56-split-once-structured-keys.md)
+- **Testing** — [#38](38-deterministic-async-tests.md) → [#47](47-integration-tests-separate-crate.md) → [#55](55-races-beyond-the-borrow-checker.md)
+- **Tooling, ecosystem & distribution** — [#60](60-compile-time-version-stamping.md) → [#63](63-what-clippy-teaches.md) → [#65](65-health-files-and-metadata.md) → [#69](69-distributing-a-rust-cli.md)
+
+## Adding a lesson for a new PR
+
+1. Copy [`_TEMPLATE.md`](_TEMPLATE.md) to `docs/lessons/<PR-number>-<slug>.md` (slug = 3–5 kebab-case words from the title).
+2. Read the real diff (`gh pr diff <N>`) and pick the *single* most instructive concept it demonstrates. Verify the angle against the code — the diff wins over any preconception.
+3. Use real snippets from that diff, with the file path. Never invent code.
+4. If the PR has little or no Rust, say so plainly and teach what it does contain.
+5. Add a row to the table above (keep it in PR-number order) and, where it fits, a step on a themed reading path.
+
+### Where this is headed
+
+The intent is a canonical pattern: when a PR merges, its teaching plan gets posted as a
+comment on the PR itself, so the lesson lives next to the change that motivated it. These
+files are written to double as that comment — self-contained, and postable as-is with
+`gh pr comment <N> --body-file docs/lessons/<N>-<slug>.md`.
diff --git a/docs/lessons/_TEMPLATE.md b/docs/lessons/_TEMPLATE.md
new file mode 100644
index 0000000..258a62b
--- /dev/null
+++ b/docs/lessons/_TEMPLATE.md
@@ -0,0 +1,44 @@
+<!--
+Lesson template. One file per merged PR: docs/lessons/<NN>-<slug>.md
+Goal: teach one practical Rust concept, grounded in real code this PR shipped.
+Keep it tight. Real snippets from the diff, not invented ones. Honest labels:
+if a PR has little or no Rust, say so and teach the tooling/ecosystem lesson instead.
+This file is also meant to be postable as a post-merge teaching comment on the PR itself.
+-->
+
+# PR #NN — <PR title>
+
+> **Rust lesson:** <one sentence — the single concept a reader should walk away with>
+> **Tags:** `concept-one` · `concept-two`
+> **Merged:** YYYY-MM-DD · +A/−D · [View PR](https://github.com/nonrational/adjacent/pull/NN)
+
+## The situation
+
+One or two sentences: what the PR set out to do, in plain terms. The practical
+problem that forced the Rust concept to show up.
+
+## The Rust idea
+
+Teach the concept. Assume the reader knows another language but is new to Rust.
+Explain *why* Rust works this way, not just the syntax.
+
+## In this PR
+
+Real code from the diff, with the file path. Walk through the lines that matter.
+
+```rust
+// crates/adj/src/<file>.rs
+<snippet lifted from the actual PR>
+```
+
+## Why it matters
+
+The trap this avoids, or what a non-Rust language would have let you get wrong.
+
+## Related lessons
+
+- PR #NN also leans on this.
+
+## Dig deeper
+
+- [The Rust Book, ch. N.N](https://doc.rust-lang.org/book/) — <chapter name>
diff --git a/docs/lessons/glossary.json b/docs/lessons/glossary.json
new file mode 100644
index 0000000..9e58ef2
--- /dev/null
+++ b/docs/lessons/glossary.json
@@ -0,0 +1,362 @@
+{
+  "ownership": {
+    "term": "ownership",
+    "aliases": [],
+    "short": "Every value has exactly one owner. When the owner goes out of scope the value is dropped and its memory freed. No garbage collector, no manual free().",
+    "why": "The single-owner rule is the root of Rust's memory safety, and the reason sharing, borrowing, and moving all have to be made explicit rather than assumed.",
+    "prereqs": [],
+    "link": { "label": "Rust Book 4.1", "url": "https://doc.rust-lang.org/book/ch04-01-what-is-ownership.html" }
+  },
+  "borrowing": {
+    "term": "borrowing",
+    "aliases": ["reference"],
+    "short": "Accessing a value through a reference (&T) without taking ownership. You can have many shared &T reads, or exactly one exclusive &mut T, but never both at once.",
+    "why": "Borrowing lets code use a value without moving it, and the one-writer-or-many-readers rule is what stops data races at compile time instead of in production.",
+    "prereqs": ["ownership"],
+    "link": { "label": "Rust Book 4.2", "url": "https://doc.rust-lang.org/book/ch04-02-references-and-borrowing.html" }
+  },
+  "move": {
+    "term": "move",
+    "aliases": ["move semantics"],
+    "short": "Assigning or passing a non-Copy value transfers ownership; the source can no longer be used. `move` on a closure forces it to take ownership of what it captures.",
+    "why": "A spawned task must own what it touches. `move` is how you hand ownership into a closure so it can outlive the function that created it.",
+    "prereqs": ["ownership"],
+    "link": { "label": "Rust Book 4.1", "url": "https://doc.rust-lang.org/book/ch04-01-what-is-ownership.html#variables-and-data-interacting-with-move" }
+  },
+  "lifetime": {
+    "term": "lifetime",
+    "aliases": [],
+    "short": "The span of code for which a reference stays valid. The compiler checks that no reference outlives the value it points at, sometimes with named annotations like 'a.",
+    "why": "Lifetimes are how Rust guarantees a reference can never dangle. Most are inferred; you only write them when the compiler can't tell which input a returned reference came from.",
+    "prereqs": ["borrowing"],
+    "link": { "label": "Rust Book 10.3", "url": "https://doc.rust-lang.org/book/ch10-03-lifetime-syntax.html" }
+  },
+  "static-lifetime": {
+    "term": "'static",
+    "aliases": ["'static"],
+    "short": "A lifetime meaning \"lives for the entire program.\" A value is 'static if it owns all its data (borrows nothing) or points at data baked into the binary.",
+    "why": "A task handed to a background executor must be 'static: it may outlive the function that spawned it, so it can't borrow anything on that function's stack.",
+    "prereqs": ["lifetime"],
+    "link": { "label": "Rust Book 10.3", "url": "https://doc.rust-lang.org/book/ch10-03-lifetime-syntax.html#the-static-lifetime" }
+  },
+  "send-sync": {
+    "term": "Send / Sync",
+    "aliases": ["Send", "Sync", "Send + Sync"],
+    "short": "Marker traits the compiler infers automatically: Send means a value can be moved to another thread; Sync means it can be shared by reference across threads.",
+    "why": "They are what let the compiler reject cross-thread data races before the program runs. Arc is Send + Sync; Rc is neither, which is why spawn rejects it.",
+    "prereqs": ["ownership"],
+    "link": { "label": "Rust Book 16.4", "url": "https://doc.rust-lang.org/book/ch16-04-extensible-concurrency-sync-and-send.html" }
+  },
+  "interior-mutability": {
+    "term": "interior mutability",
+    "aliases": ["interior mutability", "RefCell"],
+    "short": "A pattern where you mutate data through a shared (&T) reference, with a wrapper type (Cell, RefCell, Mutex) enforcing the borrow rules at runtime instead of compile time.",
+    "why": "Sometimes you genuinely need to mutate shared state; interior mutability moves the one-writer check to runtime so the compiler will allow it, and a Mutex is its thread-safe form.",
+    "prereqs": ["ownership", "borrowing"],
+    "link": { "label": "Rust Book 15.5", "url": "https://doc.rust-lang.org/book/ch15-05-interior-mutability.html" }
+  },
+  "reference-counting": {
+    "term": "reference counting",
+    "aliases": [],
+    "short": "Sharing ownership of one value among several owners by keeping a count of how many exist; the value is dropped when the last owner goes away. Rc for one thread, Arc across threads.",
+    "why": "It's the escape hatch for when a single owner isn't enough. The count is the trade you make: cheap clones that share, at the cost of a runtime counter and no compile-time single-owner guarantee.",
+    "prereqs": ["ownership"],
+    "link": { "label": "Rust Book 15.4", "url": "https://doc.rust-lang.org/book/ch15-04-rc.html" }
+  },
+  "rc": {
+    "term": "Rc<T>",
+    "aliases": ["Rc"],
+    "short": "A single-threaded reference-counted pointer. Cloning it bumps a non-atomic count and hands back another owner of the same value.",
+    "why": "Cheaper than Arc because the count isn't atomic, but that's exactly why it isn't Send: hand it to another thread and the compiler stops you. Reach for Arc when threads are involved.",
+    "prereqs": ["reference-counting", "send-sync"],
+    "link": { "label": "Rust Book 15.4", "url": "https://doc.rust-lang.org/book/ch15-04-rc.html" }
+  },
+  "arc": {
+    "term": "Arc<T>",
+    "aliases": ["Arc", "Arc<Mutex<T>>", "Arc<Mutex<Inner>>", "Arc<T>"],
+    "short": "Atomically reference-counted shared pointer. Cloning it bumps a thread-safe refcount and hands back a second owner of the same value, not a copy.",
+    "why": "Lets two threads or tasks own one value at once. It is how a detached task can touch state the spawner still holds. Wrap it around a Mutex when the shared value also needs mutation.",
+    "prereqs": ["reference-counting", "move", "send-sync"],
+    "link": { "label": "Rust Book 16.3", "url": "https://doc.rust-lang.org/book/ch16-03-shared-state.html" }
+  },
+  "weak": {
+    "term": "Weak<T>",
+    "aliases": ["Weak"],
+    "short": "A non-owning reference to an Arc/Rc value. It doesn't keep the value alive; upgrade() returns None once the last strong owner is gone.",
+    "why": "Breaks reference cycles that would otherwise leak, and lets a map hold entries that clean themselves up: store Weak values and the map can drop the dead ones.",
+    "prereqs": ["arc"],
+    "link": { "label": "Rust Book 15.6", "url": "https://doc.rust-lang.org/book/ch15-06-reference-cycles.html" }
+  },
+  "mutex": {
+    "term": "Mutex<T>",
+    "aliases": ["Mutex", "Mutex<T>"],
+    "short": "A lock guarding interior data so only one holder mutates at a time. tokio's async Mutex yields the task while waiting instead of blocking the whole thread.",
+    "why": "Shared ownership alone still races on writes. The Mutex is what makes the shared mutation safe, and the compiler won't let you reach the data without taking the lock first.",
+    "prereqs": ["interior-mutability", "send-sync"],
+    "link": { "label": "Rust Book 16.3", "url": "https://doc.rust-lang.org/book/ch16-03-shared-state.html" }
+  },
+  "async-await": {
+    "term": "async / .await",
+    "aliases": [".await", "async"],
+    "short": "async fn returns a future that does nothing until awaited; .await drives it and yields control back to the runtime while waiting, so one thread can juggle many tasks.",
+    "why": "It's cooperative concurrency: awaiting a slow I/O call frees the thread to run other tasks instead of blocking, which is how a single process can supervise many servers at once.",
+    "prereqs": [],
+    "link": { "label": "Rust Book 17.1", "url": "https://doc.rust-lang.org/book/ch17-01-futures-and-syntax.html" }
+  },
+  "tokio-spawn": {
+    "term": "tokio::spawn",
+    "aliases": ["tokio::spawn"],
+    "short": "Hands a future to the tokio runtime to run concurrently, returning a JoinHandle. The task may run on any worker thread and may outlive the caller, so it must be 'static and Send.",
+    "why": "The go-to way to run work in the background. Its 'static + Send bounds are exactly why detached tasks reach for Arc<Mutex<T>> instead of borrowing the caller's state.",
+    "prereqs": ["async-await", "send-sync", "static-lifetime", "arc"],
+    "link": { "label": "tokio docs", "url": "https://docs.rs/tokio/latest/tokio/task/fn.spawn.html" }
+  },
+  "timeout": {
+    "term": "tokio::time::timeout",
+    "aliases": ["tokio::time::timeout"],
+    "short": "Wraps a future with a deadline; it resolves to Err once the duration elapses, cancelling the inner future.",
+    "why": "Bounds how long async work may take so a hung boot or a wedged health check turns into a clean, reportable failure instead of a task that waits forever.",
+    "prereqs": ["async-await", "result"],
+    "link": { "label": "tokio docs", "url": "https://docs.rs/tokio/latest/tokio/time/fn.timeout.html" }
+  },
+  "option": {
+    "term": "Option<T>",
+    "aliases": ["Option", "Option<T>", "Some", "None"],
+    "short": "An enum that is either Some(value) or None. Rust has no null; absence is a value you must handle, checked by the compiler.",
+    "why": "\"Might be missing\" becomes a case the type forces you to consider, so you can't accidentally use a value that isn't there. Serde fills a missing field with None for you.",
+    "prereqs": [],
+    "link": { "label": "Rust Book 6.1", "url": "https://doc.rust-lang.org/book/ch06-01-defining-an-enum.html#the-option-enum-and-its-advantages-over-null-values" }
+  },
+  "result": {
+    "term": "Result<T, E>",
+    "aliases": ["Result", "Result<T, E>", "Ok", "Err"],
+    "short": "An enum that is either Ok(value) or Err(error). Rust has no exceptions; a fallible operation returns its error as a value you must handle.",
+    "why": "Failure is in the type signature, so you can't ignore it by accident. How you handle the Err (surface it, default it, propagate it) becomes a deliberate choice at each call site.",
+    "prereqs": [],
+    "link": { "label": "Rust Book 9.2", "url": "https://doc.rust-lang.org/book/ch09-02-recoverable-errors-with-result.html" }
+  },
+  "question-mark": {
+    "term": "the ? operator",
+    "aliases": ["?"],
+    "short": "On a Result or Option, ? unwraps the Ok/Some value or early-returns the Err/None from the enclosing function. It replaces a match that would just propagate the error.",
+    "why": "Turns manual error-forwarding into one character, keeping the happy path readable while still handling every failure explicitly.",
+    "prereqs": ["result", "option"],
+    "link": { "label": "Rust Book 9.2", "url": "https://doc.rust-lang.org/book/ch09-02-recoverable-errors-with-result.html#a-shortcut-for-propagating-errors-the--operator" }
+  },
+  "combinators": {
+    "term": "combinators",
+    "aliases": [".ok()", "unwrap_or", "unwrap_or_else", "and_then", "as_deref"],
+    "short": "Methods on Option/Result that transform them without a match: map, and_then, ok, unwrap_or, unwrap_or_else, and friends. Each takes a closure or a default.",
+    "why": "They express \"do this if present, else that\" as a chain instead of a branch. The distinction matters: unwrap_or throws the error away, unwrap_or_else hands it to you first.",
+    "prereqs": ["option", "result", "closure"],
+    "link": { "label": "Option docs", "url": "https://doc.rust-lang.org/std/option/enum.Option.html" }
+  },
+  "match": {
+    "term": "match / if let",
+    "aliases": ["match", "if let"],
+    "short": "match compares a value against patterns and must cover every case; if let is the shorthand for when you only care about one pattern and ignore the rest.",
+    "why": "Exhaustive matching means adding a new enum variant makes the compiler point you at every place that must handle it, so \"forgot a case\" becomes a build error.",
+    "prereqs": ["option"],
+    "link": { "label": "Rust Book 6.2", "url": "https://doc.rust-lang.org/book/ch06-02-match.html" }
+  },
+  "closure": {
+    "term": "closure",
+    "aliases": ["closure"],
+    "short": "An anonymous function written with |args| body that can capture variables from its surrounding scope, by reference or (with move) by value.",
+    "why": "Closures are how you pass behavior around: a combinator's transform, a task's body, a Drop guard's cleanup. What they capture, and whether they move it, decides their lifetime.",
+    "prereqs": ["ownership"],
+    "link": { "label": "Rust Book 13.1", "url": "https://doc.rust-lang.org/book/ch13-01-closures.html" }
+  },
+  "iterator": {
+    "term": "iterator",
+    "aliases": ["Iterator", ".iter()", ".map()"],
+    "short": "A lazy sequence: .iter() and adapters like .map() build a pipeline that does no work until something drives it. Nothing is computed until you consume it.",
+    "why": "Laziness means you can chain transforms cheaply and only pay for what you actually take. The pipeline stays declarative; collect (or a for loop) is what makes it run.",
+    "prereqs": ["closure"],
+    "link": { "label": "Rust Book 13.2", "url": "https://doc.rust-lang.org/book/ch13-02-iterators.html" }
+  },
+  "collect": {
+    "term": "collect",
+    "aliases": [".collect()", "collect"],
+    "short": "Consumes an iterator and gathers its items into a collection (Vec, HashMap, String, ...). It's the driver that finally runs a lazy iterator pipeline.",
+    "why": "Turns one collection into another in a single expression, with the target type telling collect what to build. It's where a map/filter chain stops being lazy and produces a value.",
+    "prereqs": ["iterator"],
+    "link": { "label": "Iterator::collect", "url": "https://doc.rust-lang.org/std/iter/trait.Iterator.html#method.collect" }
+  },
+  "trait": {
+    "term": "trait",
+    "aliases": ["trait"],
+    "short": "A named set of methods a type can implement, like an interface. Code can then require \"any type that implements this trait\" rather than one concrete type.",
+    "why": "Traits are Rust's main tool for shared behavior and abstraction, and implementing a library's trait is how you plug your own type into that library's machinery.",
+    "prereqs": [],
+    "link": { "label": "Rust Book 10.2", "url": "https://doc.rust-lang.org/book/ch10-02-traits.html" }
+  },
+  "generics": {
+    "term": "generics",
+    "aliases": ["generic", "generics"],
+    "short": "Writing code over a type parameter (like T or S) instead of a concrete type, so one function or struct works for many types.",
+    "why": "Write the logic once and let the compiler specialize it per type. Combined with trait bounds, generics give you abstraction with no runtime cost.",
+    "prereqs": ["trait"],
+    "link": { "label": "Rust Book 10.1", "url": "https://doc.rust-lang.org/book/ch10-01-syntax.html" }
+  },
+  "trait-bound": {
+    "term": "trait bound",
+    "aliases": ["trait bound", "trait bounds"],
+    "short": "A constraint on a generic type, written like T: Display, saying \"T must implement this trait.\" It's what lets generic code actually call methods on T.",
+    "why": "The bound is the contract: it tells the compiler which methods are available on the type parameter, and tells callers which types they're allowed to pass.",
+    "prereqs": ["generics"],
+    "link": { "label": "Rust Book 10.2", "url": "https://doc.rust-lang.org/book/ch10-02-traits.html#traits-as-parameters" }
+  },
+  "static-dispatch": {
+    "term": "static dispatch",
+    "aliases": ["static dispatch"],
+    "short": "Resolving which concrete method to call at compile time. Generic code is monomorphized into a specialized copy per type, so calls are direct with no runtime lookup.",
+    "why": "It's abstraction for free: the generic loop over a stream type compiles down to the same machine code you'd have written by hand for each concrete type.",
+    "prereqs": ["generics", "monomorphization"],
+    "link": { "label": "Rust Book 17.2", "url": "https://doc.rust-lang.org/book/ch17-02-trait-objects.html#trait-objects-perform-dynamic-dispatch" }
+  },
+  "dynamic-dispatch": {
+    "term": "dynamic dispatch",
+    "aliases": ["dyn", "dynamic dispatch", "trait object"],
+    "short": "Resolving the method at runtime through a trait object (dyn Trait), which carries a pointer to the right implementation. One code path handles many types.",
+    "why": "Trades a tiny runtime indirection for flexibility: you can store different implementing types together or choose one at runtime, which generics can't do.",
+    "prereqs": ["trait"],
+    "link": { "label": "Rust Book 17.2", "url": "https://doc.rust-lang.org/book/ch17-02-trait-objects.html" }
+  },
+  "monomorphization": {
+    "term": "monomorphization",
+    "aliases": ["monomorphization", "monomorphized"],
+    "short": "The compiler's process of turning generic code into concrete code by stamping out a specialized copy for each type it's used with.",
+    "why": "It's why generics have zero runtime overhead: by the time the program runs, each generic use is just ordinary type-specific code. The cost is paid in compile time and binary size.",
+    "prereqs": ["generics"],
+    "link": { "label": "Rust Book 10.1", "url": "https://doc.rust-lang.org/book/ch10-01-syntax.html#performance-of-code-using-generics" }
+  },
+  "drop": {
+    "term": "Drop / RAII",
+    "aliases": ["Drop", "RAII"],
+    "short": "The Drop trait runs cleanup code automatically when a value goes out of scope. Tie a resource's release to a value's lifetime and you can't forget to free it.",
+    "why": "Files close, locks release, and guards fire without a manual step. The catch: a signal-killed process skips destructors, so external cleanup can't rely on Drop alone.",
+    "prereqs": ["ownership"],
+    "link": { "label": "Rust Book 15.3", "url": "https://doc.rust-lang.org/book/ch15-03-drop.html" }
+  },
+  "newtype": {
+    "term": "newtype pattern",
+    "aliases": ["newtype", "HeaderValue"],
+    "short": "Wrapping a value in a single-field struct to give it a distinct type, so a validated or domain-specific value can't be confused with a plain one.",
+    "why": "The wrapper is where you enforce an invariant once (a HeaderValue is a validated byte-string, not any String), and the type system carries that guarantee everywhere after.",
+    "prereqs": ["trait"],
+    "link": { "label": "Rust Book 19.3", "url": "https://doc.rust-lang.org/book/ch19-03-advanced-traits.html#using-the-newtype-pattern-to-implement-external-traits" }
+  },
+  "derive-macro": {
+    "term": "derive macro",
+    "aliases": ["derive", "#[derive(Deserialize)]", "#[derive(Serialize, Deserialize)]"],
+    "short": "A #[derive(...)] attribute that generates a trait implementation for your type at compile time, so you don't hand-write boilerplate impls.",
+    "why": "One line gives you the code for common traits (Debug, Clone, and serde's Serialize/Deserialize). You only hand-write the impl when the derived shape isn't exactly what you need.",
+    "prereqs": ["trait"],
+    "link": { "label": "Rust Book 19.5", "url": "https://doc.rust-lang.org/book/ch19-05-macros.html#how-to-write-a-custom-derive-macro" }
+  },
+  "serde": {
+    "term": "Serialize / Deserialize",
+    "aliases": ["Serialize", "Deserialize", "serde"],
+    "short": "serde's two traits for converting Rust values to and from formats like JSON or TOML. Usually derived; #[serde(...)] attributes tune field names, defaults, and shape.",
+    "why": "Deriving them on a dedicated DTO type pins your public wire format to a Rust type, so the contract lives in code and the compiler keeps the two in sync.",
+    "prereqs": ["derive-macro"],
+    "link": { "label": "serde.rs", "url": "https://serde.rs/derive.html" }
+  },
+  "unsafe-ffi": {
+    "term": "unsafe / FFI",
+    "aliases": ["unsafe", "FFI"],
+    "short": "unsafe marks code where you, not the compiler, uphold the safety rules, typically to call across a foreign function interface (FFI) into C or a system library.",
+    "why": "It's the escape hatch for things the borrow checker can't verify, like calling into the OS keychain. The unsafe block is a deliberate, auditable boundary, not a free-for-all.",
+    "prereqs": ["ownership"],
+    "link": { "label": "Rust Book 19.1", "url": "https://doc.rust-lang.org/book/ch19-01-unsafe-rust.html" }
+  },
+  "instant": {
+    "term": "Instant vs SystemTime",
+    "aliases": ["Instant", "SystemTime"],
+    "short": "Instant is a monotonic clock for measuring elapsed time; SystemTime is the wall clock that can jump backward when the OS adjusts it.",
+    "why": "For deadlines and timeouts you want Instant, because it never goes backward. Reach for SystemTime only when you need an actual calendar time.",
+    "prereqs": [],
+    "link": { "label": "std::time::Instant", "url": "https://doc.rust-lang.org/std/time/struct.Instant.html" }
+  },
+  "vec": {
+    "term": "Vec<T>",
+    "aliases": ["Vec", "Vec<T>"],
+    "short": "A growable, heap-allocated array of T. It owns its elements and frees them when it's dropped.",
+    "why": "The default owned collection. Building one with the vec![] macro or by collecting an iterator is the everyday way to hold a variable number of values.",
+    "prereqs": ["ownership"],
+    "link": { "label": "std::vec::Vec", "url": "https://doc.rust-lang.org/std/vec/struct.Vec.html" }
+  },
+  "hashmap": {
+    "term": "HashMap<K, V>",
+    "aliases": ["HashMap"],
+    "short": "A hash-table mapping owned keys to owned values, with average O(1) insert and lookup.",
+    "why": "The standard key-value store. It owns what you put in it, and methods like retain let you edit it in place without rebuilding it.",
+    "prereqs": ["ownership"],
+    "link": { "label": "std::collections::HashMap", "url": "https://doc.rust-lang.org/std/collections/struct.HashMap.html" }
+  },
+  "hashmap-retain": {
+    "term": "HashMap::retain",
+    "aliases": ["HashMap::retain", "retain"],
+    "short": "Keeps only the entries for which a closure returns true, removing the rest in one in-place pass over the map.",
+    "why": "The idiomatic way to garbage-collect a map (for example, dropping entries whose Weak value has expired) without allocating a new one or iterating twice.",
+    "prereqs": ["closure", "hashmap"],
+    "link": { "label": "HashMap::retain", "url": "https://doc.rust-lang.org/std/collections/struct.HashMap.html#method.retain" }
+  },
+  "str-vs-string": {
+    "term": "&str vs String",
+    "aliases": ["String", "&str"],
+    "short": "String is an owned, growable UTF-8 buffer; &str is a borrowed view into one (or into a string literal). String owns, &str borrows.",
+    "why": "The distinction is ownership again: take &str in function arguments to borrow without allocating, and return String when the caller needs to own the result.",
+    "prereqs": ["ownership", "borrowing"],
+    "link": { "label": "Rust Book 8.2", "url": "https://doc.rust-lang.org/book/ch08-02-strings.html" }
+  },
+  "split-once": {
+    "term": "str::split_once",
+    "aliases": ["split_once", "str::split_once"],
+    "short": "Cuts a string at the first occurrence of a delimiter into two borrowed &str slices, returning Option so \"delimiter not found\" is a None case, not a panic.",
+    "why": "Exactly right for parsing key=value or label.name: you get both halves as borrows of the original, and the Option makes the missing-delimiter case something you handle, not a bug.",
+    "prereqs": ["option", "str-vs-string"],
+    "link": { "label": "str::split_once", "url": "https://doc.rust-lang.org/std/primitive.str.html#method.split_once" }
+  },
+  "format-macro": {
+    "term": "format!",
+    "aliases": ["format!"],
+    "short": "Builds a new String from a template, filling {} placeholders with values. {name} captures a variable of that name directly from scope.",
+    "why": "The everyday way to assemble strings. Its inline-capture form keeps templated text readable, and it's how derived data like a URL or an env value gets composed.",
+    "prereqs": ["str-vs-string"],
+    "link": { "label": "std::format!", "url": "https://doc.rust-lang.org/std/macro.format.html" }
+  },
+  "build-rs": {
+    "term": "build.rs",
+    "aliases": ["build.rs"],
+    "short": "A build script: Rust code the compiler runs before compiling your crate. Printing cargo:rustc-env=KEY=VALUE injects a value the crate can read at compile time.",
+    "why": "It's how compile-time facts (a git SHA, a build timestamp) get baked into the binary, so the program can report exactly which build it is without any runtime lookup.",
+    "prereqs": [],
+    "link": { "label": "Cargo Book", "url": "https://doc.rust-lang.org/cargo/reference/build-scripts.html" }
+  },
+  "env-macro": {
+    "term": "env! / option_env!",
+    "aliases": ["env!", "option_env!"],
+    "short": "Compile-time macros that read an environment variable and bake it into the binary as a &'static str. env! fails the build if it's unset; option_env! yields an Option instead.",
+    "why": "Paired with build.rs, they turn build-time environment values into constants compiled into the program, so there's nothing to read or fail at runtime.",
+    "prereqs": ["build-rs", "static-lifetime"],
+    "link": { "label": "std::env!", "url": "https://doc.rust-lang.org/std/macro.env.html" }
+  },
+  "include-str": {
+    "term": "include_str!",
+    "aliases": ["include_str!"],
+    "short": "A macro that reads a file at compile time and embeds its contents into the binary as a &'static str.",
+    "why": "Bakes a whole document (a template, a help text) into the executable, so it ships as one self-contained file with nothing to load from disk at runtime.",
+    "prereqs": ["static-lifetime"],
+    "link": { "label": "std::include_str!", "url": "https://doc.rust-lang.org/std/macro.include_str.html" }
+  },
+  "command": {
+    "term": "Command",
+    "aliases": ["Command"],
+    "short": "The builder for spawning a child process: chain .env(), .arg(), .stdout() to configure it, then .spawn(). It inherits the parent's environment by default.",
+    "why": "A textbook builder pattern, and the surface where a supervisor injects a child's port and environment before starting it, one .env() layer at a time.",
+    "prereqs": [],
+    "link": { "label": "std::process::Command", "url": "https://doc.rust-lang.org/std/process/struct.Command.html" }
+  }
+}
diff --git a/docs/superpowers/lessons-generator-landmines.md b/docs/superpowers/lessons-generator-landmines.md
new file mode 100644
index 0000000..e2cea32
--- /dev/null
+++ b/docs/superpowers/lessons-generator-landmines.md
@@ -0,0 +1,74 @@
+# Landmines: building the lessons generator (and the skill that extracts it)
+
+Hard-won gotchas from building `ent/lessons/build.mjs` and its interactive site. Read
+before touching the generator or extracting the `lessons-from-prs` / site-build skills
+(see `docs/superpowers/specs/2026-07-12-lessons-from-prs-skill-design.md`). Each one cost
+a real debugging loop; none is obvious from the code alone.
+
+## 1. The `\u0000` → NUL-byte trap (the expensive one)
+
+Writing a literal `\u0000` escape in **any Write/Edit tool content** JSON-decodes to a
+real NUL (`0x00`) byte on disk. Git then treats the file as **binary**: no line diff, no
+`git blame`, `grep -n` reports "binary file matches" instead of line numbers. On a shared
+file that every task builds on, this compounds fast.
+
+- The engine deliberately builds its placeholder sentinel with `String.fromCharCode(0)`
+  at runtime, so the **source stays pure ASCII** (commit `026cdfc`). Never reintroduce a
+  literal `\u0000` into `build.mjs` via a tool.
+- After any edit to `build.mjs`, verify: `tr -cd '\000' < ent/lessons/build.mjs | wc -c`
+  must print `0`, and `file ent/lessons/build.mjs` must say "text", not "data".
+- To emit bytes a tool keeps mangling, generate the file with a Python script using
+  `chr(...)` and raw strings, then verify and install. Several fixes this session landed
+  that way because the edit tools could not represent the bytes directly.
+
+## 2. Test against REAL repo content, not just synthetic fixtures
+
+The plan's hand-written fixtures passed while real corpus data broke. Every parser/
+renderer needs a real-content check, not only unit fixtures:
+
+- **Wrapped list items** — bullets/numbered items that wrap across source lines were
+  truncated, leaking the remainder into a stray `<p>` (found only against real lessons;
+  commit `19160b5`). ~half the lessons wrap.
+- **GFM table-cell pipe escapes** — a table cell escapes a literal pipe as `\|`; the raw
+  backslashes leaked into a rendered takeaway (`.unwrap_or_else(\|err\|)`; commit
+  `2b9e314`).
+- **Real header formats** — em-dash titles and a Unicode minus (`−`, U+2212) in the
+  `+A/−D` delta; synthetic fixtures used ASCII. `parseLesson` was verified against all 31
+  real lessons before it was trusted.
+
+Lesson: for any new repo the skill targets, run the renderer/parser over that repo's
+actual lessons and eyeball the output before believing green unit tests.
+
+## 3. Browser verification can't be skipped, and Node tests can't replace it
+
+The drawer's real behavior is browser-side. A Node presence-test (assert the emitted JS
+contains a click handler) cannot catch layout, z-index, or pointer-events bugs.
+
+- The Chrome extension was offline one session, so the drawer went unverified by
+  automation — and a real bug shipped: the **closed `.drawer-scrim`** (`opacity: 0` but
+  `position: fixed; inset: 0; z-index: 10`) swallowed every click, because `opacity: 0`
+  does **not** disable pointer events. Fixed with `pointer-events: none` until `.open`
+  (commit `3ebd523`). A human live-click caught it.
+- Always include an explicit manual step: serve the site, click a term, walk a prereq
+  chip, press Esc. `python3 -m http.server <port>` from the repo root works (avoid 8080 —
+  that's the `adj` daemon). If the browser automation extension is connected, drive it;
+  otherwise say so and ask for a human pass.
+
+## 4. Escaping context: text vs attribute
+
+HTML-emitting helpers must distinguish text-node escaping (`& < >`) from attribute-value
+escaping (adds `"`). The browser-side drawer `esc()` initially escaped only `& < >` but
+filled double-quoted attributes (`data-term="…"`, `href="…"`); a `"` in a glossary key or
+URL would break out. It now also escapes `"` (commit `fff4e41`). The server-side pair is
+`escapeHtml` (text) vs `escapeAttr` (attributes) — mirror that split anywhere you build
+markup as strings.
+
+## 5. Portability scrub is load-bearing (for the extracted skill)
+
+`~/.claude` is a **public** repo, so any skill extracted from this work is a published
+artifact. Per `~/.dotfiles/.claude/rules/skill-authoring.md`, no project-specific
+identifier may survive into the skill: scrub `adjacent`, `adj.ac`, `nonrational`,
+`d4a574`, `ent/lessons`, and Rust-as-the-only-language into a neutral invented example.
+Gate before done: `grep -rniE '<project nouns>' <skill-dir>` returns only neutral
+examples. The engine/theme seam exists so all repo-specific values live in one `THEME`
+object, not scattered through the engine.
diff --git a/docs/superpowers/plans/2026-07-11-interactive-lessons.md b/docs/superpowers/plans/2026-07-11-interactive-lessons.md
new file mode 100644
index 0000000..3b6479d
--- /dev/null
+++ b/docs/superpowers/plans/2026-07-11-interactive-lessons.md
@@ -0,0 +1,1385 @@
+# Interactive Lessons Surface Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Generate an interactive HTML page per Rust lesson under `ent/lessons/`, where backticked foundational terms are clickable and open a side panel with a definition, a why-it-matters line, and clickable one-level prerequisite chains.
+
+**Architecture:** A single dependency-free Node ESM generator, `ent/lessons/build.mjs`, parses `docs/lessons/*.md` (the single source of truth) plus `docs/lessons/glossary.json`, and emits static HTML pages, an index, and shared assets (`lessons.css`, `drawer.js`, `glossary.js`) into `ent/lessons/`. The generator is written as a neutral engine plus a thin `THEME` object at the top of the file, so the eventual reusable skill swaps the theme without touching the engine. Pure render/parse functions are unit-tested with Node's built-in test runner; the browser drawer is verified manually.
+
+**Tech Stack:** Node.js 26.2.0 (ESM, built-ins only: `node:fs`, `node:path`, `node:url`, `node:test`, `node:assert`). No npm packages. Plain HTML/CSS/JS output. `just` recipes for build + serve.
+
+## Global Constraints
+
+- **Node 26.2.0**, pinned in `.tool-versions`. Use only Node built-in modules. **Zero npm dependencies** — `ent/` stays dependency-free and outside the Cargo workspace.
+- **Never modify any `docs/lessons/*.md` file.** The markdown is the single source of truth; the site is generated *from* it.
+- **Never modify `ent/index.html`.** The landing page is out of scope; only read it for the palette.
+- Every generated output file begins with `<!-- generated by build.mjs; edit docs/lessons/*.md -->` (HTML) or `/* generated by build.mjs; edit docs/lessons/*.md */` (CSS/JS).
+- Generated files **are committed** (so `ent/` stays directly serveable). Regeneration diffs are expected in review.
+- All Adjacent-specific values (palette `#d4a574` etc., the `adj.ac/ent` wordmark, paths) live **only** in the `THEME` object. Engine functions take theme/glossary as parameters and carry no hard-coded Adjacent identifiers. (The portable-tooling "no project identifiers" rule applies to the *future* extracted skill, not to this v1; v1's identifiers are confined to `THEME`.)
+- Dark-only styling, reusing `ent/index.html`'s palette.
+- **Commit messages:** plain, descriptive, **no** Conventional-Commit prefixes (`feat:`/`fix:` are forbidden). Append the session's `Co-Authored-By` and `Claude-Session` trailers to each commit. Stage explicit paths (`git add <path>`), never `git commit -a`.
+- Run the generator and tests from the **repo root** (`node ent/lessons/build.mjs`, `node --test ent/lessons/`); paths resolve against `process.cwd()`.
+- `import.meta.main` guards `main()` so importing `build.mjs` in tests has no side effects.
+
+---
+
+### Task 1: Inline markdown renderer
+
+The smallest engine primitive: turn a run of inline markdown text into HTML. Handles inline code, links (rewriting `NN-slug.md` cross-links to `.html`), bold, and italic, with correct HTML escaping. Accepts an optional glossary index whose behavior is exercised in Task 4; here it defaults to unused.
+
+**Files:**
+- Create: `ent/lessons/build.mjs`
+- Test: `ent/lessons/build.test.mjs`
+
+**Interfaces:**
+- Consumes: nothing (first task).
+- Produces:
+  - `escapeHtml(s: string): string` — escapes `& < >`.
+  - `escapeAttr(s: string): string` — escapes `& < > "`.
+  - `renderInline(text: string, opts?: { glossaryIndex?: Map<string,string> }): string` — inline markdown to HTML.
+
+- [ ] **Step 1: Write the failing test**
+
+Create `ent/lessons/build.test.mjs`:
+
+```js
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { escapeHtml, escapeAttr, renderInline } from './build.mjs';
+
+test('escapeHtml escapes angle brackets and ampersands', () => {
+  assert.equal(escapeHtml('a < b & c > d'), 'a &lt; b &amp; c &gt; d');
+});
+
+test('escapeAttr also escapes double quotes', () => {
+  assert.equal(escapeAttr('say "hi" & <go>'), 'say &quot;hi&quot; &amp; &lt;go&gt;');
+});
+
+test('renderInline: inline code is escaped and wrapped in <code>', () => {
+  assert.equal(renderInline('use `Vec<T>` here'), 'use <code>Vec&lt;T&gt;</code> here');
+});
+
+test('renderInline: bold and italic', () => {
+  assert.equal(renderInline('**bold** and *soft*'), '<strong>bold</strong> and <em>soft</em>');
+});
+
+test('renderInline: content inside inline code is not treated as bold/italic', () => {
+  assert.equal(renderInline('`a * b * c`'), '<code>a * b * c</code>');
+});
+
+test('renderInline: external link passes through', () => {
+  assert.equal(
+    renderInline('[View PR](https://example.com/pull/16)'),
+    '<a href="https://example.com/pull/16">View PR</a>',
+  );
+});
+
+test('renderInline: cross-lesson .md link is rewritten to .html', () => {
+  assert.equal(
+    renderInline('[PR #40](40-serve-https-local-ca.md)'),
+    '<a href="40-serve-https-local-ca.html">PR #40</a>',
+  );
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `node --test ent/lessons/build.test.mjs`
+Expected: FAIL — `Cannot find module './build.mjs'` (or "export not found").
+
+- [ ] **Step 3: Write minimal implementation**
+
+Create `ent/lessons/build.mjs`:
+
+```js
+// Dependency-free generator for the interactive Rust lessons site.
+// Reads docs/lessons/*.md (source of truth) + docs/lessons/glossary.json,
+// emits static HTML + shared assets into ent/lessons/. Run from repo root.
+
+export function escapeHtml(s) {
+  return String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+
+export function escapeAttr(s) {
+  return escapeHtml(s).replace(/"/g, '&quot;');
+}
+
+// Render one run of inline markdown. Inline code is extracted first so its
+// contents are never reinterpreted as emphasis; links are extracted before
+// escaping so their hrefs stay clean. A glossary index (alias -> key), when
+// supplied, turns a matching code span into a clickable term button (Task 4).
+export function renderInline(text, { glossaryIndex } = {}) {
+  const slots = [];
+  // NUL-delimited placeholders: NUL never appears in lesson prose, so restoring
+  // stashed HTML can never collide with real text.
+  const stash = (html) => { slots.push(html); return `\u0000${slots.length - 1}\u0000`; };
+
+  let s = String(text).replace(/`([^`]+)`/g, (_, code) => {
+    const inner = `<code>${escapeHtml(code)}</code>`;
+    const key = glossaryIndex && glossaryIndex.get(code);
+    return stash(
+      key
+        ? `<button type="button" class="term" data-term="${escapeAttr(key)}">${inner}</button>`
+        : inner,
+    );
+  });
+
+  s = s.replace(/\[([^\]]+)\]\(([^)]+)\)/g, (_, label, href) => {
+    const h = /^\d+-[a-z0-9-]+\.md$/.test(href) ? href.replace(/\.md$/, '.html') : href;
+    return stash(`<a href="${escapeAttr(h)}">${renderInline(label, { glossaryIndex })}</a>`);
+  });
+
+  s = escapeHtml(s)
+    .replace(/\*\*([^*]+)\*\*/g, '<strong>$1</strong>')
+    .replace(/\*([^*]+)\*/g, '<em>$1</em>');
+
+  return s.replace(/\u0000(\d+)\u0000/g, (_, i) => slots[Number(i)]);
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `node --test ent/lessons/build.test.mjs`
+Expected: PASS — 7 passing, 0 failing.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add ent/lessons/build.mjs ent/lessons/build.test.mjs
+git commit -m "Add inline markdown renderer for the lessons generator"
+```
+
+---
+
+### Task 2: Block markdown renderer
+
+Turns a lesson body (headings, paragraphs, fenced code, lists) into HTML, delegating inline runs to `renderInline`. Fenced code content is literal: it is escaped, never inline-rendered, and never annotated. Supports one level of nested unordered lists (only #65 uses it) and ordered lists (used by 7 lessons).
+
+**Files:**
+- Modify: `ent/lessons/build.mjs`
+- Test: `ent/lessons/build.test.mjs`
+
+**Interfaces:**
+- Consumes: `renderInline`, `escapeHtml` (Task 1).
+- Produces: `renderMarkdown(body: string, opts?: { glossaryIndex?: Map<string,string> }): string` — block markdown to HTML.
+
+- [ ] **Step 1: Write the failing test**
+
+Append to `ent/lessons/build.test.mjs`:
+
+```js
+import { renderMarkdown } from './build.mjs';
+
+test('renderMarkdown: heading levels', () => {
+  assert.equal(renderMarkdown('## The Rust idea'), '<h2>The Rust idea</h2>');
+  assert.equal(renderMarkdown('### Where this is headed'), '<h3>Where this is headed</h3>');
+});
+
+test('renderMarkdown: paragraph joins wrapped lines and renders inline', () => {
+  assert.equal(
+    renderMarkdown('Clone an `Arc`\nto share it.'),
+    '<p>Clone an <code>Arc</code> to share it.</p>',
+  );
+});
+
+test('renderMarkdown: fenced code is literal, escaped, not inline-rendered', () => {
+  const md = '```rust\nlet x: Vec<u8> = *ptr; // **not bold**\n```';
+  assert.equal(
+    renderMarkdown(md),
+    '<pre><code class="language-rust">let x: Vec&lt;u8&gt; = *ptr; // **not bold**\n</code></pre>',
+  );
+});
+
+test('renderMarkdown: unordered list with one nested level', () => {
+  const md = '- top one\n- top two\n  - nested a';
+  assert.equal(
+    renderMarkdown(md),
+    '<ul><li>top one</li><li>top two<ul><li>nested a</li></ul></li></ul>',
+  );
+});
+
+test('renderMarkdown: ordered list', () => {
+  assert.equal(renderMarkdown('1. first\n2. second'), '<ol><li>first</li><li>second</li></ol>');
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `node --test ent/lessons/build.test.mjs`
+Expected: FAIL — `renderMarkdown` is not exported.
+
+- [ ] **Step 3: Write minimal implementation**
+
+Append to `ent/lessons/build.mjs`:
+
+```js
+// Block-level renderer for the bounded markdown the lessons use: ATX headings,
+// paragraphs, fenced code (literal), and unordered/ordered lists with one nesting
+// level. Blockquotes are handled by parseLesson (the header) and do not appear in
+// bodies, so they are intentionally unsupported here.
+export function renderMarkdown(body, { glossaryIndex } = {}) {
+  const lines = String(body).replace(/\r\n/g, '\n').split('\n');
+  const out = [];
+  let i = 0;
+
+  const listItemHtml = (text) => renderInline(text, { glossaryIndex });
+
+  while (i < lines.length) {
+    const line = lines[i];
+
+    if (/^```/.test(line)) {
+      const lang = line.slice(3).trim();
+      const buf = [];
+      i++;
+      while (i < lines.length && !/^```/.test(lines[i])) buf.push(lines[i++]);
+      i++; // consume closing fence
+      const cls = lang ? ` class="language-${escapeAttr(lang)}"` : '';
+      out.push(`<pre><code${cls}>${escapeHtml(buf.join('\n') + '\n')}</code></pre>`);
+      continue;
+    }
+
+    const heading = line.match(/^(#{1,3})\s+(.*)$/);
+    if (heading) {
+      const level = heading[1].length;
+      out.push(`<h${level}>${renderInline(heading[2].trim(), { glossaryIndex })}</h${level}>`);
+      i++;
+      continue;
+    }
+
+    if (/^\s*([-*]|\d+\.)\s+/.test(line)) {
+      const ordered = /^\s*\d+\.\s+/.test(line);
+      const tag = ordered ? 'ol' : 'ul';
+      const items = [];
+      while (i < lines.length && /^\s*([-*]|\d+\.)\s+/.test(lines[i])) {
+        const m = lines[i].match(/^(\s*)([-*]|\d+\.)\s+(.*)$/);
+        const indented = m[1].length >= 2;
+        const text = listItemHtml(m[3]);
+        if (indented && items.length) {
+          const last = items.length - 1;
+          items[last] = items[last].replace(/<\/li>$/, '') + `<ul><li>${text}</li></ul></li>`;
+        } else {
+          items.push(`<li>${text}</li>`);
+        }
+        i++;
+      }
+      out.push(`<${tag}>${items.join('')}</${tag}>`);
+      continue;
+    }
+
+    if (line.trim() === '') {
+      i++;
+      continue;
+    }
+
+    const para = [];
+    while (i < lines.length && lines[i].trim() !== '' && !/^(#{1,3}\s|```|\s*([-*]|\d+\.)\s)/.test(lines[i])) {
+      para.push(lines[i]);
+      i++;
+    }
+    out.push(`<p>${renderInline(para.join(' ').replace(/\s+/g, ' ').trim(), { glossaryIndex })}</p>`);
+  }
+
+  return out.join('');
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `node --test ent/lessons/build.test.mjs`
+Expected: PASS — 12 passing, 0 failing.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add ent/lessons/build.mjs ent/lessons/build.test.mjs
+git commit -m "Add block markdown renderer for the lessons generator"
+```
+
+---
+
+### Task 3: Lesson parser
+
+Splits a lesson file into structured metadata (PR number, slug, title, the headline lesson sentence, tags, merged info) and the body markdown. This is the contract between the fixed lesson template and every downstream renderer.
+
+**Files:**
+- Modify: `ent/lessons/build.mjs`
+- Test: `ent/lessons/build.test.mjs`
+
+**Interfaces:**
+- Consumes: nothing new.
+- Produces: `parseLesson(filename: string, md: string): { pr: number, slug: string, title: string, lesson: string, tags: string[], merged: { date: string, delta: string, url: string }, bodyMarkdown: string }`.
+
+- [ ] **Step 1: Write the failing test**
+
+Append to `ent/lessons/build.test.mjs`:
+
+```js
+import { parseLesson } from './build.mjs';
+
+const SAMPLE = `<!-- Lesson for PR #16. Teaches one concept. -->
+
+# PR #16 — Tracer: supervised app with logs
+
+> **Rust lesson:** Hand the task an \`Arc<Mutex<T>>\` clone.
+> **Tags:** \`Arc<Mutex<T>>\` · \`tokio::spawn\`
+> **Merged:** 2026-06-08 · +2369/−0 · [View PR](https://github.com/nonrational/adjacent/pull/16)
+
+## The situation
+
+First paragraph.
+`;
+
+test('parseLesson extracts pr, slug, and title', () => {
+  const p = parseLesson('16-supervised-app-with-logs.md', SAMPLE);
+  assert.equal(p.pr, 16);
+  assert.equal(p.slug, 'supervised-app-with-logs');
+  assert.equal(p.title, 'PR #16 — Tracer: supervised app with logs');
+});
+
+test('parseLesson extracts the lesson sentence and tags', () => {
+  const p = parseLesson('16-supervised-app-with-logs.md', SAMPLE);
+  assert.equal(p.lesson, 'Hand the task an `Arc<Mutex<T>>` clone.');
+  assert.deepEqual(p.tags, ['Arc<Mutex<T>>', 'tokio::spawn']);
+});
+
+test('parseLesson extracts merged date, delta, and url', () => {
+  const p = parseLesson('16-supervised-app-with-logs.md', SAMPLE);
+  assert.equal(p.merged.date, '2026-06-08');
+  assert.equal(p.merged.delta, '+2369/−0');
+  assert.equal(p.merged.url, 'https://github.com/nonrational/adjacent/pull/16');
+});
+
+test('parseLesson body starts after the blockquote header', () => {
+  const p = parseLesson('16-supervised-app-with-logs.md', SAMPLE);
+  assert.ok(p.bodyMarkdown.startsWith('## The situation'));
+  assert.ok(!p.bodyMarkdown.includes('Rust lesson:'));
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `node --test ent/lessons/build.test.mjs`
+Expected: FAIL — `parseLesson` is not exported.
+
+- [ ] **Step 3: Write minimal implementation**
+
+Append to `ent/lessons/build.mjs`:
+
+```js
+// Parse a lesson file of the fixed template shape into structured parts.
+export function parseLesson(filename, md) {
+  const fm = filename.match(/^(\d+)-([a-z0-9-]+)\.md$/);
+  if (!fm) throw new Error(`not a lesson filename: ${filename}`);
+  const pr = Number(fm[1]);
+  const slug = fm[2];
+
+  let rest = String(md).replace(/^/, '').replace(/^<!--[\s\S]*?-->\s*/, '');
+
+  const titleMatch = rest.match(/^#\s+(.*)\n?/);
+  const title = titleMatch ? titleMatch[1].trim() : '';
+  if (titleMatch) rest = rest.slice(titleMatch[0].length);
+
+  const lines = rest.split('\n');
+  let i = 0;
+  while (i < lines.length && lines[i].trim() === '') i++;
+  const quote = [];
+  while (i < lines.length && lines[i].startsWith('>')) {
+    quote.push(lines[i].replace(/^>\s?/, ''));
+    i++;
+  }
+  const bodyMarkdown = lines.slice(i).join('\n').trim();
+
+  const field = (label) => (quote.find((l) => l.startsWith(`**${label}:**`)) || '')
+    .replace(new RegExp(`^\\*\\*${label}:\\*\\*\\s*`), '')
+    .trim();
+
+  const lesson = field('Rust lesson');
+  const tags = field('Tags').split('·').map((t) => t.replace(/`/g, '').trim()).filter(Boolean);
+  const mergedRaw = field('Merged');
+  const mm = mergedRaw.match(/^([0-9-]+)\s*·\s*(.+?)\s*·\s*\[[^\]]*\]\(([^)]+)\)/);
+  const merged = mm
+    ? { date: mm[1].trim(), delta: mm[2].trim(), url: mm[3].trim() }
+    : { date: '', delta: '', url: '' };
+
+  return { pr, slug, title, lesson, tags, merged, bodyMarkdown };
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `node --test ent/lessons/build.test.mjs`
+Expected: PASS — 16 passing, 0 failing.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add ent/lessons/build.mjs ent/lessons/build.test.mjs
+git commit -m "Add lesson parser for the fixed lesson template"
+```
+
+---
+
+### Task 4: Glossary loading, validation, index, coverage, and term annotation
+
+Adds the glossary layer: load/validate the JSON, build the alias→key index, report backticked terms missing from the glossary, and (by feeding the index into `renderInline`) make matching code spans clickable. Creates a small but real seed `glossary.json`; Task 9 expands it to the full set.
+
+**Files:**
+- Create: `docs/lessons/glossary.json`
+- Modify: `ent/lessons/build.mjs`
+- Test: `ent/lessons/build.test.mjs`
+
+**Interfaces:**
+- Consumes: `renderInline` (Task 1), `parseLesson` (Task 3).
+- Produces:
+  - `validateGlossary(glossary: object): { errors: string[], warnings: string[] }`
+  - `buildGlossaryIndex(glossary: object): Map<string,string>` — every term and alias maps to its key.
+  - `coverageReport(lessons: ParsedLesson[], glossaryIndex: Map<string,string>): { term: string, count: number }[]` — backticked terms (outside fenced code) absent from the glossary, most frequent first.
+
+- [ ] **Step 1: Write the failing test**
+
+Append to `ent/lessons/build.test.mjs`:
+
+```js
+import { validateGlossary, buildGlossaryIndex, coverageReport } from './build.mjs';
+
+const GLOSSARY = {
+  arc: { term: 'Arc<T>', aliases: ['Arc', 'Arc<Mutex<T>>'], short: 's', why: 'w', prereqs: ['ownership'], link: { label: 'x', url: 'y' } },
+  ownership: { term: 'ownership', aliases: [], short: 's', why: 'w', prereqs: [], link: { label: 'x', url: 'y' } },
+};
+
+test('validateGlossary: clean glossary has no errors', () => {
+  assert.deepEqual(validateGlossary(GLOSSARY).errors, []);
+});
+
+test('validateGlossary: dangling prereq is an error', () => {
+  const bad = { arc: { term: 'Arc<T>', aliases: [], prereqs: ['nope'] } };
+  assert.equal(validateGlossary(bad).errors.length, 1);
+  assert.match(validateGlossary(bad).errors[0], /nope/);
+});
+
+test('validateGlossary: duplicate alias across entries is an error', () => {
+  const bad = {
+    a: { term: 'A', aliases: ['shared'], prereqs: [] },
+    b: { term: 'B', aliases: ['shared'], prereqs: [] },
+  };
+  assert.match(validateGlossary(bad).errors[0], /shared/);
+});
+
+test('buildGlossaryIndex maps every term and alias to its key', () => {
+  const idx = buildGlossaryIndex(GLOSSARY);
+  assert.equal(idx.get('Arc'), 'arc');
+  assert.equal(idx.get('Arc<Mutex<T>>'), 'arc');
+  assert.equal(idx.get('Arc<T>'), 'arc');
+  assert.equal(idx.get('ownership'), 'ownership');
+});
+
+test('renderInline wraps a glossary-matched code span as a term button', () => {
+  const idx = buildGlossaryIndex(GLOSSARY);
+  assert.equal(
+    renderInline('use `Arc` now', { glossaryIndex: idx }),
+    'use <button type="button" class="term" data-term="arc"><code>Arc</code></button> now',
+  );
+});
+
+test('coverageReport lists backticked terms missing from the glossary, not those present', () => {
+  const idx = buildGlossaryIndex(GLOSSARY);
+  const lessons = [{ bodyMarkdown: 'see `Arc` and `Weak`\n```rust\n`Mutex` in code\n```' }];
+  const rep = coverageReport(lessons, idx);
+  assert.deepEqual(rep, [{ term: 'Weak', count: 1 }]);
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `node --test ent/lessons/build.test.mjs`
+Expected: FAIL — `validateGlossary` not exported.
+
+- [ ] **Step 3: Write minimal implementation**
+
+Append to `ent/lessons/build.mjs`:
+
+```js
+// Every prereq must resolve to a real entry; every alias/term must be unique
+// across entries (an ambiguous alias could not annotate deterministically).
+export function validateGlossary(glossary) {
+  const errors = [];
+  const warnings = [];
+  const keys = new Set(Object.keys(glossary));
+  const seen = new Map();
+  for (const [key, e] of Object.entries(glossary)) {
+    for (const p of e.prereqs || []) {
+      if (!keys.has(p)) errors.push(`entry '${key}': prereq '${p}' has no glossary entry`);
+    }
+    for (const name of [e.term, ...(e.aliases || [])]) {
+      if (!name) continue;
+      if (seen.has(name) && seen.get(name) !== key) {
+        errors.push(`alias '${name}' maps to both '${seen.get(name)}' and '${key}'`);
+      } else {
+        seen.set(name, key);
+      }
+    }
+  }
+  return { errors, warnings };
+}
+
+export function buildGlossaryIndex(glossary) {
+  const idx = new Map();
+  for (const [key, e] of Object.entries(glossary)) {
+    for (const name of [e.term, ...(e.aliases || [])]) {
+      if (name) idx.set(name, key);
+    }
+  }
+  return idx;
+}
+
+export function coverageReport(lessons, glossaryIndex) {
+  const counts = new Map();
+  for (const l of lessons) {
+    const noFences = String(l.bodyMarkdown).replace(/```[\s\S]*?```/g, '');
+    for (const m of noFences.matchAll(/`([^`]+)`/g)) {
+      const t = m[1];
+      if (!glossaryIndex.has(t)) counts.set(t, (counts.get(t) || 0) + 1);
+    }
+  }
+  return [...counts.entries()]
+    .map(([term, count]) => ({ term, count }))
+    .sort((a, b) => b.count - a.count || a.term.localeCompare(b.term));
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `node --test ent/lessons/build.test.mjs`
+Expected: PASS — 22 passing, 0 failing.
+
+- [ ] **Step 5: Create the seed glossary**
+
+Create `docs/lessons/glossary.json` with real entries for PR #16's terms (expanded in Task 9):
+
+```json
+{
+  "arc": {
+    "term": "Arc<T>",
+    "aliases": ["Arc", "Arc<Mutex<T>>", "Arc<Mutex<Inner>>"],
+    "short": "Atomically reference-counted shared pointer. Cloning it bumps a refcount and hands back a second owner of the same value, not a copy.",
+    "why": "Lets two threads or tasks own one value at once. It is how a detached task can touch state the spawner still holds.",
+    "prereqs": ["ownership", "move", "send-sync"],
+    "link": { "label": "Rust Book 16.3", "url": "https://doc.rust-lang.org/book/ch16-03-shared-state.html" }
+  },
+  "mutex": {
+    "term": "Mutex<T>",
+    "aliases": ["Mutex"],
+    "short": "A lock guarding interior data so only one holder mutates at a time. tokio's async Mutex yields the thread while waiting instead of blocking it.",
+    "why": "Shared ownership alone still races on writes. The Mutex is what makes the shared mutation safe, checked at compile time.",
+    "prereqs": ["ownership", "send-sync"],
+    "link": { "label": "Rust Book 16.3", "url": "https://doc.rust-lang.org/book/ch16-03-shared-state.html" }
+  },
+  "ownership": {
+    "term": "ownership",
+    "aliases": [],
+    "short": "Every value has exactly one owner; when the owner goes out of scope the value is dropped. No garbage collector, no manual free.",
+    "why": "The single-owner rule is the root of Rust's memory safety and the reason sharing has to be made explicit.",
+    "prereqs": [],
+    "link": { "label": "Rust Book 4.1", "url": "https://doc.rust-lang.org/book/ch04-01-what-is-ownership.html" }
+  },
+  "move": {
+    "term": "move",
+    "aliases": ["move semantics"],
+    "short": "Assigning or passing a non-Copy value transfers ownership; the source can no longer be used. `move` on a closure forces it to own its captures.",
+    "why": "A spawned task must own what it touches. `move` is how you hand ownership into it so it can outlive the caller.",
+    "prereqs": ["ownership"],
+    "link": { "label": "Rust Book 4.1", "url": "https://doc.rust-lang.org/book/ch04-01-what-is-ownership.html#variables-and-data-interacting-with-move" }
+  },
+  "send-sync": {
+    "term": "Send / Sync",
+    "aliases": ["Send", "Sync", "Send + Sync"],
+    "short": "Marker traits the compiler infers: Send means a value can move to another thread; Sync means it can be shared by reference across threads.",
+    "why": "They are what let the compiler reject data races before the program runs. Arc is Send/Sync; Rc is not.",
+    "prereqs": ["ownership"],
+    "link": { "label": "Rust Book 16.4", "url": "https://doc.rust-lang.org/book/ch16-04-extensible-concurrency-sync-and-send.html" }
+  }
+}
+```
+
+- [ ] **Step 6: Verify the seed glossary validates**
+
+Run:
+```bash
+node -e "import('./ent/lessons/build.mjs').then(m => { const g = JSON.parse(require('fs').readFileSync('docs/lessons/glossary.json')); console.log(m.validateGlossary(g)); })"
+```
+Expected: `{ errors: [], warnings: [] }`.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add ent/lessons/build.mjs ent/lessons/build.test.mjs docs/lessons/glossary.json
+git commit -m "Add glossary loading, validation, index, coverage, and term annotation"
+```
+
+---
+
+### Task 5: Lesson page template and shared static assets
+
+Pure render functions that produce a full lesson HTML page and the shared assets (`lessons.css` from the theme palette, `glossary.js` from the glossary data). No file writes yet — those live in `main()` (Task 8), so these stay unit-testable.
+
+**Files:**
+- Modify: `ent/lessons/build.mjs`
+- Test: `ent/lessons/build.test.mjs`
+
+**Interfaces:**
+- Consumes: `renderMarkdown`, `renderInline`, `buildGlossaryIndex`, `escapeHtml`, `escapeAttr`.
+- Produces:
+  - `THEME` (object) — palette, font, wordmark, siteTitle, repoUrl, paths.
+  - `renderTagChips(tags: string[], glossaryIndex: Map<string,string>): string`
+  - `renderLessonPage(parsed, opts: { glossaryIndex: Map<string,string>, theme?: object }): string`
+  - `renderStylesheet(theme?: object): string`
+  - `renderGlossaryScript(glossary: object): string`
+
+- [ ] **Step 1: Write the failing test**
+
+Append to `ent/lessons/build.test.mjs`:
+
+```js
+import {
+  THEME, renderTagChips, renderLessonPage, renderStylesheet, renderGlossaryScript,
+} from './build.mjs';
+
+const PARSED = {
+  pr: 16, slug: 'supervised-app-with-logs',
+  title: 'PR #16 — Tracer: supervised app with logs',
+  lesson: 'Hand the task an `Arc<Mutex<T>>` clone.',
+  tags: ['Arc<Mutex<T>>', 'tokio::spawn'],
+  merged: { date: '2026-06-08', delta: '+2369/−0', url: 'https://github.com/nonrational/adjacent/pull/16' },
+  bodyMarkdown: '## The situation\n\nBoot it with an `Arc`.',
+};
+const IDX = buildGlossaryIndex({
+  arc: { term: 'Arc<T>', aliases: ['Arc', 'Arc<Mutex<T>>'], prereqs: [] },
+});
+
+test('renderTagChips: a glossary tag becomes a term button, others plain', () => {
+  const html = renderTagChips(['Arc<Mutex<T>>', 'tokio::spawn'], IDX);
+  assert.match(html, /data-term="arc"[^>]*>[^<]*<code>Arc&lt;Mutex&lt;T&gt;&gt;<\/code>/);
+  assert.match(html, /tokio::spawn/);
+});
+
+test('renderLessonPage: full document with provenance header and asset links', () => {
+  const html = renderLessonPage(PARSED, { glossaryIndex: IDX });
+  assert.ok(html.startsWith('<!-- generated by build.mjs'));
+  assert.match(html, /<!DOCTYPE html>/);
+  assert.match(html, /<link rel="stylesheet" href="lessons\.css">/);
+  assert.match(html, /<script src="glossary\.js"><\/script>/);
+  assert.match(html, /<script src="drawer\.js" defer><\/script>/);
+  assert.match(html, /PR #16 — Tracer: supervised app with logs/);
+  // A body code span that matches the glossary is annotated.
+  assert.match(html, /data-term="arc"><code>Arc<\/code>/);
+});
+
+test('renderStylesheet: emits the theme accent as a CSS custom property', () => {
+  assert.match(renderStylesheet(), /--accent:\s*#d4a574/);
+});
+
+test('renderGlossaryScript: assigns the glossary to a global', () => {
+  const js = renderGlossaryScript({ arc: { term: 'Arc<T>' } });
+  assert.match(js, /window\.__GLOSSARY__ = /);
+  assert.match(js, /"Arc<T>"/);
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `node --test ent/lessons/build.test.mjs`
+Expected: FAIL — `THEME`/`renderLessonPage` not exported.
+
+- [ ] **Step 3: Write minimal implementation**
+
+Append to `ent/lessons/build.mjs`. The `THEME` object is the sole home of Adjacent-specific values (the extraction seam):
+
+```js
+// ---- Theme + config (the repo-specific seam; swap this to retarget) ----
+export const THEME = {
+  name: 'adjacent',
+  palette: {
+    ink: '#0a0a0a', paper: '#ededea', soft: '#b5b5af', dim: '#7a7a74',
+    rule: '#1f1f1d', accent: '#d4a574', accentDim: '#8a6a44',
+  },
+  fontLinks: [
+    '<link rel="preconnect" href="https://fonts.googleapis.com">',
+    '<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>',
+    '<link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@300;400;500;700&display=swap" rel="stylesheet">',
+  ].join('\n  '),
+  fontStack: "'JetBrains Mono', ui-monospace, SFMono-Regular, Menlo, monospace",
+  wordmark: { a: 'adj.ac', slash: '/', b: 'ent' },
+  siteTitle: 'adj.ac/ent — Rust, one PR at a time',
+  repoUrl: 'https://github.com/nonrational/adjacent',
+  paths: { lessonsDir: 'docs/lessons', readme: 'docs/lessons/README.md', outDir: 'ent/lessons' },
+};
+
+const HTML_HEADER = '<!-- generated by build.mjs; edit docs/lessons/*.md -->';
+const ASSET_HEADER = '/* generated by build.mjs; edit docs/lessons/*.md */';
+
+export function renderTagChips(tags, glossaryIndex) {
+  return tags
+    .map((t) => {
+      const key = glossaryIndex.get(t);
+      const code = `<code>${escapeHtml(t)}</code>`;
+      return key
+        ? `<button type="button" class="term tag" data-term="${escapeAttr(key)}">${code}</button>`
+        : `<span class="tag">${code}</span>`;
+    })
+    .join('');
+}
+
+export function renderLessonPage(parsed, { glossaryIndex, theme = THEME }) {
+  const { a, slash, b } = theme.wordmark;
+  const body = renderMarkdown(parsed.bodyMarkdown, { glossaryIndex });
+  const lesson = renderInline(parsed.lesson, { glossaryIndex });
+  const chips = renderTagChips(parsed.tags, glossaryIndex);
+  const prLink = parsed.merged.url
+    ? `<a href="${escapeAttr(parsed.merged.url)}">View PR</a>`
+    : '';
+  return `${HTML_HEADER}
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${escapeHtml(parsed.title)}</title>
+  ${theme.fontLinks}
+  <link rel="stylesheet" href="lessons.css">
+</head>
+<body>
+  <div class="frame">
+    <header>
+      <a class="wordmark" href="index.html"><span class="a">${a}</span><span class="slash">${slash}</span><span class="b">${b}</span></a>
+      <a class="back" href="index.html">all lessons</a>
+    </header>
+    <article>
+      <h1>${escapeHtml(parsed.title)}</h1>
+      <div class="lesson-header">
+        <p class="lesson">${lesson}</p>
+        <p class="tags">${chips}</p>
+        <p class="meta">${escapeHtml(parsed.merged.date)} · ${escapeHtml(parsed.merged.delta)} · ${prLink}</p>
+      </div>
+      ${body}
+    </article>
+  </div>
+  <script src="glossary.js"></script>
+  <script src="drawer.js" defer></script>
+</body>
+</html>
+`;
+}
+
+export function renderStylesheet(theme = THEME) {
+  const p = theme.palette;
+  return `${ASSET_HEADER}
+:root {
+  --ink: ${p.ink}; --paper: ${p.paper}; --soft: ${p.soft}; --dim: ${p.dim};
+  --rule: ${p.rule}; --accent: ${p.accent}; --accent-dim: ${p.accentDim};
+}
+* { box-sizing: border-box; margin: 0; padding: 0; }
+html, body { background: var(--ink); color: var(--paper); font-family: ${theme.fontStack}; font-size: 15px; line-height: 1.65; -webkit-font-smoothing: antialiased; }
+body { min-height: 100vh; padding: 3rem clamp(1.25rem, 6vw, 5rem); }
+.frame { max-width: 760px; margin: 0 auto; }
+header { display: flex; justify-content: space-between; align-items: baseline; margin-bottom: 3rem; }
+.wordmark { font-weight: 700; font-size: 1.1rem; letter-spacing: -0.03em; text-decoration: none; }
+.wordmark .a { color: var(--paper); } .wordmark .b { color: var(--accent); } .wordmark .slash { color: var(--rule); font-weight: 300; margin: 0 0.1em; }
+.back { font-size: 12px; color: var(--dim); text-transform: uppercase; letter-spacing: 0.1em; text-decoration: none; border-bottom: 1px dotted var(--dim); }
+.back:hover { color: var(--accent); border-color: var(--accent); }
+article h1 { font-size: clamp(1.6rem, 4vw, 2.3rem); font-weight: 700; letter-spacing: -0.02em; line-height: 1.15; margin-bottom: 1.5rem; }
+.lesson-header { border-left: 2px solid var(--accent-dim); padding-left: 1.1rem; margin-bottom: 2.5rem; }
+.lesson-header .lesson { font-size: 1.15rem; font-weight: 300; margin-bottom: 0.75rem; }
+.lesson-header .tags { display: flex; flex-wrap: wrap; gap: 0.4rem; margin-bottom: 0.6rem; }
+.lesson-header .meta { font-size: 12px; color: var(--dim); letter-spacing: 0.04em; }
+article h2 { font-size: 1.25rem; margin: 2.5rem 0 1rem; padding-top: 1.25rem; border-top: 1px solid var(--rule); }
+article h3 { font-size: 1.05rem; margin: 1.75rem 0 0.75rem; }
+article p { margin-bottom: 1rem; color: var(--paper); }
+article ul, article ol { margin: 0 0 1rem 1.4rem; }
+article li { margin-bottom: 0.35rem; }
+article a { color: var(--paper); text-decoration: none; border-bottom: 1px solid var(--accent-dim); }
+article a:hover { color: var(--accent); border-color: var(--accent); }
+code { font-family: inherit; color: var(--accent); font-size: 0.95em; }
+pre { background: rgba(255,255,255,0.02); border: 1px solid var(--rule); border-left: 2px solid var(--accent-dim); padding: 1rem 1.15rem; margin-bottom: 1.25rem; overflow-x: auto; }
+pre code { color: var(--paper); font-size: 13px; line-height: 1.5; }
+.term { font: inherit; background: none; border: none; padding: 0; cursor: pointer; border-bottom: 1px dotted var(--accent); }
+.term:hover, .term:focus-visible { background: rgba(212,165,116,0.1); }
+.tag code { font-size: 0.85em; }
+span.tag { border-bottom: 1px dotted var(--rule); }
+/* Drawer (built by drawer.js) */
+.drawer-scrim { position: fixed; inset: 0; background: rgba(0,0,0,0.4); opacity: 0; transition: opacity 0.15s; z-index: 10; }
+.drawer-scrim.open { opacity: 1; }
+.drawer { position: fixed; top: 0; right: 0; height: 100%; width: min(360px, 90vw); background: var(--ink); border-left: 1px solid var(--rule); transform: translateX(100%); transition: transform 0.18s ease-out; z-index: 11; padding: 1.75rem 1.5rem; overflow-y: auto; }
+.drawer.open { transform: none; }
+.drawer .close { position: absolute; top: 1rem; right: 1.1rem; background: none; border: none; color: var(--dim); font: inherit; font-size: 1.2rem; cursor: pointer; }
+.drawer .close:hover { color: var(--accent); }
+.drawer .back-link { background: none; border: none; color: var(--dim); font: inherit; font-size: 12px; letter-spacing: 0.08em; text-transform: uppercase; cursor: pointer; margin-bottom: 1rem; display: none; }
+.drawer.has-history .back-link { display: inline-block; }
+.drawer .d-term { color: var(--accent); font-weight: 700; font-size: 1.1rem; margin-bottom: 0.9rem; word-break: break-word; }
+.drawer .d-label { font-size: 11px; letter-spacing: 0.16em; text-transform: uppercase; color: var(--dim); margin: 1.2rem 0 0.4rem; }
+.drawer .d-short, .drawer .d-why { color: var(--paper); font-size: 0.95rem; }
+.drawer .d-prereqs { display: flex; flex-wrap: wrap; gap: 0.4rem; }
+.drawer .d-prereqs .term { border: 1px solid var(--accent-dim); border-radius: 2px; padding: 0.2rem 0.55rem; }
+.drawer .d-link a { color: var(--accent); font-size: 0.9rem; }
+@media (max-width: 540px) { body { padding: 2rem 1.1rem; } }
+`;
+}
+
+export function renderGlossaryScript(glossary) {
+  return `${ASSET_HEADER}\nwindow.__GLOSSARY__ = ${JSON.stringify(glossary, null, 0)};\n`;
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `node --test ent/lessons/build.test.mjs`
+Expected: PASS — 27 passing, 0 failing.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add ent/lessons/build.mjs ent/lessons/build.test.mjs
+git commit -m "Add lesson page template and themed shared assets"
+```
+
+---
+
+### Task 6: The drawer interaction (`drawer.js`)
+
+The browser-side behavior: clicking a `.term` opens the side panel with the glossary entry, prereq chips descend into their own entries with a back affordance, and Esc / scrim / close button dismiss it. This is a static JS string constant emitted by the generator; because its behavior is browser-side, it is verified by driving the page, not by a Node unit test.
+
+**Files:**
+- Modify: `ent/lessons/build.mjs`
+- Test: `ent/lessons/build.test.mjs` (presence check only)
+
+**Interfaces:**
+- Consumes: `window.__GLOSSARY__` (from `glossary.js`), `.term[data-term]` buttons (from the page).
+- Produces: `DRAWER_JS` (string constant) and `renderDrawerScript(): string`.
+
+- [ ] **Step 1: Write the failing test**
+
+Append to `ent/lessons/build.test.mjs`:
+
+```js
+import { renderDrawerScript } from './build.mjs';
+
+test('renderDrawerScript emits provenance header and wires term clicks', () => {
+  const js = renderDrawerScript();
+  assert.ok(js.startsWith('/* generated by build.mjs'));
+  assert.match(js, /addEventListener\('click'/);
+  assert.match(js, /__GLOSSARY__/);
+  assert.match(js, /Escape/);
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `node --test ent/lessons/build.test.mjs`
+Expected: FAIL — `renderDrawerScript` not exported.
+
+- [ ] **Step 3: Write minimal implementation**
+
+Append to `ent/lessons/build.mjs`:
+
+```js
+// Browser-side drawer. Built as a string so the generator can emit it verbatim.
+// Progressive enhancement: with JS off, .term buttons are inert and the lesson
+// stays fully readable.
+const DRAWER_JS = String.raw`(() => {
+  const G = window.__GLOSSARY__ || {};
+  const scrim = document.createElement('div');
+  scrim.className = 'drawer-scrim';
+  const drawer = document.createElement('aside');
+  drawer.className = 'drawer';
+  drawer.setAttribute('role', 'dialog');
+  drawer.setAttribute('aria-label', 'Term explanation');
+  drawer.innerHTML =
+    '<button class="close" aria-label="Close">×</button>' +
+    '<button class="back-link">← back</button>' +
+    '<div class="d-body"></div>';
+  document.body.append(scrim, drawer);
+  const body = drawer.querySelector('.d-body');
+  const esc = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+  let history = [];
+
+  function render(key) {
+    const e = G[key];
+    if (!e) return;
+    const prereqs = (e.prereqs || [])
+      .filter((k) => G[k])
+      .map((k) => '<button type="button" class="term" data-term="' + esc(k) + '"><code>' + esc(G[k].term) + '</code></button>')
+      .join('');
+    const link = e.link ? '<p class="d-label">Dig deeper</p><p class="d-link"><a href="' + esc(e.link.url) + '" target="_blank" rel="noopener">' + esc(e.link.label) + '</a></p>' : '';
+    body.innerHTML =
+      '<p class="d-term">' + esc(e.term) + '</p>' +
+      '<p class="d-short">' + esc(e.short || '') + '</p>' +
+      (e.why ? '<p class="d-label">Why it matters</p><p class="d-why">' + esc(e.why) + '</p>' : '') +
+      (prereqs ? '<p class="d-label">Learn first</p><div class="d-prereqs">' + prereqs + '</div>' : '') +
+      link;
+    // Back is shown only once we've descended past the root term.
+    drawer.classList.toggle('has-history', history.length > 1);
+  }
+
+  function open(key) {
+    history = [key];
+    render(key);
+    scrim.classList.add('open');
+    drawer.classList.add('open');
+  }
+  function close() {
+    scrim.classList.remove('open');
+    drawer.classList.remove('open');
+    history = [];
+    drawer.classList.remove('has-history');
+  }
+
+  document.addEventListener('click', (ev) => {
+    const term = ev.target.closest('.term');
+    if (term && term.dataset.term) {
+      ev.preventDefault();
+      if (ev.target.closest('.drawer')) {
+        history.push(term.dataset.term); // descend into a prereq
+        render(term.dataset.term);
+      } else {
+        open(term.dataset.term);         // open from the lesson prose
+      }
+      return;
+    }
+    if (ev.target.closest('.drawer .close')) { close(); }
+  });
+  drawer.querySelector('.back-link').addEventListener('click', () => {
+    history.pop();
+    const prev = history[history.length - 1];
+    if (prev) { render(prev); } else { close(); }
+  });
+  scrim.addEventListener('click', close);
+  document.addEventListener('keydown', (ev) => { if (ev.key === 'Escape') close(); });
+})();
+`;
+
+export function renderDrawerScript() {
+  return `${ASSET_HEADER}\n${DRAWER_JS}`;
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `node --test ent/lessons/build.test.mjs`
+Expected: PASS — 28 passing, 0 failing.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add ent/lessons/build.mjs ent/lessons/build.test.mjs
+git commit -m "Add browser-side drawer interaction for term annotations"
+```
+
+(Browser verification of the drawer happens in Task 8 once `main()` can emit a real page.)
+
+---
+
+### Task 7: Index page from README
+
+Parse `README.md`'s lesson table and reading-path lists (targeted regex, same known-structure approach as the lesson parser) into `index.html`, preserving the curated takeaways, the ◦ honesty markers, and the themed reading paths.
+
+**Files:**
+- Modify: `ent/lessons/build.mjs`
+- Test: `ent/lessons/build.test.mjs`
+
+**Interfaces:**
+- Consumes: `renderInline`, `escapeHtml`, `THEME`.
+- Produces: `parseReadmeIndex(readmeMd: string): { rows: { pr: number, href: string, lesson: string, takeaway: string, sparse: boolean }[], paths: { theme: string, html: string }[] }` and `renderIndexPage(readmeMd: string, opts?: { theme?: object }): string`.
+
+- [ ] **Step 1: Write the failing test**
+
+Append to `ent/lessons/build.test.mjs`:
+
+```js
+import { parseReadmeIndex, renderIndexPage } from './build.mjs';
+
+const README = `# Rust, one PR at a time
+
+Intro prose.
+
+## The lessons
+
+| PR | Lesson | The one-line takeaway |
+|----|--------|-----------------------|
+| [#16](16-supervised-app-with-logs.md) | \`Arc<Mutex<T>>\` + \`tokio::spawn\` | Clone an \`Arc\` to share. |
+| [#34](34-fix-landing-page-redirect.md) ◦ | Client-side redirects | How a meta refresh works. |
+
+◦ = little or no Rust.
+
+## Reading paths by theme
+
+- **Error handling** — [#29](29-deadlines-and-failure-enums.md) → [#48](48-warn-dont-swallow-errors.md)
+`;
+
+test('parseReadmeIndex extracts rows including the sparse marker', () => {
+  const { rows } = parseReadmeIndex(README);
+  assert.equal(rows.length, 2);
+  assert.equal(rows[0].pr, 16);
+  assert.equal(rows[0].href, '16-supervised-app-with-logs.html');
+  assert.equal(rows[0].sparse, false);
+  assert.equal(rows[1].sparse, true);
+});
+
+test('parseReadmeIndex extracts reading paths', () => {
+  const { paths } = parseReadmeIndex(README);
+  assert.equal(paths.length, 1);
+  assert.match(paths[0].theme, /Error handling/);
+  assert.match(paths[0].html, /29-deadlines-and-failure-enums\.html/);
+});
+
+test('renderIndexPage produces a document linking to lesson pages', () => {
+  const html = renderIndexPage(README);
+  assert.ok(html.startsWith('<!-- generated by build.mjs'));
+  assert.match(html, /href="16-supervised-app-with-logs\.html"/);
+  assert.match(html, /<link rel="stylesheet" href="lessons\.css">/);
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `node --test ent/lessons/build.test.mjs`
+Expected: FAIL — `parseReadmeIndex` not exported.
+
+- [ ] **Step 3: Write minimal implementation**
+
+Append to `ent/lessons/build.mjs`:
+
+```js
+export function parseReadmeIndex(readmeMd) {
+  const rows = [];
+  const rowRe = /^\|\s*\[#(\d+)\]\(([^)]+)\)\s*(◦)?\s*\|\s*(.+?)\s*\|\s*(.+?)\s*\|$/gm;
+  for (const m of readmeMd.matchAll(rowRe)) {
+    rows.push({
+      pr: Number(m[1]),
+      href: m[2].replace(/\.md$/, '.html'),
+      sparse: Boolean(m[3]),
+      lesson: m[4],
+      takeaway: m[5],
+    });
+  }
+  const paths = [];
+  const pathRe = /^-\s+\*\*(.+?)\*\*\s+—\s+(.+)$/gm;
+  for (const m of readmeMd.matchAll(pathRe)) {
+    paths.push({ theme: m[1], html: renderInline(m[2]) });
+  }
+  return { rows, paths };
+}
+
+export function renderIndexPage(readmeMd, { theme = THEME } = {}) {
+  const { rows, paths } = parseReadmeIndex(readmeMd);
+  const { a, slash, b } = theme.wordmark;
+  const rowHtml = rows
+    .map((r) => `<tr${r.sparse ? ' class="sparse"' : ''}><td class="pr"><a href="${escapeAttr(r.href)}">#${r.pr}</a>${r.sparse ? ' <span class="mark">◦</span>' : ''}</td><td>${renderInline(r.lesson)}</td><td class="takeaway">${renderInline(r.takeaway)}</td></tr>`)
+    .join('\n      ');
+  const pathHtml = paths
+    .map((p) => `<li><strong>${escapeHtml(p.theme)}</strong> — ${p.html}</li>`)
+    .join('\n      ');
+  return `${HTML_HEADER}
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${escapeHtml(theme.siteTitle)}</title>
+  ${theme.fontLinks}
+  <link rel="stylesheet" href="lessons.css">
+</head>
+<body>
+  <div class="frame">
+    <header>
+      <a class="wordmark" href="${escapeAttr(theme.repoUrl)}"><span class="a">${a}</span><span class="slash">${slash}</span><span class="b">${b}</span></a>
+      <span class="back">Rust, one PR at a time</span>
+    </header>
+    <article>
+      <h1>Rust, one PR at a time</h1>
+      <table class="index">
+      ${rowHtml}
+      </table>
+      <h2>Reading paths by theme</h2>
+      <ul>
+      ${pathHtml}
+      </ul>
+    </article>
+  </div>
+</body>
+</html>
+`;
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `node --test ent/lessons/build.test.mjs`
+Expected: PASS — 31 passing, 0 failing.
+
+- [ ] **Step 5: Add index table styling**
+
+In `renderStylesheet`, before the drawer comment, append these rules to the returned string (add inside the template literal):
+
+```css
+table.index { width: 100%; border-collapse: collapse; margin-bottom: 2.5rem; font-size: 0.9rem; }
+table.index td { border-bottom: 1px solid var(--rule); padding: 0.6rem 0.75rem 0.6rem 0; vertical-align: top; }
+table.index td.pr { white-space: nowrap; }
+table.index td.pr a { color: var(--accent); border: none; }
+table.index td.takeaway { color: var(--soft); }
+table.index tr.sparse td { color: var(--dim); }
+table.index .mark { color: var(--accent-dim); }
+```
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add ent/lessons/build.mjs ent/lessons/build.test.mjs
+git commit -m "Add index page generation from the lessons README"
+```
+
+---
+
+### Task 8: Orchestration (`buildSite` + `main`), `--check`, justfile, end-to-end verification
+
+Wire the pure functions into a pure `buildSite` (returns a filename→content map) and a thin `main()` that reads real files and writes the map. Add validation/link gating, the `--check` mode, and the `just` recipes. Verify end-to-end against the real repo and drive the drawer in a browser.
+
+**Files:**
+- Modify: `ent/lessons/build.mjs`
+- Modify: `justfile`
+- Test: `ent/lessons/build.test.mjs`
+
+**Interfaces:**
+- Consumes: every prior function.
+- Produces:
+  - `buildSite(input: { lessons: ParsedLesson[], glossary: object, readmeMd: string, theme?: object }): Map<string,string>` — all output files (pages, `index.html`, `lessons.css`, `drawer.js`, `glossary.js`).
+  - `checkCrossLinks(lessons: ParsedLesson[]): string[]` — errors for `NN-slug.md` links with no matching lesson file.
+  - `main(argv: string[]): Promise<void>` — read, validate, then emit or (`--check`) report.
+
+- [ ] **Step 1: Write the failing test**
+
+Append to `ent/lessons/build.test.mjs`:
+
+```js
+import { buildSite, checkCrossLinks } from './build.mjs';
+
+const GL = {
+  arc: { term: 'Arc<T>', aliases: ['Arc'], short: 's', why: 'w', prereqs: [], link: { label: 'x', url: 'y' } },
+};
+const LESSONS = [{
+  pr: 16, slug: 'supervised-app-with-logs', title: 'PR #16 — X',
+  lesson: 'Clone an `Arc`.', tags: ['Arc'],
+  merged: { date: '2026-06-08', delta: '+1/−0', url: 'https://example.com/16' },
+  bodyMarkdown: 'Boot with an `Arc`. See [PR #17](17-inject-port-into-child-env.md).',
+}];
+
+test('buildSite returns pages plus the four shared assets', () => {
+  const files = buildSite({ lessons: LESSONS, glossary: GL, readmeMd: '## The lessons\n' });
+  assert.ok(files.has('16-supervised-app-with-logs.html'));
+  assert.ok(files.has('index.html'));
+  assert.ok(files.has('lessons.css'));
+  assert.ok(files.has('drawer.js'));
+  assert.ok(files.has('glossary.js'));
+  assert.match(files.get('16-supervised-app-with-logs.html'), /data-term="arc"/);
+});
+
+test('checkCrossLinks flags a link with no target lesson', () => {
+  const errs = checkCrossLinks(LESSONS); // #17 not in the list
+  assert.equal(errs.length, 1);
+  assert.match(errs[0], /17-inject-port-into-child-env/);
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `node --test ent/lessons/build.test.mjs`
+Expected: FAIL — `buildSite` not exported.
+
+- [ ] **Step 3: Write minimal implementation**
+
+Append to `ent/lessons/build.mjs`:
+
+```js
+import { readFileSync, writeFileSync, readdirSync, mkdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export function checkCrossLinks(lessons) {
+  const known = new Set(lessons.map((l) => `${l.pr}-${l.slug}.md`));
+  const errors = [];
+  const linkRe = /\]\((\d+-[a-z0-9-]+\.md)\)/g;
+  for (const l of lessons) {
+    for (const m of l.bodyMarkdown.matchAll(linkRe)) {
+      if (!known.has(m[1])) errors.push(`${l.pr}-${l.slug}.md links to missing lesson '${m[1]}'`);
+    }
+  }
+  return errors;
+}
+
+export function buildSite({ lessons, glossary, readmeMd, theme = THEME }) {
+  const glossaryIndex = buildGlossaryIndex(glossary);
+  const files = new Map();
+  for (const lesson of lessons) {
+    files.set(`${lesson.pr}-${lesson.slug}.html`, renderLessonPage(lesson, { glossaryIndex, theme }));
+  }
+  files.set('index.html', renderIndexPage(readmeMd, { theme }));
+  files.set('lessons.css', renderStylesheet(theme));
+  files.set('drawer.js', renderDrawerScript());
+  files.set('glossary.js', renderGlossaryScript(glossary));
+  return files;
+}
+
+export async function main(argv) {
+  const check = argv.includes('--check');
+  const root = process.cwd();
+  const { lessonsDir, readme, outDir } = THEME.paths;
+
+  const glossary = JSON.parse(readFileSync(join(root, lessonsDir, 'glossary.json'), 'utf8'));
+  const { errors } = validateGlossary(glossary);
+
+  const files = readdirSync(join(root, lessonsDir)).filter((f) => /^\d+-[a-z0-9-]+\.md$/.test(f));
+  const lessons = files
+    .map((f) => parseLesson(f, readFileSync(join(root, lessonsDir, f), 'utf8')))
+    .sort((a, b) => a.pr - b.pr);
+  const linkErrors = checkCrossLinks(lessons);
+
+  const allErrors = [...errors, ...linkErrors];
+  if (allErrors.length) {
+    console.error('build failed:\n' + allErrors.map((e) => '  - ' + e).join('\n'));
+    process.exitCode = 1;
+    return;
+  }
+
+  const missing = coverageReport(lessons, buildGlossaryIndex(glossary));
+  if (missing.length) {
+    console.log(`coverage: ${missing.length} backticked terms not in glossary (top 10):`);
+    console.log(missing.slice(0, 10).map((m) => `  ${m.count}x  ${m.term}`).join('\n'));
+  }
+
+  if (check) {
+    console.log(`check OK — ${lessons.length} lessons, ${Object.keys(glossary).length} glossary entries`);
+    return;
+  }
+
+  const readmeMd = readFileSync(join(root, readme), 'utf8');
+  const out = buildSite({ lessons, glossary, readmeMd });
+  mkdirSync(join(root, outDir), { recursive: true });
+  for (const [name, content] of out) writeFileSync(join(root, outDir, name), content);
+  console.log(`wrote ${out.size} files to ${outDir}`);
+}
+
+if (import.meta.main) {
+  main(process.argv.slice(2));
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `node --test ent/lessons/build.test.mjs`
+Expected: PASS — 33 passing, 0 failing.
+
+- [ ] **Step 5: Run the real build and the check**
+
+Run:
+```bash
+node ent/lessons/build.mjs --check
+node ent/lessons/build.mjs
+ls ent/lessons/
+```
+Expected: `--check` prints a coverage list and `check OK — 31 lessons, 5 glossary entries`; the build prints `wrote 35 files to ent/lessons` (31 lesson pages + `index.html` + `lessons.css` + `drawer.js` + `glossary.js`); `ls` shows the generated `.html` pages plus `lessons.css`, `drawer.js`, `glossary.js`.
+
+- [ ] **Step 6: Add the justfile recipes**
+
+Modify `justfile` — add a `build-lessons` recipe and make `serve` depend on it. Replace the existing `serve` recipe:
+
+```make
+build-lessons:
+  node ent/lessons/build.mjs
+
+serve: build-lessons
+  npx live-server --port=8081
+```
+
+- [ ] **Step 7: Verify in the browser (the `verify` skill)**
+
+First check nothing else holds the ports (per CLAUDE.md):
+```bash
+lsof -nP -iTCP:8080 -sTCP:LISTEN; lsof -nP -iTCP:8081 -sTCP:LISTEN
+```
+Then `just serve`, open `http://127.0.0.1:8081/ent/lessons/16-supervised-app-with-logs.html`, and confirm by driving the page (Claude-in-Chrome or manually):
+- The `Arc<Mutex<T>>` term in the lesson sentence and body is dotted-underlined; clicking it opens the drawer with the definition, "Why it matters", and "Learn first" chips (ownership, move, Send / Sync).
+- Clicking the `move` chip swaps the drawer to `move` and shows a back affordance; back returns to `Arc<T>`.
+- Esc and clicking the scrim both close the drawer.
+- `index.html` lists all 31 lessons and links resolve.
+- Loading the page via `file://` still opens the drawer (glossary.js needs no server).
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add ent/lessons/build.mjs ent/lessons/build.test.mjs justfile ent/lessons/*.html ent/lessons/lessons.css ent/lessons/drawer.js ent/lessons/glossary.js
+git commit -m "Wire generator orchestration, --check gate, justfile recipes, and generated site"
+```
+
+---
+
+### Task 9: Author the full glossary (human review gate)
+
+Expand `docs/lessons/glossary.json` from the 5 seed entries to the full foundational set, so the coverage report is small and the important terms across all 31 lessons annotate. This is content work; it ends at a human review checkpoint, per the spec.
+
+**Files:**
+- Modify: `docs/lessons/glossary.json`
+
+**Interfaces:**
+- Consumes: the coverage report from `node ent/lessons/build.mjs --check`.
+- Produces: a reviewed glossary.
+
+- [ ] **Step 1: List what's missing**
+
+Run: `node ent/lessons/build.mjs --check`
+Read the coverage report. Cross-reference the spec's seed list: ownership, borrowing, move, lifetime, `'static`, reference counting / `Arc`, `Rc`, `Weak`, `Mutex`, interior mutability, `Send`/`Sync`, trait, trait bound, `dyn` vs generic (dynamic vs static dispatch), monomorphization, `Option`, `Result`, `?`, combinators, closure, `Drop`/RAII, iterator / laziness, `collect`, newtype, derive macro, `Serialize`/`Deserialize`, FFI / `unsafe`, `Instant` vs `SystemTime`, `HashMap::retain`, `&str` vs `String`, `split_once`, `include_str!`, `build.rs`, `env!` / `option_env!`.
+
+- [ ] **Step 2: Draft each entry**
+
+For each term add an entry following the seed shape: `term`, `aliases` (the exact backticked strings that appear in the lessons — check the coverage report and the lessons for the real spellings), a plain-language `short`, a `why`, `prereqs` (keys of foundational terms, forming the learning ladder), and a `link` to the relevant Rust Book / std doc chapter. Keep `short` to one or two sentences; assume the reader knows another language but is new to Rust. Do not invent prereq edges that create no teaching value; a foundational term like `ownership` has `prereqs: []`.
+
+- [ ] **Step 3: Validate and re-check coverage**
+
+Run:
+```bash
+node ent/lessons/build.mjs --check
+```
+Expected: `errors: []` (no dangling prereqs, no duplicate aliases), and a materially shorter coverage list (remaining entries should be genuinely incidental code like `.env(k, v)`, not foundational concepts).
+
+- [ ] **Step 4: Regenerate the site**
+
+Run: `node ent/lessons/build.mjs`
+
+- [ ] **Step 5: Human review gate**
+
+Present `docs/lessons/glossary.json` to the user for review before committing. Teaching accuracy is the point; the definitions, the "why", and especially the prereq ladders need a human read. Do not commit until approved. Apply requested edits, then re-run Step 3.
+
+- [ ] **Step 6: Commit (after approval)**
+
+```bash
+git add docs/lessons/glossary.json ent/lessons/*.html ent/lessons/glossary.js
+git commit -m "Author the full foundational-term glossary"
+```
+
+---
+
+## Self-Review
+
+**1. Spec coverage:**
+
+- Data model (`glossary.json`, aliases, prereqs, one-level chains) → Tasks 4, 9; drawer chains → Task 6.
+- Term annotation via backticked code spans + tag chips, markdown untouched → Tasks 4 (code spans), 5 (tag chips). Every occurrence annotated → Task 4 implementation.
+- Generation pipeline, bounded parser (headings, bold, italic, inline code, fenced-literal, ul/ol nesting, links), fenced content not re-parsed → Tasks 1, 2. Cross-link rewrite → Task 1. Coverage report → Task 4/8.
+- Emit per-lesson pages + index + shared `lessons.css`/`drawer.js`/`glossary.js`, provenance headers → Tasks 5, 6, 7, 8. `glossary.js` sets a global so the drawer works over `file://` → Task 5, verified Task 8 Step 7.
+- Engine/theme seam (`THEME` object holds all Adjacent values) → Task 5.
+- Page anatomy, dark-only palette reuse, subtle term affordance, side panel with back → Tasks 5 (CSS/template), 6 (behavior).
+- Two surfaces (postable markdown untouched; drawer only on the site) → guaranteed by "never modify lesson .md" constraint; no task writes to `docs/lessons/*.md`.
+- justfile `build-lessons` + `serve` dependency → Task 8. Generated files committed → Tasks 8, 9.
+- Testing: `--check` validates + gates + coverage → Task 8; manual browser verify → Task 8 Step 7.
+- Out of scope (highlight-any-phrase, visual graph, multi-word prose annotation, search, light/dark toggle) → not implemented, correct.
+
+**2. Placeholder scan:** No "TBD"/"handle edge cases"/"similar to Task N". Every code step shows complete, runnable code (the drawer in Task 6 included).
+
+**3. Type consistency:** `glossaryIndex` is a `Map<string,string>` everywhere (Tasks 1, 2, 4, 5, 8). `renderInline`/`renderMarkdown` share the `{ glossaryIndex }` options shape. `parseLesson` output fields (`pr, slug, title, lesson, tags, merged, bodyMarkdown`) are consumed unchanged by `renderLessonPage`, `checkCrossLinks`, `coverageReport`, and `buildSite`. `THEME.paths` (`lessonsDir, readme, outDir`) is read only in `main`. Asset filenames (`lessons.css`, `drawer.js`, `glossary.js`) match between the page `<link>`/`<script>` tags (Task 5) and `buildSite`'s map keys (Task 8).
diff --git a/docs/superpowers/specs/2026-07-11-interactive-lessons-design.md b/docs/superpowers/specs/2026-07-11-interactive-lessons-design.md
new file mode 100644
index 0000000..406a08d
--- /dev/null
+++ b/docs/superpowers/specs/2026-07-11-interactive-lessons-design.md
@@ -0,0 +1,248 @@
+# Interactive surface for the Rust lessons series
+
+**Date:** 2026-07-11\
+**Status:** Approved design, pre-implementation
+
+## Problem
+
+`docs/lessons/` holds a 31-file teaching series: one Rust lesson per merged PR, each
+grounded in the real diff. The files are excellent as prose, but a newcomer hits
+foundational terms they don't yet own. A lesson says "hand the task an `Arc<Mutex<T>>`
+clone" and assumes the reader can already climb ownership → move → `Send`/`Sync` to
+appreciate why. Today that climb is on the reader.
+
+We want an interactive surface where a reader can click a foundational term and get a
+plain-language definition, why it matters, and — the distinctive ask — **what they'd need
+to learn first**. The prerequisite chain is the novel part, not an afterthought.
+
+## Goal
+
+Generate an interactive HTML page per lesson, served from `ent/lessons/`, where:
+
+- Foundational terms in the prose are clickable.
+- Clicking a term opens a side panel with a definition, a "why it matters" line, and a
+  row of clickable **prerequisite** terms ("learn these first").
+- The lesson markdown in `docs/lessons/` stays the single source of truth. The interactive
+  layer is generated *from* it, never a fork of it.
+
+The ultimate goal (see "Where it's headed") is a reusable skill that does this for any
+repo, annotating its PRs with lesson plans and building this same interactive site. This
+v1 builds the concrete Adjacent instance, with the code seamed so that extraction is a
+lift, not a rewrite.
+
+## Design
+
+### Data model — the glossary is the "learn more" layer
+
+One checked-in file, `docs/lessons/glossary.json`, sits next to the lessons it explains.
+Each entry:
+
+```json
+{
+  "arc": {
+    "term": "Arc<T>",
+    "aliases": ["Arc", "Arc<Mutex<T>>", "Arc<Mutex<Inner>>"],
+    "short": "Atomically reference-counted shared pointer. Cloning it bumps a refcount and hands back a second owner of the same value, not a copy.",
+    "why": "Lets two threads or tasks own one value at once. It is how a detached task can touch state the spawner still holds.",
+    "prereqs": ["ownership", "move", "send-sync"],
+    "link": { "label": "Rust Book 16.3", "url": "https://doc.rust-lang.org/book/ch16-03-shared-state.html" }
+  }
+}
+```
+
+- **`aliases`** are the exact strings that appear in the prose (mostly inside backticks)
+  that resolve to this entry.
+- **`prereqs`** are other glossary keys. This array *is* the dependency graph; there is no
+  separate graph file. It is a directed graph encoded as adjacency lists.
+- The side panel shows a term's **direct** prereqs (one level) as clickable chips. Clicking
+  one swaps the panel to that term. One level plus click-to-descend gives the "climb the
+  ladder" experience with zero cycle risk and no rendered node diagram.
+
+The glossary is an authored data file, drafted by the agent and reviewed by a human before
+publish, because teaching accuracy is the whole point. Framing note for reusability: the
+glossary is an **output** the tooling produces for a repo, not an asset baked into the
+tooling. A Python project would get a Python glossary.
+
+### How a prose term becomes clickable
+
+The lessons already wrap Rust terms in backticks (inline code). The generator walks each
+lesson's inline-code spans; any span whose text matches a glossary alias becomes an
+annotated, clickable term. The **Tags** line in each lesson header (already a controlled
+vocabulary) also becomes clickable into the glossary.
+
+Two consequences, stated plainly:
+
+- The lesson markdown is never modified. It stays the single source of truth.
+- Only backticked code spans and tag chips are annotation candidates, so an English prose
+  word never false-matches. The word "move" in a sentence stays plain; only `move` in
+  backticks lights up. The cost: a multi-word prose phrase that is not backticked (for
+  example "automatic reference counting" written out) does not annotate in v1. This is the
+  honest limitation, recorded in Out of scope and dialed up later.
+
+Every matching code span is annotated (not just the first per page); code spans are already
+visually distinct, so a subtle dotted underline on the glossary matches is a light touch.
+If it reads as noisy in review, the dial is "first occurrence per page."
+
+### Generation pipeline — `ent/lessons/build.mjs`
+
+A dependency-free Node ESM script. Because every lesson has the identical template
+structure, it parses with targeted logic instead of pulling in a CommonMark library, so
+`ent/` stays dependency-free.
+
+Parser scope (the bounded set the lessons actually use, confirmed by survey):
+
+- ATX headings `#` / `##` / `###`
+- The three-line blockquote header (lesson / tags / merged)
+- Paragraphs, bold `**...**`, italic `*...*`, inline code `` `...` ``, links `[t](u)`
+- Fenced code blocks ` ```lang ` for any language (bash, html, make, markdown, rust, sh,
+  toml, yaml). **Fenced content is literal**: a ` ```markdown ` block is rendered as code,
+  never re-parsed, and inline-code annotation does not descend into fences.
+- Unordered lists with one level of nesting; ordered lists (`1.`)
+
+Explicitly **not** in the lesson bodies (so not in scope): tables, images, raw HTML in
+prose. (The one table and the reading-path lists live in `README.md`; see the index below.)
+
+Steps:
+
+1. Read and validate `glossary.json`: every `prereqs` key resolves to a real entry, aliases
+   are unique across entries, and emit a **coverage report** of backticked terms found
+   across all lessons that are not in the glossary (so gaps are visible).
+2. For each `docs/lessons/<NN>-<slug>.md`: parse the leading comment, `# PR #NN — title`,
+   the three-line blockquote, and the `##` sections; render the bounded markdown to HTML;
+   annotate glossary matches in inline-code spans and the tags line; rewrite cross-lesson
+   links (`40-...md` → `40-...html`).
+3. Emit `ent/lessons/<NN>-<slug>.html` per lesson, plus `ent/lessons/index.html`.
+4. Every generated file carries a `<!-- generated by build.mjs; edit docs/lessons/*.md -->`
+   header comment.
+
+Shared assets, emitted once into `ent/lessons/` and referenced by every page:
+`lessons.css`, `drawer.js`, and `glossary.js` (which assigns `window.__GLOSSARY__ = {...}`
+so the drawer needs no `fetch` and works over `file://`). A multi-page set shares assets
+rather than inlining 31 copies; this is a deliberate departure from the single landing
+page's fully-inlined approach, chosen for maintainability. (If fully self-contained pages
+are preferred, the generator can inline instead.)
+
+The index page is built by parsing `README.md`'s table rows and reading-path lines with
+targeted regex (same known-structure philosophy as the lesson parser, no general table
+renderer). This keeps `README.md` the source of truth for the curated takeaways, the ◦
+honesty markers, and the themed reading paths.
+
+### The engine / theme seam (for reusability)
+
+`build.mjs` is structured as a neutral **engine** plus a thin **theme + config** layer, so
+the eventual skill reuses the engine and swaps the theme:
+
+- **Engine (portable, no Adjacent identifiers):** parse a lesson of the known template
+  shape; render the bounded markdown; match and annotate glossary aliases; build the drawer
+  data; emit a page and the shared assets; parse an index from a README of the known shape.
+- **Theme + config (repo-specific):** a single `THEME` object at the top of the file —
+  palette, font stack, wordmark parts, site title, repo URL, and the input/output paths.
+  v1 fills it with Adjacent's values (`--ink`/`--paper`/`--accent #d4a574`, JetBrains Mono,
+  the `adj.ac/ent` wordmark, `docs/lessons` → `ent/lessons`).
+
+This is one file with a clear internal boundary, not a premature multi-package split
+(YAGNI). The boundary is the documented extraction line.
+
+### Page anatomy and interaction
+
+Reuse `ent/index.html`'s design language exactly: `--ink` background, `--paper` text,
+`--accent` `#d4a574`, JetBrains Mono, the dotted-underline link treatment. Dark-only, to
+match the landing page.
+
+- **Reading column** centered, roughly 72ch, article-style.
+- **Term affordance:** glossary-matched code spans get a dotted underline in the accent
+  color and a pointer cursor. Plain code stays plain.
+- **Side panel** slides in from the right (about 360px) on term click, showing: the term in
+  monospace accent, the short definition, "Why it matters", a "Learn first" row of clickable
+  prereq chips, and the external link. Descending into a prereq swaps the content with a
+  back affordance. Closes on Esc or click-away.
+- **Progressive enhancement:** like the landing page's copy buttons, the drawer is built in
+  JS. With JS off the lesson is fully readable, code stays code, links still work.
+- **Index page** carries the chronological table, the ◦ markers, and the themed reading
+  paths, each linking into the generated pages.
+
+### The two surfaces (postable markdown vs hosted drawer)
+
+The source markdown was written to double as a `gh pr comment` body. A GitHub comment
+strips JS and scoped CSS, so the interactive drawer cannot live inside a PR comment. The
+tooling therefore produces two distinct surfaces from one source: the plain-markdown lesson
+(postable to the PR) and the hosted interactive site (where the drawer lives). The design
+keeps these separate and never assumes the annotations survive inside a comment.
+
+### justfile
+
+Add a `build-lessons` recipe and make `serve` depend on it, so the site is always fresh in
+dev:
+
+```make
+build-lessons:
+  node ent/lessons/build.mjs
+
+serve: build-lessons
+  npx live-server --port=8081
+```
+
+Generated pages are committed (consistent with the repo committing other generated
+artifacts, and so `ent/` stays directly serveable with no build step for a future `adj.ac`
+deploy). The `generated by build.mjs` header makes provenance clear. This is the one small
+choice worth a human nod at review time.
+
+## Testing
+
+Every normal build runs the validations below and fails fast (non-zero exit) on an
+integrity error, so a broken glossary or dangling link can never emit a page. `--check`
+runs the same validations without emitting files, for use as a pre-commit or CI gate.
+
+**Generator self-check (`node ent/lessons/build.mjs --check`):**
+
+- Glossary integrity: every `prereqs` key resolves; aliases are unique across entries.
+  Exits non-zero on failure so it can gate.
+- Link integrity: every rewritten cross-lesson link resolves to an emitted file.
+- Coverage report: backticked terms across all lessons that are absent from the glossary,
+  printed (not fatal) so the gap is visible.
+
+**Manual verification (per the `verify` skill at implementation time):**
+
+- `just serve` (after checking `lsof -nP -iTCP:8080 -sTCP:LISTEN` and `:8081`), open a
+  lesson, click `Arc<Mutex<T>>`, confirm the drawer content, click a prereq chip to descend,
+  Esc to close.
+- Load a page over `file://` to confirm `glossary.js` works without a server.
+- View a page with JS disabled to confirm the lesson is fully readable.
+
+## Where it's headed — the reusable skill
+
+The end state is a skill that runs against any repo, drafts a per-PR lesson plan and a
+per-repo glossary, and builds this interactive site. Four disciplines in this v1 keep that
+path a lift rather than a rewrite:
+
+1. **Engine / theme seam.** The generic engine carries no Adjacent identifiers; everything
+   repo-specific lives in the `THEME` object.
+2. **Glossary and lessons are generated outputs**, not assets baked into the tooling. The
+   skill's job is to produce them per repo.
+3. **Two surfaces, kept separate:** postable markdown lesson vs hosted interactive site.
+4. **Build one, then extract.** Ship the concrete Adjacent instance first; you cannot design
+   good portable seams against repos that do not exist yet. Extraction happens once this
+   instance is real, and must obey the portable-tooling rule (no project-specific
+   identifiers survive into the skill).
+
+## Out of scope (v1)
+
+- **Highlight-any-phrase "go deeper."** The north-star interaction: select arbitrary prose
+  and ask for a deeper explanation. The side-panel drawer is deliberately the surface it
+  would plug into later.
+- **Rendered visual dependency-graph diagram.** v1 surfaces the graph as one-level prereq
+  chains with click-to-descend, not as a drawn node/edge view.
+- **Multi-word prose-phrase annotation.** Only backticked code spans and tag chips annotate
+  in v1.
+- **Full-text search across lessons.**
+- **Light/dark toggle.** Dark-only, matching the landing page.
+
+## Seed glossary terms
+
+Drafted by the agent, reviewed by a human before publish. From the tags and concepts across
+the 31 lessons: ownership, borrowing, move, lifetime, `'static`, reference counting / `Arc`,
+`Rc`, `Weak`, `Mutex`, interior mutability, `Send`/`Sync`, trait, trait bound, `dyn` vs
+generic (dynamic vs static dispatch), monomorphization, `Option`, `Result`, `?`,
+combinators, closure, `Drop`/RAII, iterator / laziness, `collect`, newtype, derive macro,
+`Serialize`/`Deserialize`, FFI / `unsafe`, `Instant` vs `SystemTime`, `HashMap::retain`,
+`&str` vs `String`, `split_once`, `include_str!`, `build.rs`, `env!` / `option_env!`.
diff --git a/docs/superpowers/specs/2026-07-12-lessons-from-prs-skill-design.md b/docs/superpowers/specs/2026-07-12-lessons-from-prs-skill-design.md
new file mode 100644
index 0000000..5388178
--- /dev/null
+++ b/docs/superpowers/specs/2026-07-12-lessons-from-prs-skill-design.md
@@ -0,0 +1,117 @@
+# `lessons-from-prs` skill design
+
+**Date:** 2026-07-12\
+**Status:** Approved design, pre-implementation (uncommitted by request)
+
+## Problem
+
+We built a concrete "learn by example, one PR at a time" teaching series for this
+repo: one lesson per merged PR, drafted from the real diff, plus an interactive site
+with clickable glossary terms and prerequisite ladders. The *process* that produced
+those lessons is reusable across any repo, but it currently lives only as prose in
+`docs/lessons/README.md` ("Adding a lesson for a new PR") and as tacit judgment. There
+is no tool to point at another repo and get the same teaching notes.
+
+## Goal
+
+A reusable skill, **`lessons-from-prs`**, that drafts per-PR teaching lessons from real
+diffs in any repo. It packages the authoring judgment (pick one concept, honesty rule,
+real snippets, fixed template) into a repeatable, language-agnostic flow, and it keeps a
+running vocabulary index that seeds a later glossary.
+
+This is the "build one, then extract" step named in the interactive-lessons spec
+(`docs/superpowers/specs/2026-07-11-interactive-lessons-design.md`, section "Where it's
+headed — the reusable skill"). This v1 is **authoring-first**: the interactive site and
+the full glossary are deferred (see Out of scope).
+
+## The reference instance (extract from, don't duplicate)
+
+- Authoring process + honesty rule + "Adding a lesson": `docs/lessons/README.md`.
+- The fixed lesson template: `docs/lessons/_TEMPLATE.md`.
+- 31 worked examples: `docs/lessons/<NN>-<slug>.md`.
+- The (deferred) site engine and glossary format: `ent/lessons/build.mjs`,
+  `docs/lessons/glossary.json` — these ride with the deferred site skill, NOT this one.
+
+## Design
+
+### Where it lives
+
+`~/.claude/skills/lessons-from-prs/`. Note `~/.claude` is a **public** repo, so the
+skill is a published, shareable artifact: the portable-tooling rule
+(`~/.dotfiles/.claude/rules/skill-authoring.md`) applies in full. No project-specific
+identifiers may appear in the skill files; any example uses a neutral invented domain
+(support tickets, invoices — varied), and a grep gate confirms it before done. The word
+"Adjacent" / "adj.ac" / "Rust"-as-the-only-language must not leak into the skill.
+
+### Two invocation modes, one drafting logic
+
+- **Per-PR (default):** run in the target repo, pass a PR number. Read the diff, draft
+  the lesson, present it for review/edit, save it. The maintenance loop, run when a PR
+  merges.
+- **Backfill:** pass a PR range or `--all`. Draft lessons for many PRs into files for
+  batch review. Bootstraps an existing repo (how the 31 reference lessons were made).
+
+The per-PR drafting is identical in both; backfill is that logic in a loop with
+batched, not inline, review.
+
+### The authoring process it encodes (the reusable core)
+
+1. **Read the real diff** (`gh pr diff <N>` / `gh pr view <N>`), never the title alone.
+   The diff wins over any preconception; verify the chosen angle against the code.
+2. **One concept per lesson.** Pick the single most instructive idea the PR demonstrates.
+3. **Honesty rule.** If a PR has little/no language content (docs, a deletion, config),
+   say so plainly and teach what it *does* contain (release engineering, project
+   hygiene, docs-as-contract), marked as such. Never fabricate a lesson.
+4. **Real snippets only,** lifted from the diff with the file path as a leading comment;
+   elisions marked. Never invent code.
+5. **Fixed template** (bundled generic `_TEMPLATE.md`): the `<!-- -->` provenance
+   comment, `# PR #NN — <title>`, a three-line blockquote (lesson sentence / Tags /
+   Merged with +A/−D and a View-PR link), then sections `The situation` / `The idea` /
+   `In this PR` / `Why it matters` / `Related lessons` / `Dig deeper`. Cross-links to
+   sibling lessons use relative `NN-slug.md` links. The uniform structure is a contract
+   a future site parses without heuristics.
+6. **Language-parametric voice.** Infer the repo's primary language/domain and adapt the
+   teaching voice and the "Dig deeper" links (the language's book/std docs) accordingly.
+   The template and the five rules above are language-neutral.
+
+### Artifacts it writes
+
+- `docs/lessons/<NN>-<slug>.md` per PR (slug = 3–5 kebab-case words from the title).
+- A **running vocabulary index** aggregating each lesson's `Tags` across the series (the
+  seed vocabulary for the future glossary). Definitions and prerequisite edges are NOT
+  produced here — they are deferred with the site. Exact filename/format is an
+  implementation detail for the plan (e.g. a simple `docs/lessons/VOCABULARY.md` table of
+  term → lessons that use it), kept trivially regenerable from the lessons' Tags lines.
+
+### Posting is opt-in and gated
+
+A lesson is written to double as a `gh pr comment --body-file` body. Posting sends
+content on the user's behalf (outward-facing), so the skill **drafts and saves locally
+by default** and posts a PR comment only with the user's explicit per-PR go-ahead. It
+never posts automatically, and never in backfill mode without confirmation.
+
+### Bundled resources
+
+- A **generic `_TEMPLATE.md`** (the reference template with all project nouns removed).
+- The **authoring checklist** (the six rules above) as the skill's core guidance, with
+  progressive disclosure per the write-a-skill conventions.
+
+## Out of scope for v1 (deferred, recorded)
+
+- **Interactive site generation** (the drawer, term annotations, prereq ladders). Rides
+  with a separate future site-build skill that wraps the existing `build.mjs` engine.
+- **Full glossary** (plain-language definitions + prerequisite graph). Deferred with the
+  site; v1 only tracks the vocabulary (Tags), not definitions.
+- **Auto-posting** PR comments without per-PR confirmation.
+- **Non-GitHub forges.** v1 assumes `gh` / GitHub PRs.
+
+## Testing / acceptance
+
+- Point the skill at this repo and re-draft the lesson for a known PR (e.g. #16); the
+  output should match the reference lesson's shape and pick a defensible concept, with
+  real snippets from the actual diff.
+- Run the honesty rule against a no-lesson PR (e.g. #68, a ten-line docs deletion) and
+  confirm it produces an honest "little/no lesson here" entry, not a fabricated concept.
+- Backfill a small range and confirm batch drafting + a coherent vocabulary index.
+- **Portability gate:** `grep -rniE '<project nouns>' ~/.claude/skills/lessons-from-prs`
+  returns only neutral examples — no reference-instance identifiers survive.
diff --git a/ent/lessons/16-supervised-app-with-logs.html b/ent/lessons/16-supervised-app-with-logs.html
new file mode 100644
index 0000000..aaa1cc2
--- /dev/null
+++ b/ent/lessons/16-supervised-app-with-logs.html
@@ -0,0 +1,71 @@
+<!-- generated by build.mjs; edit docs/lessons/*.md -->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>PR #16 — Tracer: supervised app with logs</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@300;400;500;700&display=swap" rel="stylesheet">
+  <link rel="stylesheet" href="lessons.css">
+</head>
+<body>
+  <div class="frame">
+    <header>
+      <a class="wordmark" href="index.html"><span class="a">adj.ac</span><span class="slash">/</span><span class="b">ent</span></a>
+      <a class="back" href="index.html">all lessons</a>
+    </header>
+    <article>
+      <h1>PR #16 — Tracer: supervised app with logs</h1>
+      <div class="lesson-header">
+        <p class="lesson">To mutate state from an async task that outlives the function that spawned it, hand the task an <button type="button" class="term" data-term="arc"><code>Arc&lt;Mutex&lt;T&gt;&gt;</code></button> clone — <button type="button" class="term" data-term="arc"><code>Arc</code></button> gives shared ownership across threads, the <button type="button" class="term" data-term="mutex"><code>Mutex</code></button> makes the mutation safe.</p>
+        <p class="tags"><button type="button" class="term tag" data-term="arc"><code>Arc&lt;Mutex&lt;T&gt;&gt;</code></button><button type="button" class="term tag" data-term="tokio-spawn"><code>tokio::spawn</code></button></p>
+        <p class="meta">2026-06-08 · +2369/−0 · <a href="https://github.com/nonrational/adjacent/pull/16">View PR</a></p>
+      </div>
+      <h2>The situation</h2><p>This is the tracer-bullet PR that stood the project up: register a dev-server directory, boot it, capture its logs, and report whether it's running, stopped, or crashed. The core is a <code>Supervisor</code> that spawns a child process and then needs to know, later and asynchronously, when that child exits — and update its recorded state accordingly. The catch: the code that spawns the child returns immediately, but the exit can happen minutes later. Two different tasks end up touching the same state, and Rust will not let that happen by accident.</p><h2>The Rust idea</h2><p>In a garbage-collected language you would capture <code>this</code> in a callback and mutate a field whenever the process exits. Nobody checks who else is touching that field at the same time.</p><p>Rust makes the sharing explicit, for two reasons:</p><ol><li><strong>Lifetimes.</strong> A task handed to <button type="button" class="term" data-term="tokio-spawn"><code>tokio::spawn</code></button> must be <button type="button" class="term" data-term="static-lifetime"><code>'static</code></button> — it may outlive the function that created it, so it cannot borrow anything on that function's stack (including <code>&amp;self</code>). It has to <em>own</em> what it uses.</li><li><strong>Threads.</strong> Tokio's default runtime is multi-threaded, so the spawned task may run on a different worker thread than the one that spawned it. Anything it captures must be safe to send and share across threads (<button type="button" class="term" data-term="send-sync"><code>Send + Sync</code></button>).</li></ol><p><button type="button" class="term" data-term="arc"><code>Arc&lt;Mutex&lt;T&gt;&gt;</code></button> is the idiomatic answer to both:</p><ul><li><button type="button" class="term" data-term="arc"><code>Arc&lt;T&gt;</code></button> — an <strong>a</strong>tomically <strong>r</strong>eference-<strong>c</strong>ounted pointer. Cloning it doesn't copy the data; it bumps a refcount and hands back a second owner of the <em>same</em> <code>T</code>. Both owners are <button type="button" class="term" data-term="static-lifetime"><code>'static</code></button>, so both can go into spawned tasks.</li><li><button type="button" class="term" data-term="mutex"><code>Mutex&lt;T&gt;</code></button> — guards the interior so only one task mutates at a time. <code>tokio::sync::Mutex::lock().await</code> <em>yields</em> the worker thread while waiting instead of blocking it, which is what you want inside async code.</li></ul><p>The single-threaded shortcut <code>Rc&lt;RefCell&lt;T&gt;&gt;</code> won't compile here: <button type="button" class="term" data-term="rc"><code>Rc</code></button> isn't <button type="button" class="term" data-term="send-sync"><code>Send</code></button>, so <button type="button" class="term" data-term="tokio-spawn"><code>tokio::spawn</code></button> rejects it.</p><h2>In this PR</h2><p>The supervisor holds all app state behind one shared, locked handle:</p><pre><code class="language-rust">// crates/adj/src/supervisor.rs
+#[derive(Default)]
+pub struct Supervisor {
+    inner: Arc&lt;Mutex&lt;Inner&gt;&gt;,
+}
+
+#[derive(Default)]
+struct Inner {
+    apps: HashMap&lt;String, AppRuntime&gt;,
+}
+</code></pre><p><code>up()</code> spawns the child, records it as <code>Running</code>, then detaches a task to wait for the exit:</p><pre><code class="language-rust">// crates/adj/src/supervisor.rs
+pub async fn up(&amp;self, app_dir: PathBuf, cfg: AppConfig) -&gt; Result&lt;u32&gt; {
+    let name = cfg.name.clone();
+    let mut inner = self.inner.lock().await;
+    // ...
+    let mut child = command
+        .spawn()
+        .with_context(|| format!("spawning `{}`", cfg.cmd))?;
+
+    let pid = child.id().ok_or_else(|| anyhow!("spawned child has no pid"))?;
+
+    inner.apps.insert(
+        name.clone(),
+        AppRuntime { state: AppState::Running { pid }, intentional_stop: false },
+    );
+
+    // Detach the wait task so the supervisor can observe exit/crash without holding the lock.
+    let inner_handle = self.inner.clone();
+    let watch_name = name.clone();
+    tokio::spawn(async move {
+        let status = child.wait().await;
+        let mut guard = inner_handle.lock().await;
+        if let Some(rt) = guard.apps.get_mut(&amp;watch_name) {
+            // ... record Stopped, or Crashed { exit_code }
+        }
+    });
+
+    Ok(pid)
+}
+</code></pre><p>The load-bearing lines are the two just before <button type="button" class="term" data-term="tokio-spawn"><code>tokio::spawn</code></button>:</p><ul><li><code>let inner_handle = self.inner.clone();</code> clones the <strong><button type="button" class="term" data-term="arc"><code>Arc</code></button></strong>, not the <code>Inner</code>. The new handle points at the same <code>Mutex&lt;Inner&gt;</code> the <code>Supervisor</code> still owns.</li><li><code>async move { ... }</code> moves <code>inner_handle</code>, <code>watch_name</code>, and <code>child</code> <em>into</em> the task. Now the task owns everything it touches — no borrow of <code>self</code>, so the <button type="button" class="term" data-term="static-lifetime"><code>'static</code></button> requirement is satisfied.</li></ul><p>When the child eventually exits, the task takes the lock (<code>inner_handle.lock().await</code>) and flips the app's <code>state</code> from <code>Running</code> to <code>Stopped</code> or <code>Crashed</code>. Meanwhile <code>state()</code>, <code>down()</code>, and the next <code>up()</code> all reach the same <button type="button" class="term" data-term="hashmap"><code>HashMap</code></button> through the same <button type="button" class="term" data-term="mutex"><code>Mutex</code></button> — one writer at a time, no data race, enforced at compile time.</p><h2>Why it matters</h2><p>Without <button type="button" class="term" data-term="arc"><code>Arc</code></button>, you can't share the state at all: the spawned task can't borrow <code>self</code>, and moving <code>self.inner</code> into it would leave the <code>Supervisor</code> with nothing. Without the <button type="button" class="term" data-term="mutex"><code>Mutex</code></button>, two tasks writing the same <button type="button" class="term" data-term="hashmap"><code>HashMap</code></button> is a data race — which in most languages is a heisenbug you find in production, and in Rust is a compile error you fix before lunch. The pattern is verbose on purpose: it forces you to name, up front, exactly which state is shared and how it's synchronized.</p><h2>Related lessons</h2><ul><li>Later PRs reuse this exact <code>Arc&lt;Mutex&lt;...&gt;&gt;</code> foundation for trickier concurrency — the proxy's lazy-boot single-flight and the idle scanner's re-check-under-lock both build on the supervisor's <code>Inner</code> mutex. Those PRs are the place to teach the <em>variations</em> (single-flight, closing the request-vs-scanner race), not the base pattern taught here.</li></ul><h2>Dig deeper</h2><ul><li><a href="https://doc.rust-lang.org/book/ch16-03-shared-state.html">The Rust Book, ch. 16.3</a> — Shared-State Concurrency (<button type="button" class="term" data-term="mutex"><code>Mutex&lt;T&gt;</code></button> and <button type="button" class="term" data-term="arc"><code>Arc&lt;T&gt;</code></button>)</li></ul>
+    </article>
+  </div>
+  <script src="glossary.js"></script>
+  <script src="drawer.js" defer></script>
+</body>
+</html>
diff --git a/ent/lessons/17-inject-port-into-child-env.html b/ent/lessons/17-inject-port-into-child-env.html
new file mode 100644
index 0000000..03c680e
--- /dev/null
+++ b/ent/lessons/17-inject-port-into-child-env.html
@@ -0,0 +1,54 @@
+<!-- generated by build.mjs; edit docs/lessons/*.md -->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>PR #17 — Inject PORT into supervised processes</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@300;400;500;700&display=swap" rel="stylesheet">
+  <link rel="stylesheet" href="lessons.css">
+</head>
+<body>
+  <div class="frame">
+    <header>
+      <a class="wordmark" href="index.html"><span class="a">adj.ac</span><span class="slash">/</span><span class="b">ent</span></a>
+      <a class="back" href="index.html">all lessons</a>
+    </header>
+    <article>
+      <h1>PR #17 — Inject PORT into supervised processes</h1>
+      <div class="lesson-header">
+        <p class="lesson"><code>tokio::process::Command</code> is a builder that inherits the parent process's environment by default; each <code>&amp;mut self</code> method chains, and <code>.env(key, value)</code> layers one variable on top before <code>.spawn()</code> runs anything.</p>
+        <p class="tags"><span class="tag"><code>tokio::process::Command</code></span><span class="tag"><code>builder-pattern</code></span><span class="tag"><code>env-vars</code></span></p>
+        <p class="meta">2026-06-08 · +322/−12 · <a href="https://github.com/nonrational/adjacent/pull/17">View PR</a></p>
+      </div>
+      <h2>The situation</h2><p>A supervised dev server has to bind <em>somewhere</em>, and the daemon — not the app — picks the port (it allocates a free one via a <code>:0</code> bind probe). So the daemon must hand that number to the child before it starts. The classic Unix mechanism is an environment variable: inject <code>PORT=54321</code> into the child's environment, and the app reads <code>$PORT</code> and binds it. Some apps insist on a different name, so <code>adjacent.toml</code> gains a <code>port_env</code> knob to rename the injected variable.</p><h2>The Rust idea</h2><p>Rust has no keyword arguments, no default parameters, and no function overloading. When a thing has many optional knobs and one final "go" step — spawning a process is the textbook case — the idiomatic shape is the <strong>builder pattern</strong>.</p><p><code>Command::new("sh")</code> returns a mutable <button type="button" class="term" data-term="command"><code>Command</code></button>. Every configuration method (<code>.arg</code>, <code>.current_dir</code>, <code>.env</code>, <code>.stdout</code>, <code>.process_group</code>) takes <code>&amp;mut self</code> and returns <code>&amp;mut Self</code>. Returning the same mutable borrow is what lets calls chain, and because nothing is <em>moved</em>, you can also configure across several statements on the same binding. Nothing actually runs until a terminal method — here <code>.spawn()</code>.</p><p>The environment piece has one detail that trips people up: <strong>a freshly built <button type="button" class="term" data-term="command"><code>Command</code></button> inherits the parent process's entire environment.</strong> You start with a full copy of whatever the daemon itself was launched with. The env methods then edit that inherited set:</p><ul><li><code>.env(key, value)</code> — insert or <strong>override</strong> one entry.</li><li><code>.envs(iter)</code> — the same, for many at once.</li><li><code>.env_remove(key)</code> — drop one inherited entry.</li><li><code>.env_clear()</code> — throw the whole inheritance away and start empty.</li></ul><p>"Inherit, then override" is a precedence decision baked into the default: a later <code>.env</code> wins over whatever the child would have inherited under the same name.</p><h2>In this PR</h2><p>The core is a handful of chained builder calls in <code>up()</code>. The port name is resolved first, then layered onto the command:</p><pre><code class="language-rust">// crates/adj/src/supervisor.rs
+let port_env = cfg.port_env.as_deref().unwrap_or("PORT");
+let mut command = Command::new("sh");
+command
+    .arg("-c")
+    .arg(&amp;cfg.cmd)
+    .current_dir(&amp;app_dir)
+    .env(port_env, port.to_string())
+    .stdin(Stdio::null())
+    .stdout(Stdio::from(log_file))
+    .stderr(Stdio::from(stderr_file));
+</code></pre><ul><li><code>cfg.port_env.as_deref().unwrap_or("PORT")</code> collapses <code>Option&lt;String&gt;</code> into a plain <button type="button" class="term" data-term="str-vs-string"><code>&amp;str</code></button>: <code>as_deref()</code> borrows the inner <button type="button" class="term" data-term="str-vs-string"><code>String</code></button> as <button type="button" class="term" data-term="str-vs-string"><code>&amp;str</code></button> if present, and <code>unwrap_or("PORT")</code> supplies the default when it's <button type="button" class="term" data-term="option"><code>None</code></button>. One expression, one default, no branch.</li><li><code>.env(port_env, port.to_string())</code> layers exactly one variable onto the inherited environment. The value has to be an <em>owned</em> <button type="button" class="term" data-term="str-vs-string"><code>String</code></button> (<code>port</code> is a <code>u16</code>), because <code>.env</code> keeps the bytes for the eventual spawn — a borrowed slice tied to this stack frame wouldn't outlive it.</li></ul><p>The config field that feeds <code>port_env</code> is optional by construction:</p><pre><code class="language-rust">// crates/adj/src/registry.rs
+/// Override the env var name used to inject the assigned port.
+/// When unset, Adjacent exports `PORT`. When set, it exports the named variable instead.
+#[serde(default)]
+pub port_env: Option&lt;String&gt;,
+</code></pre><p><code>#[serde(default)]</code> means an absent key deserializes to <button type="button" class="term" data-term="option"><code>None</code></button> instead of erroring — that's what makes <code>port_env</code> opt-in.</p><p>The load-bearing proof that inheritance is the default lives in the test harness:</p><pre><code class="language-rust">// crates/adj/tests/tracer.rs
+// Scrub port-related env vars from the parent shell so the daemon (and any child it
+// spawns) starts from a known-clean slate. Without this, `PORT=3000 cargo test` would
+// pass `PORT` through to the supervised child and silently break the rename test.
+c.env_remove("PORT");
+c.env_remove("BIND_PORT");
+</code></pre><p>Read that comment as a demonstration of the semantics: because <button type="button" class="term" data-term="command"><code>Command</code></button> copies the parent's environment and <code>.env</code> only touches the keys you name, a stray <code>PORT</code> in the test runner's own environment flows straight through to the child. The <code>rename</code> test asserts the child sees <code>BIND_PORT</code> set and <code>PORT</code> <em>unset</em> — which is only true if the parent isn't leaking a <code>PORT</code> of its own.</p><h2>Why it matters</h2><p>In a language where you mutate a shared, global <code>process.env</code>, injecting a variable is order-dependent and easy to leak between spawns. The <button type="button" class="term" data-term="command"><code>Command</code></button> builder gives you an isolated, per-child edit list assembled on a <code>&amp;mut Command</code>, so the process can't be spawned half-configured — there's no window where the child exists but <code>PORT</code> hasn't been set yet, because <code>.spawn()</code> is the last thing you call.</p><p>The trap the builder's default hides is the inheritance itself. It's convenient (the child gets <code>PATH</code>, <code>HOME</code>, and the rest for free) but it's also a silent channel: if the daemon happened to run with <code>PORT</code> in its own environment, every child would inherit it, and injection would be masking rather than setting. That's exactly why the test scrubs <code>PORT</code>/<code>BIND_PORT</code> before starting — not paranoia, but a direct consequence of "inherit, then override" being the default you signed up for.</p><h2>Related lessons</h2><ul><li>PR #16 stands up the <code>Supervisor</code> and the <code>up()</code> method this <code>.env()</code> call lives inside — the <button type="button" class="term" data-term="arc"><code>Arc&lt;Mutex&lt;Inner&gt;&gt;</code></button> state and the wait-for-exit task are the foundation this port injection slots into.</li><li>PR #76 generalizes this single-variable mechanic into a whole daemon-owned <code>ADJ_*</code> namespace (<code>ADJ_NAME</code>, <code>ADJ_HOST</code>, <code>ADJ_URL</code>, …) injected <em>after</em> <code>env_file</code> and <code>[env]</code> so the daemon's values win — that's where the full env-layering-and-precedence story gets taught. #17 is the one-variable version; #76 is the layered namespace.</li></ul><h2>Dig deeper</h2><ul><li><a href="https://doc.rust-lang.org/std/process/struct.Command.html"><code>std::process::Command</code></a> — tokio's <button type="button" class="term" data-term="command"><code>Command</code></button> mirrors this API. The docs for <code>.env</code>, <code>.envs</code>, <code>.env_remove</code>, and <code>.env_clear</code> spell out the inherit-then-edit model, and the struct-level intro is a clean example of the builder pattern.</li></ul>
+    </article>
+  </div>
+  <script src="glossary.js"></script>
+  <script src="drawer.js" defer></script>
+</body>
+</html>
diff --git a/ent/lessons/19-optional-fields-with-serde.html b/ent/lessons/19-optional-fields-with-serde.html
new file mode 100644
index 0000000..6d181ad
--- /dev/null
+++ b/ent/lessons/19-optional-fields-with-serde.html
@@ -0,0 +1,67 @@
+<!-- generated by build.mjs; edit docs/lessons/*.md -->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>PR #19 — Env loading: [env] table and env_file pointer</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@300;400;500;700&display=swap" rel="stylesheet">
+  <link rel="stylesheet" href="lessons.css">
+</head>
+<body>
+  <div class="frame">
+    <header>
+      <a class="wordmark" href="index.html"><span class="a">adj.ac</span><span class="slash">/</span><span class="b">ent</span></a>
+      <a class="back" href="index.html">all lessons</a>
+    </header>
+    <article>
+      <h1>PR #19 — Env loading: [env] table and env_file pointer</h1>
+      <div class="lesson-header">
+        <p class="lesson"><button type="button" class="term" data-term="option"><code>Option&lt;T&gt;</code></button> is how a struct field says "this may be absent" — and serde's derive fills a missing <button type="button" class="term" data-term="option"><code>Option</code></button> field with <button type="button" class="term" data-term="option"><code>None</code></button> for you, while <code>#[serde(default)]</code> is what saves any <em>non</em>-<button type="button" class="term" data-term="option"><code>Option</code></button> field from erroring when its key is missing.</p>
+        <p class="tags"><span class="tag"><code>option</code></span><button type="button" class="term tag" data-term="serde"><code>serde</code></button><span class="tag"><code>deserialize</code></span><span class="tag"><code>config</code></span></p>
+        <p class="meta">2026-06-08 · +509/−1 · <a href="https://github.com/nonrational/adjacent/pull/19">View PR</a></p>
+      </div>
+      <h2>The situation</h2><p><code>adjacent.toml</code> grew two new, entirely optional fields: an <code>[env]</code> table of committed-safe <code>KEY = "value"</code> pairs, and <code>env_file</code>, a pointer to a dotenv file. Most apps set neither. The config struct has to parse a TOML file where these keys are usually just <em>not there</em> — and it must not treat "absent" as an error. That is a modeling question before it is a parsing one: how does a Rust struct field say "maybe nothing"?</p><h2>The Rust idea</h2><p>Rust has no <code>null</code>. A <button type="button" class="term" data-term="str-vs-string"><code>String</code></button> field always holds a real string; there is no back-door "empty" value that means "unset." When absence is a legitimate state, you say so in the type with <button type="button" class="term" data-term="option"><code>Option&lt;T&gt;</code></button> — an enum with exactly two variants:</p><pre><code class="language-rust">enum Option&lt;T&gt; {
+    None,       // absent
+    Some(T),    // present, carrying a T
+}
+</code></pre><p>The payoff is that the compiler forces every reader to handle both cases before they can touch the inner <code>T</code>. "I forgot the field might be missing" stops being a runtime surprise and becomes a compile error.</p><p>serde bridges this to the data on disk. When you <button type="button" class="term" data-term="derive-macro"><code>#[derive(Deserialize)]</code></button>, serde generates code that walks the TOML and fills each struct field. Its default stance is strict: <strong>a field whose key is missing from the input is an error</strong> ("missing field <code>port</code>"). That is usually what you want — a required field that silently vanished is a bug.</p><p>Two things soften that strictness, and they are easy to conflate:</p><ul><li><code>#[serde(default)]</code> — "if this key is missing, use the type's <code>Default</code> instead of erroring." This is what makes a field genuinely optional at the data level.</li><li><button type="button" class="term" data-term="option"><code>Option&lt;T&gt;</code></button> — a <em>special case</em> serde already knows about. A missing <button type="button" class="term" data-term="option"><code>Option&lt;T&gt;</code></button> field deserializes to <button type="button" class="term" data-term="option"><code>None</code></button> on its own, without <code>#[serde(default)]</code>, because serde special-cases the "no value" path for options.</li></ul><p>So for the <button type="button" class="term" data-term="option"><code>Option</code></button> fields in this PR, the <code>#[serde(default)]</code> attribute is technically redundant — they would parse to <button type="button" class="term" data-term="option"><code>None</code></button> regardless. It is kept for consistency with the existing <code>port_env</code> field above them, and because the intent reads clearly at a glance. Drop <button type="button" class="term" data-term="option"><code>Option</code></button> for a required-but-defaulted field (say <code>port: u64</code> defaulting to <code>0</code>) and the attribute stops being optional itself: without it, a missing <code>port</code> is a hard error.</p><h2>In this PR</h2><p>The whole change to the config type is four lines of field declarations:</p><pre><code class="language-rust">// crates/adj/src/registry.rs
+pub struct AppConfig {
+    pub name: String,
+    pub cmd: String,
+    #[serde(default)]
+    pub port_env: Option&lt;String&gt;,
+    /// Committed-safe environment variables merged into the spawned process env.
+    /// On conflict with `env_file`, this table wins. PORT injection always wins over both.
+    #[serde(default)]
+    pub env: Option&lt;BTreeMap&lt;String, String&gt;&gt;,
+    /// Path to a dotenv-format file, resolved relative to the registered app directory.
+    /// Missing files are a startup error.
+    #[serde(default)]
+    pub env_file: Option&lt;String&gt;,
+}
+</code></pre><p><code>name</code> and <code>cmd</code> are bare <button type="button" class="term" data-term="str-vs-string"><code>String</code></button> — required, and a manifest missing either one is rightly rejected. The two new fields are <button type="button" class="term" data-term="option"><code>Option</code></button>, so <button type="button" class="term" data-term="option"><code>None</code></button> is the normal, no-error resting state.</p><p>Notice <code>env</code> is <code>Option&lt;BTreeMap&lt;String, String&gt;&gt;</code>. A TOML <code>[env]</code> table maps straight onto a map type, and serde recurses: it deserializes each <code>KEY = "value"</code> entry into a <code>(String, String)</code> pair. <code>BTreeMap</code> (not <button type="button" class="term" data-term="hashmap"><code>HashMap</code></button>) keeps the keys sorted, so iterating it later to set env vars is deterministic — the same manifest always applies its overrides in the same order.</p><p>The consumer side then reads these as ordinary <button type="button" class="term" data-term="option"><code>Option</code></button>s, and the <code>if let Some(...)</code> is the compiler-enforced "handle both cases":</p><pre><code class="language-rust">// crates/adj/src/supervisor.rs
+// Resolve env layers before any port allocation so a missing `env_file` or unreadable
+// file fails fast with a clear error (and doesn't leak a port reservation).
+let env_file_values = if let Some(rel) = cfg.env_file.as_deref() {
+    let resolved = app_dir.join(rel);
+    Some(load_env_file(&amp;resolved)?)
+} else {
+    None
+};
+</code></pre><pre><code class="language-rust">// crates/adj/src/supervisor.rs
+if let Some(values) = &amp;cfg.env {
+    for (k, v) in values {
+        command.env(k, v);
+    }
+}
+command.env(port_env, port.to_string());
+</code></pre><p><button type="button" class="term" data-term="option"><code>None</code></button> means "no <code>[env]</code> table, do nothing"; <code>Some(values)</code> unwraps the map so you can iterate it. There is no way to iterate the map without first proving it exists — that is <button type="button" class="term" data-term="option"><code>Option</code></button> doing its job.</p><p>One honest footnote: <code>env_file</code> points at a <em>dotenv</em> file, which is not TOML, so serde doesn't parse its contents. The PR hand-rolls a tiny <code>parse_dotenv</code> in <code>crates/adj/src/env.rs</code>. serde's reach ends at the <code>adjacent.toml</code> boundary; the file it points to is parsed by hand.</p><h2>Why it matters</h2><p>In a language with <code>null</code>, "this field is optional" and "I forgot to set this field" look identical at the type level — both are <code>null</code> — and the difference only shows up as a <code>NullPointerException</code> at 2am. Rust splits them: absence is <button type="button" class="term" data-term="option"><code>Option</code></button>, and the compiler won't let you read through it without checking. Pair that with serde's default strictness and you get a config loader where <em>required</em> fields are enforced for free (a missing <code>cmd</code> is rejected at parse time) and <em>optional</em> fields are spelled out deliberately, one <button type="button" class="term" data-term="option"><code>Option</code></button> at a time. The trap this avoids is the silent empty-string or zero-value that a laxer parser would hand you for a field the user never wrote.</p><h2>Related lessons</h2><ul><li>PR #48 stays in this same <code>AppConfig</code> neighborhood but on the <button type="button" class="term" data-term="result"><code>Result</code></button> side — not swallowing a parse <button type="button" class="term" data-term="result"><code>Err</code></button> when a <em>present</em> field is malformed. #19 is about a field being absent; #48 is about a field being present-but-wrong.</li><li>PR #22 covers the mirror-image direction, serde <button type="button" class="term" data-term="serde"><code>Serialize</code></button> for the JSON DTOs; PR #75 covers <em>writing</em> an <code>adjacent.toml</code>. This lesson stays strictly on the <button type="button" class="term" data-term="serde"><code>Deserialize</code></button> + <button type="button" class="term" data-term="option"><code>Option</code></button> reading side.</li></ul><h2>Dig deeper</h2><ul><li><a href="https://doc.rust-lang.org/book/ch06-01-defining-an-enum.html#the-option-enum-and-its-advantages-over-null-values">The Rust Book, ch. 6.1</a> — the <button type="button" class="term" data-term="option"><code>Option</code></button> enum and its advantages over null.</li><li><a href="https://serde.rs/field-attrs.html">serde: field attributes</a> — <code>#[serde(default)]</code> and how missing fields are handled.</li></ul>
+    </article>
+  </div>
+  <script src="glossary.js"></script>
+  <script src="drawer.js" defer></script>
+</body>
+</html>
diff --git a/ent/lessons/22-serialize-wire-dto-contract.html b/ent/lessons/22-serialize-wire-dto-contract.html
new file mode 100644
index 0000000..03437fb
--- /dev/null
+++ b/ent/lessons/22-serialize-wire-dto-contract.html
@@ -0,0 +1,88 @@
+<!-- generated by build.mjs; edit docs/lessons/*.md -->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>PR #22 — Agent JSON output on read commands</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@300;400;500;700&display=swap" rel="stylesheet">
+  <link rel="stylesheet" href="lessons.css">
+</head>
+<body>
+  <div class="frame">
+    <header>
+      <a class="wordmark" href="index.html"><span class="a">adj.ac</span><span class="slash">/</span><span class="b">ent</span></a>
+      <a class="back" href="index.html">all lessons</a>
+    </header>
+    <article>
+      <h1>PR #22 — Agent JSON output on read commands</h1>
+      <div class="lesson-header">
+        <p class="lesson">Emit your public JSON through dedicated DTO structs, not your internal types — <code>#[derive(Serialize)]</code> when the type's natural shape already matches the contract, and hand-write <code>impl Serialize</code> when you need to pin an exact shape the derive won't give you.</p>
+        <p class="tags"><button type="button" class="term tag" data-term="serde"><code>serde</code></button><button type="button" class="term tag" data-term="serde"><code>Serialize</code></button><span class="tag"><code>wire-contract</code></span></p>
+        <p class="meta">2026-06-08 · +1071/−38 · <a href="https://github.com/nonrational/adjacent/pull/22">View PR</a></p>
+      </div>
+      <h2>The situation</h2><p>Every read command (<code>adj list</code>, <code>status</code>, <code>logs</code>) grew a <code>--json</code> flag, and the output is a <em>documented, stable</em> schema — <code>crates/adj/JSON.md</code> is the contract, and the test suite asserts the exact keys. The catch: the internal <code>AppState</code> enum already crosses the daemon's IPC socket as serde JSON, but the shape serde gives that enum is <em>not</em> the flat shape the public <code>--json</code> contract promises. The PR had to publish an exact documented shape without letting serde's internal enum encoding leak out as the public API.</p><h2>The Rust idea</h2><p><code>#[derive(Serialize)]</code> is a procedural macro. At compile time it reads a type's fields and <em>writes</em> an <code>impl Serialize</code> for you — attribute-driven code generation. You never see the generated code, but it's ordinary Rust, and <code>#[serde(...)]</code> attributes steer what it emits:</p><ul><li><code>#[serde(rename_all = "snake_case")]</code> — <code>Stdout</code> becomes <code>"stdout"</code> on the wire.</li><li><code>#[serde(tag = "kind")]</code> on an enum — each variant serializes as an object carrying a <code>kind</code> discriminator, e.g. <code>{"kind":"running","pid":…,"port":…}</code>.</li><li><code>#[serde(skip_serializing_if = "Option::is_none")]</code> — omit the field entirely when the check passes.</li></ul><p>That derived encoding is faithful and <em>reversible</em> — it round-trips cleanly back through <button type="button" class="term" data-term="serde"><code>Deserialize</code></button>, which is exactly what you want for a type you both send and receive (the daemon's IPC). But it is welded to the type's internal structure. Rename a variant, add a field, switch the tag representation, and the JSON moves with it. That's fine for an internal wire format both ends rebuild from the same crate. It's a landmine for a <em>public</em> contract that outside <code>jq</code> scripts depend on.</p><p>The discipline is a <strong>DTO</strong> — a data-transfer object, a struct whose only job is the wire shape, separate from the type it borrows from. Two cases:</p><ol><li>When the DTO's natural derived shape already equals the contract, derive it and move on.</li><li>When it doesn't — you need a flat object, a hoisted field, an enum rendered as a bare string — remember <button type="button" class="term" data-term="serde"><code>Serialize</code></button> is just a trait. The derive is one implementation; you can write your own and emit exactly the keys the contract documents.</li></ol><p>This PR does both, side by side.</p><h2>In this PR</h2><p>The internal type is a tagged enum. It derives <button type="button" class="term" data-term="serde"><code>Serialize</code></button>/<button type="button" class="term" data-term="serde"><code>Deserialize</code></button> because it round-trips over IPC, and the new <code>started_at</code> is optional so old serialized state still deserializes:</p><pre><code class="language-rust">// crates/adj-protocol/src/lib.rs
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(tag = "kind", rename_all = "snake_case")]
+pub enum AppState {
+    Stopped,
+    Running {
+        pid: u32,
+        port: u16,
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        started_at: Option&lt;String&gt;,
+    },
+    Crashed { exit_code: i32 },
+}
+</code></pre><p>Serialized directly, an <code>AppState::Running</code> is <code>{"kind":"running","pid":…,"port":…}</code> — the <code>kind</code> tag, port nested inside the state object. But <code>JSON.md</code> documents <code>list</code> entries as <em>flat</em>: <code>{ "name": …, "path": …, "state": "running", "port": 53412 }</code>. <code>state</code> is a plain string; <code>port</code> sits at the top level and appears only when running. The derive can't produce that from <code>AppState</code> — so the PR introduces a DTO with a hand-written impl:</p><pre><code class="language-rust">// crates/adj-protocol/src/lib.rs
+#[derive(Debug, Clone)]
+pub struct ListEntryDto&lt;'a&gt; {
+    pub name: &amp;'a str,
+    pub path: &amp;'a str,
+    pub state: &amp;'a AppState,
+}
+
+impl&lt;'a&gt; Serialize for ListEntryDto&lt;'a&gt; {
+    fn serialize&lt;S: Serializer&gt;(&amp;self, serializer: S) -&gt; Result&lt;S::Ok, S::Error&gt; {
+        use serde::ser::SerializeMap;
+        let mut map = serializer.serialize_map(None)?;
+        map.serialize_entry("name", self.name)?;
+        map.serialize_entry("path", self.path)?;
+        map.serialize_entry("state", state_tag(self.state))?;
+        if let AppState::Running { port, .. } = self.state {
+            map.serialize_entry("port", port)?;
+        }
+        map.end()
+    }
+}
+</code></pre><p>Every documented key is written by hand, in order. <code>state</code> is flattened to a bare string by a small helper instead of the enum's tagged object:</p><pre><code class="language-rust">// crates/adj-protocol/src/lib.rs
+fn state_tag(state: &amp;AppState) -&gt; &amp;'static str {
+    match state {
+        AppState::Stopped =&gt; "stopped",
+        AppState::Running { .. } =&gt; "running",
+        AppState::Crashed { .. } =&gt; "crashed",
+    }
+}
+</code></pre><p>The <button type="button" class="term" data-term="match"><code>if let</code></button> is where "<code>port</code> present iff running" lives — it's a fact about the <em>contract</em>, expressed in the serializer, not a property serde could infer from the enum. The DTO borrows (<code>&amp;'a str</code>, <code>&amp;'a AppState</code>) rather than cloning, so producing the wire view costs nothing but the JSON text. <code>StatusDto</code> does the same for <code>status --json</code>, adding <code>pid</code> / <code>started_at</code> / <code>exit_code</code> per state.</p><p>Contrast the log record. Its natural flat shape <em>is</em> the contract, so the derive is enough — no hand-written impl:</p><pre><code class="language-rust">// crates/adj-protocol/src/lib.rs
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct LogRecord {
+    pub ts: String,
+    pub stream: LogStream,
+    pub line: String,
+}
+
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "snake_case")]
+pub enum LogStream {
+    Stdout,
+    Stderr,
+}
+</code></pre><p>That's the whole judgment call in one file: derive <code>LogRecord</code> (shape matches, and it round-trips back off disk), hand-write <code>ListEntryDto</code> (shape doesn't match, and it's write-only).</p><h2>Why it matters</h2><p>Slap <code>#[derive(Serialize)]</code> on <code>AppState</code> and hand it to <code>println!</code> and you've quietly published serde's <code>{"kind":"running",…}</code> nesting as your public API. It works, the tests pass, everyone's happy — until you rename a variant or restructure the enum six months later and every downstream <code>jq</code> pipeline breaks, with nothing in the type to warn you the shape was load-bearing. The DTO is the seam that decouples the contract from the type: <code>AppState</code> stays free to change, <code>ListEntryDto</code>'s impl stays pinned to <code>JSON.md</code>, and <code>json_output.rs</code> asserts the exact keys so drift shows up as a red test, not a support ticket. In a dynamically-typed language you'd assemble that dict by hand anyway; Rust's derive is convenient enough to tempt you into exposing the internal shape by accident, and the DTO is the deliberate "no, this is the wire format" boundary.</p><h2>Related lessons</h2><ul><li><strong>PR #16</strong> (<button type="button" class="term" data-term="arc"><code>Arc&lt;Mutex&lt;T&gt;&gt;</code></button>) — this same PR reuses that pattern to write the JSONL: the <code>LogWriter</code> wraps the file in <code>Arc&lt;Mutex&lt;tokio::fs::File&gt;&gt;</code> so the stdout and stderr reader tasks can append <code>LogRecord</code>s without racing.</li><li><strong>PR #19</strong> teaches the mirror image on the read side — <button type="button" class="term" data-term="derive-macro"><code>#[derive(Deserialize)]</code></button> and <button type="button" class="term" data-term="option"><code>Option</code></button> fields. Here <code>LogRecord</code> round-trips both ways; #22 is the <button type="button" class="term" data-term="serde"><code>Serialize</code></button> half, #19 the <button type="button" class="term" data-term="serde"><code>Deserialize</code></button> half.</li><li><strong>PR #40</strong> (generics) — the hand-written <code>fn serialize&lt;S: Serializer&gt;</code> is generic over the output format; that's the trait-bound machinery #40 covers, applied to serde's serializer.</li></ul><h2>Dig deeper</h2><ul><li><a href="https://serde.rs/derive.html">serde.rs — Using derive</a> — how <button type="button" class="term" data-term="derive-macro"><code>#[derive(Serialize, Deserialize)]</code></button> and the <code>#[serde(...)]</code> attributes drive codegen.</li><li><a href="https://serde.rs/impl-serialize.html">serde.rs — Implementing Serialize</a> — writing the trait by hand with <code>SerializeMap</code>, for the shapes the derive won't give you.</li></ul>
+    </article>
+  </div>
+  <script src="glossary.js"></script>
+  <script src="drawer.js" defer></script>
+</body>
+</html>
diff --git a/ent/lessons/24-single-flight-boot-gate.html b/ent/lessons/24-single-flight-boot-gate.html
new file mode 100644
index 0000000..94092a2
--- /dev/null
+++ b/ent/lessons/24-single-flight-boot-gate.html
@@ -0,0 +1,71 @@
+<!-- generated by build.mjs; edit docs/lessons/*.md -->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>PR #24 — Reverse proxy + lazy-boot + hostname routing</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@300;400;500;700&display=swap" rel="stylesheet">
+  <link rel="stylesheet" href="lessons.css">
+</head>
+<body>
+  <div class="frame">
+    <header>
+      <a class="wordmark" href="index.html"><span class="a">adj.ac</span><span class="slash">/</span><span class="b">ent</span></a>
+      <a class="back" href="index.html">all lessons</a>
+    </header>
+    <article>
+      <h1>PR #24 — Reverse proxy + lazy-boot + hostname routing</h1>
+      <div class="lesson-header">
+        <p class="lesson">To boot a resource exactly once under concurrent demand, gate it with a <em>per-key</em> lock and re-check the state after you acquire it — a short-lived map lock hands out the per-name lock, which one waiter holds across the slow work while the rest re-check and skip it.</p>
+        <p class="tags"><span class="tag"><code>single-flight</code></span><span class="tag"><code>per-key-mutex</code></span></p>
+        <p class="meta">2026-06-08 · +905/−0 · <a href="https://github.com/nonrational/adjacent/pull/24">View PR</a></p>
+      </div>
+      <h2>The situation</h2><p>The proxy lazy-boots an app on its first request. But a browser opening a page fires many requests at once — HTML, then a dozen assets — and an agent might hit the same host in parallel too. If each first-request naively booted the app, three concurrent hits would spawn three dev servers fighting over one port. That's a <em>thundering herd</em>: N callers all racing to create the same thing. The fix is <strong>single-flight</strong> — one boot runs, everyone else waits for it and reuses the result.</p><h2>The Rust idea</h2><p>Single-flight is a lock plus a <strong>double check</strong>. You check the state, and if the resource already exists you're done. If not, you take a lock, then check <em>again</em> — because another task may have finished the boot while you were waiting for the lock. Only if it's still missing do you do the work.</p><p>Two design choices make this fast:</p><ol><li><strong>Per-key locking, not a global lock.</strong> One <button type="button" class="term" data-term="mutex"><code>Mutex</code></button> guarding all boots would serialize <em>unrelated</em> apps: booting <code>site</code> would block the first request to <code>blog</code>. Instead we keep a <code>HashMap&lt;name, Arc&lt;Mutex&lt;()&gt;&gt;&gt;</code> — one lock per app name. Booting <code>site</code> and <code>blog</code> proceed independently; only concurrent boots of the <em>same</em> name serialize.</li></ol><ol><li><strong>Two lock granularities.</strong> The map itself needs a lock (two tasks might insert a new name at once). But you only hold the map lock long enough to look up or create the per-name lock, then you <code>.clone()</code> the <button type="button" class="term" data-term="arc"><code>Arc</code></button> and release the map. The slow part — the actual boot — is held under the per-name lock, not the map lock. If you held the map lock across the boot, you'd be back to a global lock and lose the whole point.</li></ol><p>The <code>Mutex&lt;()&gt;</code> guards <em>nothing</em> — its value is the empty tuple. It's a pure mutual-exclusion token; the thing being protected is the boot side effect, not any data inside the lock.</p><h2>In this PR</h2><p>The gate is a lock-of-locks. The map is behind one <button type="button" class="term" data-term="mutex"><code>Mutex</code></button>; each entry is an <code>Arc&lt;Mutex&lt;()&gt;&gt;</code> you can clone out and hold on its own:</p><pre><code class="language-rust">// crates/adj/src/proxy.rs
+#[derive(Default)]
+pub struct BootGate {
+    locks: Mutex&lt;HashMap&lt;String, Arc&lt;Mutex&lt;()&gt;&gt;&gt;&gt;,
+}
+
+impl BootGate {
+    async fn lock_for(&amp;self, name: &amp;str) -&gt; Arc&lt;Mutex&lt;()&gt;&gt; {
+        let mut map = self.locks.lock().await;
+        map.entry(name.to_string())
+            .or_insert_with(|| Arc::new(Mutex::new(())))
+            .clone()
+    }
+}
+</code></pre><p><code>lock_for</code> takes the map lock, gets-or-creates the per-name lock, clones the <button type="button" class="term" data-term="arc"><code>Arc</code></button>, and returns — the map guard drops at the end of the function, so the map is free again immediately. The caller now holds a clone of the per-name lock and can hold <em>it</em> for as long as the boot takes.</p><p><code>ensure_running</code> is the double check. A fast path avoids the lock entirely when the app is already hot, then the slow path serializes and re-checks:</p><pre><code class="language-rust">// crates/adj/src/proxy.rs
+async fn ensure_running(/* ... */) -&gt; Result&lt;u16, ProxyError&gt; {
+    // Fast path: already running. Skip taking the per-name lock to avoid head-of-line blocking
+    // when the app is hot.
+    if let AppState::Running { port, .. } = supervisor.state(name).await {
+        return Ok(port);
+    }
+
+    // ... look up the registry entry + config once, outside the lock ...
+
+    // Single-flight: serialize concurrent boot attempts for this name. The first holder runs the
+    // boot; later holders re-check state under the lock and find Running.
+    let name_lock = gate.lock_for(name).await;
+    let _guard = name_lock.lock().await;
+
+    if let AppState::Running { port, .. } = supervisor.state(name).await {
+        return Ok(port);
+    }
+
+    supervisor
+        .up(entry.path.clone(), cfg.clone())
+        .await
+        .map_err(ProxyError::Other)?;
+    // ... then poll until the child binds its port ...
+}
+</code></pre><p>Three requests for <code>flight.adj.ac</code> arrive together. All three miss the fast path. All three call <code>lock_for</code> and get the <em>same</em> <code>Arc&lt;Mutex&lt;()&gt;&gt;</code>. One wins <code>name_lock.lock().await</code> and boots; the other two block on <button type="button" class="term" data-term="async-await"><code>.await</code></button> (yielding their worker threads, not spinning). When the winner drops <code>_guard</code>, the next task acquires the lock, hits the re-check, sees <code>Running</code>, and returns the port without booting. The PR's integration test asserts exactly this: three concurrent first-requests, <code>assert_eq!(spawns, 1)</code>.</p><p>The <code>let _guard = ...</code> binding matters. The guard is held until the end of the function scope; naming it <code>_guard</code> (not <code>_</code>) keeps it alive. Bind it to a bare <code>_</code> and Rust drops it <em>immediately</em>, releasing the lock before the boot even starts — silently defeating the whole mechanism.</p><h2>Why it matters</h2><p>In a garbage-collected language you'd reach for a <code>ConcurrentHashMap.computeIfAbsent</code> or a library <code>singleflight</code> helper and mostly not think about the re-check. Do it by hand and the classic bug is checking state only <em>before</em> the lock: two tasks both see "stopped", both wait, both acquire the lock in turn, and both boot — the lock made them polite but didn't make the boot single. The second check, <em>inside</em> the lock, is the load-bearing line. The other trap is reaching for one global lock for simplicity, which quietly turns independent app boots into a queue. Per-key locking keeps unrelated work parallel; the double-check keeps related work single.</p><h2>Related lessons</h2><ul><li>PR #16 introduces the base <button type="button" class="term" data-term="arc"><code>Arc&lt;Mutex&lt;T&gt;&gt;</code></button> pattern this builds on — shared ownership across <button type="button" class="term" data-term="tokio-spawn"><code>tokio::spawn</code></button>ed tasks. Read that first; this lesson is the single-flight <em>variation</em> layered on top.</li></ul><h2>Dig deeper</h2><ul><li><a href="https://docs.rs/tokio/latest/tokio/sync/struct.Mutex.html"><code>tokio::sync::Mutex</code></a> — the async mutex used here; note the docs' guidance on holding a guard across <button type="button" class="term" data-term="async-await"><code>.await</code></button>, which is exactly what the boot lock does.</li></ul>
+    </article>
+  </div>
+  <script src="glossary.js"></script>
+  <script src="drawer.js" defer></script>
+</body>
+</html>
diff --git a/ent/lessons/29-deadlines-and-failure-enums.html b/ent/lessons/29-deadlines-and-failure-enums.html
new file mode 100644
index 0000000..f876624
--- /dev/null
+++ b/ent/lessons/29-deadlines-and-failure-enums.html
@@ -0,0 +1,87 @@
+<!-- generated by build.mjs; edit docs/lessons/*.md -->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>PR #29 — Readiness URL, wait-ready, and idle shutdown</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@300;400;500;700&display=swap" rel="stylesheet">
+  <link rel="stylesheet" href="lessons.css">
+</head>
+<body>
+  <div class="frame">
+    <header>
+      <a class="wordmark" href="index.html"><span class="a">adj.ac</span><span class="slash">/</span><span class="b">ent</span></a>
+      <a class="back" href="index.html">all lessons</a>
+    </header>
+    <article>
+      <h1>PR #29 — Readiness URL, wait-ready, and idle shutdown</h1>
+      <div class="lesson-header">
+        <p class="lesson">Bound async work two ways — thread a <code>deadline: Instant</code> through a poll loop, and wrap a single hang-prone <code>await</code> in <button type="button" class="term" data-term="timeout"><code>tokio::time::timeout</code></button> — then model the outcomes as a custom enum so each caller can react to <em>why</em> the wait ended, not just <em>that</em> it did.</p>
+        <p class="tags"><span class="tag"><code>tokio-timeout</code></span><span class="tag"><code>deadlines</code></span><span class="tag"><code>error-enum</code></span></p>
+        <p class="meta">2026-06-08 · +1102/−56 · <a href="https://github.com/nonrational/adjacent/pull/29">View PR</a></p>
+      </div>
+      <h2>The situation</h2><p>When a request arrives for a stopped app, the proxy lazy-boots it and holds the request until the app answers. That "wait until ready" is unbounded by nature: the app might take two seconds, or crash on startup, or accept the TCP connection but never write a byte. This PR pulled the wait into <code>readiness.rs</code>, added an optional <code>health_check_url</code> (poll for a 2xx instead of a bare TCP open), and shared the same code with the new <code>adj wait-ready</code> command. Both callers need the same thing: a wait that <em>always</em> ends, and an answer that says <em>how</em> it ended.</p><h2>The Rust idea</h2><p>Two distinct tools, because there are two distinct hangs to bound.</p><p><strong>Bounding the whole operation — a deadline.</strong> An <button type="button" class="term" data-term="instant"><code>Instant</code></button> is an absolute point on the monotonic clock. Compute it once (<code>now() + timeout</code>), thread it into the loop, and each pass checks <code>now() &gt;= deadline</code>. An absolute deadline stays fixed no matter how many times you re-enter the check; a relative "time remaining" would have to be recomputed on every iteration. This bounds the <em>sum</em> of many poll attempts.</p><p><strong>Bounding one attempt — <button type="button" class="term" data-term="timeout"><code>tokio::time::timeout</code></button>.</strong> A single <button type="button" class="term" data-term="async-await"><code>.await</code></button> can block forever — an HTTP GET to a socket that accepts but never responds never resolves. <code>tokio::time::timeout(dur, fut)</code> races <code>fut</code> against a timer and returns <code>Result&lt;T, Elapsed&gt;</code>: <code>Ok(value)</code> if the future finished first, <code>Err(Elapsed)</code> if the clock won. This bounds one attempt so a single hung probe can't stall the whole poll cadence.</p><p><strong>Modeling the outcome — a custom enum.</strong> You could return <code>Result&lt;u16, anyhow::Error&gt;</code>, but then "crashed" and "timed out" are both just strings, and a caller who wants to treat them differently is stuck matching on message text. Instead, define an enum with one variant per outcome. Now the caller <button type="button" class="term" data-term="match"><code>match</code></button>es on the variant, and — the payoff — a crash can <em>short-circuit</em> the poll loop instead of waiting out the full deadline.</p><h2>In this PR</h2><p>The outcome type. Note it's a plain <code>#[derive(Debug)]</code> enum — no <code>thiserror</code>, no <code>Display</code>, no <code>std::error::Error</code> impl. It never needs one: it's an internal signal that each caller matches immediately and translates into its own error surface.</p><pre><code class="language-rust">// crates/adj/src/readiness.rs
+#[derive(Debug)]
+pub enum ReadinessError {
+    /// The supervisor reports the app is not running and the deadline passed before it bound
+    /// its port (or the configured health URL never returned 2xx).
+    Timeout,
+    /// The supervised process exited non-zero while we were waiting.
+    Crashed { exit_code: i32 },
+}
+</code></pre><p>The wait itself takes the <code>deadline</code> as a parameter and polls. The <code>Crashed</code> arm returns <em>immediately</em> — that's the whole reason the enum earns its keep:</p><pre><code class="language-rust">// crates/adj/src/readiness.rs
+pub async fn wait_ready(
+    name: &amp;str,
+    supervisor: &amp;Supervisor,
+    cfg: &amp;AppConfig,
+    deadline: tokio::time::Instant,
+) -&gt; Result&lt;u16, ReadinessError&gt; {
+    loop {
+        match supervisor.state(name).await {
+            AppState::Running { port, .. } =&gt; {
+                if probe_once(port, cfg.health_check_url.as_deref()).await {
+                    return Ok(port);
+                }
+                if tokio::time::Instant::now() &gt;= deadline {
+                    return Err(ReadinessError::Timeout);
+                }
+                tokio::time::sleep(READY_POLL_INTERVAL).await;
+            }
+            AppState::Crashed { exit_code } =&gt; {
+                return Err(ReadinessError::Crashed { exit_code });
+            }
+            AppState::Stopped =&gt; {
+                if tokio::time::Instant::now() &gt;= deadline {
+                    return Err(ReadinessError::Timeout);
+                }
+                tokio::time::sleep(READY_POLL_INTERVAL).await;
+            }
+        }
+    }
+}
+</code></pre><p>Inside a single probe, <button type="button" class="term" data-term="timeout"><code>tokio::time::timeout</code></button> bounds the one <code>await</code> that could hang forever — an app that completes the TCP handshake but never writes a response:</p><pre><code class="language-rust">// crates/adj/src/readiness.rs
+    tokio::time::timeout(Duration::from_millis(500), attempt)
+        .await
+        .ok()
+        .flatten()
+        .unwrap_or(false)
+</code></pre><p><code>timeout(...)</code> yields <code>Result&lt;Option&lt;bool&gt;, Elapsed&gt;</code>. <button type="button" class="term" data-term="combinators"><code>.ok()</code></button> drops the <code>Elapsed</code> into <code>Option&lt;Option&lt;bool&gt;&gt;</code>, <code>.flatten()</code> collapses the nesting, and <code>.unwrap_or(false)</code> maps <em>both</em> failure shapes — the timer fired, or the request errored — to "not ready, poll again." A timed-out probe is not fatal; it just means try once more before the outer deadline.</p><p>The payoff lands at the callers, where the <em>same two variants</em> fan out to <em>different</em> surfaces. In the daemon's <code>wait-ready</code> handler each becomes a distinct CLI-facing message:</p><pre><code class="language-rust">// crates/adj/src/daemon.rs
+    match readiness_wait(&amp;name, supervisor.as_ref(), &amp;cfg, deadline).await {
+        Ok(_) =&gt; Ok(Response::Ok),
+        Err(ReadinessError::Timeout) =&gt; Err(anyhow!(
+            "app `{name}` did not become ready within {timeout:?}"
+        )),
+        Err(ReadinessError::Crashed { exit_code }) =&gt; Err(anyhow!(
+            "app `{name}` crashed while waiting for ready (exit {exit_code})"
+        )),
+    }
+</code></pre><p>The proxy's boot path matches the identical enum but maps <code>Timeout</code> to an HTTP 504 and <code>Crashed</code> to a 502. One outcome type, two error surfaces, zero string-sniffing.</p><h2>Why it matters</h2><p>Collapse <code>ReadinessError</code> back into a single <code>anyhow::Error</code> string and two things break. First, the boot path loses the short-circuit: a crash would fall through as "still not ready," and the proxy would poll a dead process until the 60-second deadline before finally giving up — a full minute of a user staring at a hung request for an app that died in the first 200ms. The <code>Crashed</code> variant is what lets the loop bail the instant the supervisor reports the exit. Second, without either bound — the outer deadline or the inner <code>timeout</code> — a never-ready app pins the request (or the <code>adj wait-ready</code> process) forever. A language with exceptions would let you <code>throw</code> on timeout, but you'd still be hand-rolling the "which failure was it" dispatch on message strings; the enum makes the answer a type the compiler checks you handled.</p><h2>Related lessons</h2><ul><li>PR #48 revisits the combinator move in this very file — <code>.ok().flatten().unwrap_or(false)</code> deliberately swallows the <code>Elapsed</code> and error cases because a failed probe is a <em>recovery</em>, not a mistake. #48 is about the opposite call: when swallowing an error is the wrong default.</li><li>PR #16 introduced the <code>Arc&lt;Supervisor&gt;</code> that <code>wait_ready</code> borrows as <code>&amp;Supervisor</code> — the shared, lock-guarded state the poll loop reads on every pass.</li><li>PR #52 later hardens the inner probe: the diff here relied on hyper's drop behavior to tear down the connection after a timed-out attempt, and #52 replaces that with an explicit task <code>abort()</code> — the cancellation counterpart to this lesson's timeout.</li></ul><h2>Dig deeper</h2><ul><li><a href="https://docs.rs/tokio/latest/tokio/time/fn.timeout.html"><button type="button" class="term" data-term="timeout"><code>tokio::time::timeout</code></button></a> — the future-vs-timer race and its <code>Result&lt;T, Elapsed&gt;</code> return.</li><li><a href="https://docs.rs/thiserror/latest/thiserror/"><code>thiserror</code></a> — reach for it the day <code>ReadinessError</code> needs a <code>Display</code> impl to cross an API boundary; here a plain <code>Debug</code> enum matched at the call site was enough.</li></ul>
+    </article>
+  </div>
+  <script src="glossary.js"></script>
+  <script src="drawer.js" defer></script>
+</body>
+</html>
diff --git a/ent/lessons/34-fix-landing-page-redirect.html b/ent/lessons/34-fix-landing-page-redirect.html
new file mode 100644
index 0000000..495280d
--- /dev/null
+++ b/ent/lessons/34-fix-landing-page-redirect.html
@@ -0,0 +1,40 @@
+<!-- generated by build.mjs; edit docs/lessons/*.md -->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>PR #34 — Fix landing-page redirect (adj.ac/ent)</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@300;400;500;700&display=swap" rel="stylesheet">
+  <link rel="stylesheet" href="lessons.css">
+</head>
+<body>
+  <div class="frame">
+    <header>
+      <a class="wordmark" href="index.html"><span class="a">adj.ac</span><span class="slash">/</span><span class="b">ent</span></a>
+      <a class="back" href="index.html">all lessons</a>
+    </header>
+    <article>
+      <h1>PR #34 — Fix landing-page redirect (adj.ac/ent)</h1>
+      <div class="lesson-header">
+        <p class="lesson">None — this PR ships no Rust. It fixes a broken client-side redirect on the static apex page (<code>/cent</code> → <code>/ent/</code>) and teaches how a zero-config <code>&lt;meta http-equiv="refresh"&gt;</code> bounce works, plus why the <code>/</code> in <code>adj.ac/ent</code> is a real URL path boundary rather than decoration.</p>
+        <p class="tags"><span class="tag"><code>redirects</code></span><span class="tag"><code>static-site</code></span><span class="tag"><code>html</code></span></p>
+        <p class="meta">2026-06-08 · +96/−5 · <a href="https://github.com/nonrational/adjacent/pull/34">View PR</a></p>
+      </div>
+      <h2>The situation</h2><p>The apex domain <code>adj.ac</code> serves a bare <code>index.html</code> whose only job is to bounce visitors to the real landing page. It redirected to <code>/cent</code> — a path that exists nowhere in the repo. One stray <code>c</code>, and the bounce dead-ended on a 404. This PR retargets the redirect to <code>/ent/</code> and fills in the real page underneath it.</p><h2>The idea (no Rust this time)</h2><p>A static site has no server code at the apex to emit an HTTP <code>301</code>/<code>302</code> redirect — issuing a real 3xx needs host-specific config (<code>.htaccess</code>, a Cloudflare <code>_redirects</code> file, etc.). The option that works on <em>any</em> dumb static host with zero config is a <strong>meta refresh</strong>: a tag in the HTML <code>&lt;head&gt;</code> that the browser parses and acts on.</p><pre><code class="language-html">&lt;!-- index.html (apex) --&gt;
+&lt;meta http-equiv="refresh" content="0; URL='/ent/'"&gt;
+&lt;link rel="canonical" href="https://adj.ac/ent/"&gt;
+</code></pre><p><code>content="0; URL='/ent/'"</code> reads as <em>wait 0 seconds, then navigate to <code>/ent/</code></em>. The <code>0</code> makes it immediate. Two details carry weight:</p><ul><li><strong>Root-relative, trailing slash.</strong> The leading <code>/</code> resolves from the domain root regardless of where the visitor entered. The trailing slash points at the <em>directory</em> <code>/ent/</code>, whose index (<code>ent/index.html</code>) the host serves. The old <code>/cent</code> was just a typo for <code>/ent</code> — but a redirect target is a plain string, so nothing flagged that the path didn't exist.</li><li><strong><code>rel="canonical"</code>.</strong> Meta-refresh shells look like duplicate content or a sneaky redirect to a crawler. The canonical link tells search engines "the real address is <code>/ent/</code> — index <em>that</em>, not this empty bouncer."</li></ul><h2>The pun is load-bearing on the path</h2><p><code>adj.ac/ent</code> read aloud is "adjacent." That only works because it is a <em>real</em> URL: <code>adj.ac</code> is the registered domain, <code>/</code> is the literal path separator, and <code>ent</code> is a genuine path beneath it. So the landing content has to live at <code>/ent/</code> for the joke to resolve — the brand depends on the file layout. The wordmark markup encodes the same three-part split:</p><pre><code class="language-html">&lt;!-- ent/index.html --&gt;
+&lt;h1 class="wordmark"&gt;&lt;span class="a"&gt;adj.ac&lt;/span&gt;&lt;span class="slash"&gt;/&lt;/span&gt;&lt;span class="b"&gt;ent&lt;/span&gt;&lt;/h1&gt;
+</code></pre><p>Domain in paper-white, slash in rule-gray, <code>ent</code> in accent — the styling makes the <code>/</code> read as a boundary, not a hyphen. (CLAUDE.md locks this: the split is <code>adj.ac</code> + <code>ent</code>, <em>never</em> <code>adj</code> + <code>ac.ent</code>, and "the <code>/</code> is the URL path boundary.")</p><h2>The one tooling detail</h2><p><code>.tool-versions</code> gains a line:</p><pre><code># .tool-versions
+rust 1.92.0
+nodejs 26.2.0
+</code></pre><p>The site is tooled through Node (<code>npx live-server</code>, per the <code>justfile</code>), so asdf pins a Node version alongside the Rust toolchain. Anyone building the landing page now gets the same runtime — the pin lives beside the compiler pin even though Cargo never touches the web frontend.</p><h2>Why it matters</h2><p>A meta refresh is the cheapest redirect that runs on any static host — no server, no config file. The cost is an extra round trip (fetch the shell, then fetch the target) and a weaker signal to search engines than a real <code>301</code>, which the canonical link partially repairs.</p><p>The failure this PR fixes is the one meta refresh makes easy: the target is a <em>string</em>, not a checked reference. <code>/cent</code> ships fine and silently dead-ends — nothing validates that the path exists until a human loads the page. Contrast a router written in code, where a route pointing at a missing handler often won't compile or will trip a test. A redirect string has no such safety net, so the typo survives all the way to production.</p><h2>Related lessons</h2><ul><li><strong>PR #46</strong> also ships no Rust and covers this same <code>ent/</code> landing page — but from the repo-layout angle: why the site sits <em>beside</em> the Cargo workspace so <code>cargo build</code> never sees it. This lesson is the redirect that <em>points at</em> that directory; #46 is where the directory lives.</li></ul><h2>Dig deeper</h2><ul><li><a href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta#http-equiv">MDN — <code>&lt;meta http-equiv&gt;</code>, the <code>refresh</code> value</a> — syntax, and why the spec discourages non-zero timers for accessibility.</li><li><a href="https://developers.google.com/search/docs/crawling-indexing/consolidate-duplicate-urls">Google Search Central — Consolidate duplicate URLs (<code>rel=canonical</code>)</a> — what the canonical link buys you on a bouncer page.</li></ul>
+    </article>
+  </div>
+  <script src="glossary.js"></script>
+  <script src="drawer.js" defer></script>
+</body>
+</html>
diff --git a/ent/lessons/36-docs-as-config-contract.html b/ent/lessons/36-docs-as-config-contract.html
new file mode 100644
index 0000000..218714e
--- /dev/null
+++ b/ent/lessons/36-docs-as-config-contract.html
@@ -0,0 +1,48 @@
+<!-- generated by build.mjs; edit docs/lessons/*.md -->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>PR #36 — Document `health_check_url`, `idle_timeout`, and `adj wait-ready` in README</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@300;400;500;700&display=swap" rel="stylesheet">
+  <link rel="stylesheet" href="lessons.css">
+</head>
+<body>
+  <div class="frame">
+    <header>
+      <a class="wordmark" href="index.html"><span class="a">adj.ac</span><span class="slash">/</span><span class="b">ent</span></a>
+      <a class="back" href="index.html">all lessons</a>
+    </header>
+    <article>
+      <h1>PR #36 — Document `health_check_url`, `idle_timeout`, and `adj wait-ready` in README</h1>
+      <div class="lesson-header">
+        <p class="lesson">None — this PR is pure README prose (+8/−1), no Rust code. The lesson is that user-facing docs <em>are</em> the config contract, and the Rust-ecosystem angle worth knowing is <strong>doctests</strong>: <code>cargo test</code> compiles and runs the ``<code>rust</code>`` examples in your doc comments, so documented examples can't silently rot.</p>
+        <p class="tags"><span class="tag"><code>docs-as-contract</code></span><span class="tag"><code>doctests</code></span></p>
+        <p class="meta">2026-06-08 · +8/−1 · <a href="https://github.com/nonrational/adjacent/pull/36">View PR</a></p>
+      </div>
+      <h2>The situation</h2><p>Three features already shipped — readiness probing, idle shutdown, and <code>adj wait-ready</code> — but the README didn't mention them. If a config key works in the code and isn't in the docs, nobody outside the codebase knows it exists. This PR closes that gap: three bullets plus two new lines in the example <code>adjacent.toml</code>.</p><h2>The idea (no Rust this time)</h2><p>For a config-driven tool, the README <em>is</em> the contract. A user reads the example <code>adjacent.toml</code>, copies it, and trusts that <code>idle_timeout = "30m"</code> does what the comment says. The docs aren't decoration on top of the behavior — for anyone who doesn't read the source, they <em>are</em> the behavior.</p><p>Which raises the perennial problem: prose drifts. Rename a key, change a default, and the README quietly lies until someone notices. Plain Markdown like this README has no defense against that — a human has to catch it.</p><h2>In this PR</h2><p>The diff adds the optional fields to the example config, with defaults called out in comments:</p><pre><code class="language-toml"># README.md
+name = "site"
+cmd = "npm run dev"           # must bind to $PORT
+
+# Optional:
+health_check_url = "/healthz" # poll for 2xx instead of TCP-open
+idle_timeout = "30m"          # stop after no requests (default "15m", or "off")
+</code></pre><p>And a bullet stating the contract in prose:</p><pre><code class="language-markdown">- Idle shutdown. Apps stop after no proxied requests for `idle_timeout`
+  (default `"15m"`, accepts `"30s"` / `"1h"` / `"off"`).
+</code></pre><p>Nothing here is compiled or tested. If someone later changes the default from <code>"15m"</code> to <code>"20m"</code> in the Rust code, this Markdown keeps claiming <code>"15m"</code> and no tool complains.</p><h2>Why it matters — the Rust angle</h2><p>Rust's answer to doc drift is the <strong>doctest</strong>. When you put a fenced ``<code>rust</code>`<code> block in a </code>///<code> doc comment, </code>cargo test` extracts it, compiles it, and runs it as a real test:</p><pre><code class="language-rust">/// Parses an idle-timeout string into a `Duration`.
+///
+/// ```
+/// # use adj::parse_timeout;
+/// assert_eq!(parse_timeout("30s").unwrap().as_secs(), 30);
+/// ```
+pub fn parse_timeout(s: &amp;str) -&gt; Result&lt;Duration, ParseError&gt; { /* ... */ }
+</code></pre><p>If the function signature changes or the behavior drifts, that example stops compiling or fails its assertion, and CI goes red. The documented example <em>cannot</em> silently rot, because it's also a test.</p><p>This README is plain Markdown, so it gets none of that — the diff doesn't demonstrate doctests, and honesty demands saying so. But the contrast is the lesson: a config table in prose is only as correct as the last human who read it; a doctest is correct as long as CI is green.</p><h2>Related lessons</h2><ul><li>PR #16 documents the supervised-app-with-logs flow — same "docs describe a contract the code enforces" shape, from the other direction.</li></ul><h2>Dig deeper</h2><ul><li><a href="https://doc.rust-lang.org/rustdoc/write-documentation/documentation-tests.html">rustdoc — Documentation tests</a> — how <code>cargo test</code> runs the examples in your docs, and the <code>#</code>-hidden-line trick shown above.</li></ul>
+    </article>
+  </div>
+  <script src="glossary.js"></script>
+  <script src="drawer.js" defer></script>
+</body>
+</html>
diff --git a/ent/lessons/37-signals-bypass-drop-cleanup.html b/ent/lessons/37-signals-bypass-drop-cleanup.html
new file mode 100644
index 0000000..3874a99
--- /dev/null
+++ b/ent/lessons/37-signals-bypass-drop-cleanup.html
@@ -0,0 +1,53 @@
+<!-- generated by build.mjs; edit docs/lessons/*.md -->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>PR #37 — Handle SIGTERM in daemon socket cleanup</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@300;400;500;700&display=swap" rel="stylesheet">
+  <link rel="stylesheet" href="lessons.css">
+</head>
+<body>
+  <div class="frame">
+    <header>
+      <a class="wordmark" href="index.html"><span class="a">adj.ac</span><span class="slash">/</span><span class="b">ent</span></a>
+      <a class="back" href="index.html">all lessons</a>
+    </header>
+    <article>
+      <h1>PR #37 — Handle SIGTERM in daemon socket cleanup</h1>
+      <div class="lesson-header">
+        <p class="lesson"><button type="button" class="term" data-term="drop"><code>Drop</code></button> runs on normal scope exit and panic unwinding, but a process killed by a signal skips destructors entirely — so external cleanup like unlinking a Unix socket has to be done explicitly in a <code>tokio::signal</code> handler.</p>
+        <p class="tags"><span class="tag"><code>tokio-signal</code></span><span class="tag"><code>drop</code></span><span class="tag"><code>graceful-shutdown</code></span></p>
+        <p class="meta">2026-06-08 · +15/−4 · <a href="https://github.com/nonrational/adjacent/pull/37">View PR</a></p>
+      </div>
+      <h2>The situation</h2><p>The daemon binds a Unix socket at <code>~/.adjacent/sock</code>. That's a real file on disk, and a stale one blocks the next boot — <code>UnixListener::bind</code> fails if the path already exists. The daemon already cleaned it up on Ctrl-C. But <code>brew services stop</code> and launchd don't send Ctrl-C (SIGINT); they send <strong>SIGTERM</strong>. So a service-managed shutdown left the socket behind, and the next start had to notice the corpse and remove it. This PR handles SIGTERM too, so the socket goes away cleanly on the shutdown path that actually ships.</p><h2>The Rust idea</h2><p>Rust's usual answer to "clean up a resource" is RAII: give the resource a type, put the teardown in a <button type="button" class="term" data-term="drop"><code>Drop</code></button> impl, and the compiler runs it for you when the value leaves scope. A <code>File</code> closes itself; a <code>MutexGuard</code> unlocks itself. You don't write cleanup at every early return, because <button type="button" class="term" data-term="drop"><code>Drop</code></button> is wired to <em>scope exit</em>.</p><p>Here's the catch that trips people coming from garbage-collected or exception-based languages: <strong><button type="button" class="term" data-term="drop"><code>Drop</code></button> only runs when Rust is in control of the exit.</strong> There are exactly two paths that run destructors — a value going out of scope normally, and stack unwinding during a <code>panic!</code>. A signal is neither. When the kernel delivers SIGTERM (or SIGINT) and the process takes the default action, it just <em>stops</em>. No stack unwinds. No <button type="button" class="term" data-term="drop"><code>Drop</code></button> fires. Whatever was living on the stack — including a <code>UnixListener</code> — is abandoned, and the OS reclaims memory and file descriptors, but it does <strong>not</strong> run your teardown logic or unlink a socket path you created.</p><p>So RAII cannot save you here. Even if you wrote a <button type="button" class="term" data-term="drop"><code>Drop</code></button> impl that removed the socket file, SIGTERM would walk right past it. The only way to react to a signal is to <em>ask</em> the runtime to tell you when one arrives, then do the cleanup yourself before you exit.</p><p>That's what <code>tokio::signal</code> is for. Two shapes matter:</p><ul><li><code>tokio::signal::ctrl_c()</code> returns a <strong>future</strong> that resolves once, when SIGINT arrives.</li><li><code>tokio::signal::unix::signal(SignalKind::terminate())</code> returns a <code>Result&lt;Signal&gt;</code> — a <strong>stream</strong> you poll with <code>.recv()</code>, because a signal can fire many times over a process's life.</li></ul><p>You want to react to <em>whichever</em> comes first, so you race them with <code>tokio::select!</code> — the async "wait on several things, wake on the first to complete" primitive.</p><h2>In this PR</h2><pre><code class="language-rust">// crates/adj/src/daemon.rs
+
+// Best-effort cleanup of the socket on shutdown signals so subsequent boots aren't blocked.
+// SIGTERM matters specifically for `brew services stop` / launchd-driven shutdown; SIGINT
+// covers interactive Ctrl-C in the foreground. Either signal triggers the same cleanup.
+let socket_for_signal = socket.clone();
+tokio::spawn(async move {
+    let mut sigterm = match tokio::signal::unix::signal(tokio::signal::unix::SignalKind::terminate()) {
+        Ok(s) =&gt; s,
+        Err(err) =&gt; {
+            tracing::warn!("failed to install SIGTERM handler: {err}");
+            return;
+        }
+    };
+    tokio::select! {
+        _ = tokio::signal::ctrl_c() =&gt; {}
+        _ = sigterm.recv() =&gt; {}
+    }
+    let _ = std::fs::remove_file(&amp;socket_for_signal);
+    std::process::exit(0);
+});
+</code></pre><p>Walking the lines that matter:</p><ul><li><strong>Installing the handler can fail</strong>, so <code>signal(...)</code> returns a <button type="button" class="term" data-term="result"><code>Result</code></button>. The <button type="button" class="term" data-term="match"><code>match</code></button> binds the <code>Signal</code> on success; on failure it warns and <code>return</code>s out of the task. That's deliberately best-effort — a daemon that can't install a SIGTERM handler should still serve requests, it just won't self-clean on that signal. (See PR #48 for the "warn, don't swallow" reflex.)</li><li><strong><code>tokio::select!</code></strong> races the two sources. Both arms have empty bodies (<code>{}</code>) — we don't care <em>which</em> signal woke us, only that one did. Whichever future resolves first, <code>select!</code> drops the other and control falls through to the shared cleanup below it. Without <code>select!</code> you'd <button type="button" class="term" data-term="async-await"><code>.await</code></button> one source and be deaf to the other.</li><li><strong>The cleanup is explicit and ordered</strong>: remove the socket file first, <em>then</em> exit. <code>let _ =</code> discards the <code>io::Result</code> from <code>remove_file</code> — if the file's already gone, there's nothing to fix.</li><li><strong><code>std::process::exit(0)</code></strong> is the punchline that proves the whole point. <code>process::exit</code> terminates immediately and <strong>also does not run destructors</strong> — it's the same "Rust isn't unwinding" situation the signal put us in. That's exactly why the <code>remove_file</code> call sits <em>above</em> it. If we were relying on <button type="button" class="term" data-term="drop"><code>Drop</code></button> for the socket, <code>exit(0)</code> would skip it just like SIGTERM would. Cleanup has to happen by hand, before the process is gone.</li></ul><h2>Why it matters</h2><p>The trap is assuming RAII is a universal cleanup guarantee. In a GC language you'd reach for a shutdown hook and hit the same wall from the other side; in Rust it's tempting to think "I'll put it in <button type="button" class="term" data-term="drop"><code>Drop</code></button>" and move on. But <button type="button" class="term" data-term="drop"><code>Drop</code></button> is a contract about <em>scopes</em>, not about <em>process lifetime</em>. Signals, <code>abort()</code>, <code>std::process::exit</code>, and a hard <code>SIGKILL</code> (which you can't catch at all) all end the process without unwinding. Any resource that outlives the process's memory — a file on disk, a lock file, a socket path, a row in a database marked "in use" — needs an explicit teardown on the paths where <button type="button" class="term" data-term="drop"><code>Drop</code></button> won't run. <code>tokio::signal</code> is how you get a chance to run that teardown for the signals you <em>can</em> catch.</p><h2>Related lessons</h2><ul><li><strong>PR #52</strong> is the exact converse of this one: it uses <button type="button" class="term" data-term="drop"><code>Drop</code></button> deliberately, as an RAII guard that aborts a background task when a value goes out of scope. Read them together — #52 shows <button type="button" class="term" data-term="drop"><code>Drop</code></button>'s reach (any normal scope exit, guaranteed), #37 shows its limit (a signal walks right past it).</li><li><strong>PR #16</strong> covers the <code>Arc&lt;Mutex&lt;…&gt;&gt;</code> sharing pattern; the same <code>socket.clone()</code> + <button type="button" class="term" data-term="move"><code>move</code></button> closure shape shows up here to hand the path into the spawned task.</li><li><strong>PR #48</strong> — the <code>match ... Err(err) =&gt; warn; return</code> arm is the "surface the error, don't swallow it" habit applied to handler installation.</li></ul><h2>Dig deeper</h2><ul><li><a href="https://docs.rs/tokio/latest/tokio/signal/index.html"><code>tokio::signal</code> module docs</a> — <code>ctrl_c</code>, the Unix <code>SignalKind</code> / <code>Signal::recv</code> stream API, and the caveats about async-signal-safety.</li><li><a href="https://doc.rust-lang.org/book/ch15-03-drop.html">The Rust Book, ch. 15.3</a> — Running Code on Cleanup with the <button type="button" class="term" data-term="drop"><code>Drop</code></button> Trait (what <button type="button" class="term" data-term="drop"><code>Drop</code></button> guarantees — and, by omission, what it doesn't).</li></ul>
+    </article>
+  </div>
+  <script src="glossary.js"></script>
+  <script src="drawer.js" defer></script>
+</body>
+</html>
diff --git a/ent/lessons/38-deterministic-async-tests.html b/ent/lessons/38-deterministic-async-tests.html
new file mode 100644
index 0000000..52bb404
--- /dev/null
+++ b/ent/lessons/38-deterministic-async-tests.html
@@ -0,0 +1,54 @@
+<!-- generated by build.mjs; edit docs/lessons/*.md -->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>PR #38 — Fix flaky proxy single-flight test and add CI workflow</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@300;400;500;700&display=swap" rel="stylesheet">
+  <link rel="stylesheet" href="lessons.css">
+</head>
+<body>
+  <div class="frame">
+    <header>
+      <a class="wordmark" href="index.html"><span class="a">adj.ac</span><span class="slash">/</span><span class="b">ent</span></a>
+      <a class="back" href="index.html">all lessons</a>
+    </header>
+    <article>
+      <h1>PR #38 — Fix flaky proxy single-flight test and add CI workflow</h1>
+      <div class="lesson-header">
+        <p class="lesson">A deterministic async test drives real concurrency and asserts on <em>observable state</em> you can count, not on timing — and when such a test still flakes, the flake is a real race in the code, not test noise.</p>
+        <p class="tags"><span class="tag"><code>#[tokio::test]</code></span><span class="tag"><code>test-determinism</code></span></p>
+        <p class="meta">2026-06-08 · +45/−16 · <a href="https://github.com/nonrational/adjacent/pull/38">View PR</a></p>
+      </div>
+      <h2>The situation</h2><p>A test fired three concurrent first-requests at a cold app and asserted two things: every request got <code>200</code>, and the app booted exactly once. It passed locally, then flaked in CI with a <code>502</code>. The obvious "fix" — sprinkle a <code>sleep</code>, bump a timeout — would have buried the problem. The real fix was one deletion in the proxy. The PR also added <code>.github/workflows/ci.yml</code> (build + test on every PR, toolchain pinned to 1.92.0, cargo cache) so flakes surface on a clean machine instead of only on someone's laptop.</p><h2>The Rust idea</h2><p><code>#[tokio::test]</code> is the async cousin of <code>#[test]</code>. A plain <code>#[test]</code> can't <button type="button" class="term" data-term="async-await"><code>.await</code></button> anything — there's no runtime to drive the futures. The macro wraps your <code>async fn</code> so it spins up a Tokio runtime, runs the test to completion, and tears the runtime down. That's all it does; the <em>discipline</em> is on you.</p><p>To test concurrency deterministically, two rules:</p><ol><li><strong>Drive real concurrent work.</strong> <code>tokio::task::spawn_blocking</code> hands each closure to a real OS thread, so three of them race for genuine. Don't simulate the race — cause it.</li><li><strong>Assert on observable state, never on timing.</strong> A <code>sleep(100ms)</code> is a <em>guess</em> that the system finished within 100ms. On a loaded CI box it didn't, and the test flakes. A count of lines in a file, or an HTTP status code, is a <em>fact</em>. Assert the fact.</li></ol><p>The test already did both. It spawns three real requests, then checks a spawn-counter file:</p><pre><code class="language-rust">// crates/adj/tests/proxy.rs  (existing test, unchanged by this PR)
+for h in handles {
+    let (status_line, body) = h.await.expect("join").expect("http_get");
+    assert!(status_line.contains(" 200 "), "status: {status_line}");
+}
+// ...
+assert_eq!(spawns, 1, "expected single boot, saw {spawns} spawns");
+</code></pre><p>So why flake? Because a correctly-written deterministic test that flakes is telling you the <em>code under test</em> has a race. Here it did.</p><h2>In this PR</h2><p>The proxy had a "fast path" that returned a port the instant the supervisor reported <code>Running</code> — skipping the readiness wait. But the supervisor flips to <code>Running</code> the moment it spawns the child shell, <em>before</em> the child has bound its port. A second concurrent request that hit the fast path in that window forwarded to a dead socket: <code>502</code>.</p><pre><code class="language-rust">// crates/adj/src/proxy.rs  —  removed (the flaky fast path)
+if let AppState::Running { port, .. } = supervisor.state(name).await {
+    return Ok(port);
+}
+</code></pre><p>The fix routes <em>every</em> request through the per-name lock and then <code>wait_ready</code>, which polls the app's real readiness (a TCP probe that actually connects) before returning:</p><pre><code class="language-rust">// crates/adj/src/proxy.rs  —  the fix
+// We intentionally do NOT short-circuit on a Running state outside the lock. The supervisor
+// flips state to Running the moment it spawns the child — before the child has bound its
+// port. [...] would forward to a port that wasn't accepting yet and get back a spurious 502.
+let name_lock = gate.lock_for(name).await;
+let _guard = name_lock.lock().await;
+
+if !matches!(supervisor.state(name).await, AppState::Running { .. }) {
+    supervisor.up(entry.path.clone(), cfg.clone()).await.map_err(ProxyError::Other)?;
+}
+// ...falls through to wait_ready before forwarding
+</code></pre><p>Notice the symmetry. The <em>test</em> waits on observable state (a spawn count), and the <em>fix</em> makes the proxy wait on observable state (a live TCP connection) instead of trusting a <code>Running</code> enum that leads reality by a few microseconds. Same principle on both sides: don't trust a signal that fires before the thing it signals is true.</p><h2>Why it matters</h2><p>In most languages the reflex for a flaky concurrency test is to add a delay until it goes green. That doesn't remove the race — it just widens the window so the race loses <em>most</em> of the time, and the <code>502</code> returns under production load when no test is watching. Rust doesn't save you from this; the discipline does. Assert facts you can count, drive the real race, and when a deterministic test flakes, hunt the bug in the code rather than padding the test. The single-line deletion here is the whole fix — the test was right all along.</p><h2>Related lessons</h2><ul><li><strong>PR #24</strong> built the per-name single-flight <code>BootGate</code> this test exercises — the <code>lock_for(name)</code> + re-check pattern is the code under test here.</li><li><strong>PR #16</strong> covers the <code>Arc&lt;Mutex&gt;</code> sharing that lets the supervisor state and boot gate be read from many concurrent request tasks at once.</li></ul><h2>Dig deeper</h2><ul><li><a href="https://docs.rs/tokio/latest/tokio/attr.test.html">Tokio docs — Testing</a> — what <code>#[tokio::test]</code> actually expands to, and its runtime flavors.</li><li><a href="https://doc.rust-lang.org/book/ch11-00-testing.html">The Rust Book, ch. 11</a> — writing and running tests.</li></ul>
+    </article>
+  </div>
+  <script src="glossary.js"></script>
+  <script src="drawer.js" defer></script>
+</body>
+</html>
diff --git a/ent/lessons/40-serve-https-local-ca.html b/ent/lessons/40-serve-https-local-ca.html
new file mode 100644
index 0000000..395215b
--- /dev/null
+++ b/ent/lessons/40-serve-https-local-ca.html
@@ -0,0 +1,65 @@
+<!-- generated by build.mjs; edit docs/lessons/*.md -->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>PR #40 — Serve HTTPS on :8443 via opt-in local CA</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@300;400;500;700&display=swap" rel="stylesheet">
+  <link rel="stylesheet" href="lessons.css">
+</head>
+<body>
+  <div class="frame">
+    <header>
+      <a class="wordmark" href="index.html"><span class="a">adj.ac</span><span class="slash">/</span><span class="b">ent</span></a>
+      <a class="back" href="index.html">all lessons</a>
+    </header>
+    <article>
+      <h1>PR #40 — Serve HTTPS on :8443 via opt-in local CA</h1>
+      <div class="lesson-header">
+        <p class="lesson">A generic function bounded by traits is compiled into a specialized copy per concrete type (monomorphization), so one serve loop drives both a plain <code>TcpStream</code> and a TLS-wrapped stream at zero runtime cost.</p>
+        <p class="tags"><button type="button" class="term tag" data-term="generics"><code>generics</code></button><span class="tag"><code>trait-bounds</code></span></p>
+        <p class="meta">2026-06-08 · +1242/−49 · <a href="https://github.com/nonrational/adjacent/pull/40">View PR</a></p>
+      </div>
+      <h2>The situation</h2><p>The daemon already ran an HTTP reverse proxy. This PR adds an HTTPS listener on <code>:8443</code> that terminates TLS with a locally-issued cert, then routes requests exactly like the HTTP path. The two listeners differ only at accept time: one hands back a raw TCP stream, the other a TLS stream wrapped around one. Everything after — read the request, look up the app, proxy it — is identical. The problem: how do you write that shared "everything after" once when the two streams are different concrete types?</p><h2>The Rust idea</h2><p>A <strong>generic function</strong> with <strong>trait bounds</strong> is Rust's answer. You write the body once against a type parameter <code>S</code>, and you constrain <code>S</code> to exactly the capabilities the body uses. The compiler then does <strong>monomorphization</strong>: for every concrete type you actually call the function with, it stamps out a separate, specialized copy with <code>S</code> replaced. <code>serve_plain::&lt;TcpStream&gt;</code> and <code>serve_plain::&lt;TlsStream&lt;TcpStream&gt;&gt;</code> become two real functions in the binary.</p><p>This is <em>static dispatch</em>. In Java or Go you'd take an interface parameter and pay a vtable lookup on every method call through it. Rust's monomorphized copies call the concrete methods directly — inlinable, no indirection, no per-call cost. You trade a little binary size (two copies) for speed. (Rust also offers <code>dyn Trait</code> for real dynamic dispatch when you <em>want</em> one function and are willing to pay the vtable; here, static is the right call.)</p><p>The bounds are not decoration — each one is load-bearing:</p><ul><li><code>AsyncRead + AsyncWrite</code> — the serve loop reads request bytes off the stream and writes the response back. Without both, <code>hyper</code>'s <code>serve_connection</code> won't accept the stream.</li><li><code>Unpin</code> — async I/O is poll-based and the runtime needs to move the stream around; <code>Unpin</code> promises it's safe to move even after polling has begun.</li><li><button type="button" class="term" data-term="send-sync"><code>Send</code></button> — the connection is driven inside <button type="button" class="term" data-term="tokio-spawn"><code>tokio::spawn</code></button>, which may run it on a different worker thread, so the stream must be safe to send across threads.</li><li><button type="button" class="term" data-term="static-lifetime"><code>'static</code></button> — the spawned task can outlive the stack frame that launched it, so <code>S</code> may not borrow anything shorter-lived.</li></ul><p>Drop any one bound and the code that <em>needs</em> that capability fails to compile. The bound list is the exact contract the body demands, checked at the call site, not at runtime.</p><h2>In this PR</h2><p>The shared loop, written once against a type parameter:</p><pre><code class="language-rust">// crates/adj/src/proxy.rs
+/// Run one HTTP/1.1 connection against the proxy's per-request handler. Parameterized over the
+/// underlying stream so the HTTP and HTTPS listeners share the same serve loop — the difference
+/// between them is purely accept-time framing.
+async fn serve_plain&lt;S&gt;(stream: S, sup: Arc&lt;Supervisor&gt;, gate: Arc&lt;BootGate&gt;)
+where
+    S: tokio::io::AsyncRead + tokio::io::AsyncWrite + Unpin + Send + 'static,
+{
+    let io = TokioIo::new(stream);
+    let service = service_fn(move |req: Request&lt;Incoming&gt;| {
+        // ... clone sup + gate, dispatch to handle(req, ...)
+    });
+    if let Err(err) = server_http1::Builder::new()
+        .serve_connection(io, service)
+        .with_upgrades()
+        .await
+    {
+        tracing::debug!("proxy connection ended: {err}");
+    }
+}
+</code></pre><p>The HTTP listener calls it with the raw accepted stream:</p><pre><code class="language-rust">// crates/adj/src/proxy.rs — inside run()
+tokio::spawn(async move {
+    serve_plain(stream, sup, gate).await;   // S = TcpStream
+});
+</code></pre><p>The HTTPS listener does the TLS handshake first, then hands the <em>wrapped</em> stream to the same function:</p><pre><code class="language-rust">// crates/adj/src/proxy.rs — inside run_https()
+let tls_stream = match acceptor.accept(stream).await {
+    Ok(s) =&gt; s,
+    Err(err) =&gt; {
+        tracing::debug!("tls handshake failed: {err}");
+        return;
+    }
+};
+serve_plain(tls_stream, sup, gate).await;    // S = TlsStream&lt;TcpStream&gt;
+</code></pre><p>Note there are no turbofish annotations at the call sites — the compiler infers <code>S</code> from the argument's type. The <code>TlsStream</code> that <code>tokio_rustls</code> produces already implements <code>AsyncRead + AsyncWrite + Unpin + Send</code>, so it satisfies the bounds and the identical body just works.</p><h2>Why it matters</h2><p>The alternative is copy-paste: a second serve loop for the TLS stream, byte-for-byte the same except the parameter type. Two copies drift. A bug fix or a <code>with_upgrades()</code> tweak lands in one and gets forgotten in the other. Generics collapse them into a single source of truth that the type system re-checks against every concrete stream you feed it.</p><p>A dynamically-typed language would let you pass either stream into one function and only find out at runtime — mid-request, on a live connection — that one of them can't do something the body assumed. Rust's bounds move that check to compile time: if a stream type is missing <button type="button" class="term" data-term="send-sync"><code>Send</code></button>, the <button type="button" class="term" data-term="tokio-spawn"><code>tokio::spawn</code></button> call site refuses to build. You cannot ship the broken combination.</p><h2>Related lessons</h2><ul><li>The <code>run_https</code> task is spawned best-effort (logs at <code>error!</code> and exits if the CA is missing, leaving HTTP and the control plane serving) — a small lesson in fault-isolated <code>tokio</code> tasks.</li></ul><h2>Dig deeper</h2><ul><li><a href="https://doc.rust-lang.org/book/ch10-01-syntax.html">The Rust Book, ch. 10.1</a> — Generic Data Types</li><li><a href="https://doc.rust-lang.org/book/ch10-02-traits.html">The Rust Book, ch. 10.2</a> — Traits: Defining Shared Behavior (see "Using Trait Bounds" and the note on monomorphization in ch. 10.1)</li></ul>
+    </article>
+  </div>
+  <script src="glossary.js"></script>
+  <script src="drawer.js" defer></script>
+</body>
+</html>
diff --git a/ent/lessons/41-raw-string-templated-doc.html b/ent/lessons/41-raw-string-templated-doc.html
new file mode 100644
index 0000000..cc6fd11
--- /dev/null
+++ b/ent/lessons/41-raw-string-templated-doc.html
@@ -0,0 +1,59 @@
+<!-- generated by build.mjs; edit docs/lessons/*.md -->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>PR #41 — Add `adj agent-instructions` command</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@300;400;500;700&display=swap" rel="stylesheet">
+  <link rel="stylesheet" href="lessons.css">
+</head>
+<body>
+  <div class="frame">
+    <header>
+      <a class="wordmark" href="index.html"><span class="a">adj.ac</span><span class="slash">/</span><span class="b">ent</span></a>
+      <a class="back" href="index.html">all lessons</a>
+    </header>
+    <article>
+      <h1>PR #41 — Add `adj agent-instructions` command</h1>
+      <div class="lesson-header">
+        <p class="lesson">A raw string literal (<code>r#"…"#</code>) bakes a whole multi-line document into the binary verbatim — no escaping, no external file — and <button type="button" class="term" data-term="format-macro"><code>format!</code></button>'s in-scope capture (<code>{name}</code>) splices in the dynamic fields, so the template ships <em>inside</em> the binary and only the two live values are read at run time.</p>
+        <p class="tags"><span class="tag"><code>raw-string-literals</code></span><span class="tag"><code>format-macro</code></span><span class="tag"><code>string-templating</code></span></p>
+        <p class="meta">2026-06-08 · +783/−0 · <a href="https://github.com/nonrational/adjacent/pull/41">View PR</a></p>
+      </div>
+      <h2>The situation</h2><p><code>adj agent-instructions</code> prints a markdown steering doc telling a coding agent to drive the app through <code>adj</code> instead of running the dev command itself. The doc is mostly fixed prose with two holes: the app's <code>name</code> and its <code>cmd</code>, both read from <code>adjacent.toml</code>. The whole thing prints to stdout — no daemon, no template file on disk. So where does the boilerplate live, and how do the two fields get spliced in?</p><h2>The Rust idea</h2><p><strong>Raw string literals.</strong> An ordinary <code>"..."</code> string processes escapes: <code>\n</code> is a newline, <code>\t</code> a tab, and to put a literal <code>"</code> or <code>\</code> inside you have to escape it. That gets painful fast for a multi-line markdown doc full of backticks and <code>#</code> headers. A <em>raw</em> string turns escape processing off — <code>r"..."</code> treats every character between the quotes literally, backslashes and newlines included.</p><p>The <code>#</code> delimiters guard the ends: <code>r#"..."#</code> only terminates at the <code>"#</code> sequence, so a bare <code>"</code> inside the content won't close it early. Need to embed the sequence <code>"#</code> itself? Add more hashes — <code>r##"..."##</code>. This is the same tool you'd reach for with a regex or a Windows path, here holding a page of markdown exactly as it renders.</p><p>Because the literal is written directly in the source, it compiles into the binary's read-only data. The boilerplate is <em>self-contained</em> — there is no <code>template.md</code> to ship alongside <code>adj</code> and no file read at run time for the fixed text.</p><p><strong>Templating with <button type="button" class="term" data-term="format-macro"><code>format!</code></button>.</strong> The two dynamic fields are <code>{name}</code> and <code>{cmd}</code>. Since Rust 2021, <button type="button" class="term" data-term="format-macro"><code>format!</code></button> captures identifiers that are already in scope: <code>{name}</code> means "the local variable <code>name</code>," with no trailing <code>name = name</code> argument. That's why <code>render</code>'s parameters are <em>named</em> <code>name</code> and <code>cmd</code> to match the placeholders, and the <button type="button" class="term" data-term="format-macro"><code>format!</code></button> call has no arguments after the string.</p><h2>In this PR</h2><p>The template is a raw string literal; <button type="button" class="term" data-term="format-macro"><code>format!</code></button> fills the two holes (trimmed):</p><pre><code class="language-rust">// crates/adj/src/agent_docs.rs
+fn render(name: &amp;str, cmd: &amp;str) -&gt; String {
+    format!(
+        r#"# Working with `{name}` via Adjacent
+
+This project's dev server is supervised by **Adjacent** (`adj`). The agent does not
+start the server directly — `adj` lazy-boots it on the first proxied request, captures
+stdout/stderr to `~/.adjacent/logs/{name}.log`, and stops it on idle.
+
+## Don't run the dev command yourself
+
+Don't run `{cmd}` directly. Adjacent owns the process. Running it directly
+double-binds the port and Adjacent loses visibility into the log stream.
+// ... (adj status / logs / restart / wait-ready, verify loop) ...
+"#
+    )
+}
+</code></pre><p>The only thing read from disk at run time is the manifest, and only to pull <code>name</code> and <code>cmd</code> out of it — everything else is already in the binary:</p><pre><code class="language-rust">// crates/adj/src/agent_docs.rs
+pub fn emit(path: Option&lt;String&gt;) -&gt; Result&lt;()&gt; {
+    let dir: PathBuf = match path {
+        Some(p) =&gt; PathBuf::from(p),
+        None =&gt; std::env::current_dir().context("resolving current directory")?,
+    };
+    let cfg = registry::read_app_config(&amp;dir)?;
+    print!("{}", render(&amp;cfg.name, &amp;cfg.cmd));
+    Ok(())
+}
+</code></pre><p>One subtlety: <button type="button" class="term" data-term="format-macro"><code>format!</code></button> still treats <code>{</code> and <code>}</code> specially even inside a raw string, so a <em>literal</em> brace in the doc would have to be written <code>{{</code> or <code>}}</code>. This template has none, which is part of why the plain <button type="button" class="term" data-term="format-macro"><code>format!</code></button> stays readable.</p><h2>Why it matters</h2><p>Reach for a run-time read instead — <code>std::fs::read_to_string("template.md")</code> — and the binary grows a hidden dependency: the file has to exist at the right path when <code>adj</code> runs. Ship the binary on its own and the command breaks at run time with a "file not found," not at build time. Baking the text into the source removes that whole failure mode: if it compiled, the content is there.</p><p>The sibling technique for the <em>same</em> self-contained benefit is <button type="button" class="term" data-term="include-str"><code>include_str!</code></button>, which pulls an entire separate file's bytes in <strong>at compile time</strong> — best when the asset is large or edited by someone who shouldn't touch <code>.rs</code> files. This repo does exactly that for the dashboard HTML (<code>const HTML: &amp;str = include_str!("../assets/status.html")</code> in <code>status.rs</code>). For a two-field template a few dozen lines long, an inline raw string keeps the text next to the one function that formats it — no second file to keep in sync. Same "it's in the binary" guarantee, different call on where the source text lives.</p><h2>Related lessons</h2><ul><li>PR #48 covers the <button type="button" class="term" data-term="result"><code>Result</code></button> / <button type="button" class="term" data-term="question-mark"><code>?</code></button> / <code>anyhow::Context</code> machinery visible in <code>emit</code> here — the <code>.context(...)?</code> that turns a failed <code>current_dir()</code> into a labeled error instead of a silent one.</li><li>The <button type="button" class="term" data-term="include-str"><code>include_str!</code></button> route to a self-contained binary — embedding a <em>whole file</em> at compile time — shows up in the dashboard work (PR #45); this PR deliberately inlines a literal instead, so the two make a clean before/after on "when is the asset big enough to earn its own file?"</li></ul><h2>Dig deeper</h2><ul><li><a href="https://doc.rust-lang.org/reference/tokens.html#raw-string-literals">Rust Reference — Raw string literals</a> — the <code>r#"…"#</code> grammar and the multi-hash rule.</li><li><a href="https://doc.rust-lang.org/std/fmt/"><code>std::fmt</code></a> — <button type="button" class="term" data-term="format-macro"><code>format!</code></button> syntax, including captured identifiers (<code>{name}</code>) and escaping braces with <code>{{</code> / <code>}}</code>.</li><li><a href="https://doc.rust-lang.org/std/macro.include_str.html"><code>std::include_str!</code></a> — the sibling: embed an external file's contents into the binary at compile time.</li></ul>
+    </article>
+  </div>
+  <script src="glossary.js"></script>
+  <script src="drawer.js" defer></script>
+</body>
+</html>
diff --git a/ent/lessons/43-trait-as-extension-point.html b/ent/lessons/43-trait-as-extension-point.html
new file mode 100644
index 0000000..b389653
--- /dev/null
+++ b/ent/lessons/43-trait-as-extension-point.html
@@ -0,0 +1,71 @@
+<!-- generated by build.mjs; edit docs/lessons/*.md -->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>PR #43 — Move CA private key into the macOS Keychain and add nameConstraints</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@300;400;500;700&display=swap" rel="stylesheet">
+  <link rel="stylesheet" href="lessons.css">
+</head>
+<body>
+  <div class="frame">
+    <header>
+      <a class="wordmark" href="index.html"><span class="a">adj.ac</span><span class="slash">/</span><span class="b">ent</span></a>
+      <a class="back" href="index.html">all lessons</a>
+    </header>
+    <article>
+      <h1>PR #43 — Move CA private key into the macOS Keychain and add nameConstraints</h1>
+      <div class="lesson-header">
+        <p class="lesson">Implementing a trait a <em>library</em> defines lets you plug your own behavior into that library's machinery — here, <code>KeychainKey</code> implements rcgen's <code>RemoteKeyPair</code> so certificate signing calls out to the macOS Keychain and the private key never enters process memory.</p>
+        <p class="tags"><span class="tag"><code>trait-impl</code></span><span class="tag"><code>ffi</code></span></p>
+        <p class="meta">2026-06-09 · +682/−38 · <a href="https://github.com/nonrational/adjacent/pull/43">View PR</a></p>
+      </div>
+      <h2>The situation</h2><p>The local CA's private key used to sit at <code>~/.adjacent/ca.key</code> — a PEM file any backup tool or process running as the user could copy. This PR moves the key into the macOS login keychain, marked non-extractable, so the bytes never leave the OS. But rcgen — the crate that builds and signs the CA cert — normally expects to <em>hold</em> the private key and sign with it directly. How do you let rcgen produce a signed certificate when it can't have the key?</p><h2>The Rust idea</h2><p>rcgen anticipated exactly this and left a seam: a trait, <code>RemoteKeyPair</code>. A library that exposes a trait is saying "I don't need to own this behavior; give me anything that can do these three things and I'll call back into it." That's a trait used as an <strong>extension point</strong>. You don't subclass rcgen or fork it — you write a struct of your own and <em>implement its trait</em> for that struct. rcgen then drives your code without ever knowing what's behind it: an HSM, a cloud KMS, or in our case the macOS Keychain.</p><p><code>RemoteKeyPair</code> requires three methods — hand me the public key, tell me the signature algorithm, and sign these bytes. Fill all three and rcgen treats your type as a signer. The <code>sign</code> method is where the magic happens: rcgen calls it, and <em>your</em> implementation decides how the signature gets made. Ours forwards the request to the OS.</p><p>This is the mirror image of <a href="40-serve-https-local-ca.html">PR #40</a>. There, a trait was a <strong>bound</strong> on a generic — "I accept any <code>S</code> that can read and write" — resolved at compile time into a specialized copy per type (static dispatch). Here we go the other way: we <em>implement</em> a trait and hand rcgen a <code>Box&lt;dyn RemoteKeyPair&gt;</code>, a <strong>trait object</strong>. rcgen holds one boxed value and dispatches through a vtable at runtime, because it's compiled once and must work with signers it's never heard of. Same feature — traits — two opposite uses: constraining a caller vs. supplying a plug-in.</p><h2>In this PR</h2><p>The trait implementation. rcgen defines the three method signatures; we fill each with keychain-backed behavior:</p><pre><code class="language-rust">// crates/adj/src/tls/keychain.rs
+impl RemoteKeyPair for KeychainKey {
+    fn public_key(&amp;self) -&gt; &amp;[u8] {
+        &amp;self.public_bytes
+    }
+
+    fn algorithm(&amp;self) -&gt; &amp;'static SignatureAlgorithm {
+        &amp;PKCS_ECDSA_P256_SHA256
+    }
+
+    fn sign(&amp;self, msg: &amp;[u8]) -&gt; std::result::Result&lt;Vec&lt;u8&gt;, RcgenError&gt; {
+        self.private
+            .create_signature(Algorithm::ECDSASignatureMessageX962SHA256, msg)
+            .map_err(|cf_err| {
+                // rcgen's RemoteKeyError has no payload — log the CFError so it's not lost.
+                tracing::error!(error = %cf_err, "Keychain signing failed");
+                RcgenError::RemoteKeyError
+            })
+    }
+}
+</code></pre><p>Note <code>sign</code> returns rcgen's <code>Result&lt;Vec&lt;u8&gt;, RcgenError&gt;</code>, not our own error type — the trait dictates the shape, so we <code>map_err</code> the Keychain's error into the variant rcgen expects.</p><p>Handing the implementation to rcgen is one call. <code>Box::new(self)</code> puts our value on the heap as a trait object so rcgen can store it behind <code>dyn RemoteKeyPair</code>:</p><pre><code class="language-rust">// crates/adj/src/tls/keychain.rs
+pub fn into_rcgen_keypair(self) -&gt; Result&lt;KeyPair&gt; {
+    KeyPair::from_remote(Box::new(self))
+        .map_err(|e| anyhow!("constructing rcgen KeyPair from Keychain handle: {e}"))
+}
+</code></pre><p>From rcgen's side the key is now indistinguishable from any other. The cert-building code is untouched — <code>self_signed</code> reaches through the trait and calls our <code>sign</code> when it needs a signature:</p><pre><code class="language-rust">// crates/adj/src/tls.rs — generate_ca()
+let ca_handle = keychain::generate().context("creating Keychain CA key")?;
+let ca_key = ca_handle.into_rcgen_keypair()?;
+let params = build_ca_params();
+let signed = params
+    .self_signed(&amp;ca_key)          // rcgen calls KeychainKey::sign() in here
+    .context("self-signing CA cert")?;
+</code></pre><h3>Supporting detail: the <button type="button" class="term" data-term="unsafe-ffi"><code>unsafe</code></button> FFI seam</h3><p>Our <code>sign</code> bottoms out in Apple's C Security framework, and generating the key does too. That crossing is where <button type="button" class="term" data-term="unsafe-ffi"><code>unsafe</code></button> shows up. A C constant the Rust bindings didn't expose gets linked directly:</p><pre><code class="language-rust">// crates/adj/src/tls/keychain.rs
+extern "C" {
+    static kSecAttrIsExtractable: core_foundation_sys::string::CFStringRef;
+}
+</code></pre><p>And the raw call into the framework is wrapped in <button type="button" class="term" data-term="unsafe-ffi"><code>unsafe</code></button>:</p><pre><code class="language-rust">// crates/adj/src/tls/keychain.rs — create_random_key()
+let key_ref: SecKeyRef =
+    unsafe { SecKeyCreateRandomKey(params.as_concrete_TypeRef(), &amp;mut err) };
+</code></pre><p><button type="button" class="term" data-term="unsafe-ffi"><code>unsafe</code></button> here doesn't mean "dangerous" — it means <em>the compiler can't verify this</em>. Rust's guarantees (valid pointers, correct ownership, no data races) stop at the C boundary. The C framework might hand back a null pointer, or expect a specific retain/release discipline the borrow checker knows nothing about. <button type="button" class="term" data-term="unsafe-ffi"><code>unsafe</code></button> is you signing off: "I've read the framework's contract and I'm upholding it." It marks the exact lines where that promise lives, so a reader knows precisely where Rust's safety net ends and manual care begins.</p><h2>Why it matters</h2><p>The extension-point pattern is how you get library code to do something its authors never imagined — sign with a key they can't see — without touching their source. rcgen stays a dependency you pull from crates.io; the keychain integration lives entirely in your crate. The trait is the contract between them, and the compiler enforces that you honor it: leave out <code>sign</code>, or return the wrong error type, and it won't build.</p><p>A language without this seam would force a worse trade. You'd either fork rcgen to teach it about keychains, or pull the private key into memory so rcgen could sign the ordinary way — which is the exact thing this PR set out to prevent. The trait lets the key stay in the OS while rcgen does its job none the wiser.</p><h2>Related lessons</h2><ul><li><a href="40-serve-https-local-ca.html">PR #40</a> — the <em>other</em> face of traits: as a <strong>bound</strong> on a generic (static dispatch, monomorphized per type). Read side by side with this one to see constraining-a-caller vs. supplying-a-plug-in.</li></ul><h2>Dig deeper</h2><ul><li><a href="https://doc.rust-lang.org/book/ch10-02-traits.html">The Rust Book, ch. 10.2</a> — Traits: Defining Shared Behavior (implementing a trait on your own type; trait objects and <code>Box&lt;dyn Trait&gt;</code> are in ch. 18.2)</li><li><a href="https://doc.rust-lang.org/nomicon/ffi.html">The Rustonomicon, ch. on FFI</a> — calling C, <code>extern</code> blocks, and why the boundary is <button type="button" class="term" data-term="unsafe-ffi"><code>unsafe</code></button></li></ul>
+    </article>
+  </div>
+  <script src="glossary.js"></script>
+  <script src="drawer.js" defer></script>
+</body>
+</html>
diff --git a/ent/lessons/45-iterator-map-collect-rows.html b/ent/lessons/45-iterator-map-collect-rows.html
new file mode 100644
index 0000000..6f31329
--- /dev/null
+++ b/ent/lessons/45-iterator-map-collect-rows.html
@@ -0,0 +1,49 @@
+<!-- generated by build.mjs; edit docs/lessons/*.md -->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>PR #45 — Add built-in dashboard at status.adj.ac</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@300;400;500;700&display=swap" rel="stylesheet">
+  <link rel="stylesheet" href="lessons.css">
+</head>
+<body>
+  <div class="frame">
+    <header>
+      <a class="wordmark" href="index.html"><span class="a">adj.ac</span><span class="slash">/</span><span class="b">ent</span></a>
+      <a class="back" href="index.html">all lessons</a>
+    </header>
+    <article>
+      <h1>PR #45 — Add built-in dashboard at status.adj.ac</h1>
+      <div class="lesson-header">
+        <p class="lesson"><code>iter().map(f).collect()</code> is how you turn one collection into another — a lazy pipeline that does nothing until <button type="button" class="term" data-term="collect"><code>collect</code></button> drives it.</p>
+        <p class="tags"><span class="tag"><code>iterators</code></span><span class="tag"><code>map-collect</code></span></p>
+        <p class="meta">2026-06-09 · +817/−0 · <a href="https://github.com/nonrational/adjacent/pull/45">View PR</a></p>
+      </div>
+      <h2>The situation</h2><p>The dashboard at <code>status.adj.ac</code> polls <code>GET /apps.json</code> and gets back one JSON object per registered app. The daemon holds each app as an <code>AppSummary</code> (name, path, live state). The handler's job: take that list and produce a list of wire-shaped <code>DashboardEntry</code> objects to serialize. Classic "transform a collection into rendered rows."</p><h2>The Rust idea</h2><p>In many languages you'd write a <code>for</code> loop, build an empty array, and <code>push</code> each transformed item. Rust can do that too — but the idiomatic move is an <strong>iterator chain</strong>: <button type="button" class="term" data-term="iterator"><code>.iter()</code></button> to walk the collection, <code>.map(f)</code> to transform each element, <button type="button" class="term" data-term="collect"><code>.collect()</code></button> to gather the results into a new collection.</p><p>Two things make this worth learning:</p><p><strong>Iterators are lazy.</strong> <code>.map(f)</code> doesn't run <code>f</code> on anything. It returns a <code>Map</code> value that <em>remembers</em> what to do. Nothing happens until something pulls items through — here, <button type="button" class="term" data-term="collect"><code>.collect()</code></button>. That's why you can chain ten adapters and pay for zero of them until the final consumer runs. (In a test below, <code>.find()</code> is a consumer that stops early — it walks only as far as the first match.)</p><p><strong><button type="button" class="term" data-term="collect"><code>.collect()</code></button> builds the target type.</strong> The type you're collecting <em>into</em> drives it. Annotate the binding as <code>Vec&lt;DashboardEntry&gt;</code> and <button type="button" class="term" data-term="collect"><code>collect</code></button> fills a <button type="button" class="term" data-term="vec"><code>Vec</code></button>. The compiler infers the rest.</p><h2>In this PR</h2><p>The transform is one line — a pure, synchronous mapping:</p><pre><code class="language-rust">// crates/adj/src/status.rs
+let dtos: Vec&lt;DashboardEntry&gt; = entries.iter().map(dashboard_entry).collect();
+// ... then serde_json::to_vec(&amp;dtos) turns the Vec into the JSON body
+</code></pre><p><code>entries.iter()</code> yields <code>&amp;AppSummary</code>. <code>dashboard_entry</code> takes exactly that and returns a <code>DashboardEntry</code>, so it drops straight in as the map function — no closure needed. <button type="button" class="term" data-term="collect"><code>.collect()</code></button> gathers them into the <button type="button" class="term" data-term="vec"><code>Vec</code></button> the annotation asks for. Read it left to right: "for each summary, make a dashboard entry, gather them up."</p><p>Contrast that with the function that <em>builds</em> <code>entries</code> a few lines down:</p><pre><code class="language-rust">// crates/adj/src/status.rs
+async fn snapshot(supervisor: Arc&lt;Supervisor&gt;) -&gt; anyhow::Result&lt;Vec&lt;AppSummary&gt;&gt; {
+    let reg = Registry::load()?;
+    let mut entries = Vec::with_capacity(reg.apps.len());
+    for (name, entry) in &amp;reg.apps {
+        let state = supervisor.state(name).await;
+        entries.push(AppSummary {
+            name: name.clone(),
+            path: entry.path.display().to_string(),
+            state,
+        });
+    }
+    Ok(entries)
+}
+</code></pre><p>Why a plain <code>for</code> loop here and a <code>.map().collect()</code> there? Because this loop <button type="button" class="term" data-term="async-await"><code>.await</code></button>s <code>supervisor.state(name)</code> on every pass. A plain <button type="button" class="term" data-term="iterator"><code>.map()</code></button> closure can't <code>await</code> — its output would be a future, not a value — so an async transform falls back to the loop. The rule of thumb: <strong>synchronous, side-effect-free transform → iterator chain; anything that awaits or fails per-item → loop.</strong> The two idioms sit side by side in the same file, each used where it fits.</p><p>One efficiency note in the loop: <code>Vec::with_capacity(reg.apps.len())</code> pre-allocates for the known count, so the <code>push</code>es never trigger a reallocation + copy as the vector grows.</p><h2>Why it matters</h2><p><code>.iter().map(f).collect()</code> reads as a single intention — "these become those" — where a hand-rolled loop makes you track a mutable accumulator and read three lines to confirm it only ever appends. The laziness means chains stay cheap: no intermediate collection is materialized between adapters. And because <code>dashboard_entry</code> returns a <code>DashboardEntry&lt;'_&gt;</code> that <em>borrows</em> (<code>&amp;'a str</code>) from each <code>AppSummary</code> rather than cloning strings, the whole render is references until <code>serde_json::to_vec</code> walks them — the <code>entries</code> vector just has to outlive the serialize call.</p><p>The trap the chain sidesteps: reaching for it when the per-item work can fail or await. A <button type="button" class="term" data-term="iterator"><code>.map()</code></button> that returns <button type="button" class="term" data-term="result"><code>Result</code></button> leaves you holding a <code>Vec&lt;Result&lt;T, E&gt;&gt;</code> and no clean error path; that's exactly why <code>snapshot</code> stays a loop with <button type="button" class="term" data-term="question-mark"><code>?</code></button>. Match the tool to the shape of the work.</p><h2>Related lessons</h2><ul><li>PR #41 owns <button type="button" class="term" data-term="include-str"><code>include_str!</code></button> — the static HTML shell (<code>const HTML</code>) is embedded that way; this lesson is only about the <em>dynamic</em> JSON the iterator chain builds.</li><li>PR #16 — the <code>Arc&lt;Supervisor&gt;</code> threaded through <code>snapshot</code> and <code>handle</code> is the <code>Arc&lt;Mutex&gt;</code> sharing pattern.</li></ul><h2>Dig deeper</h2><ul><li><a href="https://doc.rust-lang.org/book/ch13-02-iterators.html">The Rust Book, ch. 13.2</a> — Processing a Series of Items with Iterators (laziness, <code>map</code>, <button type="button" class="term" data-term="collect"><code>collect</code></button>).</li><li><a href="https://doc.rust-lang.org/std/fmt/trait.Write.html"><code>std::fmt::Write</code></a> — the string-building cousin: when you <em>do</em> assemble text by hand, <code>write!</code>/<code>writeln!</code> append into one <button type="button" class="term" data-term="str-vs-string"><code>String</code></button> instead of allocating a fresh string per <button type="button" class="term" data-term="format-macro"><code>format!</code></button> + <code>+</code>.</li></ul>
+    </article>
+  </div>
+  <script src="glossary.js"></script>
+  <script src="drawer.js" defer></script>
+</body>
+</html>
diff --git a/ent/lessons/46-revamp-landing-positioning-page.html b/ent/lessons/46-revamp-landing-positioning-page.html
new file mode 100644
index 0000000..67ad0f1
--- /dev/null
+++ b/ent/lessons/46-revamp-landing-positioning-page.html
@@ -0,0 +1,67 @@
+<!-- generated by build.mjs; edit docs/lessons/*.md -->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>PR #46 — Revamp landing page into a positioning page</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@300;400;500;700&display=swap" rel="stylesheet">
+  <link rel="stylesheet" href="lessons.css">
+</head>
+<body>
+  <div class="frame">
+    <header>
+      <a class="wordmark" href="index.html"><span class="a">adj.ac</span><span class="slash">/</span><span class="b">ent</span></a>
+      <a class="back" href="index.html">all lessons</a>
+    </header>
+    <article>
+      <h1>PR #46 — Revamp landing page into a positioning page</h1>
+      <div class="lesson-header">
+        <p class="lesson">None — this PR has no Rust code. It's the <code>ent/</code> landing page (HTML/CSS). The lesson is how a single-binary Rust project carries a web frontend <em>beside</em> the Cargo workspace so the two never touch, and the one Rust-ecosystem convention the diff does hit: dual <code>MIT OR Apache-2.0</code> licensing.</p>
+        <p class="tags"><span class="tag"><code>repo-layout</code></span><span class="tag"><code>web-frontend</code></span><span class="tag"><code>dual-license</code></span></p>
+        <p class="meta">2026-06-09 · +341/−24 · <a href="https://github.com/nonrational/adjacent/pull/46">View PR</a></p>
+      </div>
+      <h2>The situation</h2><p>Adjacent needed a real landing page — not just a wordmark, but a <em>positioning page</em>: hero, problem statement, the four-command flow, design principles, status. A "positioning page" answers "what is this and why do I care" for a first-time visitor, versus a "coming soon" placeholder. The whole change lives in <code>ent/</code>, the project's static web frontend. No crate was rebuilt.</p><h2>The idea (no Rust this time)</h2><p>Adjacent is one Rust binary, <code>adj</code>. But the project also ships a website. The question every polyglot repo faces: <em>where do the web assets live so they don't leak into the build of the thing you actually compile?</em></p><p>Cargo's answer is the <strong>workspace membership list</strong>. Cargo only sees, compiles, and lints what <code>members</code> names. Anything else in the tree is invisible to it — a directory of HTML is just files on disk as far as <code>cargo build</code> is concerned. So the convention is: put the frontend in a <strong>sibling directory</strong> to <code>crates/</code>, and leave it out of <code>members</code>. It gets served or deployed by something else (here, eventually Cloudflare Pages), never bundled into the binary.</p><h2>In this PR</h2><p>The workspace lists two crates and nothing web-facing:</p><pre><code class="language-toml"># Cargo.toml
+[workspace]
+members = [
+    "crates/adj",
+    "crates/adj-protocol",
+]
+</code></pre><p>The site lives one level up from those crates, entirely outside that list:</p><pre><code>adjacent/
+├── crates/          # the Cargo workspace — what `adj` compiles
+│   ├── adj/
+│   └── adj-protocol/
+├── ent/             # the web frontend — Cargo never sees this
+│   ├── index.html
+│   └── favicon.svg
+└── index.html       # root redirect → /ent/
+</code></pre><p><code>ent/index.html</code> is where the 341 lines land — plain HTML with an inline <code>&lt;style&gt;</code> block, no build step. The positioning content is the new hero category line and the two-column problem statement:</p><pre><code class="language-html">&lt;!-- ent/index.html --&gt;
+&lt;p class="category"&gt;Adjacent is a local dev-server harness &amp;mdash; one supervised
+  dev server that you and your agent share, behind a real URL.&lt;/p&gt;
+
+&lt;section class="statement"&gt;
+  &lt;h2&gt;Your dev server has two developers now.&lt;/h2&gt;
+  &lt;div&gt;
+    &lt;p&gt;When you and your agent need the same local server, you evict each other.
+      The agent takes the process &amp;mdash; you lose the logs. You take it back
+      &amp;mdash; the agent can't verify its work.&lt;/p&gt;
+    &lt;p&gt;&lt;strong&gt;Adjacent supervises the server so neither of you has to own
+      it.&lt;/strong&gt; One daemon boots, routes and watches every app; both of you
+      talk to it through the same CLI.&lt;/p&gt;
+  &lt;/div&gt;
+&lt;/section&gt;
+</code></pre><p>The root-level <code>index.html</code> is a one-line redirect so <code>adj.ac/</code> lands on the real page at <code>adj.ac/ent/</code> — the <code>/ent</code> path split is the brand pun (<code>adj.ac</code> + <code>ent</code>), enforced by URL structure:</p><pre><code class="language-html">&lt;!-- index.html --&gt;
+&lt;meta http-equiv="refresh" content="0; URL='/ent/'"&gt;
+&lt;link rel="canonical" href="https://adj.ac/ent/"&gt;
+</code></pre><h3>The one Rust-ecosystem thing in the diff</h3><p><code>Cargo.toml</code> flips the license, and this <em>is</em> a Rust convention worth knowing:</p><pre><code class="language-toml"># Cargo.toml — before / after
+-license = "MIT"
++license = "MIT OR Apache-2.0"
+</code></pre><p>Rust itself, and the overwhelming majority of crates on crates.io, dual-license under <strong><code>MIT OR Apache-2.0</code></strong>. The SPDX <code>OR</code> means a downstream user picks either license — MIT for simplicity, Apache-2.0 for its explicit patent grant. It's the community default; publishing a crate under bare MIT reads as slightly off-convention. The PR added <code>LICENSE-MIT</code> and <code>LICENSE-APACHE</code> files to match, which is the expected on-disk layout for a dual-licensed Rust project.</p><h2>Why it matters</h2><p>Keep the frontend out of <code>members</code> and Cargo stays fast and honest: <code>cargo build</code> compiles only Rust, <code>cargo test</code> runs only Rust tests, and a broken bit of CSS can never fail a <code>cargo</code> command. Pull the site <em>into</em> the workspace — say, as a crate with a <button type="button" class="term" data-term="build-rs"><code>build.rs</code></button> that embeds the HTML — and now every landing-page tweak recompiles the binary and CI treats a copy edit like a code change. The sibling directory is the cheap, correct boundary.</p><p>On licensing: <code>MIT OR Apache-2.0</code> isn't cosmetic. The Apache-2.0 half carries an explicit patent grant that bare MIT lacks, and matching the ecosystem default is what lets other Rust projects depend on yours without a legal review.</p><h2>Related lessons</h2><ul><li>The <code>justfile</code> here also bumped <code>just serve</code> to <code>--port=8081</code> so live-server wouldn't collide with the proxy's default <code>:8080</code> — a small nod to the exact port-contention problem Adjacent exists to solve.</li></ul><h2>Dig deeper</h2><ul><li><a href="https://doc.rust-lang.org/cargo/reference/workspaces.html">The Cargo Book — Workspaces</a> — how <code>members</code> defines what Cargo compiles, and why a sibling directory stays invisible.</li><li><a href="https://rust-lang.github.io/api-guidelines/necessities.html#crate-and-its-dependencies-have-a-permissive-license-c-permissive">Rust API Guidelines — Necessities</a> — the <code>MIT OR Apache-2.0</code> dual-license convention, stated as a guideline.</li></ul>
+    </article>
+  </div>
+  <script src="glossary.js"></script>
+  <script src="drawer.js" defer></script>
+</body>
+</html>
diff --git a/ent/lessons/47-integration-tests-separate-crate.html b/ent/lessons/47-integration-tests-separate-crate.html
new file mode 100644
index 0000000..d605570
--- /dev/null
+++ b/ent/lessons/47-integration-tests-separate-crate.html
@@ -0,0 +1,55 @@
+<!-- generated by build.mjs; edit docs/lessons/*.md -->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>PR #47 — Document and test the docker run container convention</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@300;400;500;700&display=swap" rel="stylesheet">
+  <link rel="stylesheet" href="lessons.css">
+</head>
+<body>
+  <div class="frame">
+    <header>
+      <a class="wordmark" href="index.html"><span class="a">adj.ac</span><span class="slash">/</span><span class="b">ent</span></a>
+      <a class="back" href="index.html">all lessons</a>
+    </header>
+    <article>
+      <h1>PR #47 — Document and test the docker run container convention</h1>
+      <div class="lesson-header">
+        <p class="lesson">Every file under <code>crates/adj/tests/</code> is compiled as its <em>own</em> separate crate that links your code as an outside dependency — so it can only touch the public API, and for a binary-only crate that means driving the compiled executable via <code>CARGO_BIN_EXE_adj</code>.</p>
+        <p class="tags"><span class="tag"><code>integration-tests</code></span><span class="tag"><code>CARGO_BIN_EXE</code></span></p>
+        <p class="meta">2026-06-10 · +283/−0 · <a href="https://github.com/nonrational/adjacent/pull/47">View PR</a></p>
+      </div>
+      <h2>The situation</h2><p>The PR is honest about being two things: a README section documenting how to run a containerized app under Adjacent, plus one new integration test that proves the convention actually works. The test — <code>crates/adj/tests/docker.rs</code> — lazy-boots <code>traefik/whoami</code> through the proxy, asserts a 200, checks <code>docker ps</code> sees the container, then runs <code>adj down</code> and confirms the container is gone. That last assertion is the one that would catch a signal-forwarding regression.</p><p>To do all that, the test has to start a <em>real</em> <code>adj</code> daemon and talk to it exactly like a user would. That constraint isn't incidental — it falls straight out of how Rust organizes tests.</p><h2>The Rust idea</h2><p>Rust has two places tests live, and they are not interchangeable:</p><ol><li><strong>Unit tests</strong> — a <code>#[cfg(test)] mod tests { ... }</code> block <em>inside</em> a source file (e.g. <code>src/supervisor.rs</code>). This module is compiled as part of the same crate, so it can reach <em>private</em> functions, structs, and fields. Use it to test internals.</li></ol><ol><li><strong>Integration tests</strong> — each file in the top-level <code>tests/</code> directory. Here's the part that surprises people coming from other languages: <strong>Cargo compiles each of these files as its own independent crate</strong>, and that crate depends on yours the way any outside consumer would. It can only see <code>pub</code> items. Private internals are invisible to it, on purpose — an integration test proves the <em>public surface</em> works.</li></ol><p>Now the twist that makes <code>adj</code> interesting. <code>crates/adj</code> is a <strong>binary-only</strong> crate: its <code>Cargo.toml</code> declares a <code>[[bin]]</code> and there's no <code>lib.rs</code>. A binary exposes no library API to an external crate at all — there are no <code>pub fn</code>s to call. So the integration test can't link against <code>adj</code> and call functions. Instead it drives the compiled <code>adj</code> executable as a subprocess, the same as a shell would.</p><p>Cargo makes that ergonomic: when it builds the test, it sets an environment variable <code>CARGO_BIN_EXE_&lt;name&gt;</code> to the absolute path of the compiled binary. <code>env!(...)</code> reads it <em>at compile time</em>, so the path is baked in — no guessing at <code>target/debug/</code>, no <code>cargo build</code> ordering to manage.</p><h2>In this PR</h2><p>The test resolves the binary through that Cargo-provided variable:</p><pre><code class="language-rust">// crates/adj/tests/docker.rs
+fn adj_bin() -&gt; PathBuf {
+    PathBuf::from(env!("CARGO_BIN_EXE_adj"))
+}
+</code></pre><p>Because it's driving a real binary, it also stands up a real daemon — sandboxed into a throwaway <code>TempDir</code> via <code>ADJACENT_HOME</code>, on a random port via <code>ADJACENT_PROXY_PORT</code>, so the test never touches your actual <code>~/.adjacent/</code>:</p><pre><code class="language-rust">// crates/adj/tests/docker.rs
+fn cmd(&amp;self) -&gt; Command {
+    let mut c = Command::new(adj_bin());
+    c.env("ADJACENT_HOME", &amp;self.home_path);
+    c.env("ADJACENT_PROXY_PORT", self.proxy_port.to_string());
+    c.env("RUST_LOG", "warn");
+    c.env_remove("PORT");
+    c.env_remove("BIND_PORT");
+    c
+}
+</code></pre><p>The test itself is <button type="button" class="term" data-term="async-await"><code>async</code></button>, so it's annotated <code>#[tokio::test]</code> — the async cousin of <code>#[test]</code>, which spins up a Tokio runtime around the test body so you can <button type="button" class="term" data-term="async-await"><code>.await</code></button> inside it (here: awaiting daemon startup, subprocess output, and the container teardown poll):</p><pre><code class="language-rust">// crates/adj/tests/docker.rs
+#[tokio::test]
+async fn docker_run_lazy_boots_and_down_stops_the_container() {
+    if !docker_ready().await {
+        eprintln!("skipping: no reachable Docker daemon (or {IMAGE} unavailable)");
+        return;
+    }
+    // ... boot through the proxy, assert 200, then `adj down` and confirm gone
+}
+</code></pre><p>One more integration-test detail worth naming: this file uses <code>tempfile</code> and <code>tokio</code>, and both are available because <code>Cargo.toml</code> lists them under <code>[dev-dependencies]</code> — dependencies compiled only for tests and examples, never shipped in the release binary.</p><h2>Why it matters</h2><p>The unit-vs-integration split is a real design decision, not boilerplate. Reaching into private state from a <code>#[cfg(test)] mod tests</code> is convenient, but it tests the code you <em>wrote</em>, not the code your users <em>touch</em>. The separate-crate rule forces the integration layer to go through the front door: for a library that means calling only <code>pub</code> items; for a binary like <code>adj</code> it means shelling out to the actual executable. That's why this test can honestly claim to prove the documented container convention — it exercises the same <code>adj add</code> / proxy / <code>adj down</code> path a developer runs by hand, with nothing mocked and no private shortcut.</p><p>Skip the <code>CARGO_BIN_EXE_&lt;name&gt;</code> variable and you'd hardcode <code>target/debug/adj</code>, which breaks under <code>--release</code>, breaks on the CI runner's target dir, and silently runs a <em>stale</em> binary if you forget to rebuild. Letting Cargo hand you the path removes all three traps.</p><h2>Related lessons</h2><ul><li>PR #38 works inside this same <code>tests/</code> directory but teaches a different axis: making an async integration test <em>deterministic</em> (killing flakiness). This lesson is the layout — where tests live and what they can see; #38 is how to make one reliable once it's there.</li><li>PR #16 stood up the supervisor this test ultimately drives; the daemon it boots is the <code>Arc&lt;Mutex&lt;...&gt;&gt;</code> machinery taught there, exercised end-to-end from outside.</li></ul><h2>Dig deeper</h2><ul><li><a href="https://doc.rust-lang.org/book/ch11-03-test-organization.html">The Rust Book, ch. 11.3</a> — Test Organization (the unit-vs-integration split, the <code>tests/</code> directory, and testing binary crates)</li></ul>
+    </article>
+  </div>
+  <script src="glossary.js"></script>
+  <script src="drawer.js" defer></script>
+</body>
+</html>
diff --git a/ent/lessons/48-warn-dont-swallow-errors.html b/ent/lessons/48-warn-dont-swallow-errors.html
new file mode 100644
index 0000000..bb2e3c8
--- /dev/null
+++ b/ent/lessons/48-warn-dont-swallow-errors.html
@@ -0,0 +1,61 @@
+<!-- generated by build.mjs; edit docs/lessons/*.md -->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>PR #48 — Warn instead of silently defaulting on idle_timeout parse failure</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@300;400;500;700&display=swap" rel="stylesheet">
+  <link rel="stylesheet" href="lessons.css">
+</head>
+<body>
+  <div class="frame">
+    <header>
+      <a class="wordmark" href="index.html"><span class="a">adj.ac</span><span class="slash">/</span><span class="b">ent</span></a>
+      <a class="back" href="index.html">all lessons</a>
+    </header>
+    <article>
+      <h1>PR #48 — Warn instead of silently defaulting on idle_timeout parse failure</h1>
+      <div class="lesson-header">
+        <p class="lesson">A <button type="button" class="term" data-term="result"><code>Result</code></button> is a value you must consume, but combinators like <code>.unwrap_or(default)</code> let you throw the <button type="button" class="term" data-term="result"><code>Err</code></button> away — reach for <code>.unwrap_or_else(|err| …)</code> when the error is worth surfacing before you fall back.</p>
+        <p class="tags"><span class="tag"><code>result</code></span><span class="tag"><code>error-handling</code></span><button type="button" class="term tag" data-term="combinators"><code>combinators</code></button></p>
+        <p class="meta">2026-06-13 · +75/−2 · <a href="https://github.com/nonrational/adjacent/pull/48">View PR</a></p>
+      </div>
+      <h2>The situation</h2><p>A bad <code>idle_timeout</code> string in <code>adjacent.toml</code> (say <code>"10x"</code>) used to fall back to the 15-minute default without a peep. <code>idle_timeout_for</code> called <code>.unwrap_or(Some(DEFAULT_IDLE_TIMEOUT))</code> on the parse <button type="button" class="term" data-term="result"><code>Result</code></button>, discarding the parse error. Today that path is unreachable — <code>read_app_config</code> validates eagerly — but a future caller that skips validation would turn a config typo into a silent default. This PR keeps the fallback but makes it observable.</p><h2>The Rust idea</h2><p>Rust has no exceptions. A function that can fail returns <button type="button" class="term" data-term="result"><code>Result&lt;T, E&gt;</code></button> — an enum with two variants, <code>Ok(T)</code> and <code>Err(E)</code>. The failure is an ordinary value the caller holds in their hand, and the type system won't let you read the <code>T</code> without first acknowledging the <button type="button" class="term" data-term="result"><code>Err</code></button> might be there. That is the whole safety story: fallibility is visible in the signature and unavoidable at the call site.</p><p>But "unavoidable" is not the same as "surfaced." The standard library ships combinators that collapse a <button type="button" class="term" data-term="result"><code>Result</code></button> down to a plain value, and some of them drop the error on the floor:</p><ul><li><code>.unwrap_or(default)</code> — returns the <button type="button" class="term" data-term="result"><code>Ok</code></button> value, or <code>default</code> on <button type="button" class="term" data-term="result"><code>Err</code></button>. The <code>E</code> is never bound to anything; it's gone.</li><li><button type="button" class="term" data-term="combinators"><code>.ok()</code></button> — turns <button type="button" class="term" data-term="result"><code>Result&lt;T, E&gt;</code></button> into <button type="button" class="term" data-term="option"><code>Option&lt;T&gt;</code></button>, discarding <code>E</code>.</li><li><code>let Ok(x) = … else { … }</code> — the <code>else</code> arm can't see the error either.</li></ul><p>Each one is a legitimate tool and each one silently swallows the <button type="button" class="term" data-term="result"><code>Err</code></button>. The compiler is happy — you <em>did</em> handle the <button type="button" class="term" data-term="result"><code>Result</code></button> — so the type system stops nudging you the moment you pick a combinator that ignores the payload. Swallowing an error is a code smell precisely because it looks identical to handling it.</p><p>The fix is the lazy sibling: <code>.unwrap_or_else(|err| …)</code> takes a closure that receives the <button type="button" class="term" data-term="result"><code>Err</code></button> value. Now the error is bound to <code>err</code>, and you can log it, count it, or enrich it before returning your fallback. Same default, but the failure is no longer invisible.</p><p>(<code>_else</code> also means the fallback is computed lazily — the closure only runs on <button type="button" class="term" data-term="result"><code>Err</code></button> — but here the real win is getting your hands on <code>err</code>.)</p><h2>In this PR</h2><pre><code class="language-rust">// crates/adj/src/registry.rs
+
+// before:
+Some(s) =&gt; parse_idle_timeout(s).unwrap_or(Some(DEFAULT_IDLE_TIMEOUT)),
+
+// after:
+// Unreachable when callers go through `read_app_config`, which validates eagerly.
+// Warn loudly anyway so a future code path that skips validation can't turn a
+// config typo into a silent default.
+Some(s) =&gt; parse_idle_timeout(s).unwrap_or_else(|err| {
+    tracing::warn!(
+        idle_timeout = s,
+        error = %err,
+        default = ?DEFAULT_IDLE_TIMEOUT,
+        "invalid idle_timeout; falling back to default"
+    );
+    Some(DEFAULT_IDLE_TIMEOUT)
+}),
+</code></pre><p>The signature never changed — <code>idle_timeout_for</code> still returns <code>Option&lt;Duration&gt;</code>, so nothing downstream in <code>supervisor.rs</code> has to grow an error path. The only difference is that the <code>err</code> from <code>parse_idle_timeout</code> now flows into the closure instead of being dropped. <code>%err</code> formats it with <code>Display</code>, <code>?DEFAULT_IDLE_TIMEOUT</code> with <code>Debug</code> — both are <code>tracing</code>'s field syntax for capturing structured values.</p><p>The test pins the one observable change. Since the returned value is identical before and after, the assertion has to capture the log output:</p><pre><code class="language-rust">// crates/adj/src/registry.rs
+let resolved = tracing::subscriber::with_default(subscriber, || {
+    idle_timeout_for(&amp;cfg_with_idle_timeout(Some("10x")))
+});
+
+assert_eq!(resolved, Some(DEFAULT_IDLE_TIMEOUT));
+let logs = String::from_utf8(capture.0.lock().unwrap().clone()).unwrap();
+assert!(
+    logs.contains("invalid idle_timeout") &amp;&amp; logs.contains("10x") &amp;&amp; logs.contains("900s"),
+    "expected a warn naming the bad value and the default it fell back to, got: {logs}"
+);
+</code></pre><h2>Why it matters</h2><p>In a language with exceptions, the equivalent bug is a bare <code>catch (Exception e) {}</code> — the swallowed-error smell everyone recognizes. Rust doesn't force you to write that; it hands you a tidy one-liner (<code>.unwrap_or</code>) that does exactly the same thing and reads as intentional. The lesson is that Rust guarantees you <em>considered</em> the <button type="button" class="term" data-term="result"><code>Result</code></button>, not that you <em>surfaced</em> it. When the fallback is a real recovery worth keeping quiet about, <code>.unwrap_or</code> is fine. When the <button type="button" class="term" data-term="result"><code>Err</code></button> means "someone made a mistake" — a config typo, a malformed input — reach for <code>.unwrap_or_else</code> and at least say so on the way down.</p><h2>Related lessons</h2><ul><li>PR #49 tightens the <em>producer</em> side of this same function neighborhood: it makes <code>parse_idle_timeout</code> return a precise <button type="button" class="term" data-term="result"><code>Err</code></button> (rejecting zero durations with a message pointing at <code>off</code>). #48 is about not swallowing that <button type="button" class="term" data-term="result"><code>Err</code></button>; #49 is about making it worth reading.</li></ul><h2>Dig deeper</h2><ul><li><a href="https://doc.rust-lang.org/book/ch09-00-error-handling.html">The Rust Book, ch. 9</a> — Error Handling (<button type="button" class="term" data-term="result"><code>Result</code></button>, the <button type="button" class="term" data-term="question-mark"><code>?</code></button> operator, and when to recover vs. propagate)</li></ul>
+    </article>
+  </div>
+  <script src="glossary.js"></script>
+  <script src="drawer.js" defer></script>
+</body>
+</html>
diff --git a/ent/lessons/49-parse-dont-validate-actionable-errors.html b/ent/lessons/49-parse-dont-validate-actionable-errors.html
new file mode 100644
index 0000000..123ec2f
--- /dev/null
+++ b/ent/lessons/49-parse-dont-validate-actionable-errors.html
@@ -0,0 +1,56 @@
+<!-- generated by build.mjs; edit docs/lessons/*.md -->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>PR #49 — Reject zero idle_timeout with a pointer to off</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@300;400;500;700&display=swap" rel="stylesheet">
+  <link rel="stylesheet" href="lessons.css">
+</head>
+<body>
+  <div class="frame">
+    <header>
+      <a class="wordmark" href="index.html"><span class="a">adj.ac</span><span class="slash">/</span><span class="b">ent</span></a>
+      <a class="back" href="index.html">all lessons</a>
+    </header>
+    <article>
+      <h1>PR #49 — Reject zero idle_timeout with a pointer to off</h1>
+      <div class="lesson-header">
+        <p class="lesson">Push validation <em>into</em> the parser so an invalid value can't exist downstream — and spend the extra line making the <button type="button" class="term" data-term="result"><code>Err</code></button> message tell the user what to do instead.</p>
+        <p class="tags"><span class="tag"><code>parse-dont-validate</code></span><span class="tag"><code>error-handling</code></span><span class="tag"><code>result</code></span></p>
+        <p class="meta">2026-06-13 · +21/−0 · <a href="https://github.com/nonrational/adjacent/pull/49">View PR</a></p>
+      </div>
+      <h2>The situation</h2><p><code>idle_timeout = "0s"</code> used to parse cleanly into a zero <code>Duration</code>. That value then flowed into the idle scanner, which compares each app's idle age against its timeout every 500ms — a zero window means the app is <em>always</em> past its timeout, so it gets SIGTERM'd on the very next tick. The app quietly stops itself forever. This PR makes <code>parse_idle_timeout</code> reject zero at the door, and point the user at the thing they almost certainly meant: <code>"off"</code>.</p><h2>The Rust idea</h2><p><strong>"Parse, don't validate."</strong> There are two ways to handle an untrusted input.</p><ul><li><em>Validate:</em> accept it into your normal type (a <code>Duration</code>), then check <code>if dur.is_zero()</code> at each place that cares. The type says nothing — every consumer has to remember the rule, and a new call site can forget it.</li><li><em>Parse:</em> do the check once, at the boundary, and return a type that <em>cannot represent the bad state</em>. Downstream code holds a value that is correct by construction.</li></ul><p><code>parse_idle_timeout</code> returns <code>Result&lt;Option&lt;Duration&gt;&gt;</code>, and that type already encodes three distinct outcomes:</p><ul><li><code>Err(_)</code> — the input was malformed or nonsensical.</li><li><code>Ok(None)</code> — idle shutdown is explicitly disabled (<code>"off"</code>).</li><li><code>Ok(Some(d))</code> — a real, positive timeout.</li></ul><p>Before this PR, a fourth state leaked through: <code>Ok(Some(Duration::ZERO))</code>, a "valid" timeout that behaves like a self-destruct. Moving the <code>is_zero()</code> check <em>inside</em> the parser deletes that state. After the function returns <code>Ok(Some(d))</code>, every caller can trust <code>d</code> is non-zero without checking — the scanner never has to defend against a zero window, because one can't reach it.</p><p>The second half of the lesson is the <button type="button" class="term" data-term="result"><code>Err</code></button> itself. Rust's <button type="button" class="term" data-term="result"><code>Result</code></button> makes failure a value you must handle, but it says nothing about the <em>quality</em> of the error. <code>Err(anyhow!("invalid duration"))</code> is technically a failure and practically useless. An actionable message names what went wrong <strong>and</strong> what to do instead.</p><h2>In this PR</h2><p>The check sits at the end of the parser, right before the only <code>Ok(Some(...))</code> return:</p><pre><code class="language-rust">// crates/adj/src/registry.rs
+if dur.is_zero() {
+    return Err(anyhow!(
+        "idle_timeout of zero would stop the app on every idle scan; use `off` to disable idle shutdown"
+    ));
+}
+Ok(Some(dur))
+</code></pre><p>That message is the whole point. It has two clauses: the <em>consequence</em> ("would stop the app on every idle scan") so the user understands why zero is refused, and the <em>fix</em> ("use <code>off</code> to disable idle shutdown") so they know the exact next keystroke. <code>anyhow!</code> is the <code>anyhow</code> crate's macro for building an ad-hoc error from a format string — the same ergonomics as <button type="button" class="term" data-term="format-macro"><code>format!</code></button>, but it produces an <button type="button" class="term" data-term="result"><code>Err</code></button> value.</p><p>The doc comment is updated to explain the <em>why</em> for the next reader, not just the <em>what</em>:</p><pre><code class="language-rust">// crates/adj/src/registry.rs
+/// Zero durations are rejected: a zero window would make the app a permanent shutdown
+/// candidate (stopped on every scan tick), and users writing `"0s"` almost always mean
+/// "disable" — which is what `"off"` does.
+</code></pre><p>The test pins the contract — every zero unit is rejected, and the message steers toward <code>off</code>:</p><pre><code class="language-rust">// crates/adj/src/registry.rs
+#[test]
+fn rejects_zero_and_points_at_off() {
+    for raw in ["0s", "0ms", "0m", "0h"] {
+        let err = parse_idle_timeout(raw).unwrap_err();
+        assert!(
+            err.to_string().contains("use `off`"),
+            "error for {:?} should suggest `off`, got: {}",
+            raw,
+            err
+        );
+    }
+}
+</code></pre><p>Note what it asserts: not the whole string (brittle), but that the fix — <code>use </code>off`` — is present. The test guards the <em>actionable</em> part of the message specifically.</p><h2>Why it matters</h2><p>Because the check lives in the parser and <code>read_app_config</code> calls it eagerly, the error surfaces at <code>adj add</code> / <code>adj up</code> time — while the user is looking at their config — instead of manifesting hours later as a server that mysteriously won't stay up. That's the payoff of parse-don't-validate: the failure appears at the boundary, with full context, once. A language that let you pass a raw <code>Duration</code> around and hope every consumer re-checks it would push that failure deep into the runtime, far from the typo that caused it.</p><h2>Related lessons</h2><ul><li><strong>PR #48</strong> is the mirror image — the <em>consumer</em> side of this exact function. #48 is about not <em>swallowing</em> the <button type="button" class="term" data-term="result"><code>Err</code></button> that <code>parse_idle_timeout</code> returns (reach for <code>.unwrap_or_else</code> over <code>.unwrap_or</code>); #49 is about making that <button type="button" class="term" data-term="result"><code>Err</code></button> precise and worth reading in the first place. A good error is a handshake: the producer writes something actionable, the consumer bothers to surface it.</li><li><strong>PR #29</strong> covered error <em>enums</em> (giving failures distinct types). #49 is the complementary skill: even a stringly-typed <code>anyhow!</code> error earns its keep when the <em>message</em> tells the user what to do.</li></ul><h2>Dig deeper</h2><ul><li><a href="https://lexi-lambda.github.io/blog/2019/11/05/parse-don-t-validate/">Parse, don't validate</a> — the canonical essay. Written for Haskell, but the core move (make illegal states unrepresentable by choosing return types that exclude them) is exactly what the <code>Result&lt;Option&lt;Duration&gt;&gt;</code> signature does here.</li><li><a href="https://doc.rust-lang.org/book/ch09-00-error-handling.html">The Rust Book, ch. 9</a> — Error Handling: <button type="button" class="term" data-term="result"><code>Result</code></button>, the <button type="button" class="term" data-term="question-mark"><code>?</code></button> operator, and recoverable-vs-unrecoverable failure.</li></ul>
+    </article>
+  </div>
+  <script src="glossary.js"></script>
+  <script src="drawer.js" defer></script>
+</body>
+</html>
diff --git a/ent/lessons/50-weak-refs-self-cleaning-map.html b/ent/lessons/50-weak-refs-self-cleaning-map.html
new file mode 100644
index 0000000..5f8172a
--- /dev/null
+++ b/ent/lessons/50-weak-refs-self-cleaning-map.html
@@ -0,0 +1,57 @@
+<!-- generated by build.mjs; edit docs/lessons/*.md -->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>PR #50 — Proxy follow-ups: deadline timing, BootGate GC, NAT-replacement warning</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@300;400;500;700&display=swap" rel="stylesheet">
+  <link rel="stylesheet" href="lessons.css">
+</head>
+<body>
+  <div class="frame">
+    <header>
+      <a class="wordmark" href="index.html"><span class="a">adj.ac</span><span class="slash">/</span><span class="b">ent</span></a>
+      <a class="back" href="index.html">all lessons</a>
+    </header>
+    <article>
+      <h1>PR #50 — Proxy follow-ups: deadline timing, BootGate GC, NAT-replacement warning</h1>
+      <div class="lesson-header">
+        <p class="lesson">Store <button type="button" class="term" data-term="weak"><code>Weak</code></button> references as a map's values so the map garbage-collects itself — an entry lives only while some in-flight boot still holds the strong <button type="button" class="term" data-term="arc"><code>Arc</code></button>, and <button type="button" class="term" data-term="hashmap-retain"><code>HashMap::retain</code></button> sweeps the dead ones in one in-place pass.</p>
+        <p class="tags"><span class="tag"><code>weak-references</code></span><span class="tag"><code>hashmap-retain</code></span></p>
+        <p class="meta">2026-06-13 · +48/−6 · <a href="https://github.com/nonrational/adjacent/pull/50">View PR</a></p>
+      </div>
+      <h2>The situation</h2><p>The proxy's <code>BootGate</code> keeps one lock per app name so concurrent first-requests boot the app exactly once (that mechanism is PR #24). But the original map held an <code>Arc&lt;Mutex&lt;()&gt;&gt;</code> per name, and nothing ever removed entries. Every name the daemon ever routed left a permanent row in the map. The daemon is long-lived, and there is <strong>no app-removal RPC</strong> to hook a cleanup call onto — so the map only ever grew. A slow leak, but a leak. This PR makes the map bound itself to boots that are actually in flight.</p><h2>The Rust idea</h2><p><button type="button" class="term" data-term="arc"><code>Arc&lt;T&gt;</code></button> is a <em>strong</em> reference: as long as one <button type="button" class="term" data-term="arc"><code>Arc</code></button> exists, the value stays alive. <button type="button" class="term" data-term="weak"><code>Weak&lt;T&gt;</code></button> is a <em>non-owning</em> reference to the same value — it points at the data but does <strong>not</strong> count toward keeping it alive. When the last <button type="button" class="term" data-term="arc"><code>Arc</code></button> drops, the value is freed even if <button type="button" class="term" data-term="weak"><code>Weak</code></button>s still point at where it used to be.</p><p>Because a <button type="button" class="term" data-term="weak"><code>Weak</code></button> might be dangling, you can't dereference it directly. You call <code>.upgrade()</code>, which returns <code>Option&lt;Arc&lt;T&gt;&gt;</code>: <button type="button" class="term" data-term="option"><code>Some</code></button> if the value is still alive (and hands you a fresh strong ref), <button type="button" class="term" data-term="option"><code>None</code></button> if it's gone. That <button type="button" class="term" data-term="option"><code>Option</code></button> is Rust forcing you to handle "the thing I referenced no longer exists" — there is no way to accidentally touch freed memory.</p><p>Two more pieces the diff uses:</p><ul><li><code>Arc::downgrade(&amp;arc)</code> mints a <button type="button" class="term" data-term="weak"><code>Weak</code></button> from an <button type="button" class="term" data-term="arc"><code>Arc</code></button> — that's what you store in the map.</li><li><code>weak.strong_count()</code> asks how many strong <button type="button" class="term" data-term="arc"><code>Arc</code></button>s are still out there. Zero means the value is dead and the entry is garbage.</li><li><code>HashMap::retain(|k, v| bool)</code> walks every entry once and drops those where the closure returns <code>false</code>, editing the map <strong>in place</strong> — no rebuild, no second allocation.</li></ul><p>Put together: store <button type="button" class="term" data-term="weak"><code>Weak</code></button> values, and an entry becomes collectable the moment its last <button type="button" class="term" data-term="arc"><code>Arc</code></button> drops. <code>retain(|_, w| w.strong_count() &gt; 0)</code> is the sweep.</p><h2>In this PR</h2><p>The map's value type flips from <button type="button" class="term" data-term="arc"><code>Arc</code></button> to <button type="button" class="term" data-term="weak"><code>Weak</code></button>:</p><pre><code class="language-rust">// crates/adj/src/proxy.rs
+#[derive(Default)]
+pub struct BootGate {
+    locks: Mutex&lt;HashMap&lt;String, std::sync::Weak&lt;Mutex&lt;()&gt;&gt;&gt;&gt;,
+}
+</code></pre><p>And <code>lock_for</code> prunes on the way in, then either upgrades the surviving entry or mints a fresh lock:</p><pre><code class="language-rust">// crates/adj/src/proxy.rs
+async fn lock_for(&amp;self, name: &amp;str) -&gt; Arc&lt;Mutex&lt;()&gt;&gt; {
+    let mut map = self.locks.lock().await;
+    map.retain(|_, weak| weak.strong_count() &gt; 0);
+    if let Some(existing) = map.get(name).and_then(std::sync::Weak::upgrade) {
+        return existing;
+    }
+    let lock = Arc::new(Mutex::new(()));
+    map.insert(name.to_string(), Arc::downgrade(&amp;lock));
+    lock
+}
+</code></pre><p>Trace the lifetime. <code>lock_for</code> returns an <button type="button" class="term" data-term="arc"><code>Arc</code></button> — the caller in <code>ensure_running</code> holds it (<code>let name_lock = gate.lock_for(name).await;</code>) for the whole boot. So while a boot is in flight, at least one strong <button type="button" class="term" data-term="arc"><code>Arc</code></button> exists, <code>strong_count()</code> is <code>&gt; 0</code>, and the map entry survives <button type="button" class="term" data-term="hashmap-retain"><code>retain</code></button>. Concurrent requests for the <em>same</em> name <code>upgrade()</code> that same live <button type="button" class="term" data-term="weak"><code>Weak</code></button> and get the <em>same</em> <button type="button" class="term" data-term="arc"><code>Arc</code></button> back — single-flight identity is preserved (the new unit test asserts <code>Arc::ptr_eq(&amp;lock_a, &amp;lock_a2)</code>). Once the boot finishes and every caller drops its <button type="button" class="term" data-term="arc"><code>Arc</code></button>, <code>strong_count()</code> falls to zero, and the <em>next</em> <code>lock_for</code> call sweeps the dead entry. The map is now bounded by the number of boots happening right now, not by every name ever seen.</p><p>The new test spells out the whole arc — hold two locks, confirm neither is pruned while alive, drop them all, then confirm the next lookup collects them:</p><pre><code class="language-rust">// crates/adj/src/proxy.rs
+drop(lock_a);
+drop(lock_a2);
+drop(lock_b);
+// All strong refs gone — the next lock_for sweeps the dead entries.
+let _lock_c = gate.lock_for("c").await;
+let map = gate.locks.lock().await;
+assert_eq!(map.len(), 1);
+assert!(map.contains_key("c"));
+</code></pre><h2>Why it matters</h2><p>The trap is thinking of a map as a passive container and forgetting it's a <em>strong</em> owner. In the original code the <button type="button" class="term" data-term="hashmap"><code>HashMap</code></button> held <button type="button" class="term" data-term="arc"><code>Arc</code></button>s, so those apps could never be freed — the map itself was the reason they stayed alive. This is exactly the situation a garbage collector <em>can't</em> rescue you from either: a GC won't collect an object the map still strongly references, so a Java <button type="button" class="term" data-term="hashmap"><code>HashMap</code></button> here would leak the same way. The tool for "reference it, but don't be the reason it lives" is a weak reference — <button type="button" class="term" data-term="weak"><code>Weak&lt;T&gt;</code></button> in Rust, <code>WeakHashMap</code> in Java. Reaching for it turns an ever-growing map into a self-cleaning one, and the safety of <code>upgrade()</code> returning an <button type="button" class="term" data-term="option"><code>Option</code></button> means the "it might be gone" case is impossible to forget.</p><h2>Related lessons</h2><ul><li>PR #24 owns the single-flight boot itself — the per-name lock and the double-check that make concurrent first-requests boot an app exactly once. This lesson is the follow-up that stops the lock <em>map</em> from growing forever; read #24 first for what the map is <em>for</em>.</li><li>Same PR, second thread (monotonic time): <code>ensure_running</code> now captures its boot deadline as <code>let deadline = tokio::time::Instant::now() + boot_timeout;</code> <strong>before</strong> calling <code>up()</code>, so a slow spawn counts against the boot budget instead of being added on top of it. <button type="button" class="term" data-term="instant"><code>Instant</code></button> is a <em>monotonic</em> clock — it only moves forward and is immune to wall-clock jumps (NTP steps, DST), which is why it's the right type for a deadline. Prefer it over <button type="button" class="term" data-term="instant"><code>SystemTime</code></button> for measuring elapsed time, and reach for <code>saturating_duration_since</code> / checked arithmetic when subtracting two <button type="button" class="term" data-term="instant"><code>Instant</code></button>s so a reordering can't underflow.</li></ul><h2>Dig deeper</h2><ul><li><a href="https://doc.rust-lang.org/std/sync/struct.Weak.html"><code>std::sync::Weak</code></a> — <code>upgrade</code>, <code>strong_count</code>, and the <button type="button" class="term" data-term="arc"><code>Arc</code></button>/<button type="button" class="term" data-term="weak"><code>Weak</code></button> ownership split.</li><li><a href="https://doc.rust-lang.org/std/collections/struct.HashMap.html#method.retain"><button type="button" class="term" data-term="hashmap-retain"><code>HashMap::retain</code></button></a> — in-place filtering in a single pass.</li><li><a href="https://doc.rust-lang.org/std/time/struct.Instant.html"><code>std::time::Instant</code></a> — the monotonic clock behind the deadline math.</li></ul>
+    </article>
+  </div>
+  <script src="glossary.js"></script>
+  <script src="drawer.js" defer></script>
+</body>
+</html>
diff --git a/ent/lessons/51-typed-http-header-values.html b/ent/lessons/51-typed-http-header-values.html
new file mode 100644
index 0000000..6532af7
--- /dev/null
+++ b/ent/lessons/51-typed-http-header-values.html
@@ -0,0 +1,59 @@
+<!-- generated by build.mjs; edit docs/lessons/*.md -->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>PR #51 — Forward X-Forwarded-* headers from the proxy</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@300;400;500;700&display=swap" rel="stylesheet">
+  <link rel="stylesheet" href="lessons.css">
+</head>
+<body>
+  <div class="frame">
+    <header>
+      <a class="wordmark" href="index.html"><span class="a">adj.ac</span><span class="slash">/</span><span class="b">ent</span></a>
+      <a class="back" href="index.html">all lessons</a>
+    </header>
+    <article>
+      <h1>PR #51 — Forward X-Forwarded-* headers from the proxy</h1>
+      <div class="lesson-header">
+        <p class="lesson">In the <code>http</code> crate a header value is a <button type="button" class="term" data-term="newtype"><code>HeaderValue</code></button> — a validated byte-string newtype, not a <button type="button" class="term" data-term="str-vs-string"><code>String</code></button> — so building one is fallible (<code>HeaderValue::from_str</code> returns a <button type="button" class="term" data-term="result"><code>Result</code></button>), and that fallibility is how the type system blocks header injection.</p>
+        <p class="tags"><span class="tag"><code>newtypes</code></span><span class="tag"><code>typed-headers</code></span><span class="tag"><code>fallible-construction</code></span></p>
+        <p class="meta">2026-06-14 · +247/−13 · <a href="https://github.com/nonrational/adjacent/pull/51">View PR</a></p>
+      </div>
+      <h2>The situation</h2><p>The proxy rewrites the incoming <code>Host</code> header to <code>127.0.0.1:&lt;port&gt;</code> so upstream dev servers with host-allowlist checks accept the request. That rewrite erases the browser's real origin. This PR restores it with the three standard reverse-proxy headers — <code>X-Forwarded-Host</code>, <code>X-Forwarded-For</code>, <code>X-Forwarded-Proto</code> — so an app can still reconstruct where the request actually came from. To set them, the code has to <em>construct</em> header values, and that is where Rust's types show up.</p><h2>The Rust idea</h2><p>The <code>http</code> crate (re-exported through <code>hyper</code>) does not model headers as <code>HashMap&lt;String, String&gt;</code>. Keys are <code>HeaderName</code>, values are <button type="button" class="term" data-term="newtype"><code>HeaderValue</code></button>, and the collection is <code>HeaderMap</code>. A <button type="button" class="term" data-term="newtype"><code>HeaderValue</code></button> is a <strong>newtype</strong> wrapping validated bytes: a header value may not contain a carriage return, line feed, or NUL. Those are exactly the bytes an attacker would use to split one header into two — the classic header/response-injection attack. Encoding the rule in a type makes the illegal value <em>unrepresentable</em>: the only way to get a <button type="button" class="term" data-term="newtype"><code>HeaderValue</code></button> is through a constructor that checks.</p><p>So <strong>construction is fallible</strong>. <code>HeaderValue::from_str(s)</code> returns <code>Result&lt;HeaderValue, InvalidHeaderValue&gt;</code> — hand it a string with a stray <code>\r\n</code> and you get <button type="button" class="term" data-term="result"><code>Err</code></button>, never a poisoned value. When the input is a compile-time constant you already know is legal, <code>HeaderValue::from_static("http")</code> skips the runtime check and hands back a <button type="button" class="term" data-term="newtype"><code>HeaderValue</code></button> directly (no <button type="button" class="term" data-term="result"><code>Result</code></button> to unwrap; it only panics if <em>you</em> wrote an illegal literal).</p><p><strong>Reading is fallible too.</strong> <code>HeaderValue::to_str()</code> returns a <button type="button" class="term" data-term="result"><code>Result</code></button>, because the wrapped bytes are opaque and aren't guaranteed to be valid UTF-8 — a <button type="button" class="term" data-term="newtype"><code>HeaderValue</code></button> is not a Rust <button type="button" class="term" data-term="str-vs-string"><code>String</code></button>, so getting a <button type="button" class="term" data-term="str-vs-string"><code>&amp;str</code></button> back out can fail.</p><p>Contrast a <button type="button" class="term" data-term="str-vs-string"><code>String</code></button>-typed header map in Python, JS, or Go: nothing stops you writing a newline into a value, and the injection surfaces (if ever) as a runtime security bug. Rust makes the unsafe value impossible to build in the first place.</p><h2>In this PR</h2><p>The whole helper, from <code>crates/adj/src/proxy.rs</code>:</p><pre><code class="language-rust">// crates/adj/src/proxy.rs
+fn set_forwarded_headers(
+    headers: &amp;mut hyper::HeaderMap,
+    original_host: &amp;str,
+    client_ip: IpAddr,
+    proto: &amp;'static str,
+) {
+    if let Ok(v) = hyper::header::HeaderValue::from_str(original_host) {
+        headers.insert("x-forwarded-host", v);
+    }
+    // ...
+    let mut chain: Vec&lt;String&gt; = headers
+        .get_all("x-forwarded-for")
+        .iter()
+        .filter_map(|v| v.to_str().ok())
+        .map(str::to_string)
+        .collect();
+    chain.push(client_ip.to_string());
+    let xff = chain.join(", ");
+    if let Ok(v) = hyper::header::HeaderValue::from_str(&amp;xff) {
+        headers.insert("x-forwarded-for", v);
+    }
+    headers.insert(
+        "x-forwarded-proto",
+        hyper::header::HeaderValue::from_static(proto),
+    );
+}
+</code></pre><p>Three constructions, three different type stories:</p><ul><li><strong><code>from_str(original_host)</code> is fallible</strong>, so it's wrapped in <code>if let Ok(v)</code>. A malformed Host produces <button type="button" class="term" data-term="result"><code>Err</code></button>, the <code>insert</code> is skipped, and the request still forwards — the bad bytes never reach the socket.</li><li><strong><code>proto</code> is <code>"http"</code> or <code>"https"</code></strong>, both compile-time-safe, so it uses <code>from_static</code> — no <button type="button" class="term" data-term="result"><code>Result</code></button>. That's also <em>why</em> the parameter is typed <code>proto: &amp;'static str</code>: <code>from_static</code> demands a <code>&amp;'static str</code>, and the accept loops thread in string literals to satisfy it.</li><li><strong>Reading the existing chain uses <code>.to_str().ok()</code>.</strong> <code>to_str</code> is the read-side <button type="button" class="term" data-term="result"><code>Result</code></button>; <button type="button" class="term" data-term="combinators"><code>.ok()</code></button> inside <code>filter_map</code> drops any value that isn't valid UTF-8 instead of blowing up.</li></ul><p>One <code>HeaderMap</code> detail worth naming: <code>insert</code> <em>replaces</em> every existing value for a name, while <code>append</code> adds another line — a <code>HeaderMap</code> is a multimap that can hold several values under one key. The helper reads them all with <code>get_all</code> (not <code>get</code>, which would see only the first line), joins them, then <code>insert</code>s once to collapse the chain back to a single line.</p><h2>Why it matters</h2><p>Header injection is the trap this avoids. Picture the string-concatenation version: <code>"X-Forwarded-Host: " + original_host</code> written straight to the socket. A Host of <code>evil\r\nX-Admin: true</code> smuggles in a whole extra header. <code>HeaderValue::from_str</code> rejects the <code>\r\n</code> before it can ever become a value, and the diff's <code>if let Ok(v)</code> turns that rejection into "quietly skip the header," never "forward the attack." Nobody had to remember to sanitize — the type simply refuses to hold the dangerous bytes.</p><h2>Related lessons</h2><ul><li>PR #40 introduced the generic <code>serve_plain</code> that this PR threads <code>client_ip</code> and <code>proto</code> through — same file, same serve loop.</li><li>PR #48 is the same "a <button type="button" class="term" data-term="result"><code>Result</code></button> is a value you must handle" discipline, one layer up; here the fallible values are <code>HeaderValue::from_str</code> and <code>.to_str()</code>.</li></ul><h2>Dig deeper</h2><ul><li><a href="https://docs.rs/http/latest/http/header/struct.HeaderMap.html"><code>http::HeaderMap</code></a> — the multimap: <code>insert</code> vs <code>append</code>, <code>get</code> vs <code>get_all</code></li><li><a href="https://docs.rs/http/latest/http/header/struct.HeaderValue.html"><code>http::HeaderValue</code></a> — <code>from_str</code> (fallible), <code>from_static</code> (infallible), <code>to_str</code> (fallible read)</li></ul>
+    </article>
+  </div>
+  <script src="glossary.js"></script>
+  <script src="drawer.js" defer></script>
+</body>
+</html>
diff --git a/ent/lessons/52-abort-detached-tokio-tasks.html b/ent/lessons/52-abort-detached-tokio-tasks.html
new file mode 100644
index 0000000..c169538
--- /dev/null
+++ b/ent/lessons/52-abort-detached-tokio-tasks.html
@@ -0,0 +1,64 @@
+<!-- generated by build.mjs; edit docs/lessons/*.md -->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>PR #52 — Abort the readiness probe's connection task when the probe resolves</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@300;400;500;700&display=swap" rel="stylesheet">
+  <link rel="stylesheet" href="lessons.css">
+</head>
+<body>
+  <div class="frame">
+    <header>
+      <a class="wordmark" href="index.html"><span class="a">adj.ac</span><span class="slash">/</span><span class="b">ent</span></a>
+      <a class="back" href="index.html">all lessons</a>
+    </header>
+    <article>
+      <h1>PR #52 — Abort the readiness probe's connection task when the probe resolves</h1>
+      <div class="lesson-header">
+        <p class="lesson"><button type="button" class="term" data-term="tokio-spawn"><code>tokio::spawn</code></button> returns a <code>JoinHandle</code>, and <em>dropping</em> that handle detaches the task so it keeps running on its own — to stop a background task once you're done with it, hold the handle and call <code>.abort()</code> (a no-op if it already finished), and for the leak-proof version let a <button type="button" class="term" data-term="drop"><code>Drop</code></button> guard fire the abort on every exit path.</p>
+        <p class="tags"><span class="tag"><code>tokio-spawn</code></span><span class="tag"><code>join-handle-abort</code></span><span class="tag"><code>task-cancellation</code></span></p>
+        <p class="meta">2026-06-14 · +86/−5 · <a href="https://github.com/nonrational/adjacent/pull/52">View PR</a></p>
+      </div>
+      <h2>The situation</h2><p>The HTTP readiness probe (added in #29) opens a TCP connection to the app and speaks HTTP/1 through hyper. Hyper's client splits into two halves: a <code>sender</code> you push the request into, and a <code>conn</code> future that must be <em>driven</em> to actually pump bytes on the socket. The idiom is to <button type="button" class="term" data-term="tokio-spawn"><code>tokio::spawn</code></button> that <code>conn</code> future so it runs in the background while you await the response on <code>sender</code>.</p><p>But the whole probe is wrapped in a 500ms <button type="button" class="term" data-term="timeout"><code>tokio::time::timeout</code></button>. If the timer wins, the <code>attempt</code> future is dropped mid-flight — and that spawned connection task, which owns a real TCP socket, is left running with nobody watching it. This PR keeps a handle to that task and aborts it once the probe resolves, timeout or not, so the task and its socket can't outlive the probe.</p><h2>The Rust idea</h2><p>Two facts a newcomer needs about spawned tasks.</p><p>*<em>1. Dropping a <code>JoinHandle</code> does not stop the task — it </em>detaches<em> it.</em><em> <code>tokio::spawn(fut)</code> hands the future to the runtime and returns a <code>JoinHandle&lt;T&gt;</code>. Await the handle and you get the task's output. But here's the surprise if you're coming from threads, or from "a future is cancelled when you drop it": dropping the </em>handle* to a spawned task doesn't cancel anything. The task keeps running to completion on its own. A bare <code>tokio::spawn(...)</code> that throws the handle away is fire-and-forget — fine for work that finishes by itself, a leak for work that might not.</p><p><strong>2. Cancellation is explicit: <code>JoinHandle::abort()</code>.</strong> It doesn't kill the task synchronously. It flags the task so the runtime drops it at its next <button type="button" class="term" data-term="async-await"><code>.await</code></button> point (or never starts it, if it hadn't run yet). Dropping the task runs the destructors of everything it owns — here, the hyper <code>conn</code> and its TCP socket. And <code>abort()</code> on an already-finished task is a harmless no-op, so calling it unconditionally after the probe is always safe: either it reclaims a lingering task, or it does nothing.</p><p>The subtle part is <em>guaranteeing</em> the abort runs. If you call it by hand, every exit path has to reach that call — every early <code>return</code>, every <button type="button" class="term" data-term="question-mark"><code>?</code></button>, every panic. Miss one and the task leaks on that path. The RAII fix is the same one the language uses for locks and files: wrap the handle in a tiny struct whose <button type="button" class="term" data-term="drop"><code>Drop</code></button> impl calls <code>abort()</code>, so the compiler runs it at scope exit on <em>every</em> path.</p><pre><code class="language-rust">// Sketch — the general RAII form (not the exact shape #52 shipped; see below).
+struct AbortOnDrop(tokio::task::JoinHandle&lt;()&gt;);
+impl Drop for AbortOnDrop {
+    fn drop(&amp;mut self) {
+        self.0.abort();
+    }
+}
+</code></pre><p><button type="button" class="term" data-term="drop"><code>Drop</code></button> running on every normal exit is exactly what makes this leak-proof — and it's the flip side of PR #37, which is the deep dive on <button type="button" class="term" data-term="drop"><code>Drop</code></button>'s reach <em>and</em> its one blind spot (a signal walks right past it).</p><h2>In this PR</h2><p>The handle is parked on a slot declared <em>outside</em> both the <code>attempt</code> future and the <code>timeout</code>, so it survives even when the timer drops <code>attempt</code> mid-flight. <button type="button" class="term" data-term="option"><code>Option</code></button> because the spawn happens partway through <code>attempt</code> — the connect might fail with <button type="button" class="term" data-term="question-mark"><code>?</code></button> before we ever spawn, so the slot is <button type="button" class="term" data-term="option"><code>Some</code></button> only once we got far enough to have a task.</p><pre><code class="language-rust">// crates/adj/src/readiness.rs
+let mut conn_task: Option&lt;tokio::task::JoinHandle&lt;()&gt;&gt; = None;
+let attempt = async {
+    let addr = SocketAddr::from(([127, 0, 0, 1], port));
+    let stream = TcpStream::connect(addr).await.ok()?;
+    let io = TokioIo::new(stream);
+    let (mut sender, conn) = client_http1::handshake::&lt;_, Empty&lt;Bytes&gt;&gt;(io).await.ok()?;
+    conn_task = Some(tokio::spawn(async move {
+        let _ = conn.await;
+    }));
+    // ... build + send the request, read the status, drain the body ...
+    Some(status.is_success())
+};
+</code></pre><p>Parking the handle <em>outside</em> the timed-out future is the crux: the thing that owns the task has to outlive the thing that might get cancelled. Then, once the probe has resolved one way or another, the abort fires unconditionally:</p><pre><code class="language-rust">// crates/adj/src/readiness.rs
+let ready = tokio::time::timeout(Duration::from_millis(500), attempt)
+    .await
+    .ok()
+    .flatten()
+    .unwrap_or(false);
+// Abort unconditionally: a no-op once the task has finished, a cancellation (dropping the
+// socket) when the probe timed out or the probe completed while the connection lingered.
+if let Some(task) = conn_task {
+    task.abort();
+}
+ready
+</code></pre><p>Two honest notes on the shape it actually shipped:</p><ul><li><strong>It's a manual abort, not the <button type="button" class="term" data-term="drop"><code>Drop</code></button> guard from the sketch.</strong> That's fine <em>here</em> because <code>http_ready</code> has a single linear tail: nothing between the <code>timeout</code> resolving and the <code>if let ... abort()</code> can <code>return</code> early or <button type="button" class="term" data-term="question-mark"><code>?</code></button> out, so every path reaches the abort. The day a function grows several <button type="button" class="term" data-term="question-mark"><code>?</code></button> early returns between grabbing a task handle and finishing with it, that's the signal to promote this manual call into the <code>AbortOnDrop</code> guard — same story as a lock, where hand-written unlock works until someone adds an early return and the guard makes it structural.</li><li><strong>The PR couldn't even reproduce the leak.</strong> As the author's write-up notes, hyper 1.x happens to resolve the <code>conn</code> future when <code>sender</code> is dropped, so the detached task was already exiting on its own. The explicit <code>abort()</code> converts "cancellation that works by accident, because of a dependency's internals" into "cancellation we own" — and the two new tests pin the no-lingering-socket behavior against future hyper changes.</li></ul><h2>Why it matters</h2><p>The trap is reading <code>tokio::spawn(fut)</code> with the handle discarded as fire-and-forget <em>cleanup</em>, when it's the opposite: the task outlives the handle. Someone from a GC language expects the task to be collected once nothing references it; someone who's learned "drop a future to cancel it" gets bitten because a <em>spawned</em> task is detached, not a bare future. One leaked socket per probe, multiplied by a poll loop, is a genuine file-descriptor leak. Holding the <code>JoinHandle</code> and aborting it — ideally from a <button type="button" class="term" data-term="drop"><code>Drop</code></button> guard so no exit path can skip it — is how you make the background task's lifetime a strict subset of the work that needed it.</p><h2>Related lessons</h2><ul><li><strong>PR #29</strong> built the <button type="button" class="term" data-term="timeout"><code>tokio::time::timeout</code></button> this abort partners with. #29 bounds <em>how long</em> the probe waits; #52 cleans up <em>what the probe spawned</em> when that bound fires. Timeout + abort are the two halves of a cancel-safe async operation — the first stops waiting, the second stops the work.</li><li><strong>PR #37</strong> is the converse-and-complement on <button type="button" class="term" data-term="drop"><code>Drop</code></button>. #37: <button type="button" class="term" data-term="drop"><code>Drop</code></button> runs on normal scope exit and panic unwinding, but a signal skips it. #52: <em>because</em> <button type="button" class="term" data-term="drop"><code>Drop</code></button> runs on every normal exit path, it's the leak-proof home for an <code>abort()</code>. Read them together for the full map of what <button type="button" class="term" data-term="drop"><code>Drop</code></button> covers and what it doesn't.</li></ul><h2>Dig deeper</h2><ul><li><a href="https://docs.rs/tokio/latest/tokio/task/struct.JoinHandle.html#method.abort"><code>JoinHandle::abort</code></a> — the cancellation semantics, and the note that dropping a <code>JoinHandle</code> detaches (does not cancel) the task.</li><li><a href="https://doc.rust-lang.org/book/ch15-03-drop.html">The Rust Book, ch. 15.3</a> — Running Code on Cleanup with the <button type="button" class="term" data-term="drop"><code>Drop</code></button> Trait, the pattern behind the <code>AbortOnDrop</code> guard.</li></ul>
+    </article>
+  </div>
+  <script src="glossary.js"></script>
+  <script src="drawer.js" defer></script>
+</body>
+</html>
diff --git a/ent/lessons/53-http-upgrade-stream-splicing.html b/ent/lessons/53-http-upgrade-stream-splicing.html
new file mode 100644
index 0000000..d78c031
--- /dev/null
+++ b/ent/lessons/53-http-upgrade-stream-splicing.html
@@ -0,0 +1,58 @@
+<!-- generated by build.mjs; edit docs/lessons/*.md -->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>PR #53 — Propagate WebSocket upgrades through the proxy</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@300;400;500;700&display=swap" rel="stylesheet">
+  <link rel="stylesheet" href="lessons.css">
+</head>
+<body>
+  <div class="frame">
+    <header>
+      <a class="wordmark" href="index.html"><span class="a">adj.ac</span><span class="slash">/</span><span class="b">ent</span></a>
+      <a class="back" href="index.html">all lessons</a>
+    </header>
+    <article>
+      <h1>PR #53 — Propagate WebSocket upgrades through the proxy</h1>
+      <div class="lesson-header">
+        <p class="lesson">An HTTP <code>Upgrade</code> trades parsed HTTP framing for the raw byte stream underneath — you reserve that stream with <code>hyper::upgrade::on</code> <em>while you still own the request</em>, then splice both raw halves with <code>tokio::io::copy_bidirectional</code>.</p>
+        <p class="tags"><span class="tag"><code>http-upgrade</code></span><span class="tag"><code>copy-bidirectional</code></span><button type="button" class="term tag" data-term="ownership"><code>ownership</code></button></p>
+        <p class="meta">2026-06-14 · +238/−2 · <a href="https://github.com/nonrational/adjacent/pull/53">View PR</a></p>
+      </div>
+      <h2>The situation</h2><p>The proxy forwarded ordinary HTTP fine, but WebSocket requests (Vite/Webpack/Next HMR) died at the proxy boundary. A WebSocket starts as a normal GET carrying <code>Upgrade: websocket</code>; the app answers <code>101 Switching Protocols</code> and from that byte onward the connection is no longer HTTP — it's a raw, full-duplex byte stream. The proxy has to notice the handshake, let it through, then get out of the way and shovel bytes both directions until someone hangs up.</p><h2>The Rust idea</h2><p>An upgrade is a <strong>handoff</strong>. Normally <code>hyper</code> owns the socket and parses framed HTTP messages for you. After a 101 there are no more messages to parse — there's a raw TCP stream underneath that hyper is finished with. <code>hyper::upgrade::on(&amp;mut req)</code> hands you a <strong>future</strong> (<code>OnUpgrade</code>) that resolves to that raw stream <em>once the upgrade completes</em>. Think of it as a claim ticket: you reserve the stream now and collect it later.</p><p>Two Rust facts make the <em>timing</em> of that claim load-bearing:</p><ul><li><strong><code>send_request(req)</code> moves the request.</strong> Sending it upstream consumes <code>req</code> by value, and the upgrade handle lives inside the request's extension map. Once the request is moved, you can never reach back in for it. So you must claim the handle <em>before</em> the move — that's the only window where the server half is still yours.</li><li><strong>The downstream upgrade only resolves after you return the 101.</strong> hyper's server loop completes the client-side upgrade only once <code>forward</code> hands back the <code>101</code> response. So awaiting the downstream future inline — before returning — would wait for something that can't happen until you return. Deadlock. The fix is to <button type="button" class="term" data-term="tokio-spawn"><code>tokio::spawn</code></button> a detached task: return the 101, and let that task collect both halves whenever they're ready.</li></ul><p>Once you hold both raw streams, <code>tokio::io::copy_bidirectional(&amp;mut a, &amp;mut b)</code> runs the two copies concurrently — <code>a → b</code> and <code>b → a</code> — and returns when both directions hit EOF. It replaces a hand-rolled "spawn two copy loops and coordinate the shutdown" dance with one call.</p><h2>In this PR</h2><p>Claim the downstream handle up front, gated on the <code>Upgrade</code> header so non-upgrade requests pay nothing (<code>.then(|| …)</code> only runs the closure when the <code>bool</code> is <code>true</code>):</p><pre><code class="language-rust">// crates/adj/src/proxy.rs
+let downstream_upgrade = req
+    .headers()
+    .contains_key(hyper::header::UPGRADE)
+    .then(|| hyper::upgrade::on(&amp;mut req));
+</code></pre><p>Drive the upstream client connection <code>with_upgrades()</code> so a 101 doesn't tear it down — the upstream's raw half has to survive past the handshake for us to claim it too:</p><pre><code class="language-rust">// crates/adj/src/proxy.rs
+if let Err(err) = conn.with_upgrades().await {
+    tracing::debug!("upstream connection ended: {err}");
+}
+</code></pre><p>On a 101, splice the two raw streams in a <strong>detached</strong> task:</p><pre><code class="language-rust">// crates/adj/src/proxy.rs
+if resp.status() == StatusCode::SWITCHING_PROTOCOLS {
+    if let Some(downstream) = downstream_upgrade {
+        let upstream = hyper::upgrade::on(&amp;mut resp);
+        tokio::spawn(async move {
+            let (down, up) = match tokio::join!(downstream, upstream) {
+                (Ok(d), Ok(u)) =&gt; (d, u),
+                // ...
+            };
+            let mut down = TokioIo::new(down);
+            let mut up = TokioIo::new(up);
+            if let Err(err) = tokio::io::copy_bidirectional(&amp;mut down, &amp;mut up).await {
+                tracing::debug!("upgraded tunnel closed: {err}");
+            }
+        });
+    }
+}
+</code></pre><p><code>tokio::join!(downstream, upstream)</code> awaits both claim tickets concurrently and yields a tuple of <button type="button" class="term" data-term="result"><code>Result</code></button>s; only when both raw streams are in hand does the pump start. The <code>TokioIo::new</code> wrappers matter: hyper's upgraded stream speaks hyper's own IO traits, but <code>copy_bidirectional</code> is a tokio function expecting <code>AsyncRead + AsyncWrite</code>, so <code>TokioIo</code> adapts one to the other.</p><h2>Why it matters</h2><p>The trap is claiming the stream too late. It's natural to reach for the upgrade handle <em>after</em> you have the response — that's when a WebSocket "feels" established. But <code>send_request</code> already moved the request by then, and Rust's ownership rules make that a hard compile error, not a subtle runtime bug: the handle is simply gone. The type system forces you to grab it during the one valid window. The second trap — awaiting the downstream upgrade inline — compiles fine and then hangs forever; the <button type="button" class="term" data-term="tokio-spawn"><code>tokio::spawn</code></button> is what keeps it from deadlocking, and the comment in the diff spells out why. A garbage-collected proxy in another language would let you hold a dangling reference to the consumed request and discover the mistake only when the tunnel silently never opens.</p><h2>Related lessons</h2><ul><li><strong>PR #40</strong> taught the generic <code>serve_plain&lt;S&gt;</code> loop these connections ride on — note it already calls <code>.with_upgrades()</code> on the <em>server</em> side. #53 is the client-side other half: without both, the upgrade completes on neither end.</li><li><strong>PR #51</strong> taught typed headers; the <code>hyper::header::UPGRADE</code> constant here is that same idea — a typed name instead of a stringly-typed <code>"upgrade"</code> lookup.</li></ul><h2>Dig deeper</h2><ul><li><a href="https://docs.rs/hyper/latest/hyper/upgrade/index.html"><code>hyper::upgrade</code></a> — the <code>on()</code> function and the <code>OnUpgrade</code> future, plus why <code>with_upgrades()</code> is required on the connection.</li><li><a href="https://docs.rs/tokio/latest/tokio/io/fn.copy_bidirectional.html"><code>tokio::io::copy_bidirectional</code></a> — the concurrent two-way byte pump and its EOF semantics.</li></ul>
+    </article>
+  </div>
+  <script src="glossary.js"></script>
+  <script src="drawer.js" defer></script>
+</body>
+</html>
diff --git a/ent/lessons/55-races-beyond-the-borrow-checker.html b/ent/lessons/55-races-beyond-the-borrow-checker.html
new file mode 100644
index 0000000..f525745
--- /dev/null
+++ b/ent/lessons/55-races-beyond-the-borrow-checker.html
@@ -0,0 +1,62 @@
+<!-- generated by build.mjs; edit docs/lessons/*.md -->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>PR #55 — Close the test-sandbox port race behind connection-reset flakes</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@300;400;500;700&display=swap" rel="stylesheet">
+  <link rel="stylesheet" href="lessons.css">
+</head>
+<body>
+  <div class="frame">
+    <header>
+      <a class="wordmark" href="index.html"><span class="a">adj.ac</span><span class="slash">/</span><span class="b">ent</span></a>
+      <a class="back" href="index.html">all lessons</a>
+    </header>
+    <article>
+      <h1>PR #55 — Close the test-sandbox port race behind connection-reset flakes</h1>
+      <div class="lesson-header">
+        <p class="lesson"><button type="button" class="term" data-term="send-sync"><code>Send</code></button>/<button type="button" class="term" data-term="send-sync"><code>Sync</code></button> and the borrow checker eliminate in-process <em>data</em> races, but logical races over shared OS state — a port, a file, a row in someone else's database — are still entirely on you.</p>
+        <p class="tags"><span class="tag"><code>race-condition</code></span><span class="tag"><code>TOCTOU</code></span></p>
+        <p class="meta">2026-06-14 · +176/−72 · <a href="https://github.com/nonrational/adjacent/pull/55">View PR</a></p>
+      </div>
+      <h2>The situation</h2><p>Integration tests each spin up their own daemon in a sandbox and need a free proxy port. The old trick: bind <code>127.0.0.1:0</code>, let the kernel pick a port, read the number, close the socket, then hand that number to the daemon to re-bind. Under <code>cargo test</code> seven suites run at once, all drawing from the same kernel ephemeral-port range. Another process could claim the port in the gap between the test closing it and the daemon re-binding it. The readiness probe's bare TCP connect then hit a <em>foreign</em> listener, called it ready, and the real request landed on a stranger's socket: "Connection reset by peer". It flaked roughly 1-in-45.</p><h2>The Rust idea</h2><p>Rust's concurrency guarantees are famous, and it's easy to over-read them. Here's the precise boundary.</p><p>A <strong>data race</strong> is two threads touching the <em>same memory location</em> at the same time, at least one of them writing, with no synchronization. That is undefined behavior in C, a heisenbug in Go, and a <em>compile error</em> in Rust. The mechanism is two marker traits the compiler tracks for every type:</p><ul><li><strong><button type="button" class="term" data-term="send-sync"><code>Send</code></button></strong> — safe to <em>move</em> to another thread.</li><li><strong><button type="button" class="term" data-term="send-sync"><code>Sync</code></button></strong> — safe to <em>share</em> by reference (<code>&amp;T</code>) across threads.</li></ul><p><button type="button" class="term" data-term="arc"><code>Arc&lt;Mutex&lt;T&gt;&gt;</code></button> is <button type="button" class="term" data-term="send-sync"><code>Send + Sync</code></button>; <code>Rc&lt;RefCell&lt;T&gt;&gt;</code> is neither. So <button type="button" class="term" data-term="tokio-spawn"><code>tokio::spawn</code></button> accepts the first and rejects the second, and the borrow checker won't let you reach shared memory except through the lock. Data races: gone, before the program ever runs.</p><p>But note the load-bearing phrase: <em>the same memory location</em>. The guarantee is about <strong>memory your process owns</strong>. The moment two processes contend over something outside that model — a TCP port in the kernel's table, a file on disk, a network resource — the compiler has no view of it. No <code>&amp;mut</code> crosses the boundary, no trait describes it, so there is nothing to check. This bug is a <strong>TOCTOU</strong> race — <em>time-of-check to time-of-use</em>: you check a fact (this port is free), and by the time you use it (bind it), the fact has changed. Classic, and completely invisible to <button type="button" class="term" data-term="send-sync"><code>Send</code></button>/<button type="button" class="term" data-term="send-sync"><code>Sync</code></button>.</p><h2>In this PR</h2><p>The old code even confessed the race in its own doc comment:</p><pre><code class="language-rust">// crates/adj/tests/proxy.rs  (deleted)
+/// Bind :0, read the assigned port, close. The kernel may reissue this number to anyone before
+/// the daemon claims it, but for a localhost test that's rare enough to accept.
+fn pick_port() -&gt; u16 {
+    let l = std::net::TcpListener::bind("127.0.0.1:0").expect("bind :0");
+    l.local_addr().expect("local_addr").port()
+}
+</code></pre><p>"Rare enough to accept" held until seven suites ran concurrently. The <code>bind → read → close → re-bind</code> sequence has a window, and a window is all a race needs.</p><p>The fix removes the window entirely. Don't pick a port and hand it off — let the daemon bind <code>:0</code> <em>itself</em>, so the port is born bound to the right process and never freed. The daemon then publishes the actually-bound port to a file:</p><pre><code class="language-rust">// crates/adj/src/proxy.rs
+let listener = TcpListener::bind(addr)
+    .await
+    .map_err(|e| anyhow!("binding proxy listener at {addr}: {e}"))?;
+let bound = listener
+    .local_addr()
+    .map_err(|e| anyhow!("reading proxy listener addr: {e}"))?
+    .port();
+report_bound_port(crate::paths::proxy_port_path(), bound);
+</code></pre><p>The test passes <code>0</code> and learns the real port by reading that file:</p><pre><code class="language-rust">// crates/adj/tests/proxy.rs
+// 0 = the daemon binds a kernel-assigned port; start_daemon learns the real port
+// from the proxy.port file. Picking a free port here and re-binding it in the
+// daemon raced concurrent test processes drawing from the same ephemeral range,
+// which flaked as "connection reset by peer" against a foreign listener.
+proxy_port: 0,
+</code></pre><pre><code class="language-rust">// crates/adj/tests/proxy.rs
+// proxy.port is written after bind, so a parsed port means the listener is live —
+// and unambiguously ours, unlike a bare TCP connect to a guessed port.
+if self.proxy_port == 0 {
+    if let Some(p) = read_port_file(&amp;port_file) {
+        self.proxy_port = p;
+    }
+}
+</code></pre><p>Two races collapse into zero. There's no free-then-rebind gap because the listener that binds the port is the one that keeps it. And the readiness signal gets stronger for free: a parsed <code>proxy.port</code> file means the listener is live <em>and ours</em>, where the old bare <code>TcpStream::connect</code> couldn't tell our daemon from a squatter on the same port.</p><h2>Why it matters</h2><p>The trap is assuming Rust's "fearless concurrency" covers all concurrency. It covers exactly one thing — shared memory inside your address space — and covers it completely. Everything with an identity outside your process is ordinary distributed-systems state, and the same discipline you'd use in any language applies: don't check-then-act across a gap where another actor can intervene. Here the fix is to eliminate the gap (bind once, keep it) rather than shrink it. Other flavors of the same lesson: hold the resource instead of releasing and reacquiring it, make the operation atomic (<code>O_CREAT | O_EXCL</code>, a <code>CAS</code>), or retry on the losing side. The borrow checker will happily let you write a textbook TOCTOU bug — it was never its job to stop you.</p><h2>Related lessons</h2><ul><li><strong>PR #16</strong> — the <button type="button" class="term" data-term="arc"><code>Arc&lt;Mutex&lt;T&gt;&gt;</code></button> pattern whose guarantee this lesson bounds: it prevents data races on in-process memory, and <em>only</em> that.</li><li><strong>PR #24</strong> — single-flight boot gate, an <em>in-process</em> logical race solved with a lock; contrast it with #55, an <em>OS-level</em> race a lock can't touch.</li><li><strong>PR #50</strong> — GCing the per-name lock map, another case of managing shared in-process state safely.</li></ul><h2>Dig deeper</h2><ul><li><a href="https://doc.rust-lang.org/book/ch16-00-concurrency.html">The Rust Book, ch. 16</a> — Fearless Concurrency. Read it for what <button type="button" class="term" data-term="send-sync"><code>Send</code></button>/<button type="button" class="term" data-term="send-sync"><code>Sync</code></button> buy you, but read it knowing the chapter is about <strong>data races</strong> specifically; the port race in this PR is deliberately outside its scope.</li></ul>
+    </article>
+  </div>
+  <script src="glossary.js"></script>
+  <script src="drawer.js" defer></script>
+</body>
+</html>
diff --git a/ent/lessons/56-split-once-structured-keys.html b/ent/lessons/56-split-once-structured-keys.html
new file mode 100644
index 0000000..6841c25
--- /dev/null
+++ b/ent/lessons/56-split-once-structured-keys.html
@@ -0,0 +1,66 @@
+<!-- generated by build.mjs; edit docs/lessons/*.md -->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>PR #56 — Worktree instances: per-label registry keys, remove/prune, wildcard TLS SANs</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@300;400;500;700&display=swap" rel="stylesheet">
+  <link rel="stylesheet" href="lessons.css">
+</head>
+<body>
+  <div class="frame">
+    <header>
+      <a class="wordmark" href="index.html"><span class="a">adj.ac</span><span class="slash">/</span><span class="b">ent</span></a>
+      <a class="back" href="index.html">all lessons</a>
+    </header>
+    <article>
+      <h1>PR #56 — Worktree instances: per-label registry keys, remove/prune, wildcard TLS SANs</h1>
+      <div class="lesson-header">
+        <p class="lesson"><button type="button" class="term" data-term="split-once"><code>str::split_once</code></button> cuts a string at the <em>first</em> delimiter into two borrowed <button type="button" class="term" data-term="str-vs-string"><code>&amp;str</code></button> slices and returns an <button type="button" class="term" data-term="option"><code>Option</code></button>, so "there was no delimiter" is a case you handle instead of a bug you forget — the clean way to parse a structured key.</p>
+        <p class="tags"><span class="tag"><code>string-slices</code></span><span class="tag"><code>split-once</code></span><button type="button" class="term tag" data-term="borrowing"><code>borrowing</code></button></p>
+        <p class="meta">2026-06-13 · +3601/−112 · <a href="https://github.com/nonrational/adjacent/pull/56">View PR</a></p>
+      </div>
+      <h2>The situation</h2><p>The registry maps a key to a path. This PR lets one base app register under several keys: a bare <code>site</code> is the app itself, and <code>feature-x.site</code> is a <em>worktree instance</em> that routes at <code>feature-x.site.adj.ac</code>. The key encodes structure — one dot separates the instance label from the base name. Every routed request has to pull those two pieces back out of a <button type="button" class="term" data-term="str-vs-string"><code>&amp;str</code></button> key, and it has to be cheap.</p><h2>The Rust idea</h2><p><code>str::split_once(delimiter)</code> splits at the <strong>first</strong> match and hands back <code>Option&lt;(&amp;str, &amp;str)&gt;</code>. Two things are worth internalizing.</p><p><strong>It returns <button type="button" class="term" data-term="option"><code>Option</code></button>, so the "no delimiter" case can't be forgotten.</strong> In many languages you write <code>"feature-x.site".split(".")</code>, get an array, and reach for <code>[0]</code> and <code>[1]</code> — hoping there was a dot. When there isn't, <code>[1]</code> is <code>undefined</code>, an out-of-bounds panic, or a silent empty string, depending on the language. That missing-delimiter path is a landmine. <button type="button" class="term" data-term="split-once"><code>split_once</code></button> turns it into a value: <code>Some((before, after))</code> when the delimiter is present, <button type="button" class="term" data-term="option"><code>None</code></button> when it isn't. A bare key like <code>"site"</code> isn't an edge case to defend against — it's simply the <button type="button" class="term" data-term="option"><code>None</code></button> arm of a <button type="button" class="term" data-term="match"><code>match</code></button>.</p><p><strong>The two pieces are borrowed slices — no allocation.</strong> A <button type="button" class="term" data-term="str-vs-string"><code>&amp;str</code></button> is a pointer + length: a <em>window</em> into bytes someone else owns. The pair <button type="button" class="term" data-term="split-once"><code>split_once</code></button> returns points straight into the original string, so splitting a key costs two integer offsets, not two heap allocations. (Contrast a <button type="button" class="term" data-term="str-vs-string"><code>String</code></button>, which owns its bytes on the heap. <button type="button" class="term" data-term="str-vs-string"><code>&amp;str</code></button> borrows; <button type="button" class="term" data-term="str-vs-string"><code>String</code></button> owns.) The price of that speed is a lifetime: the slices are valid only while the input lives — which is exactly why the helper below <em>returns</em> borrows and lets the caller decide whether to <code>.to_string()</code> them.</p><p>(<button type="button" class="term" data-term="split-once"><code>split_once</code></button> is the precise cousin of <code>split</code>, which returns a lazy iterator over <em>every</em> piece. When a string has a known two-part shape, you want the one that gives you exactly two.)</p><h2>In this PR</h2><p>The parser is six lines. <code>split_key</code> maps a registry key to <code>(Option&lt;label&gt;, base)</code>:</p><pre><code class="language-rust">// crates/adj/src/registry.rs
+/// Split a registry key into `(label, base)`. Keys are either a bare app name (`site`) or a
+/// worktree-instance key (`feature-x.site`). `add` enforces at most one dot, so `split_once`
+/// is total here.
+pub fn split_key(key: &amp;str) -&gt; (Option&lt;&amp;str&gt;, &amp;str) {
+    match key.split_once('.') {
+        Some((label, base)) =&gt; (Some(label), base),
+        None =&gt; (None, key),
+    }
+}
+
+/// The app name a registry key resolves config against: the part after the instance label,
+/// or the whole key when there is no label.
+pub fn base_name(key: &amp;str) -&gt; &amp;str {
+    split_key(key).1
+}
+</code></pre><p>Read the <button type="button" class="term" data-term="match"><code>match</code></button>: the <button type="button" class="term" data-term="option"><code>Some</code></button> arm is an instance key — wrap the label in <button type="button" class="term" data-term="option"><code>Some</code></button>, keep the base. The <button type="button" class="term" data-term="option"><code>None</code></button> arm is a bare app name — there's no label, and the whole key <em>is</em> the base. <code>base_name</code> just projects the second field (<code>.1</code>). Every return value is a borrow into <code>key</code>; nothing is copied.</p><p>Now the load-bearing detail in that doc comment: "so <button type="button" class="term" data-term="split-once"><code>split_once</code></button> is total here." <button type="button" class="term" data-term="split-once"><code>split_once</code></button> always cuts at the <em>first</em> dot. On <code>"a.b.c"</code> it yields <code>("a", "b.c")</code> — everything after the first delimiter lands in the second slice. So if a dotted app name ever slipped through, <code>feature.my.app</code> would misparse as label <code>feature</code>, base <code>my.app</code>. The claim that "the first dot is <em>the</em> structural boundary" only holds because of an invariant enforced somewhere else: app names can't contain dots. That check lives at the point where a config enters the system:</p><pre><code class="language-rust">// crates/adj/src/registry.rs
+// Dots are structural in registry keys (`&lt;label&gt;.&lt;name&gt;` is a worktree instance), so a
+// dotted app name would make `feature-x.site` ambiguous. Checked before the general
+// DNS-label check so the dot case gets its own targeted message.
+if cfg.name.contains('.') {
+    return Err(anyhow!(
+        "app name `{}` contains `.` — dots are reserved for worktree instances (`&lt;label&gt;.&lt;name&gt;`)",
+        cfg.name
+    ));
+}
+</code></pre><p>That's the other half of the design. Splitting downstream gets to be a one-liner <em>because</em> the boundary code guarantees at most one dot per key. Reject the malformed input where it enters (see #49), and the parser never has to cope with it.</p><p>The test pins both shapes — bare key and instance key — in one place:</p><pre><code class="language-rust">// crates/adj/src/registry.rs
+#[test]
+fn split_key_handles_bare_and_instance_keys() {
+    assert_eq!(split_key("site"), (None, "site"));
+    assert_eq!(split_key("feature-x.site"), (Some("feature-x"), "site"));
+    assert_eq!(base_name("site"), "site");
+    assert_eq!(base_name("feature-x.site"), "site");
+}
+</code></pre><h2>Why it matters</h2><p>The trap this sidesteps is the array-index split: grab <code>[0]</code>/<code>[1]</code>, forget the no-delimiter path, and ship a parser that panics or silently mangles a bare key. <button type="button" class="term" data-term="split-once"><code>split_once</code></button> makes "no dot" a branch the compiler forces you to write, and pairing it with the upstream <code>contains('.')</code> reject turns "the first dot is the only dot" from a hope into a guarantee. Because the two pieces are borrowed slices, this runs on every routed request without allocating a thing — the invariant lives in code, and reading it back out is free.</p><h2>Related lessons</h2><ul><li><strong>PR #49</strong> is the same file and the same move from the other end: the dotted-name reject above is a parse-don't-validate boundary check, refusing bad input at <code>read_app_config</code> so nothing downstream has to re-check it.</li><li><strong>PR #45</strong> leans on the same borrowing trick — its <code>DashboardEntry&lt;'a&gt;</code> holds <button type="button" class="term" data-term="str-vs-string"><code>&amp;str</code></button> views into each app summary instead of cloning strings, exactly like <code>split_key</code> returns windows into <code>key</code>.</li></ul><h2>Dig deeper</h2><ul><li><a href="https://doc.rust-lang.org/std/primitive.str.html#method.split_once"><button type="button" class="term" data-term="split-once"><code>str::split_once</code></button></a> — the signature (<code>Option&lt;(&amp;str, &amp;str)&gt;</code>), plus <code>rsplit_once</code> for splitting on the <em>last</em> delimiter instead of the first.</li><li><a href="https://doc.rust-lang.org/book/ch04-03-slices.html">The Rust Book, ch. 4.3</a> — The Slice Type: why a <button type="button" class="term" data-term="str-vs-string"><code>&amp;str</code></button> is a borrowed view, and how its lifetime is tied to the data it points into.</li></ul>
+    </article>
+  </div>
+  <script src="glossary.js"></script>
+  <script src="drawer.js" defer></script>
+</body>
+</html>
diff --git a/ent/lessons/60-compile-time-version-stamping.html b/ent/lessons/60-compile-time-version-stamping.html
new file mode 100644
index 0000000..d9a444f
--- /dev/null
+++ b/ent/lessons/60-compile-time-version-stamping.html
@@ -0,0 +1,73 @@
+<!-- generated by build.mjs; edit docs/lessons/*.md -->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>PR #60 — Alpha Homebrew distribution: release CI, in-repo tap formula, version stamping</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@300;400;500;700&display=swap" rel="stylesheet">
+  <link rel="stylesheet" href="lessons.css">
+</head>
+<body>
+  <div class="frame">
+    <header>
+      <a class="wordmark" href="index.html"><span class="a">adj.ac</span><span class="slash">/</span><span class="b">ent</span></a>
+      <a class="back" href="index.html">all lessons</a>
+    </header>
+    <article>
+      <h1>PR #60 — Alpha Homebrew distribution: release CI, in-repo tap formula, version stamping</h1>
+      <div class="lesson-header">
+        <p class="lesson">A <button type="button" class="term" data-term="build-rs"><code>build.rs</code></button> script runs <em>before</em> your crate compiles and can hand values to the compiler via <code>cargo:rustc-env=…</code> stdout directives, which <button type="button" class="term" data-term="env-macro"><code>env!</code></button> (build fails if the var is missing) and <button type="button" class="term" data-term="env-macro"><code>option_env!</code></button> (yields an <button type="button" class="term" data-term="option"><code>Option</code></button>, never fails) then bake into the binary as <code>&amp;'static str</code> literals.</p>
+        <p class="tags"><span class="tag"><code>build-scripts</code></span><span class="tag"><code>compile-time-env</code></span><span class="tag"><code>macros</code></span></p>
+        <p class="meta">2026-06-14 · +243/−1 · <a href="https://github.com/nonrational/adjacent/pull/60">View PR</a></p>
+      </div>
+      <h2>The situation</h2><p>Shipping <code>adj</code> via Homebrew means <code>adj --version</code> has to report something true. A tagged release should say <code>0.1.0-alpha.1</code>; a build off a random local commit should say which commit (and whether the tree was dirty). None of that lives in the source — it lives in git and in CI env vars. This PR is mostly release plumbing (a Homebrew formula, a tag-triggered CI workflow, a <code>just release</code> target), but the one genuinely instructive Rust piece is how the binary <em>learns its own version</em> at compile time.</p><h2>The Rust idea</h2><p>Rust has no runtime reflection for build metadata. A binary can't ask "what version am I?" from thin air — anything it knows must be baked in at compile time or read from disk at runtime. For a version string you want it baked in: a self-contained binary with no sidecar <code>VERSION</code> file to lose.</p><p>Rust gives you two macros that read the <em>compiler's</em> environment:</p><ul><li><strong><code>env!("NAME")</code></strong> — expands to the value of environment variable <code>NAME</code> at compile time, as a <code>&amp;'static str</code>. If <code>NAME</code> isn't set, <strong>the build fails</strong> with a clear error. Use it when the value must exist. Cargo always sets <code>CARGO_PKG_VERSION</code> from <code>Cargo.toml</code>, so <code>env!("CARGO_PKG_VERSION")</code> is guaranteed to compile.</li><li><strong><code>option_env!("NAME")</code></strong> — same idea, but expands to <code>Option&lt;&amp;'static str&gt;</code>: <code>Some(v)</code> if the var was set at compile time, <button type="button" class="term" data-term="option"><code>None</code></button> if not. It <strong>never fails the build</strong>. Use it for metadata that may or may not be there.</li></ul><p>The <code>!</code> marks these as macros, not functions. A function's argument is evaluated at runtime; these run <em>during compilation</em> and leave a string literal behind in the compiled code. That's the only way to reach the environment the compiler saw.</p><p>But where does a var like <code>ADJ_VERSION</code> come from during compilation? That's what <strong><button type="button" class="term" data-term="build-rs"><code>build.rs</code></button></strong> is for. Cargo compiles and runs <button type="button" class="term" data-term="build-rs"><code>build.rs</code></button> before compiling the crate, and the script talks back to Cargo by printing specially-formatted lines to stdout — <code>cargo:rustc-env=KEY=VALUE</code> sets an env var that <button type="button" class="term" data-term="env-macro"><code>env!</code></button>/<button type="button" class="term" data-term="env-macro"><code>option_env!</code></button> can then read while the crate compiles.</p><h2>In this PR</h2><p>The const in <code>main.rs</code> picks the git/CI-derived version when present, else the Cargo version:</p><pre><code class="language-rust">// crates/adj/src/main.rs
+const VERSION: &amp;str = match option_env!("ADJ_VERSION") {
+    Some(v) =&gt; v,
+    None =&gt; env!("CARGO_PKG_VERSION"),
+};
+</code></pre><p>The whole expression is a <code>const</code>, so it's evaluated at compile time — <button type="button" class="term" data-term="match"><code>match</code></button> works in const context. <code>option_env!("ADJ_VERSION")</code> is <button type="button" class="term" data-term="option"><code>Some</code></button> only if the build set that var; otherwise it falls through to <code>env!("CARGO_PKG_VERSION")</code>, which can't fail because Cargo always provides it. Then clap uses it:</p><pre><code class="language-rust">// crates/adj/src/main.rs
+#[command(
+    name = "adj",
+    version = VERSION,   // was: version,  (which defaults to CARGO_PKG_VERSION)
+    about = "Adjacent: supervised local dev servers"
+)]
+</code></pre><p>The build script supplies <code>ADJ_VERSION</code>:</p><pre><code class="language-rust">// crates/adj/build.rs
+fn git_describe() -&gt; Option&lt;String&gt; {
+    let out = Command::new("git")
+        .args(["describe", "--tags", "--always", "--dirty", "--match", "v*"])
+        .output()
+        .ok()?;
+    if !out.status.success() {
+        return None;
+    }
+    let v = String::from_utf8(out.stdout).ok()?;
+    let v = v.trim().trim_start_matches('v').to_string();
+    (!v.is_empty()).then_some(v)
+}
+
+fn main() {
+    let version = std::env::var("ADJ_VERSION")
+        .ok()
+        .filter(|s| !s.is_empty())
+        .or_else(git_describe);
+
+    if let Some(v) = version {
+        println!("cargo:rustc-env=ADJ_VERSION={v}");
+    }
+
+    println!("cargo:rerun-if-env-changed=ADJ_VERSION");
+    // Refresh the git-describe value when HEAD moves; workspace root is two levels up from here.
+    if Path::new("../../.git/HEAD").exists() {
+        println!("cargo:rerun-if-changed=../../.git/HEAD");
+    }
+}
+</code></pre><p>Walk the chain:</p><ol><li>CI sets <code>ADJ_VERSION</code> to the release tag (the workflow's <code>Derive version from tag</code> step strips the leading <code>v</code>). Locally that var is unset, so the script runs <code>git describe --tags --always --dirty</code> — which yields <code>0.1.0-alpha.1</code> on the exact tag, or an abbreviated commit like <code>61b2f6e</code> off a plain commit, with a <code>-dirty</code> suffix appended when the working tree has uncommitted changes.</li><li>The script prints <code>cargo:rustc-env=ADJ_VERSION=&lt;v&gt;</code>, which sets that var for the crate compile that follows.</li><li><code>option_env!("ADJ_VERSION")</code> in <code>main.rs</code> sees it and bakes it into <code>const VERSION</code>.</li></ol><p>The two trailing directives are cache control. Build scripts are cached aggressively, so without a hint Cargo would keep the stale value forever. <code>cargo:rerun-if-env-changed=ADJ_VERSION</code> re-runs the script when that var changes; <code>cargo:rerun-if-changed=../../.git/HEAD</code> re-runs it when you commit (HEAD moves), so <code>git describe</code> refreshes. Build scripts run with their working directory set to the package root (<code>crates/adj</code>), which is why the repo's <code>.git/HEAD</code> is <code>../../</code> up.</p><p>Note the <code>.ok()?</code> calls in <code>git_describe</code>: they intentionally throw away git's errors and return <button type="button" class="term" data-term="option"><code>None</code></button>, which makes the whole thing fall back to the Cargo version. That's the <em>legitimate</em> face of swallowing a <button type="button" class="term" data-term="result"><code>Result</code></button> (see #48) — a source build with no <code>.git</code> directory shouldn't fail to compile just because <code>git describe</code> can't run.</p><p>The rest of the PR is distribution tooling, not Rust: <code>.github/workflows/release.yml</code> (tag-triggered arm64 build + GitHub prerelease), <code>Formula/adj.rb</code> and <code>render-formula.sh</code> (the in-repo Homebrew tap), and a <code>just release</code> target that tags the next alpha. Worth knowing they exist; not where the Rust lesson lives. The user-facing <code>brew install</code> / <code>cargo install</code> side is #69's subject.</p><h2>Why it matters</h2><p>In many ecosystems you'd read the version from a file shipped next to the binary (a <code>package.json</code>, a bundled <code>VERSION</code>) or hardcode a string you forget to bump. Both drift, and the file can go missing. Compile-time stamping makes the binary self-describing with zero runtime dependencies. And the <button type="button" class="term" data-term="env-macro"><code>env!</code></button> vs <button type="button" class="term" data-term="env-macro"><code>option_env!</code></button> split encodes intent in the type: <button type="button" class="term" data-term="env-macro"><code>env!</code></button> says "this must exist, fail the build if it doesn't" and hands you a <button type="button" class="term" data-term="str-vs-string"><code>&amp;str</code></button>; <button type="button" class="term" data-term="env-macro"><code>option_env!</code></button> says "this might exist" and hands you an <code>Option&lt;&amp;str&gt;</code> you're forced to handle. Typo <code>CARGO_PKG_VERSION</code> and the build stops immediately — you never ship a binary that reports the wrong version because a lookup silently returned empty.</p><h2>Related lessons</h2><ul><li>PR #48 — <em>Warn instead of silently defaulting.</em> <button type="button" class="term" data-term="build-rs"><code>build.rs</code></button> here uses <code>.ok()?</code> to deliberately drop git's errors and fall back; #48 is about the cases where that silent drop is a bug. Same combinator, opposite verdict — the difference is whether the <button type="button" class="term" data-term="result"><code>Err</code></button> means "someone made a mistake."</li></ul><h2>Dig deeper</h2><ul><li><a href="https://doc.rust-lang.org/cargo/reference/build-scripts.html">The Cargo Book — Build Scripts</a> — what <button type="button" class="term" data-term="build-rs"><code>build.rs</code></button> can do and the full list of <code>cargo:</code> output directives (<code>rustc-env</code>, <code>rerun-if-changed</code>, <code>rerun-if-env-changed</code>).</li><li><a href="https://doc.rust-lang.org/std/macro.env.html">std — <button type="button" class="term" data-term="env-macro"><code>env!</code></button></a> and <a href="https://doc.rust-lang.org/std/macro.option_env.html"><button type="button" class="term" data-term="env-macro"><code>option_env!</code></button></a> — the compile-time environment macros, and why one fails the build while the other returns <button type="button" class="term" data-term="option"><code>Option</code></button>.</li></ul>
+    </article>
+  </div>
+  <script src="glossary.js"></script>
+  <script src="drawer.js" defer></script>
+</body>
+</html>
diff --git a/ent/lessons/63-what-clippy-teaches.html b/ent/lessons/63-what-clippy-teaches.html
new file mode 100644
index 0000000..f583135
--- /dev/null
+++ b/ent/lessons/63-what-clippy-teaches.html
@@ -0,0 +1,73 @@
+<!-- generated by build.mjs; edit docs/lessons/*.md -->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>PR #63 — Add a fmt + clippy lint job to CI</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@300;400;500;700&display=swap" rel="stylesheet">
+  <link rel="stylesheet" href="lessons.css">
+</head>
+<body>
+  <div class="frame">
+    <header>
+      <a class="wordmark" href="index.html"><span class="a">adj.ac</span><span class="slash">/</span><span class="b">ent</span></a>
+      <a class="back" href="index.html">all lessons</a>
+    </header>
+    <article>
+      <h1>PR #63 — Add a fmt + clippy lint job to CI</h1>
+      <div class="lesson-header">
+        <p class="lesson">Clippy is a Rust teacher wearing a linter's badge — each lint names an idiom (<code>single_match</code> → <button type="button" class="term" data-term="match"><code>if let</code></button>) or a footgun (<code>await_holding_lock</code>, <code>dead_code</code>), and the honest reply is either to adopt the idiom or to <code>#[allow]</code> it <em>with a reason</em>.</p>
+        <p class="tags"><span class="tag"><code>clippy</code></span><span class="tag"><code>rustfmt</code></span><span class="tag"><code>lints</code></span><span class="tag"><code>idioms</code></span></p>
+        <p class="meta">2026-06-14 · +604/−248 · <a href="https://github.com/nonrational/adjacent/pull/63">View PR</a></p>
+      </div>
+      <h2>The situation</h2><p>The repo had never been gated on formatting or lints. This PR adds a CI job that runs two commands and fails the build if either complains:</p><pre><code class="language-yaml"># .github/workflows/ci.yml
+- run: cargo fmt --all -- --check
+- run: cargo clippy --workspace --all-targets -- -D warnings
+</code></pre><p>To land that gate green it had to fix everything the two commands surfaced. Be honest about the split: the vast majority of the +604/−248 is one mechanical <code>cargo fmt --all</code> commit — struct literals expanded to multi-line, long calls wrapped — with no behavior change and nothing to learn. The interesting part is a tiny second commit (+46/−7) where <code>clippy -D warnings</code> forced three real changes. That's the lesson: not the formatter, but what clippy <em>taught</em>.</p><h2>The Rust idea</h2><p>Clippy ships ~700 lints, and almost none of them are about whitespace — rustfmt owns that. Clippy is about <em>idiom</em> and <em>correctness</em>. Each lint encodes a small piece of "here's how a seasoned Rust programmer would write this, and why." Running it is less like a spell-check and more like pairing with someone who keeps saying "there's a cleaner way." <code>-D warnings</code> (deny all warnings) turns that advice into a hard gate: the build fails until you either take the advice or explicitly, in writing, decline it.</p><p>Declining is a first-class move. <code>#[allow(clippy::some_lint)]</code> says "I read this lint, I understand what it's warning about, and it doesn't apply here." A clippy pass done right leaves behind a mix of both: code you improved, and a few <code>#[allow]</code>s each carrying a comment that explains the disagreement. This PR has one of each kind.</p><h2>In this PR</h2><p><strong>1. <code>single_match</code> → <button type="button" class="term" data-term="match"><code>if let</code></button>.</strong> Clippy's <code>single_match</code> fires when a <button type="button" class="term" data-term="match"><code>match</code></button> has one arm that does real work and a second arm that does nothing (<code>_ =&gt; {}</code>). Rust already has a construct for "run this code only if the value matches one pattern, otherwise skip" — that's <button type="button" class="term" data-term="match"><code>if let</code></button>. A two-arm match with an empty catch-all is <button type="button" class="term" data-term="match"><code>if let</code></button> wearing a costume, and reading it forces you to scan to the bottom to confirm the <code>_</code> really is empty.</p><pre><code class="language-rust">// crates/adj/src/tls.rs — ensure_leaf
+// before:
+match (fs::read_to_string(&amp;cert_path), fs::read_to_string(&amp;key_path)) {
+    (Ok(cert), Ok(key)) =&gt; match leaf_covers(&amp;cert, sans) {
+        Ok(true) =&gt; return Ok((cert, key)),
+        Ok(false) | Err(_) =&gt; {}
+    },
+    _ =&gt; {}
+}
+
+// after:
+if let (Ok(cert), Ok(key)) = (
+    fs::read_to_string(&amp;cert_path),
+    fs::read_to_string(&amp;key_path),
+) {
+    if let Ok(true) = leaf_covers(&amp;cert, sans) {
+        return Ok((cert, key));
+    }
+}
+</code></pre><p>Both matches collapse the same way. Semantics are identical — only a readable, SAN-covering cached leaf short-circuits; everything else (a read error, a parse error, a cert that doesn't cover the wanted names) falls through to re-issue. But the <button type="button" class="term" data-term="match"><code>if let</code></button> version <em>says</em> that: "if both files read, and the leaf covers the SANs, use it." The <code>_ =&gt; {}</code> and <code>Ok(false) | Err(_) =&gt; {}</code> filler arms are gone, so there's nothing to double-check.</p><p><strong>2. <code>await_holding_lock</code> — the documented decline.</strong> This lint flags holding a <code>std::sync::MutexGuard</code> across an <button type="button" class="term" data-term="async-await"><code>.await</code></button>. It's a real footgun: on a multi-threaded async runtime the task can be parked mid-await while still holding the lock, and another task on that same thread can block forever trying to acquire it — a deadlock. Clippy is right to warn by default. Here it's a false alarm, and the fix is to say so, not to restructure working test code:</p><pre><code class="language-rust">// crates/adj/tests/tls.rs
+#[cfg(target_os = "macos")]
+#[tokio::test]
+// The keychain guard intentionally spans the test's awaits to serialize on LOGIN_KEYCHAIN_LOCK;
+// a current-thread tokio runtime can't deadlock on it, so the std-guard-across-await lint is moot.
+#[allow(clippy::await_holding_lock)]
+async fn install_ca_generates_files_and_prints_macos_command() {
+</code></pre><p>The <code>#[allow]</code> is localized to the three tests that need it, not slapped on the whole crate. That matters: if the <em>supervisor</em> ever grows a real lock-across-await, the lint stays live to catch it. A repo-wide <code>#![allow]</code> would have silenced the warning everywhere and thrown away its value.</p><p><strong>3. <code>dead_code</code> / <code>unused_imports</code> under a cross-platform gate.</strong> The clippy job runs on <code>ubuntu-latest</code>, but the keychain code is <code>#[cfg(target_os = "macos")]</code> — it compiles to nothing on Linux. So on the CI runner, every helper that only the macOS path uses becomes genuinely dead code, and <code>-D warnings</code> promotes those warnings to errors. The fix is to <code>#[cfg]</code>-gate the now-unused items to match their only caller:</p><pre><code class="language-rust">// crates/adj/src/tls.rs
+pub(crate) use keychain::delete as delete_keychain_ca;
+// Only the macOS doctor checks load a keychain handle; on other targets the re-export is unused.
+#[cfg(target_os = "macos")]
+pub(crate) use keychain::load as load_keychain_ca;
+</code></pre><p>...and for a stub that exists only to mirror an API on the platform where it's never called, a deliberate <code>#[allow(dead_code)]</code>:</p><pre><code class="language-rust">// crates/adj/src/tls/keychain.rs — the non-macOS stub
+// Mirrors the macOS KeychainKey API for symmetry; the non-macOS doctor path never calls
+// it, so it's dead on these targets.
+#[allow(dead_code)]
+pub fn sign_canary(&amp;self) -&gt; Result&lt;()&gt; {
+    Err(unsupported())
+}
+</code></pre><p>Same test scaffolding (<code>with_temp_home</code>, <code>HOME_LOCK</code>, the <code>curl_available</code> helper) got the same <code>#[cfg(target_os = "macos")]</code> treatment.</p><h2>Why it matters</h2><p>Two takeaways a linter-skeptic misses.</p><p>First, <code>dead_code</code> under <code>--all-targets -D warnings</code> on a Linux runner is a <em>free cross-compilation check</em>. Adjacent is mostly developed on a Mac, and it's easy to leave a helper unused on platforms you never build locally. The CI job compiles the non-macOS <code>cfg</code> branches you'd otherwise never exercise, and catches the drift. The lint isn't nagging about tidiness — it's proving that every target still hangs together.</p><p>Second, a green clippy run doesn't mean "no lints fired." It means "every lint that fired was either fixed or explicitly declined with a reason." That's the discipline <code>-D warnings</code> enforces: you can't ignore advice by scrolling past it. You either take it, or you write down why you didn't — and the next reader gets that reasoning for free. An <code>#[allow]</code> with a comment is worth more than clean code that silently dodged the question.</p><h2>Related lessons</h2><ul><li>PR #40 shipped the HTTPS + local-CA machinery. The <code>ensure_leaf</code> match and the keychain helpers clippy is cleaning up here are exactly that code — this PR is #40's neighborhood one linter-pass later.</li><li>PR #48 is the same spirit in a different tool: it's about surfacing a <button type="button" class="term" data-term="result"><code>Result</code></button>'s <button type="button" class="term" data-term="result"><code>Err</code></button> instead of swallowing it. Clippy and the type system are both in the business of making the invisible visible — this PR just does it at the linter layer.</li></ul><h2>Dig deeper</h2><ul><li><a href="https://rust-lang.github.io/rust-clippy/">The Clippy lint index</a> — every lint, searchable, each with a before/after and the reasoning behind it. <code>single_match</code>, <code>await_holding_lock</code>, and the rustc <code>dead_code</code>/<code>unused_imports</code> lints all have entries worth reading.</li></ul>
+    </article>
+  </div>
+  <script src="glossary.js"></script>
+  <script src="drawer.js" defer></script>
+</body>
+</html>
diff --git a/ent/lessons/65-health-files-and-metadata.html b/ent/lessons/65-health-files-and-metadata.html
new file mode 100644
index 0000000..5e13ef2
--- /dev/null
+++ b/ent/lessons/65-health-files-and-metadata.html
@@ -0,0 +1,56 @@
+<!-- generated by build.mjs; edit docs/lessons/*.md -->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>PR #65 — Add community health files</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@300;400;500;700&display=swap" rel="stylesheet">
+  <link rel="stylesheet" href="lessons.css">
+</head>
+<body>
+  <div class="frame">
+    <header>
+      <a class="wordmark" href="index.html"><span class="a">adj.ac</span><span class="slash">/</span><span class="b">ent</span></a>
+      <a class="back" href="index.html">all lessons</a>
+    </header>
+    <article>
+      <h1>PR #65 — Add community health files</h1>
+      <div class="lesson-header">
+        <p class="lesson">None — this PR is seven Markdown/YAML files under <code>.github/</code> (+160/−0), zero Rust. The lesson is open-source project hygiene, and the Rust-ecosystem analog worth knowing: the way GitHub reads your <code>.github/</code> files and renders them into the repo UI is exactly how <strong>crates.io reads your <code>Cargo.toml</code> package metadata</strong> — <code>description</code>, <code>repository</code>, <code>readme</code>, <code>keywords</code>, <code>categories</code>, <code>license</code>, <code>rust-version</code> — and renders it into your crate page.</p>
+        <p class="tags"><span class="tag"><code>oss-hygiene</code></span><span class="tag"><code>crates.io-metadata</code></span></p>
+        <p class="meta">2026-06-14 · +160/−0 · <a href="https://github.com/nonrational/adjacent/pull/65">View PR</a></p>
+      </div>
+      <h2>The situation</h2><p>The repo had code and a README but none of the paperwork a public project is judged by: no code of conduct, no contribution guide, no security policy, no issue or PR templates. This PR adds the whole set — <code>CODE_OF_CONDUCT.md</code>, <code>CONTRIBUTING.md</code>, <code>SECURITY.md</code>, two issue templates plus a <code>config.yml</code>, and a <code>PULL_REQUEST_TEMPLATE.md</code> — all under <code>.github/</code>.</p><h2>The idea (no Rust this time)</h2><p>These are <strong>community health files</strong>, and the reason they live in <code>.github/</code> is that GitHub reads them by convention and wires them into the UI. Drop <code>CONTRIBUTING.md</code> there and the "New pull request" screen sprouts a link to it. Add <code>ISSUE_TEMPLATE/*.md</code> and the "New issue" button becomes a menu of your templates. Add <code>SECURITY.md</code> and a "Report a vulnerability" affordance appears. You're not writing docs a human has to go find — you're filling in slots a platform already knows how to render.</p><p>The trick is that the file's <strong>location and name are the contract</strong>. GitHub doesn't parse your prose; it keys off the path (<code>.github/SECURITY.md</code>) and, for templates, off the YAML front-matter at the top of the file. Get the path right and the feature lights up; get it wrong and the file is just dead Markdown.</p><h2>In this PR</h2><p>The issue templates lead with YAML front-matter — that block <em>is</em> what GitHub reads to build the template menu (the <code>name</code> and <code>about</code> become the menu entry):</p><pre><code class="language-yaml"># .github/ISSUE_TEMPLATE/feature_request.md
+---
+name: Feature Request
+about: Propose an enhancement or new capability for Adjacent
+labels: enhancement
+---
+</code></pre><p><code>config.yml</code> isn't a template — it configures the template <em>chooser</em>, keeping the blank-issue escape hatch open and routing open-ended questions to Discussions instead of the issue tracker:</p><pre><code class="language-yaml"># .github/ISSUE_TEMPLATE/config.yml
+blank_issues_enabled: true
+contact_links:
+  - name: General questions
+    url: https://github.com/nonrational/adjacent/discussions
+    about: Ask questions and discuss Adjacent in Discussions
+</code></pre><p><code>SECURITY.md</code> states a support window and points reporters at GitHub's private reporting flow rather than a public issue or an email address:</p><pre><code class="language-markdown">&lt;!-- .github/SECURITY.md --&gt;
+For security vulnerabilities, please use GitHub's [private vulnerability
+reporting feature](https://github.com/nonrational/adjacent/security/advisories/new)
+rather than opening a public issue.
+</code></pre><p>And <code>CONTRIBUTING.md</code> closes with the standard Rust dual-license inbound clause — every contribution comes in under both licenses, no extra paperwork:</p><pre><code class="language-markdown">&lt;!-- .github/CONTRIBUTING.md --&gt;
+Unless you explicitly state otherwise, any contribution intentionally submitted
+for inclusion in this work by you ... shall be dual licensed under the Apache
+License, Version 2.0 and the MIT license, without any additional terms or
+conditions.
+</code></pre><p>That clause isn't free-floating — it matches a field already in the manifest, which is the bridge to the Rust angle.</p><h2>Why it matters — the crates.io angle</h2><p>crates.io is to a published crate what GitHub's repo page is to a repo: it reads structured metadata and renders it. The source of that metadata is the <code>[package]</code> table in <code>Cargo.toml</code>. The repo's workspace manifest already carries two of the important fields, and the <code>license</code> here is the exact counterpart to the CONTRIBUTING clause above:</p><pre><code class="language-toml"># Cargo.toml — [workspace.package] (already in the repo, not added by this PR)
+license = "MIT OR Apache-2.0"
+repository = "https://github.com/nonrational/adjacent"
+</code></pre><p>If Adjacent were ever <code>cargo publish</code>ed, crates.io would surface <code>license</code> as a badge and <code>repository</code> as the "Repository" link — the same "platform renders your metadata" move as GitHub and <code>.github/</code>. But the metadata slots for a polished crate page go further, and they're worth knowing even before you publish:</p><ul><li><strong><code>description</code></strong> — the one-liner under the crate name in search results. Required to publish.</li><li><strong><code>readme</code></strong> — path to the file crates.io renders as the crate's front page (defaults to <code>README.md</code>).</li><li><strong><code>keywords</code></strong> / <strong><code>categories</code></strong> — how people find you in search and browse; <code>categories</code> must come from crates.io's fixed slug list.</li><li><strong><code>rust-version</code></strong> — your MSRV (minimum supported Rust version). Cargo refuses to build with an older toolchain and prints a clear error instead of a confusing mid-compile failure.</li></ul><p>The lesson mirrors the health files exactly: don't write a paragraph telling people your MSRV or where to file bugs — put the value in the slot the tooling reads, and the tooling shows it for you, consistently, everywhere.</p><h2>Related lessons</h2><ul><li>PR #46 covers the <code>MIT OR Apache-2.0</code> dual-license convention itself and the on-disk <code>LICENSE-*</code> layout — the CONTRIBUTING clause here is the inbound-contribution half of that same decision.</li><li>PR #36 makes the "the file's path/format <em>is</em> the contract" point from the docs side.</li></ul><h2>Dig deeper</h2><ul><li><a href="https://doc.rust-lang.org/cargo/reference/manifest.html">The Cargo Book — The Manifest Format</a> — every <code>[package]</code> field crates.io reads: <code>description</code>, <code>repository</code>, <code>readme</code>, <code>keywords</code>, <code>categories</code>, <code>license</code>, and <code>rust-version</code>.</li></ul>
+    </article>
+  </div>
+  <script src="glossary.js"></script>
+  <script src="drawer.js" defer></script>
+</body>
+</html>
diff --git a/ent/lessons/68-lean-agent-docs.html b/ent/lessons/68-lean-agent-docs.html
new file mode 100644
index 0000000..1b86cf7
--- /dev/null
+++ b/ent/lessons/68-lean-agent-docs.html
@@ -0,0 +1,37 @@
+<!-- generated by build.mjs; edit docs/lessons/*.md -->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>PR #68 — Remove the agent-identity section from CLAUDE.md</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@300;400;500;700&display=swap" rel="stylesheet">
+  <link rel="stylesheet" href="lessons.css">
+</head>
+<body>
+  <div class="frame">
+    <header>
+      <a class="wordmark" href="index.html"><span class="a">adj.ac</span><span class="slash">/</span><span class="b">ent</span></a>
+      <a class="back" href="index.html">all lessons</a>
+    </header>
+    <article>
+      <h1>PR #68 — Remove the agent-identity section from CLAUDE.md</h1>
+      <div class="lesson-header">
+        <p class="lesson">None — this is a pure documentation deletion (+0/−10), no Rust and no technical concept to teach.</p>
+        <p class="tags"><span class="tag"><code>docs-hygiene</code></span><span class="tag"><code>honest-series</code></span></p>
+        <p class="meta">2026-06-16 · +0/−10 · <a href="https://github.com/nonrational/adjacent/pull/68">View PR</a></p>
+      </div>
+      <h2>What happened</h2><p>This PR deleted the <code>## Agent identity</code> section from <code>CLAUDE.md</code> — ten lines of personal operational detail (the <code>nonreagent</code>/<code>nonrational</code> GitHub accounts, the <code>gh auth switch</code> dance, the per-commit author line) that don't belong in an open-source repo. The durable principle it encoded still lives, machine-agnostically, in each contributor's own profile:</p><pre><code class="language-markdown">## Agent identity (`nonrational/adjacent` only)
+
+Agents commit, push, and self-review as the GitHub user `nonreagent` — the human reviews and merges.
+- `gh auth switch -u nonreagent` + `gh auth setup-git` before any `git push`. Inline `GH_TOKEN=...` does nothing for `git push`.
+- **Never** run `gh pr review --approve` or `gh pr merge`. Approval and merge are the human's job.
+</code></pre><p>The meta-note worth keeping: <strong>agent-instruction files (<code>CLAUDE.md</code>, <code>AGENTS.md</code>) earn their keep by staying lean.</strong> Every line is context an agent re-reads on each task, and anything personal or repo-account-specific is noise for other contributors plus a small information leak. Prune aggressively.</p><p>And this file is the honesty principle in action: a good teaching series says so plainly when a PR carries no lesson, rather than inventing one.</p>
+    </article>
+  </div>
+  <script src="glossary.js"></script>
+  <script src="drawer.js" defer></script>
+</body>
+</html>
diff --git a/ent/lessons/69-distributing-a-rust-cli.html b/ent/lessons/69-distributing-a-rust-cli.html
new file mode 100644
index 0000000..b03994b
--- /dev/null
+++ b/ent/lessons/69-distributing-a-rust-cli.html
@@ -0,0 +1,47 @@
+<!-- generated by build.mjs; edit docs/lessons/*.md -->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>PR #69 — Add alpha install directions to the homepage</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@300;400;500;700&display=swap" rel="stylesheet">
+  <link rel="stylesheet" href="lessons.css">
+</head>
+<body>
+  <div class="frame">
+    <header>
+      <a class="wordmark" href="index.html"><span class="a">adj.ac</span><span class="slash">/</span><span class="b">ent</span></a>
+      <a class="back" href="index.html">all lessons</a>
+    </header>
+    <article>
+      <h1>PR #69 — Add alpha install directions to the homepage</h1>
+      <div class="lesson-header">
+        <p class="lesson">No Rust in this diff (it's the <code>ent/</code> homepage plus a Homebrew formula rename) — but the <em>content</em> teaches the consumer side of shipping a Rust CLI: a Homebrew tap gives users a prebuilt binary with no toolchain, versus <code>cargo install</code> compiling from source into <code>~/.cargo/bin</code>, versus grabbing the release tarball by hand.</p>
+        <p class="tags"><span class="tag"><code>distribution</code></span><span class="tag"><code>homebrew</code></span><span class="tag"><code>cargo-install</code></span></p>
+        <p class="meta">2026-06-21 · +46/−11 · <a href="https://github.com/nonrational/adjacent/pull/69">View PR</a></p>
+      </div>
+      <h2>The situation</h2><p>The alpha was installable but the homepage still said "coming soon." This PR put the real install steps on the page and renamed the Homebrew package <code>adj → adjacent</code> so <code>brew install adjacent</code> reads naturally. The diff is HTML, bash, YAML, a Ruby formula, and Markdown — zero Rust. Worth teaching anyway, because "how does a stranger get your Rust binary onto their machine" is a real question every CLI project answers, and this PR answers it in public.</p><h2>The idea (no Rust this time)</h2><p>A compiled Rust CLI is just a binary. Getting it onto a user's <code>PATH</code> has three common routes, and they trade off differently:</p><ol><li><strong>A package manager (Homebrew tap).</strong> The user runs two commands, gets a prebuilt binary, and never needs a Rust toolchain. Updates flow through <code>brew upgrade</code>. You (the producer) do the compiling once in CI and publish the artifact.</li><li><strong><code>cargo install</code>.</strong> Compiles from source on the user's machine into <code>~/.cargo/bin</code>. Requires them to have Rust installed, and the first build can take minutes. Updates are <code>cargo install --force</code>. Great for Rust developers, a non-starter for everyone else.</li><li><strong>The prebuilt release tarball, by hand.</strong> Download, extract, drop the binary on <code>PATH</code>. No toolchain, no Homebrew — but you own every update yourself.</li></ol><p>The Homebrew route is really #3 with a manager wrapped around it: the formula just points at the same release tarball and automates the download-and-place.</p><h2>In this PR</h2><p>The homepage now renders the two-command install path (<code>ent/index.html</code>):</p><pre><code class="language-html">&lt;!-- ent/index.html --&gt;
+&lt;section&gt;
+  &lt;div class="label"&gt;install &amp;middot; alpha&lt;/div&gt;
+  &lt;div class="cmds"&gt;
+    &lt;code class="cmd"&gt;&lt;span class="prompt"&gt;$&lt;/span&gt;brew tap nonrational/adjacent https://github.com/nonrational/adjacent&lt;span class="note"&gt;# straight from the repo &amp;mdash; no separate tap&lt;/span&gt;&lt;/code&gt;
+    &lt;code class="cmd"&gt;&lt;span class="prompt"&gt;$&lt;/span&gt;brew install adjacent&lt;span class="note"&gt;# Apple Silicon, unsigned alpha build&lt;/span&gt;&lt;/code&gt;
+  &lt;/div&gt;
+&lt;/section&gt;
+</code></pre><p>Which the user runs as:</p><pre><code class="language-sh">brew tap nonrational/adjacent https://github.com/nonrational/adjacent
+brew install adjacent
+</code></pre><p>Two subtleties worth naming:</p><p><strong>The package name and the binary name don't have to match.</strong> <code>brew install adjacent</code> installs a CLI you invoke as <code>adj</code>. Homebrew's formula name is just a handle for the package; what lands on <code>PATH</code> is whatever the formula installs. This PR renamed the <em>package</em> to <code>adjacent</code> while the CLAUDE.md contract keeps the <em>binary</em> <code>adj</code>.</p><p><strong>What the tap actually wraps is route #3.</strong> The formula's source of truth points straight at a prebuilt release artifact (<code>.github/scripts/render-formula.sh</code>):</p><pre><code class="language-bash"># .github/scripts/render-formula.sh
+url="https://github.com/${repo}/releases/download/${tag}/adj-${version}-aarch64-apple-darwin.tar.gz"
+</code></pre><p>So the user who runs <code>brew install adjacent</code> and the user who downloads that <code>.tar.gz</code> by hand get byte-for-byte the same binary. Homebrew is the convenience layer, not a different build.</p><p>For contrast, the from-source route lives in this repo's <code>justfile</code>:</p><pre><code class="language-make"># justfile
+install:
+  cargo install --path crates/adj
+</code></pre><p>That compiles the workspace and installs <code>adj</code> into <code>~/.cargo/bin</code> — the Rust developer's path, needing a full toolchain and a real compile, no prebuilt artifact involved.</p><h2>Why it matters</h2><p>Pick the wrong default and you lose users. Lead a non-Rust audience with <code>cargo install</code> and you've told them to install a compiler and wait for a cold build before they can try your tool — most bounce. Lead with a Homebrew tap and the cost is on <em>you</em>: CI has to build, sign (or admit it's unsigned, as this alpha does), and publish the artifact, and you have to keep the formula's <code>url</code> and <code>sha256</code> in sync with each release. This PR even adds a <code>smoke</code> CI job that taps and installs from the <em>published</em> formula, so a broken install path fails the release instead of a user. The producer eats the complexity so the consumer's path stays two commands.</p><h2>Related lessons</h2><ul><li><strong>PR #60</strong> built the <em>producer</em> half this consumes — the release CI, the in-repo tap formula, and version stamping that make <code>brew install adjacent</code> resolve to a real artifact: <a href="https://github.com/nonrational/adjacent/pull/60">View PR #60</a>. This PR is the consumer-facing directions for that machinery.</li><li><a href="46-revamp-landing-positioning-page.html">PR #46</a> — the other side of the same <code>ent/</code> homepage: how a single-binary Rust project carries a non-Rust web frontend beside its Cargo workspace. Same "honest, no-Rust diff" shape as this one.</li></ul><h2>Dig deeper</h2><ul><li><a href="https://doc.rust-lang.org/cargo/commands/cargo-install.html">The Cargo Book — <code>cargo install</code></a> — installs a binary from source into <code>~/.cargo/bin</code>; the <code>--path</code>, <code>--force</code>, and <code>--root</code> flags that control where it builds from and lands.</li><li><a href="https://docs.brew.sh/How-to-Create-and-Maintain-a-Tap">Homebrew — How to Create and Maintain a Tap</a> — the <code>user/tap/formula</code> naming triplet and why the tap and formula sharing a name (<code>nonrational/adjacent</code> + <code>adjacent</code>) is fine.</li></ul>
+    </article>
+  </div>
+  <script src="glossary.js"></script>
+  <script src="drawer.js" defer></script>
+</body>
+</html>
diff --git a/ent/lessons/75-hand-render-config-to-disk.html b/ent/lessons/75-hand-render-config-to-disk.html
new file mode 100644
index 0000000..4aa102b
--- /dev/null
+++ b/ent/lessons/75-hand-render-config-to-disk.html
@@ -0,0 +1,73 @@
+<!-- generated by build.mjs; edit docs/lessons/*.md -->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>PR #75 — Scaffold a default adjacent.toml in `adj add`</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@300;400;500;700&display=swap" rel="stylesheet">
+  <link rel="stylesheet" href="lessons.css">
+</head>
+<body>
+  <div class="frame">
+    <header>
+      <a class="wordmark" href="index.html"><span class="a">adj.ac</span><span class="slash">/</span><span class="b">ent</span></a>
+      <a class="back" href="index.html">all lessons</a>
+    </header>
+    <article>
+      <h1>PR #75 — Scaffold a default adjacent.toml in `adj add`</h1>
+      <div class="lesson-header">
+        <p class="lesson">When a config file is meant for a <em>human</em> to open and edit, hand-render it as text so comments, <code># TODO</code> placeholders, and commented-out optional fields survive — <code>toml::to_string(&amp;struct)</code> would drop every one of them — and write it with <code>std::fs::write</code> behind a <code>!path.exists()</code> guard so you never clobber a file the user already owns.</p>
+        <p class="tags"><span class="tag"><code>std::fs</code></span><span class="tag"><code>toml</code></span><span class="tag"><code>file-generation</code></span></p>
+        <p class="meta">2026-06-21 · +1552/−6 · <a href="https://github.com/nonrational/adjacent/pull/75">View PR</a></p>
+      </div>
+      <h2>The situation</h2><p><code>adj add .</code> used to dead-end when a directory had no <code>adjacent.toml</code>. This PR makes it <em>generate</em> a sensible default instead — filling in <code>name</code> and <code>cmd</code> when it can detect the stack, leaving <code># TODO</code> guidance when it can't. The generated file's whole reason for existing is that a person opens it next and edits it. So two questions: how do you produce a config file that's friendly to a human editor, and how do you write it to disk without ever overwriting one the user already wrote?</p><h2>The Rust idea</h2><p>Rust's <code>toml</code> crate can serialize a struct straight to a config string — <code>toml::to_string(&amp;cfg)</code> — the write-side mirror of the <button type="button" class="term" data-term="derive-macro"><code>#[derive(Deserialize)]</code></button> that reads <code>adjacent.toml</code> back in (PR #19). It's the obvious reach, and for a machine-to-machine file it's the right one: faithful, round-trippable, no hand-maintained text.</p><p>But <code>to_string</code> serializes <strong>data</strong>, and a struct holds no comments. Feed it an <code>AppConfig</code> and you get back exactly:</p><pre><code class="language-toml">name = "myapp"
+cmd = "npm run dev"
+</code></pre><p>No header explaining where the file came from. No <code># Optional:</code> block showing the fields the user <em>could</em> set. No <code># TODO</code> next to a value they still need to fill in. For a scaffold, those comments aren't decoration — they're the entire payload. The file is a teaching aid disguised as config.</p><p>So the tool for a human-facing config file is the opposite of a serializer: you <strong>render the text by hand</strong>, comments and all, and treat the struct as something you'll parse the result <em>back</em> into later, not something you serialize <em>from</em>. The cost is that you're now responsible for producing valid TOML yourself — which the PR pins down with a test, below.</p><h2>In this PR</h2><p><code>render</code> builds the file as a string. Every line the user benefits from — the header, the <code># TODO</code>s, the commented-out optional block — is text serde would never emit:</p><pre><code class="language-rust">// crates/adj/src/scaffold.rs
+fn render(name: Option&lt;&amp;str&gt;, cmd: Option&lt;&amp;str&gt;) -&gt; String {
+    let name_line = match name {
+        Some(n) =&gt; format!("name = \"{n}\"\n"),
+        None =&gt; "name = \"app\"  # TODO: set a name (lowercase letters, digits, `-`)\n".to_string(),
+    };
+    let cmd_line = match cmd {
+        Some(c) =&gt; format!("cmd = \"{c}\"\n"),
+        None =&gt; "cmd = \"\"  # TODO: set your dev command, e.g. \"npm run dev\"\n".to_string(),
+    };
+    format!(
+        "# Generated by `adj add` — edit and re-run if needed.\n\
+         {name_line}\
+         {cmd_line}\
+         \n\
+         # Optional:\n\
+         # port_env = \"PORT\"\n\
+         # env_file = \".env.local\"\n\
+         # idle_timeout = \"15m\"          # \"30s\" / \"1h\" / \"off\"\n\
+         # health_check_url = \"/healthz\"\n"
+    )
+}
+</code></pre><p>The <code>match name</code> / <code>match cmd</code> is where "known value" and "placeholder with guidance" branch: a detected value renders as a live <code>name = "…"</code> line, an absent one renders as a commented <code># TODO</code>. A serializer can't express that — there's no struct field that means "leave a note for the human here."</p><p>Hand-rendering does put one job on you: emitting <em>valid</em> TOML. The PR's doc comment spells out why this particular template is safe without any escaping logic —</p><pre><code class="language-rust">// crates/adj/src/scaffold.rs
+/// Render the `adjacent.toml` body. `None` fields become TODO placeholders. Detected commands
+/// come from a fixed vocabulary (none contain `"`) and `sanitize_name` guarantees `name` is
+/// `[a-z0-9-]`, so no TOML string escaping is needed here.
+</code></pre><p>— and a unit test nails the door shut by parsing the rendered string back through the real <code>toml</code> crate. If a future edit ever produces something that isn't valid TOML, this goes red:</p><pre><code class="language-rust">// crates/adj/src/scaffold.rs
+assert!(
+    toml::from_str::&lt;toml::Value&gt;(&amp;toml).is_ok(),
+    "invalid toml: {toml}"
+);
+</code></pre><p>That's the safety net that makes hand-rendering defensible: you give up serde's guaranteed-valid output, so you buy it back with a round-trip assertion.</p><p>Then the write, in <code>client::add</code>. The whole thing is guarded on the file <em>not</em> already existing:</p><pre><code class="language-rust">// crates/adj/src/client.rs
+let manifest = canon.join("adjacent.toml");
+if !manifest.exists() {
+    let scaffold = scaffold::build(&amp;canon);
+    std::fs::write(&amp;manifest, &amp;scaffold.toml)
+        .with_context(|| format!("writing {}", manifest.display()))?;
+    // ... branch on detected name/cmd ...
+}
+</code></pre><p><code>std::fs::write</code> is the one-liner form — open (creating or truncating), write the whole buffer, close, all in a call. The <code>if !manifest.exists()</code> in front of it is the not-clobbering rule: a user who already hand-wrote an <code>adjacent.toml</code> never has it silently replaced by a generated one. (An integration test asserts exactly this — an existing manifest comes back byte-identical after <code>adj add</code>.)</p><h2>Why it matters</h2><p>Two traps, one on each side.</p><p><strong>Reaching for the serializer</strong> feels like the disciplined choice and quietly produces a worse file. <code>toml::to_string(&amp;cfg)</code> is faithful and valid — and strips the comments that were the point. The user opens a two-line file with no hint of what else they can set or what they still need to fill in. Knowing <em>when not to serialize</em> is the actual skill here: struct-to-TOML for data you'll read back by machine, hand-rendered text for a file a human edits next.</p><p><strong>Skipping the existence check</strong> is the destructive one. <code>std::fs::write</code> truncates — point it at a path that already holds a carefully-tuned manifest and the old contents are gone, no prompt, no backup. The <code>!exists()</code> guard is what keeps a convenience feature from eating the user's work.</p><p>One honest caveat: <code>exists()</code>-then-<code>write()</code> is check-then-act, so there's a hair-thin window where the file could appear between the two calls. For an interactive command a person runs at a shell, that window doesn't matter. If you needed it to matter — a concurrent or hostile setting — the atomic form is <code>std::fs::OpenOptions::new().create_new(true)</code>, which fails outright if the file already exists rather than checking first. <code>adj add</code> doesn't need it; knowing the upgrade path exists is the point.</p><h2>Related lessons</h2><ul><li><strong>PR #41</strong> is the sibling technique — it also builds a document with <button type="button" class="term" data-term="format-macro"><code>format!</code></button> string templating, and teaches the raw-string-literal (<code>r#"…"#</code>) mechanics that make a multi-line template readable. This lesson is the <em>decision</em> that sits above that mechanism: why you hand-render a config at all instead of serializing a struct, plus the disk write. #41 is <em>how</em> to template; #75 is <em>when</em> (and how not to clobber).</li><li><strong>PR #19</strong> is the exact mirror: it reads <code>adjacent.toml</code> back in with <button type="button" class="term" data-term="derive-macro"><code>#[derive(Deserialize)]</code></button> and <button type="button" class="term" data-term="option"><code>Option</code></button> fields. #75 writes the file #19 parses — and #19's strict "missing <code>cmd</code> is an error" is what the <code># TODO: set your dev command</code> placeholder is steering the user away from tripping.</li><li><strong>PR #22</strong> serializes DTOs to JSON <em>with</em> serde — because that output is consumed by <code>jq</code>, a machine, where a stable derived shape is exactly right. Put next to #75 they're the clean contrast: serialize for machines, hand-render for humans.</li></ul><h2>Dig deeper</h2><ul><li><a href="https://doc.rust-lang.org/std/fs/fn.write.html"><code>std::fs::write</code></a> — the create-or-truncate one-shot write used here.</li><li><a href="https://doc.rust-lang.org/std/fs/struct.OpenOptions.html#method.create_new"><code>std::fs::OpenOptions::create_new</code></a> — the atomic "fail if it already exists" alternative to a separate <code>exists()</code> check.</li><li><a href="https://docs.rs/toml/latest/toml/">The <code>toml</code> crate</a> — <code>toml::from_str</code> (used in the round-trip test) and <code>toml::to_string</code> (the serializer this PR deliberately <em>doesn't</em> use for generation, because it drops comments).</li></ul>
+    </article>
+  </div>
+  <script src="glossary.js"></script>
+  <script src="drawer.js" defer></script>
+</body>
+</html>
diff --git a/ent/lessons/76-derived-env-precedence-order.html b/ent/lessons/76-derived-env-precedence-order.html
new file mode 100644
index 0000000..7209e0f
--- /dev/null
+++ b/ent/lessons/76-derived-env-precedence-order.html
@@ -0,0 +1,65 @@
+<!-- generated by build.mjs; edit docs/lessons/*.md -->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>PR #76 — Inject an ADJ_* boot environment into supervised apps</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@300;400;500;700&display=swap" rel="stylesheet">
+  <link rel="stylesheet" href="lessons.css">
+</head>
+<body>
+  <div class="frame">
+    <header>
+      <a class="wordmark" href="index.html"><span class="a">adj.ac</span><span class="slash">/</span><span class="b">ent</span></a>
+      <a class="back" href="index.html">all lessons</a>
+    </header>
+    <article>
+      <h1>PR #76 — Inject an ADJ_* boot environment into supervised apps</h1>
+      <div class="lesson-header">
+        <p class="lesson">Compute a namespace of derived values into a <code>Vec&lt;(String, String)&gt;</code> with <button type="button" class="term" data-term="format-macro"><code>format!</code></button>, then express precedence as insertion <em>order</em> — inject that layer last so <code>Command::env</code>'s last-writer-wins overwrites anything the user set.</p>
+        <p class="tags"><button type="button" class="term tag" data-term="format-macro"><code>format!</code></button><span class="tag"><code>last-writer-wins</code></span><span class="tag"><code>derived-data</code></span></p>
+        <p class="meta">2026-06-24 · +1303/−12 · <a href="https://github.com/nonrational/adjacent/pull/76">View PR</a></p>
+      </div>
+      <h2>The situation</h2><p>PR #17 injected one variable: <code>$PORT</code>. That let an app <em>bind</em>, but not <em>address itself</em>. A dev server behind the proxy still defaults its own links to <code>localhost:&lt;port&gt;</code> — wrong for every URL a user clicks through <code>*.adj.ac</code>. The daemon knows the real facts (the name, the <code>.adj.ac</code> host, the listener ports); the app can't reconstruct them. So the daemon now hands the app a whole reserved namespace — <code>ADJ_NAME</code>, <code>ADJ_HOST</code>, and four base URLs — computed at boot. And because they're <em>authoritative</em>, they have to beat anything the user set in <code>env_file</code> or <code>[env]</code>.</p><h2>The Rust idea</h2><p>Two ideas, tied together.</p><p><strong>Deriving data with <button type="button" class="term" data-term="format-macro"><code>format!</code></button>.</strong> <button type="button" class="term" data-term="format-macro"><code>format!</code></button> is <code>println!</code>'s sibling that returns instead of prints: it allocates a brand-new owned <button type="button" class="term" data-term="str-vs-string"><code>String</code></button> from a template. <code>format!("https://{host}")</code> interpolates the <code>host</code> variable directly (Rust's inline captures — the name in the braces is a real variable in scope). Owned is the key word: the returned <button type="button" class="term" data-term="str-vs-string"><code>String</code></button> carries its own bytes, so a function can <em>return</em> it or push it into a <button type="button" class="term" data-term="vec"><code>Vec</code></button> without any borrow outliving the stack frame it came from. That's what makes a pure "build the values" helper possible — feed it a name and two ports, get back owned pairs, no daemon or socket required to test it.</p><p><strong>Precedence as insertion order.</strong> <code>Command::env(key, value)</code> inserts-or-overrides a single entry (see #17). When you apply several layers to the same command, <em>the order you apply them in is the precedence policy</em> — the last write for a given key wins. There's no merge function, no priority flag, no "if not already set" check. To make one layer authoritative, you run it last. Precedence stops being a rule buried in a helper and becomes a visible fact about the sequence of statements.</p><h2>In this PR</h2><p>A pure helper builds the derived pairs. Note it returns <code>Vec&lt;(String, String)&gt;</code> — an <em>ordered</em> list of owned key/value tuples, not a map — because the caller only iterates it, and order is exactly what the precedence step needs:</p><pre><code class="language-rust">// crates/adj/src/supervisor.rs
+fn adj_env(name: &amp;str, http: Option&lt;u16&gt;, https: Option&lt;u16&gt;) -&gt; Vec&lt;(String, String)&gt; {
+    let host = format!("{name}{}", crate::proxy::HOST_SUFFIX);
+    let mut vars = vec![
+        ("ADJ_NAME".to_string(), name.to_string()),
+        ("ADJ_HOST".to_string(), host.clone()),
+        ("ADJ_URL".to_string(), format!("https://{host}")),
+        ("ADJ_URL_HTTP".to_string(), format!("http://{host}")),
+    ];
+    if let Some(p) = https {
+        vars.push(("ADJ_URL_DIRECT".to_string(), format!("https://{host}:{p}")));
+    }
+    if let Some(p) = http {
+        vars.push((
+            "ADJ_URL_HTTP_DIRECT".to_string(),
+            format!("http://{host}:{p}"),
+        ));
+    }
+    vars
+}
+</code></pre><ul><li><code>host</code> is computed once, then reused. <code>host.clone()</code> hands one owned copy to the <code>ADJ_HOST</code> pair while the original stays live for the three <button type="button" class="term" data-term="format-macro"><code>format!</code></button> calls below it — each of those <em>borrows</em> <code>host</code> (<code>&amp;host</code> under the hood) to read its bytes, so <code>host</code> must still exist.</li><li>The four unconditional entries go in a <code>vec![…]</code> literal. The two <code>_DIRECT</code> URLs are <strong>conditional</strong>: <code>if let Some(p) = https</code> unwraps the port only when it resolved, and <code>.push</code>es a pair carrying it. A <button type="button" class="term" data-term="option"><code>None</code></button> port means that URL is simply absent — no entry pointing at a dead port. Optionality is expressed by <em>whether the pair exists</em>, not by an empty string.</li><li>Everything is an owned <button type="button" class="term" data-term="str-vs-string"><code>String</code></button>. <code>"ADJ_NAME".to_string()</code> and each <button type="button" class="term" data-term="format-macro"><code>format!</code></button> produce data the <button type="button" class="term" data-term="vec"><code>Vec</code></button> owns outright, so the whole thing can be returned by value.</li></ul><p>Then <code>up()</code> applies it as the final env layer:</p><pre><code class="language-rust">// crates/adj/src/supervisor.rs
+command.env(port_env, port.to_string());
+// Daemon-owned ADJ_* namespace: the app's own external identity and URLs. Injected
+// after env_file/[env] so these authoritative values win over anything a user set.
+for (k, v) in adj_env(&amp;name, self.proxy_ports.http(), self.proxy_ports.https()) {
+    command.env(k, v);
+}
+</code></pre><p>The full precedence chain, top to bottom, is <code>env_file</code> → <code>[env]</code> → <code>PORT</code> → <code>ADJ_*</code>. Each <code>command.env</code> call overwrites the same key from an earlier layer. The <code>ADJ_*</code> loop runs <em>last</em>, so if a user set <code>ADJ_HOST</code> in their <code>[env]</code> table, the daemon's value silently overwrites it. That's the entire enforcement of "reserved, daemon-owned namespace" — no validation, no rejection, just position in the sequence.</p><p>Because <code>adj_env</code> is pure and returns plain data, the unit tests skip the daemon entirely and collect the pairs into a <button type="button" class="term" data-term="hashmap"><code>HashMap</code></button> for random-access lookup by key:</p><pre><code class="language-rust">// crates/adj/src/supervisor.rs
+let vars: std::collections::HashMap&lt;String, String&gt; =
+    adj_env("alannorton-com", Some(8080), Some(8443))
+        .into_iter()
+        .collect();
+assert_eq!(vars["ADJ_URL_DIRECT"], "https://alannorton-com.adj.ac:8443");
+</code></pre><p>The builder returns a <button type="button" class="term" data-term="vec"><code>Vec</code></button> (order matters, for precedence and for iteration); the test <button type="button" class="term" data-term="collect"><code>.collect()</code></button>s it into a <button type="button" class="term" data-term="hashmap"><code>HashMap</code></button> because <em>it</em> only wants "give me the value for this key." Same pairs, two container shapes, each chosen for what the code at hand does with them.</p><h2>Why it matters</h2><p>In a language where you mutate a shared, global environment or reach for a <code>merge(defaults, overrides)</code> helper, precedence is implicit and easy to get backwards. Someone reorders two blocks, or flips an argument, and user config silently starts winning over values that were supposed to be authoritative — a bug that type-checks and passes most tests. Here the policy is one readable fact: the <code>ADJ_*</code> loop is the last thing that touches the environment before spawn, so it wins by construction. Move it above the <code>[env]</code> layer and the precedence inverts — but you'd <em>see</em> that in the diff, because it's a line order, not a hidden flag.</p><p>The derived-data half pays off in testing. <button type="button" class="term" data-term="format-macro"><code>format!</code></button> returning owned <button type="button" class="term" data-term="str-vs-string"><code>String</code></button>s lets <code>adj_env</code> be a pure function of <code>(name, http, https)</code> — no I/O, no clock, no socket. Every value format, the worktree-key case, and the "port unresolved → drop the URL" rule get asserted in plain unit tests that run in microseconds, with the end-to-end test left to prove only that the wiring reaches a real child.</p><h2>Related lessons</h2><ul><li>PR #17 is the one-variable version of this exact mechanic: <code>Command::env</code> as insert-or-override, and why the value must be an owned <button type="button" class="term" data-term="str-vs-string"><code>String</code></button>. #17 injects <code>PORT</code> alone; #76 generalizes it into a computed namespace and makes the <em>layer order</em> load-bearing. Read #17 first for the builder and inheritance model; this lesson is about deriving a set of values and using order as precedence.</li><li>PR #45 builds rows the cousin way — <code>map</code> + <button type="button" class="term" data-term="collect"><code>collect</code></button> into a collection — where order doesn't carry meaning the way it does here.</li></ul><h2>Dig deeper</h2><ul><li><a href="https://doc.rust-lang.org/std/macro.format.html"><code>std::fmt</code> / the <button type="button" class="term" data-term="format-macro"><code>format!</code></button> macro</a> — the template syntax, inline argument captures (<code>{host}</code>), and that it returns an owned <button type="button" class="term" data-term="str-vs-string"><code>String</code></button>.</li><li><a href="https://doc.rust-lang.org/std/collections/struct.HashMap.html"><code>std::collections::HashMap</code></a> — the "Which collection?" preamble at the top of the <a href="https://doc.rust-lang.org/std/collections/index.html"><code>std::collections</code></a> module is the canonical guide to <button type="button" class="term" data-term="vec"><code>Vec</code></button> vs <button type="button" class="term" data-term="hashmap"><code>HashMap</code></button>: sequence-with-order vs lookup-by-key, exactly the choice this PR makes twice.</li></ul>
+    </article>
+  </div>
+  <script src="glossary.js"></script>
+  <script src="drawer.js" defer></script>
+</body>
+</html>
diff --git a/ent/lessons/build.mjs b/ent/lessons/build.mjs
new file mode 100644
index 0000000..3d06db1
--- /dev/null
+++ b/ent/lessons/build.mjs
@@ -0,0 +1,606 @@
+// Dependency-free generator for the interactive Rust lessons site.
+// Reads docs/lessons/*.md (source of truth) + docs/lessons/glossary.json,
+// emits static HTML + shared assets into ent/lessons/. Run from repo root.
+
+// Placeholder sentinel: a NUL char, built at runtime so no literal NUL (which
+// would make git treat this file as binary) ever sits in the source. NUL never
+// appears in lesson prose, so restoring placeholders can't collide with text.
+const NUL = String.fromCharCode(0);
+const PLACEHOLDER = new RegExp(NUL + '(\\d+)' + NUL, 'g');
+
+const emphasize = (str) =>
+  str.replace(/\*\*([^*]+)\*\*/g, '<strong>$1</strong>').replace(/\*([^*]+)\*/g, '<em>$1</em>');
+
+export function escapeHtml(s) {
+  return String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+
+export function escapeAttr(s) {
+  return escapeHtml(s).replace(/"/g, '&quot;');
+}
+
+// Render one run of inline markdown. Inline code is extracted first so its
+// contents are never reinterpreted as emphasis; links are extracted before
+// escaping so their hrefs stay clean. A glossary index (alias -> key), when
+// supplied, turns a matching code span into a clickable term button (Task 4).
+export function renderInline(text, { glossaryIndex } = {}) {
+  const slots = [];
+  const stash = (html) => NUL + (slots.push(html) - 1) + NUL;
+
+  let s = String(text).replace(/`([^`]+)`/g, (_, code) => {
+    const inner = `<code>${escapeHtml(code)}</code>`;
+    const key = glossaryIndex && glossaryIndex.get(code);
+    return stash(
+      key
+        ? `<button type="button" class="term" data-term="${escapeAttr(key)}">${inner}</button>`
+        : inner,
+    );
+  });
+
+  s = s.replace(/\[([^\]]+)\]\(([^)]+)\)/g, (_, label, href) => {
+    const h = /^\d+-[a-z0-9-]+\.md$/.test(href) ? href.replace(/\.md$/, '.html') : href;
+    // The label may already hold code placeholders from the pass above; escape
+    // its plain text and apply emphasis, leaving placeholders for the final
+    // restore. One shared slots array keeps nested code spans resolvable.
+    const inner = emphasize(escapeHtml(label));
+    return stash(`<a href="${escapeAttr(h)}">${inner}</a>`);
+  });
+
+  s = emphasize(escapeHtml(s));
+
+  // Restore repeatedly: a stashed link can itself contain a code placeholder,
+  // and a single global replace does not re-scan the text it just inserted.
+  while (PLACEHOLDER.test(s)) {
+    PLACEHOLDER.lastIndex = 0;
+    s = s.replace(PLACEHOLDER, (_, i) => slots[Number(i)]);
+  }
+  return s;
+}
+
+// Block-level renderer for the bounded markdown the lessons use: ATX headings,
+// paragraphs, fenced code (literal), and unordered/ordered lists with one
+// nesting level. Blockquotes are handled by parseLesson (the header) and do
+// not appear in bodies, so they are intentionally unsupported here.
+export function renderMarkdown(body, { glossaryIndex } = {}) {
+  const lines = String(body).replace(/\r\n/g, '\n').split('\n');
+  const out = [];
+  let i = 0;
+
+  while (i < lines.length) {
+    const line = lines[i];
+
+    if (/^```/.test(line)) {
+      const lang = line.slice(3).trim();
+      const buf = [];
+      i++;
+      while (i < lines.length && !/^```/.test(lines[i])) buf.push(lines[i++]);
+      i++; // consume closing fence
+      const cls = lang ? ` class="language-${escapeAttr(lang)}"` : '';
+      out.push(`<pre><code${cls}>${escapeHtml(buf.join('\n') + '\n')}</code></pre>`);
+      continue;
+    }
+
+    const heading = line.match(/^(#{1,3})\s+(.*)$/);
+    if (heading) {
+      const level = heading[1].length;
+      out.push(`<h${level}>${renderInline(heading[2].trim(), { glossaryIndex })}</h${level}>`);
+      i++;
+      continue;
+    }
+
+    if (/^\s*([-*]|\d+\.)\s+/.test(line)) {
+      const { html, next } = parseList(lines, i, glossaryIndex);
+      out.push(html);
+      i = next;
+      continue;
+    }
+
+    if (line.trim() === '') {
+      i++;
+      continue;
+    }
+
+    const para = [];
+    while (
+      i < lines.length &&
+      lines[i].trim() !== '' &&
+      !/^(#{1,3}\s|```|\s*([-*]|\d+\.)\s)/.test(lines[i])
+    ) {
+      para.push(lines[i]);
+      i++;
+    }
+    out.push(`<p>${renderInline(para.join(' ').replace(/\s+/g, ' ').trim(), { glossaryIndex })}</p>`);
+  }
+
+  return out.join('');
+}
+
+// Parse one list (plus one level of nested sub-lists) starting at line `i`.
+// Item text accumulates lazy-continuation lines (wrapped prose) the way the
+// paragraph branch does, so a bullet spanning several source lines stays a
+// single <li>. A marker indented deeper than this list's base opens a nested
+// list under the current item; a shallower marker, a blank line, a block
+// start, or a marker-type change ends the list. Returns the HTML and the
+// index just past the list.
+function parseList(lines, i, glossaryIndex) {
+  const first = lines[i].match(/^(\s*)([-*]|\d+\.)\s+/);
+  const baseIndent = first[1].length;
+  const ordered = /\d+\./.test(first[2]);
+  const tag = ordered ? 'ol' : 'ul';
+  const items = [];
+
+  while (i < lines.length) {
+    const line = lines[i];
+    if (line.trim() === '') break;              // blank line ends the list
+    if (/^(#{1,3}\s|```)/.test(line)) break;    // a block start ends the list
+    const m = line.match(/^(\s*)([-*]|\d+\.)\s+(.*)$/);
+    if (m) {
+      const indent = m[1].length;
+      if (indent > baseIndent) {                // deeper: nested list under last item
+        const sub = parseList(lines, i, glossaryIndex);
+        if (items.length) items[items.length - 1].children += sub.html;
+        i = sub.next;
+        continue;
+      }
+      if (indent < baseIndent) break;           // dedent: this list is done
+      if (/\d+\./.test(m[2]) !== ordered) break; // marker type change ends the list
+      items.push({ text: m[3], children: '' });
+      i++;
+      continue;
+    }
+    if (items.length) {                          // lazy continuation of current item
+      items[items.length - 1].text += ` ${line.trim()}`;
+      i++;
+      continue;
+    }
+    break;
+  }
+
+  const body = items
+    .map(
+      (it) =>
+        `<li>${renderInline(it.text.replace(/\s+/g, ' ').trim(), { glossaryIndex })}${it.children}</li>`,
+    )
+    .join('');
+  return { html: `<${tag}>${body}</${tag}>`, next: i };
+}
+
+// Parse a lesson file of the fixed template shape into structured parts.
+export function parseLesson(filename, md) {
+  const fm = filename.match(/^(\d+)-([a-z0-9-]+)\.md$/);
+  if (!fm) throw new Error(`not a lesson filename: ${filename}`);
+  const pr = Number(fm[1]);
+  const slug = fm[2];
+
+  let rest = String(md).replace(/^/, '').replace(/^<!--[\s\S]*?-->\s*/, '');
+
+  const titleMatch = rest.match(/^#\s+(.*)\n?/);
+  const title = titleMatch ? titleMatch[1].trim() : '';
+  if (titleMatch) rest = rest.slice(titleMatch[0].length);
+
+  const lines = rest.split('\n');
+  let i = 0;
+  while (i < lines.length && lines[i].trim() === '') i++;
+  const quote = [];
+  while (i < lines.length && lines[i].startsWith('>')) {
+    quote.push(lines[i].replace(/^>\s?/, ''));
+    i++;
+  }
+  const bodyMarkdown = lines.slice(i).join('\n').trim();
+
+  const field = (label) => (quote.find((l) => l.startsWith(`**${label}:**`)) || '')
+    .replace(new RegExp(`^\\*\\*${label}:\\*\\*\\s*`), '')
+    .trim();
+
+  const lesson = field('Rust lesson');
+  const tags = field('Tags').split('·').map((t) => t.replace(/`/g, '').trim()).filter(Boolean);
+  const mergedRaw = field('Merged');
+  const mm = mergedRaw.match(/^([0-9-]+)\s*·\s*(.+?)\s*·\s*\[[^\]]*\]\(([^)]+)\)/);
+  const merged = mm
+    ? { date: mm[1].trim(), delta: mm[2].trim(), url: mm[3].trim() }
+    : { date: '', delta: '', url: '' };
+
+  return { pr, slug, title, lesson, tags, merged, bodyMarkdown };
+}
+
+// Every prereq must resolve to a real entry; every alias/term must be unique
+// across entries (an ambiguous alias could not annotate deterministically).
+export function validateGlossary(glossary) {
+  const errors = [];
+  const warnings = [];
+  const keys = new Set(Object.keys(glossary));
+  const seen = new Map();
+  for (const [key, e] of Object.entries(glossary)) {
+    for (const p of e.prereqs || []) {
+      if (!keys.has(p)) errors.push(`entry '${key}': prereq '${p}' has no glossary entry`);
+    }
+    for (const name of [e.term, ...(e.aliases || [])]) {
+      if (!name) continue;
+      if (seen.has(name) && seen.get(name) !== key) {
+        errors.push(`alias '${name}' maps to both '${seen.get(name)}' and '${key}'`);
+      } else {
+        seen.set(name, key);
+      }
+    }
+  }
+  return { errors, warnings };
+}
+
+export function buildGlossaryIndex(glossary) {
+  const idx = new Map();
+  for (const [key, e] of Object.entries(glossary)) {
+    for (const name of [e.term, ...(e.aliases || [])]) {
+      if (name) idx.set(name, key);
+    }
+  }
+  return idx;
+}
+
+export function coverageReport(lessons, glossaryIndex) {
+  const counts = new Map();
+  for (const l of lessons) {
+    const noFences = String(l.bodyMarkdown).replace(/```[\s\S]*?```/g, '');
+    for (const m of noFences.matchAll(/`([^`]+)`/g)) {
+      const t = m[1];
+      if (!glossaryIndex.has(t)) counts.set(t, (counts.get(t) || 0) + 1);
+    }
+  }
+  return [...counts.entries()]
+    .map(([term, count]) => ({ term, count }))
+    .sort((a, b) => b.count - a.count || a.term.localeCompare(b.term));
+}
+
+// ---- Theme + config (the repo-specific seam; swap this to retarget) ----
+export const THEME = {
+  name: 'adjacent',
+  palette: {
+    ink: '#0a0a0a', paper: '#ededea', soft: '#b5b5af', dim: '#7a7a74',
+    rule: '#1f1f1d', accent: '#d4a574', accentDim: '#8a6a44',
+  },
+  fontLinks: [
+    '<link rel="preconnect" href="https://fonts.googleapis.com">',
+    '<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>',
+    '<link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@300;400;500;700&display=swap" rel="stylesheet">',
+  ].join('\n  '),
+  fontStack: "'JetBrains Mono', ui-monospace, SFMono-Regular, Menlo, monospace",
+  wordmark: { a: 'adj.ac', slash: '/', b: 'ent' },
+  siteTitle: 'adj.ac/ent — Rust, one PR at a time',
+  repoUrl: 'https://github.com/nonrational/adjacent',
+  paths: { lessonsDir: 'docs/lessons', readme: 'docs/lessons/README.md', outDir: 'ent/lessons' },
+};
+
+const HTML_HEADER = '<!-- generated by build.mjs; edit docs/lessons/*.md -->';
+const ASSET_HEADER = '/* generated by build.mjs; edit docs/lessons/*.md */';
+
+export function renderTagChips(tags, glossaryIndex) {
+  return tags
+    .map((t) => {
+      const key = glossaryIndex.get(t);
+      const code = `<code>${escapeHtml(t)}</code>`;
+      return key
+        ? `<button type="button" class="term tag" data-term="${escapeAttr(key)}">${code}</button>`
+        : `<span class="tag">${code}</span>`;
+    })
+    .join('');
+}
+
+export function renderLessonPage(parsed, { glossaryIndex, theme = THEME }) {
+  const { a, slash, b } = theme.wordmark;
+  const body = renderMarkdown(parsed.bodyMarkdown, { glossaryIndex });
+  const lesson = renderInline(parsed.lesson, { glossaryIndex });
+  const chips = renderTagChips(parsed.tags, glossaryIndex);
+  const prLink = parsed.merged.url
+    ? `<a href="${escapeAttr(parsed.merged.url)}">View PR</a>`
+    : '';
+  return `${HTML_HEADER}
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${escapeHtml(parsed.title)}</title>
+  ${theme.fontLinks}
+  <link rel="stylesheet" href="lessons.css">
+</head>
+<body>
+  <div class="frame">
+    <header>
+      <a class="wordmark" href="index.html"><span class="a">${a}</span><span class="slash">${slash}</span><span class="b">${b}</span></a>
+      <a class="back" href="index.html">all lessons</a>
+    </header>
+    <article>
+      <h1>${escapeHtml(parsed.title)}</h1>
+      <div class="lesson-header">
+        <p class="lesson">${lesson}</p>
+        <p class="tags">${chips}</p>
+        <p class="meta">${escapeHtml(parsed.merged.date)} · ${escapeHtml(parsed.merged.delta)} · ${prLink}</p>
+      </div>
+      ${body}
+    </article>
+  </div>
+  <script src="glossary.js"></script>
+  <script src="drawer.js" defer></script>
+</body>
+</html>
+`;
+}
+
+export function renderStylesheet(theme = THEME) {
+  const p = theme.palette;
+  return `${ASSET_HEADER}
+:root {
+  --ink: ${p.ink}; --paper: ${p.paper}; --soft: ${p.soft}; --dim: ${p.dim};
+  --rule: ${p.rule}; --accent: ${p.accent}; --accent-dim: ${p.accentDim};
+}
+* { box-sizing: border-box; margin: 0; padding: 0; }
+html, body { background: var(--ink); color: var(--paper); font-family: ${theme.fontStack}; font-size: 15px; line-height: 1.65; -webkit-font-smoothing: antialiased; }
+body { min-height: 100vh; padding: 3rem clamp(1.25rem, 6vw, 5rem); }
+.frame { max-width: 760px; margin: 0 auto; }
+header { display: flex; justify-content: space-between; align-items: baseline; margin-bottom: 3rem; }
+.wordmark { font-weight: 700; font-size: 1.1rem; letter-spacing: -0.03em; text-decoration: none; }
+.wordmark .a { color: var(--paper); } .wordmark .b { color: var(--accent); } .wordmark .slash { color: var(--rule); font-weight: 300; margin: 0 0.1em; }
+.back { font-size: 12px; color: var(--dim); text-transform: uppercase; letter-spacing: 0.1em; text-decoration: none; border-bottom: 1px dotted var(--dim); }
+.back:hover { color: var(--accent); border-color: var(--accent); }
+article h1 { font-size: clamp(1.6rem, 4vw, 2.3rem); font-weight: 700; letter-spacing: -0.02em; line-height: 1.15; margin-bottom: 1.5rem; }
+.lesson-header { border-left: 2px solid var(--accent-dim); padding-left: 1.1rem; margin-bottom: 2.5rem; }
+.lesson-header .lesson { font-size: 1.15rem; font-weight: 300; margin-bottom: 0.75rem; }
+.lesson-header .tags { display: flex; flex-wrap: wrap; gap: 0.4rem; margin-bottom: 0.6rem; }
+.lesson-header .meta { font-size: 12px; color: var(--dim); letter-spacing: 0.04em; }
+article h2 { font-size: 1.25rem; margin: 2.5rem 0 1rem; padding-top: 1.25rem; border-top: 1px solid var(--rule); }
+article h3 { font-size: 1.05rem; margin: 1.75rem 0 0.75rem; }
+article p { margin-bottom: 1rem; color: var(--paper); }
+article ul, article ol { margin: 0 0 1rem 1.4rem; }
+article li { margin-bottom: 0.35rem; }
+article a { color: var(--paper); text-decoration: none; border-bottom: 1px solid var(--accent-dim); }
+article a:hover { color: var(--accent); border-color: var(--accent); }
+code { font-family: inherit; color: var(--accent); font-size: 0.95em; }
+pre { background: rgba(255,255,255,0.02); border: 1px solid var(--rule); border-left: 2px solid var(--accent-dim); padding: 1rem 1.15rem; margin-bottom: 1.25rem; overflow-x: auto; }
+pre code { color: var(--paper); font-size: 13px; line-height: 1.5; }
+.term { font: inherit; background: none; border: none; padding: 0; cursor: pointer; border-bottom: 1px dotted var(--accent); }
+.term:hover, .term:focus-visible { background: rgba(212,165,116,0.1); }
+.tag code { font-size: 0.85em; }
+span.tag { border-bottom: 1px dotted var(--rule); }
+table.index { width: 100%; border-collapse: collapse; margin-bottom: 2.5rem; font-size: 0.9rem; }
+table.index td { border-bottom: 1px solid var(--rule); padding: 0.6rem 0.75rem 0.6rem 0; vertical-align: top; }
+table.index td.pr { white-space: nowrap; }
+table.index td.pr a { color: var(--accent); border: none; }
+table.index td.takeaway { color: var(--soft); }
+table.index tr.sparse td { color: var(--dim); }
+table.index .mark { color: var(--accent-dim); }
+/* Drawer (built by drawer.js) */
+.drawer-scrim { position: fixed; inset: 0; background: rgba(0,0,0,0.4); opacity: 0; pointer-events: none; transition: opacity 0.15s; z-index: 10; }
+.drawer-scrim.open { opacity: 1; pointer-events: auto; }
+.drawer { position: fixed; top: 0; right: 0; height: 100%; width: min(360px, 90vw); background: var(--ink); border-left: 1px solid var(--rule); transform: translateX(100%); transition: transform 0.18s ease-out; z-index: 11; padding: 1.75rem 1.5rem; overflow-y: auto; }
+.drawer.open { transform: none; }
+.drawer .close { position: absolute; top: 1rem; right: 1.1rem; background: none; border: none; color: var(--dim); font: inherit; font-size: 1.2rem; cursor: pointer; }
+.drawer .close:hover { color: var(--accent); }
+.drawer .back-link { background: none; border: none; color: var(--dim); font: inherit; font-size: 12px; letter-spacing: 0.08em; text-transform: uppercase; cursor: pointer; margin-bottom: 1rem; display: none; }
+.drawer.has-history .back-link { display: inline-block; }
+.drawer .d-term { color: var(--accent); font-weight: 700; font-size: 1.1rem; margin-bottom: 0.9rem; word-break: break-word; }
+.drawer .d-label { font-size: 11px; letter-spacing: 0.16em; text-transform: uppercase; color: var(--dim); margin: 1.2rem 0 0.4rem; }
+.drawer .d-short, .drawer .d-why { color: var(--paper); font-size: 0.95rem; }
+.drawer .d-prereqs { display: flex; flex-wrap: wrap; gap: 0.4rem; }
+.drawer .d-prereqs .term { border: 1px solid var(--accent-dim); border-radius: 2px; padding: 0.2rem 0.55rem; }
+.drawer .d-link a { color: var(--accent); font-size: 0.9rem; }
+@media (max-width: 540px) { body { padding: 2rem 1.1rem; } }
+`;
+}
+
+export function renderGlossaryScript(glossary) {
+  return `${ASSET_HEADER}\nwindow.__GLOSSARY__ = ${JSON.stringify(glossary, null, 0)};\n`;
+}
+
+// Browser-side drawer. Built as a string so the generator can emit it verbatim.
+// Progressive enhancement: with JS off, .term buttons are inert and the lesson
+// stays fully readable.
+const DRAWER_JS = String.raw`(() => {
+  const G = window.__GLOSSARY__ || {};
+  const scrim = document.createElement('div');
+  scrim.className = 'drawer-scrim';
+  const drawer = document.createElement('aside');
+  drawer.className = 'drawer';
+  drawer.setAttribute('role', 'dialog');
+  drawer.setAttribute('aria-label', 'Term explanation');
+  drawer.innerHTML =
+    '<button class="close" aria-label="Close">×</button>' +
+    '<button class="back-link">← back</button>' +
+    '<div class="d-body"></div>';
+  document.body.append(scrim, drawer);
+  const body = drawer.querySelector('.d-body');
+  // Escapes text and attribute values alike (includes ") so a quote in a glossary key or URL can't break out of an attribute.
+  const esc = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+  let history = [];
+
+  function render(key) {
+    const e = G[key];
+    if (!e) return;
+    const prereqs = (e.prereqs || [])
+      .filter((k) => G[k])
+      .map((k) => '<button type="button" class="term" data-term="' + esc(k) + '"><code>' + esc(G[k].term) + '</code></button>')
+      .join('');
+    const link = e.link ? '<p class="d-label">Dig deeper</p><p class="d-link"><a href="' + esc(e.link.url) + '" target="_blank" rel="noopener">' + esc(e.link.label) + '</a></p>' : '';
+    body.innerHTML =
+      '<p class="d-term">' + esc(e.term) + '</p>' +
+      '<p class="d-short">' + esc(e.short || '') + '</p>' +
+      (e.why ? '<p class="d-label">Why it matters</p><p class="d-why">' + esc(e.why) + '</p>' : '') +
+      (prereqs ? '<p class="d-label">Learn first</p><div class="d-prereqs">' + prereqs + '</div>' : '') +
+      link;
+    // Back is shown only once we've descended past the root term.
+    drawer.classList.toggle('has-history', history.length > 1);
+  }
+
+  function open(key) {
+    history = [key];
+    render(key);
+    scrim.classList.add('open');
+    drawer.classList.add('open');
+  }
+  function close() {
+    scrim.classList.remove('open');
+    drawer.classList.remove('open');
+    history = [];
+    drawer.classList.remove('has-history');
+  }
+
+  document.addEventListener('click', (ev) => {
+    const term = ev.target.closest('.term');
+    if (term && term.dataset.term) {
+      ev.preventDefault();
+      if (ev.target.closest('.drawer')) {
+        history.push(term.dataset.term); // descend into a prereq
+        render(term.dataset.term);
+      } else {
+        open(term.dataset.term);         // open from the lesson prose
+      }
+      return;
+    }
+    if (ev.target.closest('.drawer .close')) { close(); }
+  });
+  drawer.querySelector('.back-link').addEventListener('click', () => {
+    history.pop();
+    const prev = history[history.length - 1];
+    if (prev) { render(prev); } else { close(); }
+  });
+  scrim.addEventListener('click', close);
+  document.addEventListener('keydown', (ev) => { if (ev.key === 'Escape') close(); });
+})();
+`;
+
+export function renderDrawerScript() {
+  return `${ASSET_HEADER}\n${DRAWER_JS}`;
+}
+
+export function parseReadmeIndex(readmeMd) {
+  const rows = [];
+  // Markdown table cells escape a literal pipe as backslash-pipe; restore it for display.
+  const unpipe = (s) => s.replace(/\\\|/g, '|');
+  const rowRe = /^\|\s*\[#(\d+)\]\(([^)]+)\)\s*(◦)?\s*\|\s*(.+?)\s*\|\s*(.+?)\s*\|$/gm;
+  for (const m of readmeMd.matchAll(rowRe)) {
+    rows.push({
+      pr: Number(m[1]),
+      href: m[2].replace(/\.md$/, '.html'),
+      sparse: Boolean(m[3]),
+      lesson: unpipe(m[4]),
+      takeaway: unpipe(m[5]),
+    });
+  }
+  const paths = [];
+  const pathRe = /^-\s+\*\*(.+?)\*\*\s+—\s+(.+)$/gm;
+  for (const m of readmeMd.matchAll(pathRe)) {
+    paths.push({ theme: m[1], html: renderInline(m[2]) });
+  }
+  return { rows, paths };
+}
+
+export function renderIndexPage(readmeMd, { theme = THEME } = {}) {
+  const { rows, paths } = parseReadmeIndex(readmeMd);
+  const { a, slash, b } = theme.wordmark;
+  const rowHtml = rows
+    .map((r) => `<tr${r.sparse ? ' class="sparse"' : ''}><td class="pr"><a href="${escapeAttr(r.href)}">#${r.pr}</a>${r.sparse ? ' <span class="mark">◦</span>' : ''}</td><td>${renderInline(r.lesson)}</td><td class="takeaway">${renderInline(r.takeaway)}</td></tr>`)
+    .join('\n      ');
+  const pathHtml = paths
+    .map((p) => `<li><strong>${escapeHtml(p.theme)}</strong> — ${p.html}</li>`)
+    .join('\n      ');
+  return `${HTML_HEADER}
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${escapeHtml(theme.siteTitle)}</title>
+  ${theme.fontLinks}
+  <link rel="stylesheet" href="lessons.css">
+</head>
+<body>
+  <div class="frame">
+    <header>
+      <a class="wordmark" href="${escapeAttr(theme.repoUrl)}"><span class="a">${a}</span><span class="slash">${slash}</span><span class="b">${b}</span></a>
+      <span class="back">Rust, one PR at a time</span>
+    </header>
+    <article>
+      <h1>Rust, one PR at a time</h1>
+      <table class="index">
+      ${rowHtml}
+      </table>
+      <h2>Reading paths by theme</h2>
+      <ul>
+      ${pathHtml}
+      </ul>
+    </article>
+  </div>
+</body>
+</html>
+`;
+}
+
+import { readFileSync, writeFileSync, readdirSync, mkdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export function checkCrossLinks(lessons) {
+  const known = new Set(lessons.map((l) => `${l.pr}-${l.slug}.md`));
+  const errors = [];
+  const linkRe = /\]\((\d+-[a-z0-9-]+\.md)\)/g;
+  for (const l of lessons) {
+    for (const m of l.bodyMarkdown.matchAll(linkRe)) {
+      if (!known.has(m[1])) errors.push(`${l.pr}-${l.slug}.md links to missing lesson '${m[1]}'`);
+    }
+  }
+  return errors;
+}
+
+export function buildSite({ lessons, glossary, readmeMd, theme = THEME }) {
+  const glossaryIndex = buildGlossaryIndex(glossary);
+  const files = new Map();
+  for (const lesson of lessons) {
+    files.set(`${lesson.pr}-${lesson.slug}.html`, renderLessonPage(lesson, { glossaryIndex, theme }));
+  }
+  files.set('index.html', renderIndexPage(readmeMd, { theme }));
+  files.set('lessons.css', renderStylesheet(theme));
+  files.set('drawer.js', renderDrawerScript());
+  files.set('glossary.js', renderGlossaryScript(glossary));
+  return files;
+}
+
+export async function main(argv) {
+  const check = argv.includes('--check');
+  const root = process.cwd();
+  const { lessonsDir, readme, outDir } = THEME.paths;
+
+  const glossary = JSON.parse(readFileSync(join(root, lessonsDir, 'glossary.json'), 'utf8'));
+  const { errors } = validateGlossary(glossary);
+
+  const files = readdirSync(join(root, lessonsDir)).filter((f) => /^\d+-[a-z0-9-]+\.md$/.test(f));
+  const lessons = files
+    .map((f) => parseLesson(f, readFileSync(join(root, lessonsDir, f), 'utf8')))
+    .sort((a, b) => a.pr - b.pr);
+  const linkErrors = checkCrossLinks(lessons);
+
+  const allErrors = [...errors, ...linkErrors];
+  if (allErrors.length) {
+    console.error('build failed:\n' + allErrors.map((e) => '  - ' + e).join('\n'));
+    process.exitCode = 1;
+    return;
+  }
+
+  const missing = coverageReport(lessons, buildGlossaryIndex(glossary));
+  if (missing.length) {
+    console.log(`coverage: ${missing.length} backticked terms not in glossary (top 10):`);
+    console.log(missing.slice(0, 10).map((m) => `  ${m.count}x  ${m.term}`).join('\n'));
+  }
+
+  if (check) {
+    console.log(`check OK — ${lessons.length} lessons, ${Object.keys(glossary).length} glossary entries`);
+    return;
+  }
+
+  const readmeMd = readFileSync(join(root, readme), 'utf8');
+  const out = buildSite({ lessons, glossary, readmeMd });
+  mkdirSync(join(root, outDir), { recursive: true });
+  for (const [name, content] of out) writeFileSync(join(root, outDir, name), content);
+  console.log(`wrote ${out.size} files to ${outDir}`);
+}
+
+if (import.meta.main) {
+  main(process.argv.slice(2));
+}
diff --git a/ent/lessons/build.test.mjs b/ent/lessons/build.test.mjs
new file mode 100644
index 0000000..876cf15
--- /dev/null
+++ b/ent/lessons/build.test.mjs
@@ -0,0 +1,340 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { escapeHtml, escapeAttr, renderInline, renderMarkdown, parseLesson, validateGlossary, buildGlossaryIndex, coverageReport } from './build.mjs';
+
+test('escapeHtml escapes angle brackets and ampersands', () => {
+  assert.equal(escapeHtml('a < b & c > d'), 'a &lt; b &amp; c &gt; d');
+});
+
+test('escapeAttr also escapes double quotes', () => {
+  assert.equal(escapeAttr('say "hi" & <go>'), 'say &quot;hi&quot; &amp; &lt;go&gt;');
+});
+
+test('renderInline: inline code is escaped and wrapped in <code>', () => {
+  assert.equal(renderInline('use `Vec<T>` here'), 'use <code>Vec&lt;T&gt;</code> here');
+});
+
+test('renderInline: bold and italic', () => {
+  assert.equal(renderInline('**bold** and *soft*'), '<strong>bold</strong> and <em>soft</em>');
+});
+
+test('renderInline: content inside inline code is not treated as bold/italic', () => {
+  assert.equal(renderInline('`a * b * c`'), '<code>a * b * c</code>');
+});
+
+test('renderInline: external link passes through', () => {
+  assert.equal(
+    renderInline('[View PR](https://example.com/pull/16)'),
+    '<a href="https://example.com/pull/16">View PR</a>',
+  );
+});
+
+test('renderInline: cross-lesson .md link is rewritten to .html', () => {
+  assert.equal(
+    renderInline('[PR #40](40-serve-https-local-ca.md)'),
+    '<a href="40-serve-https-local-ca.html">PR #40</a>',
+  );
+});
+
+test('renderInline: a link label containing inline code renders the code span', () => {
+  assert.equal(
+    renderInline('run [`adj install-ca`](40-serve-https-local-ca.md) first'),
+    'run <a href="40-serve-https-local-ca.html"><code>adj install-ca</code></a> first',
+  );
+});
+
+test('renderMarkdown: heading levels', () => {
+  assert.equal(renderMarkdown('## The Rust idea'), '<h2>The Rust idea</h2>');
+  assert.equal(renderMarkdown('### Where this is headed'), '<h3>Where this is headed</h3>');
+});
+
+test('renderMarkdown: paragraph joins wrapped lines and renders inline', () => {
+  assert.equal(
+    renderMarkdown('Clone an `Arc`\nto share it.'),
+    '<p>Clone an <code>Arc</code> to share it.</p>',
+  );
+});
+
+test('renderMarkdown: fenced code is literal, escaped, not inline-rendered', () => {
+  const md = '```rust\nlet x: Vec<u8> = *ptr; // **not bold**\n```';
+  assert.equal(
+    renderMarkdown(md),
+    '<pre><code class="language-rust">let x: Vec&lt;u8&gt; = *ptr; // **not bold**\n</code></pre>',
+  );
+});
+
+test('renderMarkdown: unordered list with one nested level', () => {
+  const md = '- top one\n- top two\n  - nested a';
+  assert.equal(
+    renderMarkdown(md),
+    '<ul><li>top one</li><li>top two<ul><li>nested a</li></ul></li></ul>',
+  );
+});
+
+test('renderMarkdown: ordered list', () => {
+  assert.equal(renderMarkdown('1. first\n2. second'), '<ol><li>first</li><li>second</li></ol>');
+});
+
+test('renderMarkdown: a bullet wrapping across lines stays one <li>', () => {
+  assert.equal(
+    renderMarkdown('- first line\n  wrapped second'),
+    '<ul><li>first line wrapped second</li></ul>',
+  );
+});
+
+test('renderMarkdown: an ordered item wrapping across lines stays one <li>', () => {
+  assert.equal(
+    renderMarkdown('1. first line\n   wraps here\n2. second'),
+    '<ol><li>first line wraps here</li><li>second</li></ol>',
+  );
+});
+
+test('renderMarkdown: two nested siblings share one nested list', () => {
+  assert.equal(
+    renderMarkdown('- top\n  - n1\n  - n2'),
+    '<ul><li>top<ul><li>n1</li><li>n2</li></ul></li></ul>',
+  );
+});
+
+test('renderMarkdown: a marker-type change splits into two lists', () => {
+  assert.equal(
+    renderMarkdown('- a\n1. b'),
+    '<ul><li>a</li></ul><ol><li>b</li></ol>',
+  );
+});
+
+test('renderMarkdown: real wrapped bullets stay one list with no stray paragraphs', () => {
+  const md = [
+    '- **Root-relative, trailing slash.** The leading `/` resolves from the domain',
+    '  root regardless of where the visitor entered. The trailing slash points at the',
+    '  *directory* `/ent/`, whose index (`ent/index.html`) the host serves.',
+    '- **`rel="canonical"`.** Meta-refresh shells look like duplicate content or a',
+    '  sneaky redirect to a crawler.',
+  ].join('\n');
+  const html = renderMarkdown(md);
+  assert.equal((html.match(/<ul>/g) || []).length, 1);
+  assert.equal((html.match(/<li>/g) || []).length, 2);
+  assert.equal((html.match(/<p>/g) || []).length, 0);
+});
+
+const SAMPLE = `<!-- Lesson for PR #16. Teaches one concept. -->
+
+# PR #16 — Tracer: supervised app with logs
+
+> **Rust lesson:** Hand the task an \`Arc<Mutex<T>>\` clone.
+> **Tags:** \`Arc<Mutex<T>>\` · \`tokio::spawn\`
+> **Merged:** 2026-06-08 · +2369/−0 · [View PR](https://github.com/nonrational/adjacent/pull/16)
+
+## The situation
+
+First paragraph.
+`;
+
+test('parseLesson extracts pr, slug, and title', () => {
+  const p = parseLesson('16-supervised-app-with-logs.md', SAMPLE);
+  assert.equal(p.pr, 16);
+  assert.equal(p.slug, 'supervised-app-with-logs');
+  assert.equal(p.title, 'PR #16 — Tracer: supervised app with logs');
+});
+
+test('parseLesson extracts the lesson sentence and tags', () => {
+  const p = parseLesson('16-supervised-app-with-logs.md', SAMPLE);
+  assert.equal(p.lesson, 'Hand the task an `Arc<Mutex<T>>` clone.');
+  assert.deepEqual(p.tags, ['Arc<Mutex<T>>', 'tokio::spawn']);
+});
+
+test('parseLesson extracts merged date, delta, and url', () => {
+  const p = parseLesson('16-supervised-app-with-logs.md', SAMPLE);
+  assert.equal(p.merged.date, '2026-06-08');
+  assert.equal(p.merged.delta, '+2369/−0');
+  assert.equal(p.merged.url, 'https://github.com/nonrational/adjacent/pull/16');
+});
+
+test('parseLesson body starts after the blockquote header', () => {
+  const p = parseLesson('16-supervised-app-with-logs.md', SAMPLE);
+  assert.ok(p.bodyMarkdown.startsWith('## The situation'));
+  assert.ok(!p.bodyMarkdown.includes('Rust lesson:'));
+});
+
+const GLOSSARY = {
+  arc: { term: 'Arc<T>', aliases: ['Arc', 'Arc<Mutex<T>>'], short: 's', why: 'w', prereqs: ['ownership'], link: { label: 'x', url: 'y' } },
+  ownership: { term: 'ownership', aliases: [], short: 's', why: 'w', prereqs: [], link: { label: 'x', url: 'y' } },
+};
+
+test('validateGlossary: clean glossary has no errors', () => {
+  assert.deepEqual(validateGlossary(GLOSSARY).errors, []);
+});
+
+test('validateGlossary: dangling prereq is an error', () => {
+  const bad = { arc: { term: 'Arc<T>', aliases: [], prereqs: ['nope'] } };
+  assert.equal(validateGlossary(bad).errors.length, 1);
+  assert.match(validateGlossary(bad).errors[0], /nope/);
+});
+
+test('validateGlossary: duplicate alias across entries is an error', () => {
+  const bad = {
+    a: { term: 'A', aliases: ['shared'], prereqs: [] },
+    b: { term: 'B', aliases: ['shared'], prereqs: [] },
+  };
+  assert.match(validateGlossary(bad).errors[0], /shared/);
+});
+
+test('buildGlossaryIndex maps every term and alias to its key', () => {
+  const idx = buildGlossaryIndex(GLOSSARY);
+  assert.equal(idx.get('Arc'), 'arc');
+  assert.equal(idx.get('Arc<Mutex<T>>'), 'arc');
+  assert.equal(idx.get('Arc<T>'), 'arc');
+  assert.equal(idx.get('ownership'), 'ownership');
+});
+
+test('renderInline wraps a glossary-matched code span as a term button', () => {
+  const idx = buildGlossaryIndex(GLOSSARY);
+  assert.equal(
+    renderInline('use `Arc` now', { glossaryIndex: idx }),
+    'use <button type="button" class="term" data-term="arc"><code>Arc</code></button> now',
+  );
+});
+
+test('coverageReport lists backticked terms missing from the glossary, not those present', () => {
+  const idx = buildGlossaryIndex(GLOSSARY);
+  const lessons = [{ bodyMarkdown: 'see `Arc` and `Weak`\n```rust\n`Mutex` in code\n```' }];
+  const rep = coverageReport(lessons, idx);
+  assert.deepEqual(rep, [{ term: 'Weak', count: 1 }]);
+});
+
+import {
+  THEME, renderTagChips, renderLessonPage, renderStylesheet, renderGlossaryScript,
+} from './build.mjs';
+
+const PARSED = {
+  pr: 16, slug: 'supervised-app-with-logs',
+  title: 'PR #16 — Tracer: supervised app with logs',
+  lesson: 'Hand the task an `Arc<Mutex<T>>` clone.',
+  tags: ['Arc<Mutex<T>>', 'tokio::spawn'],
+  merged: { date: '2026-06-08', delta: '+2369/−0', url: 'https://github.com/nonrational/adjacent/pull/16' },
+  bodyMarkdown: '## The situation\n\nBoot it with an `Arc`.',
+};
+const IDX = buildGlossaryIndex({
+  arc: { term: 'Arc<T>', aliases: ['Arc', 'Arc<Mutex<T>>'], prereqs: [] },
+});
+
+test('renderTagChips: a glossary tag becomes a term button, others plain', () => {
+  const html = renderTagChips(['Arc<Mutex<T>>', 'tokio::spawn'], IDX);
+  assert.match(html, /data-term="arc"[^>]*>[^<]*<code>Arc&lt;Mutex&lt;T&gt;&gt;<\/code>/);
+  assert.match(html, /tokio::spawn/);
+});
+
+test('renderLessonPage: full document with provenance header and asset links', () => {
+  const html = renderLessonPage(PARSED, { glossaryIndex: IDX });
+  assert.ok(html.startsWith('<!-- generated by build.mjs'));
+  assert.match(html, /<!DOCTYPE html>/);
+  assert.match(html, /<link rel="stylesheet" href="lessons\.css">/);
+  assert.match(html, /<script src="glossary\.js"><\/script>/);
+  assert.match(html, /<script src="drawer\.js" defer><\/script>/);
+  assert.match(html, /PR #16 — Tracer: supervised app with logs/);
+  // A body code span that matches the glossary is annotated.
+  assert.match(html, /data-term="arc"><code>Arc<\/code>/);
+});
+
+test('renderStylesheet: emits the theme accent as a CSS custom property', () => {
+  assert.match(renderStylesheet(), /--accent:\s*#d4a574/);
+});
+
+test('renderGlossaryScript: assigns the glossary to a global', () => {
+  const js = renderGlossaryScript({ arc: { term: 'Arc<T>' } });
+  assert.match(js, /window\.__GLOSSARY__ = /);
+  assert.match(js, /"Arc<T>"/);
+});
+
+import { renderDrawerScript } from './build.mjs';
+
+test('renderDrawerScript emits provenance header and wires term clicks', () => {
+  const js = renderDrawerScript();
+  assert.ok(js.startsWith('/* generated by build.mjs'));
+  assert.match(js, /addEventListener\('click'/);
+  assert.match(js, /__GLOSSARY__/);
+  assert.match(js, /Escape/);
+});
+
+import { parseReadmeIndex, renderIndexPage } from './build.mjs';
+
+const README = `# Rust, one PR at a time
+
+Intro prose.
+
+## The lessons
+
+| PR | Lesson | The one-line takeaway |
+|----|--------|-----------------------|
+| [#16](16-supervised-app-with-logs.md) | \`Arc<Mutex<T>>\` + \`tokio::spawn\` | Clone an \`Arc\` to share. |
+| [#34](34-fix-landing-page-redirect.md) ◦ | Client-side redirects | How a meta refresh works. |
+
+◦ = little or no Rust.
+
+## Reading paths by theme
+
+- **Error handling** — [#29](29-deadlines-and-failure-enums.md) → [#48](48-warn-dont-swallow-errors.md)
+`;
+
+test('parseReadmeIndex extracts rows including the sparse marker', () => {
+  const { rows } = parseReadmeIndex(README);
+  assert.equal(rows.length, 2);
+  assert.equal(rows[0].pr, 16);
+  assert.equal(rows[0].href, '16-supervised-app-with-logs.html');
+  assert.equal(rows[0].sparse, false);
+  assert.equal(rows[1].sparse, true);
+});
+
+test('parseReadmeIndex extracts reading paths', () => {
+  const { paths } = parseReadmeIndex(README);
+  assert.equal(paths.length, 1);
+  assert.match(paths[0].theme, /Error handling/);
+  assert.match(paths[0].html, /29-deadlines-and-failure-enums\.html/);
+});
+
+test('renderIndexPage produces a document linking to lesson pages', () => {
+  const html = renderIndexPage(README);
+  assert.ok(html.startsWith('<!-- generated by build.mjs'));
+  assert.match(html, /href="16-supervised-app-with-logs\.html"/);
+  assert.match(html, /<link rel="stylesheet" href="lessons\.css">/);
+});
+
+test('parseReadmeIndex unescapes table-cell pipe escapes in takeaways', () => {
+  const md = [
+    '## The lessons',
+    '',
+    '| PR | Lesson | Takeaway |',
+    '|--|--|--|',
+    '| [#48](48-warn-dont-swallow-errors.md) | Errors | use `.unwrap_or_else(\|err\|)` first |',
+  ].join('\n');
+  const { rows } = parseReadmeIndex(md);
+  assert.equal(rows[0].takeaway, 'use `.unwrap_or_else(|err|)` first');
+});
+
+import { buildSite, checkCrossLinks } from './build.mjs';
+
+const GL = {
+  arc: { term: 'Arc<T>', aliases: ['Arc'], short: 's', why: 'w', prereqs: [], link: { label: 'x', url: 'y' } },
+};
+const LESSONS = [{
+  pr: 16, slug: 'supervised-app-with-logs', title: 'PR #16 — X',
+  lesson: 'Clone an `Arc`.', tags: ['Arc'],
+  merged: { date: '2026-06-08', delta: '+1/−0', url: 'https://example.com/16' },
+  bodyMarkdown: 'Boot with an `Arc`. See [PR #17](17-inject-port-into-child-env.md).',
+}];
+
+test('buildSite returns pages plus the four shared assets', () => {
+  const files = buildSite({ lessons: LESSONS, glossary: GL, readmeMd: '## The lessons\n' });
+  assert.ok(files.has('16-supervised-app-with-logs.html'));
+  assert.ok(files.has('index.html'));
+  assert.ok(files.has('lessons.css'));
+  assert.ok(files.has('drawer.js'));
+  assert.ok(files.has('glossary.js'));
+  assert.match(files.get('16-supervised-app-with-logs.html'), /data-term="arc"/);
+});
+
+test('checkCrossLinks flags a link with no target lesson', () => {
+  const errs = checkCrossLinks(LESSONS); // #17 not in the list
+  assert.equal(errs.length, 1);
+  assert.match(errs[0], /17-inject-port-into-child-env/);
+});
diff --git a/ent/lessons/drawer.js b/ent/lessons/drawer.js
new file mode 100644
index 0000000..c285bf5
--- /dev/null
+++ b/ent/lessons/drawer.js
@@ -0,0 +1,72 @@
+/* generated by build.mjs; edit docs/lessons/*.md */
+(() => {
+  const G = window.__GLOSSARY__ || {};
+  const scrim = document.createElement('div');
+  scrim.className = 'drawer-scrim';
+  const drawer = document.createElement('aside');
+  drawer.className = 'drawer';
+  drawer.setAttribute('role', 'dialog');
+  drawer.setAttribute('aria-label', 'Term explanation');
+  drawer.innerHTML =
+    '<button class="close" aria-label="Close">×</button>' +
+    '<button class="back-link">← back</button>' +
+    '<div class="d-body"></div>';
+  document.body.append(scrim, drawer);
+  const body = drawer.querySelector('.d-body');
+  // Escapes text and attribute values alike (includes ") so a quote in a glossary key or URL can't break out of an attribute.
+  const esc = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+  let history = [];
+
+  function render(key) {
+    const e = G[key];
+    if (!e) return;
+    const prereqs = (e.prereqs || [])
+      .filter((k) => G[k])
+      .map((k) => '<button type="button" class="term" data-term="' + esc(k) + '"><code>' + esc(G[k].term) + '</code></button>')
+      .join('');
+    const link = e.link ? '<p class="d-label">Dig deeper</p><p class="d-link"><a href="' + esc(e.link.url) + '" target="_blank" rel="noopener">' + esc(e.link.label) + '</a></p>' : '';
+    body.innerHTML =
+      '<p class="d-term">' + esc(e.term) + '</p>' +
+      '<p class="d-short">' + esc(e.short || '') + '</p>' +
+      (e.why ? '<p class="d-label">Why it matters</p><p class="d-why">' + esc(e.why) + '</p>' : '') +
+      (prereqs ? '<p class="d-label">Learn first</p><div class="d-prereqs">' + prereqs + '</div>' : '') +
+      link;
+    // Back is shown only once we've descended past the root term.
+    drawer.classList.toggle('has-history', history.length > 1);
+  }
+
+  function open(key) {
+    history = [key];
+    render(key);
+    scrim.classList.add('open');
+    drawer.classList.add('open');
+  }
+  function close() {
+    scrim.classList.remove('open');
+    drawer.classList.remove('open');
+    history = [];
+    drawer.classList.remove('has-history');
+  }
+
+  document.addEventListener('click', (ev) => {
+    const term = ev.target.closest('.term');
+    if (term && term.dataset.term) {
+      ev.preventDefault();
+      if (ev.target.closest('.drawer')) {
+        history.push(term.dataset.term); // descend into a prereq
+        render(term.dataset.term);
+      } else {
+        open(term.dataset.term);         // open from the lesson prose
+      }
+      return;
+    }
+    if (ev.target.closest('.drawer .close')) { close(); }
+  });
+  drawer.querySelector('.back-link').addEventListener('click', () => {
+    history.pop();
+    const prev = history[history.length - 1];
+    if (prev) { render(prev); } else { close(); }
+  });
+  scrim.addEventListener('click', close);
+  document.addEventListener('keydown', (ev) => { if (ev.key === 'Escape') close(); });
+})();
diff --git a/ent/lessons/glossary.js b/ent/lessons/glossary.js
new file mode 100644
index 0000000..399dfa1
--- /dev/null
+++ b/ent/lessons/glossary.js
@@ -0,0 +1,2 @@
+/* generated by build.mjs; edit docs/lessons/*.md */
+window.__GLOSSARY__ = {"ownership":{"term":"ownership","aliases":[],"short":"Every value has exactly one owner. When the owner goes out of scope the value is dropped and its memory freed. No garbage collector, no manual free().","why":"The single-owner rule is the root of Rust's memory safety, and the reason sharing, borrowing, and moving all have to be made explicit rather than assumed.","prereqs":[],"link":{"label":"Rust Book 4.1","url":"https://doc.rust-lang.org/book/ch04-01-what-is-ownership.html"}},"borrowing":{"term":"borrowing","aliases":["reference"],"short":"Accessing a value through a reference (&T) without taking ownership. You can have many shared &T reads, or exactly one exclusive &mut T, but never both at once.","why":"Borrowing lets code use a value without moving it, and the one-writer-or-many-readers rule is what stops data races at compile time instead of in production.","prereqs":["ownership"],"link":{"label":"Rust Book 4.2","url":"https://doc.rust-lang.org/book/ch04-02-references-and-borrowing.html"}},"move":{"term":"move","aliases":["move semantics"],"short":"Assigning or passing a non-Copy value transfers ownership; the source can no longer be used. `move` on a closure forces it to take ownership of what it captures.","why":"A spawned task must own what it touches. `move` is how you hand ownership into a closure so it can outlive the function that created it.","prereqs":["ownership"],"link":{"label":"Rust Book 4.1","url":"https://doc.rust-lang.org/book/ch04-01-what-is-ownership.html#variables-and-data-interacting-with-move"}},"lifetime":{"term":"lifetime","aliases":[],"short":"The span of code for which a reference stays valid. The compiler checks that no reference outlives the value it points at, sometimes with named annotations like 'a.","why":"Lifetimes are how Rust guarantees a reference can never dangle. Most are inferred; you only write them when the compiler can't tell which input a returned reference came from.","prereqs":["borrowing"],"link":{"label":"Rust Book 10.3","url":"https://doc.rust-lang.org/book/ch10-03-lifetime-syntax.html"}},"static-lifetime":{"term":"'static","aliases":["'static"],"short":"A lifetime meaning \"lives for the entire program.\" A value is 'static if it owns all its data (borrows nothing) or points at data baked into the binary.","why":"A task handed to a background executor must be 'static: it may outlive the function that spawned it, so it can't borrow anything on that function's stack.","prereqs":["lifetime"],"link":{"label":"Rust Book 10.3","url":"https://doc.rust-lang.org/book/ch10-03-lifetime-syntax.html#the-static-lifetime"}},"send-sync":{"term":"Send / Sync","aliases":["Send","Sync","Send + Sync"],"short":"Marker traits the compiler infers automatically: Send means a value can be moved to another thread; Sync means it can be shared by reference across threads.","why":"They are what let the compiler reject cross-thread data races before the program runs. Arc is Send + Sync; Rc is neither, which is why spawn rejects it.","prereqs":["ownership"],"link":{"label":"Rust Book 16.4","url":"https://doc.rust-lang.org/book/ch16-04-extensible-concurrency-sync-and-send.html"}},"interior-mutability":{"term":"interior mutability","aliases":["interior mutability","RefCell"],"short":"A pattern where you mutate data through a shared (&T) reference, with a wrapper type (Cell, RefCell, Mutex) enforcing the borrow rules at runtime instead of compile time.","why":"Sometimes you genuinely need to mutate shared state; interior mutability moves the one-writer check to runtime so the compiler will allow it, and a Mutex is its thread-safe form.","prereqs":["ownership","borrowing"],"link":{"label":"Rust Book 15.5","url":"https://doc.rust-lang.org/book/ch15-05-interior-mutability.html"}},"reference-counting":{"term":"reference counting","aliases":[],"short":"Sharing ownership of one value among several owners by keeping a count of how many exist; the value is dropped when the last owner goes away. Rc for one thread, Arc across threads.","why":"It's the escape hatch for when a single owner isn't enough. The count is the trade you make: cheap clones that share, at the cost of a runtime counter and no compile-time single-owner guarantee.","prereqs":["ownership"],"link":{"label":"Rust Book 15.4","url":"https://doc.rust-lang.org/book/ch15-04-rc.html"}},"rc":{"term":"Rc<T>","aliases":["Rc"],"short":"A single-threaded reference-counted pointer. Cloning it bumps a non-atomic count and hands back another owner of the same value.","why":"Cheaper than Arc because the count isn't atomic, but that's exactly why it isn't Send: hand it to another thread and the compiler stops you. Reach for Arc when threads are involved.","prereqs":["reference-counting","send-sync"],"link":{"label":"Rust Book 15.4","url":"https://doc.rust-lang.org/book/ch15-04-rc.html"}},"arc":{"term":"Arc<T>","aliases":["Arc","Arc<Mutex<T>>","Arc<Mutex<Inner>>","Arc<T>"],"short":"Atomically reference-counted shared pointer. Cloning it bumps a thread-safe refcount and hands back a second owner of the same value, not a copy.","why":"Lets two threads or tasks own one value at once. It is how a detached task can touch state the spawner still holds. Wrap it around a Mutex when the shared value also needs mutation.","prereqs":["reference-counting","move","send-sync"],"link":{"label":"Rust Book 16.3","url":"https://doc.rust-lang.org/book/ch16-03-shared-state.html"}},"weak":{"term":"Weak<T>","aliases":["Weak"],"short":"A non-owning reference to an Arc/Rc value. It doesn't keep the value alive; upgrade() returns None once the last strong owner is gone.","why":"Breaks reference cycles that would otherwise leak, and lets a map hold entries that clean themselves up: store Weak values and the map can drop the dead ones.","prereqs":["arc"],"link":{"label":"Rust Book 15.6","url":"https://doc.rust-lang.org/book/ch15-06-reference-cycles.html"}},"mutex":{"term":"Mutex<T>","aliases":["Mutex","Mutex<T>"],"short":"A lock guarding interior data so only one holder mutates at a time. tokio's async Mutex yields the task while waiting instead of blocking the whole thread.","why":"Shared ownership alone still races on writes. The Mutex is what makes the shared mutation safe, and the compiler won't let you reach the data without taking the lock first.","prereqs":["interior-mutability","send-sync"],"link":{"label":"Rust Book 16.3","url":"https://doc.rust-lang.org/book/ch16-03-shared-state.html"}},"async-await":{"term":"async / .await","aliases":[".await","async"],"short":"async fn returns a future that does nothing until awaited; .await drives it and yields control back to the runtime while waiting, so one thread can juggle many tasks.","why":"It's cooperative concurrency: awaiting a slow I/O call frees the thread to run other tasks instead of blocking, which is how a single process can supervise many servers at once.","prereqs":[],"link":{"label":"Rust Book 17.1","url":"https://doc.rust-lang.org/book/ch17-01-futures-and-syntax.html"}},"tokio-spawn":{"term":"tokio::spawn","aliases":["tokio::spawn"],"short":"Hands a future to the tokio runtime to run concurrently, returning a JoinHandle. The task may run on any worker thread and may outlive the caller, so it must be 'static and Send.","why":"The go-to way to run work in the background. Its 'static + Send bounds are exactly why detached tasks reach for Arc<Mutex<T>> instead of borrowing the caller's state.","prereqs":["async-await","send-sync","static-lifetime","arc"],"link":{"label":"tokio docs","url":"https://docs.rs/tokio/latest/tokio/task/fn.spawn.html"}},"timeout":{"term":"tokio::time::timeout","aliases":["tokio::time::timeout"],"short":"Wraps a future with a deadline; it resolves to Err once the duration elapses, cancelling the inner future.","why":"Bounds how long async work may take so a hung boot or a wedged health check turns into a clean, reportable failure instead of a task that waits forever.","prereqs":["async-await","result"],"link":{"label":"tokio docs","url":"https://docs.rs/tokio/latest/tokio/time/fn.timeout.html"}},"option":{"term":"Option<T>","aliases":["Option","Option<T>","Some","None"],"short":"An enum that is either Some(value) or None. Rust has no null; absence is a value you must handle, checked by the compiler.","why":"\"Might be missing\" becomes a case the type forces you to consider, so you can't accidentally use a value that isn't there. Serde fills a missing field with None for you.","prereqs":[],"link":{"label":"Rust Book 6.1","url":"https://doc.rust-lang.org/book/ch06-01-defining-an-enum.html#the-option-enum-and-its-advantages-over-null-values"}},"result":{"term":"Result<T, E>","aliases":["Result","Result<T, E>","Ok","Err"],"short":"An enum that is either Ok(value) or Err(error). Rust has no exceptions; a fallible operation returns its error as a value you must handle.","why":"Failure is in the type signature, so you can't ignore it by accident. How you handle the Err (surface it, default it, propagate it) becomes a deliberate choice at each call site.","prereqs":[],"link":{"label":"Rust Book 9.2","url":"https://doc.rust-lang.org/book/ch09-02-recoverable-errors-with-result.html"}},"question-mark":{"term":"the ? operator","aliases":["?"],"short":"On a Result or Option, ? unwraps the Ok/Some value or early-returns the Err/None from the enclosing function. It replaces a match that would just propagate the error.","why":"Turns manual error-forwarding into one character, keeping the happy path readable while still handling every failure explicitly.","prereqs":["result","option"],"link":{"label":"Rust Book 9.2","url":"https://doc.rust-lang.org/book/ch09-02-recoverable-errors-with-result.html#a-shortcut-for-propagating-errors-the--operator"}},"combinators":{"term":"combinators","aliases":[".ok()","unwrap_or","unwrap_or_else","and_then","as_deref"],"short":"Methods on Option/Result that transform them without a match: map, and_then, ok, unwrap_or, unwrap_or_else, and friends. Each takes a closure or a default.","why":"They express \"do this if present, else that\" as a chain instead of a branch. The distinction matters: unwrap_or throws the error away, unwrap_or_else hands it to you first.","prereqs":["option","result","closure"],"link":{"label":"Option docs","url":"https://doc.rust-lang.org/std/option/enum.Option.html"}},"match":{"term":"match / if let","aliases":["match","if let"],"short":"match compares a value against patterns and must cover every case; if let is the shorthand for when you only care about one pattern and ignore the rest.","why":"Exhaustive matching means adding a new enum variant makes the compiler point you at every place that must handle it, so \"forgot a case\" becomes a build error.","prereqs":["option"],"link":{"label":"Rust Book 6.2","url":"https://doc.rust-lang.org/book/ch06-02-match.html"}},"closure":{"term":"closure","aliases":["closure"],"short":"An anonymous function written with |args| body that can capture variables from its surrounding scope, by reference or (with move) by value.","why":"Closures are how you pass behavior around: a combinator's transform, a task's body, a Drop guard's cleanup. What they capture, and whether they move it, decides their lifetime.","prereqs":["ownership"],"link":{"label":"Rust Book 13.1","url":"https://doc.rust-lang.org/book/ch13-01-closures.html"}},"iterator":{"term":"iterator","aliases":["Iterator",".iter()",".map()"],"short":"A lazy sequence: .iter() and adapters like .map() build a pipeline that does no work until something drives it. Nothing is computed until you consume it.","why":"Laziness means you can chain transforms cheaply and only pay for what you actually take. The pipeline stays declarative; collect (or a for loop) is what makes it run.","prereqs":["closure"],"link":{"label":"Rust Book 13.2","url":"https://doc.rust-lang.org/book/ch13-02-iterators.html"}},"collect":{"term":"collect","aliases":[".collect()","collect"],"short":"Consumes an iterator and gathers its items into a collection (Vec, HashMap, String, ...). It's the driver that finally runs a lazy iterator pipeline.","why":"Turns one collection into another in a single expression, with the target type telling collect what to build. It's where a map/filter chain stops being lazy and produces a value.","prereqs":["iterator"],"link":{"label":"Iterator::collect","url":"https://doc.rust-lang.org/std/iter/trait.Iterator.html#method.collect"}},"trait":{"term":"trait","aliases":["trait"],"short":"A named set of methods a type can implement, like an interface. Code can then require \"any type that implements this trait\" rather than one concrete type.","why":"Traits are Rust's main tool for shared behavior and abstraction, and implementing a library's trait is how you plug your own type into that library's machinery.","prereqs":[],"link":{"label":"Rust Book 10.2","url":"https://doc.rust-lang.org/book/ch10-02-traits.html"}},"generics":{"term":"generics","aliases":["generic","generics"],"short":"Writing code over a type parameter (like T or S) instead of a concrete type, so one function or struct works for many types.","why":"Write the logic once and let the compiler specialize it per type. Combined with trait bounds, generics give you abstraction with no runtime cost.","prereqs":["trait"],"link":{"label":"Rust Book 10.1","url":"https://doc.rust-lang.org/book/ch10-01-syntax.html"}},"trait-bound":{"term":"trait bound","aliases":["trait bound","trait bounds"],"short":"A constraint on a generic type, written like T: Display, saying \"T must implement this trait.\" It's what lets generic code actually call methods on T.","why":"The bound is the contract: it tells the compiler which methods are available on the type parameter, and tells callers which types they're allowed to pass.","prereqs":["generics"],"link":{"label":"Rust Book 10.2","url":"https://doc.rust-lang.org/book/ch10-02-traits.html#traits-as-parameters"}},"static-dispatch":{"term":"static dispatch","aliases":["static dispatch"],"short":"Resolving which concrete method to call at compile time. Generic code is monomorphized into a specialized copy per type, so calls are direct with no runtime lookup.","why":"It's abstraction for free: the generic loop over a stream type compiles down to the same machine code you'd have written by hand for each concrete type.","prereqs":["generics","monomorphization"],"link":{"label":"Rust Book 17.2","url":"https://doc.rust-lang.org/book/ch17-02-trait-objects.html#trait-objects-perform-dynamic-dispatch"}},"dynamic-dispatch":{"term":"dynamic dispatch","aliases":["dyn","dynamic dispatch","trait object"],"short":"Resolving the method at runtime through a trait object (dyn Trait), which carries a pointer to the right implementation. One code path handles many types.","why":"Trades a tiny runtime indirection for flexibility: you can store different implementing types together or choose one at runtime, which generics can't do.","prereqs":["trait"],"link":{"label":"Rust Book 17.2","url":"https://doc.rust-lang.org/book/ch17-02-trait-objects.html"}},"monomorphization":{"term":"monomorphization","aliases":["monomorphization","monomorphized"],"short":"The compiler's process of turning generic code into concrete code by stamping out a specialized copy for each type it's used with.","why":"It's why generics have zero runtime overhead: by the time the program runs, each generic use is just ordinary type-specific code. The cost is paid in compile time and binary size.","prereqs":["generics"],"link":{"label":"Rust Book 10.1","url":"https://doc.rust-lang.org/book/ch10-01-syntax.html#performance-of-code-using-generics"}},"drop":{"term":"Drop / RAII","aliases":["Drop","RAII"],"short":"The Drop trait runs cleanup code automatically when a value goes out of scope. Tie a resource's release to a value's lifetime and you can't forget to free it.","why":"Files close, locks release, and guards fire without a manual step. The catch: a signal-killed process skips destructors, so external cleanup can't rely on Drop alone.","prereqs":["ownership"],"link":{"label":"Rust Book 15.3","url":"https://doc.rust-lang.org/book/ch15-03-drop.html"}},"newtype":{"term":"newtype pattern","aliases":["newtype","HeaderValue"],"short":"Wrapping a value in a single-field struct to give it a distinct type, so a validated or domain-specific value can't be confused with a plain one.","why":"The wrapper is where you enforce an invariant once (a HeaderValue is a validated byte-string, not any String), and the type system carries that guarantee everywhere after.","prereqs":["trait"],"link":{"label":"Rust Book 19.3","url":"https://doc.rust-lang.org/book/ch19-03-advanced-traits.html#using-the-newtype-pattern-to-implement-external-traits"}},"derive-macro":{"term":"derive macro","aliases":["derive","#[derive(Deserialize)]","#[derive(Serialize, Deserialize)]"],"short":"A #[derive(...)] attribute that generates a trait implementation for your type at compile time, so you don't hand-write boilerplate impls.","why":"One line gives you the code for common traits (Debug, Clone, and serde's Serialize/Deserialize). You only hand-write the impl when the derived shape isn't exactly what you need.","prereqs":["trait"],"link":{"label":"Rust Book 19.5","url":"https://doc.rust-lang.org/book/ch19-05-macros.html#how-to-write-a-custom-derive-macro"}},"serde":{"term":"Serialize / Deserialize","aliases":["Serialize","Deserialize","serde"],"short":"serde's two traits for converting Rust values to and from formats like JSON or TOML. Usually derived; #[serde(...)] attributes tune field names, defaults, and shape.","why":"Deriving them on a dedicated DTO type pins your public wire format to a Rust type, so the contract lives in code and the compiler keeps the two in sync.","prereqs":["derive-macro"],"link":{"label":"serde.rs","url":"https://serde.rs/derive.html"}},"unsafe-ffi":{"term":"unsafe / FFI","aliases":["unsafe","FFI"],"short":"unsafe marks code where you, not the compiler, uphold the safety rules, typically to call across a foreign function interface (FFI) into C or a system library.","why":"It's the escape hatch for things the borrow checker can't verify, like calling into the OS keychain. The unsafe block is a deliberate, auditable boundary, not a free-for-all.","prereqs":["ownership"],"link":{"label":"Rust Book 19.1","url":"https://doc.rust-lang.org/book/ch19-01-unsafe-rust.html"}},"instant":{"term":"Instant vs SystemTime","aliases":["Instant","SystemTime"],"short":"Instant is a monotonic clock for measuring elapsed time; SystemTime is the wall clock that can jump backward when the OS adjusts it.","why":"For deadlines and timeouts you want Instant, because it never goes backward. Reach for SystemTime only when you need an actual calendar time.","prereqs":[],"link":{"label":"std::time::Instant","url":"https://doc.rust-lang.org/std/time/struct.Instant.html"}},"vec":{"term":"Vec<T>","aliases":["Vec","Vec<T>"],"short":"A growable, heap-allocated array of T. It owns its elements and frees them when it's dropped.","why":"The default owned collection. Building one with the vec![] macro or by collecting an iterator is the everyday way to hold a variable number of values.","prereqs":["ownership"],"link":{"label":"std::vec::Vec","url":"https://doc.rust-lang.org/std/vec/struct.Vec.html"}},"hashmap":{"term":"HashMap<K, V>","aliases":["HashMap"],"short":"A hash-table mapping owned keys to owned values, with average O(1) insert and lookup.","why":"The standard key-value store. It owns what you put in it, and methods like retain let you edit it in place without rebuilding it.","prereqs":["ownership"],"link":{"label":"std::collections::HashMap","url":"https://doc.rust-lang.org/std/collections/struct.HashMap.html"}},"hashmap-retain":{"term":"HashMap::retain","aliases":["HashMap::retain","retain"],"short":"Keeps only the entries for which a closure returns true, removing the rest in one in-place pass over the map.","why":"The idiomatic way to garbage-collect a map (for example, dropping entries whose Weak value has expired) without allocating a new one or iterating twice.","prereqs":["closure","hashmap"],"link":{"label":"HashMap::retain","url":"https://doc.rust-lang.org/std/collections/struct.HashMap.html#method.retain"}},"str-vs-string":{"term":"&str vs String","aliases":["String","&str"],"short":"String is an owned, growable UTF-8 buffer; &str is a borrowed view into one (or into a string literal). String owns, &str borrows.","why":"The distinction is ownership again: take &str in function arguments to borrow without allocating, and return String when the caller needs to own the result.","prereqs":["ownership","borrowing"],"link":{"label":"Rust Book 8.2","url":"https://doc.rust-lang.org/book/ch08-02-strings.html"}},"split-once":{"term":"str::split_once","aliases":["split_once","str::split_once"],"short":"Cuts a string at the first occurrence of a delimiter into two borrowed &str slices, returning Option so \"delimiter not found\" is a None case, not a panic.","why":"Exactly right for parsing key=value or label.name: you get both halves as borrows of the original, and the Option makes the missing-delimiter case something you handle, not a bug.","prereqs":["option","str-vs-string"],"link":{"label":"str::split_once","url":"https://doc.rust-lang.org/std/primitive.str.html#method.split_once"}},"format-macro":{"term":"format!","aliases":["format!"],"short":"Builds a new String from a template, filling {} placeholders with values. {name} captures a variable of that name directly from scope.","why":"The everyday way to assemble strings. Its inline-capture form keeps templated text readable, and it's how derived data like a URL or an env value gets composed.","prereqs":["str-vs-string"],"link":{"label":"std::format!","url":"https://doc.rust-lang.org/std/macro.format.html"}},"build-rs":{"term":"build.rs","aliases":["build.rs"],"short":"A build script: Rust code the compiler runs before compiling your crate. Printing cargo:rustc-env=KEY=VALUE injects a value the crate can read at compile time.","why":"It's how compile-time facts (a git SHA, a build timestamp) get baked into the binary, so the program can report exactly which build it is without any runtime lookup.","prereqs":[],"link":{"label":"Cargo Book","url":"https://doc.rust-lang.org/cargo/reference/build-scripts.html"}},"env-macro":{"term":"env! / option_env!","aliases":["env!","option_env!"],"short":"Compile-time macros that read an environment variable and bake it into the binary as a &'static str. env! fails the build if it's unset; option_env! yields an Option instead.","why":"Paired with build.rs, they turn build-time environment values into constants compiled into the program, so there's nothing to read or fail at runtime.","prereqs":["build-rs","static-lifetime"],"link":{"label":"std::env!","url":"https://doc.rust-lang.org/std/macro.env.html"}},"include-str":{"term":"include_str!","aliases":["include_str!"],"short":"A macro that reads a file at compile time and embeds its contents into the binary as a &'static str.","why":"Bakes a whole document (a template, a help text) into the executable, so it ships as one self-contained file with nothing to load from disk at runtime.","prereqs":["static-lifetime"],"link":{"label":"std::include_str!","url":"https://doc.rust-lang.org/std/macro.include_str.html"}},"command":{"term":"Command","aliases":["Command"],"short":"The builder for spawning a child process: chain .env(), .arg(), .stdout() to configure it, then .spawn(). It inherits the parent's environment by default.","why":"A textbook builder pattern, and the surface where a supervisor injects a child's port and environment before starting it, one .env() layer at a time.","prereqs":[],"link":{"label":"std::process::Command","url":"https://doc.rust-lang.org/std/process/struct.Command.html"}}};
diff --git a/ent/lessons/index.html b/ent/lessons/index.html
new file mode 100644
index 0000000..16bf2a7
--- /dev/null
+++ b/ent/lessons/index.html
@@ -0,0 +1,69 @@
+<!-- generated by build.mjs; edit docs/lessons/*.md -->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>adj.ac/ent — Rust, one PR at a time</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@300;400;500;700&display=swap" rel="stylesheet">
+  <link rel="stylesheet" href="lessons.css">
+</head>
+<body>
+  <div class="frame">
+    <header>
+      <a class="wordmark" href="https://github.com/nonrational/adjacent"><span class="a">adj.ac</span><span class="slash">/</span><span class="b">ent</span></a>
+      <span class="back">Rust, one PR at a time</span>
+    </header>
+    <article>
+      <h1>Rust, one PR at a time</h1>
+      <table class="index">
+      <tr><td class="pr"><a href="16-supervised-app-with-logs.html">#16</a></td><td><code>Arc&lt;Mutex&lt;T&gt;&gt;</code> + <code>tokio::spawn</code></td><td class="takeaway">A detached task must <em>own</em> what it touches (<code>'static</code>); clone an <code>Arc</code> to share state, a <code>Mutex</code> to mutate it safely.</td></tr>
+      <tr><td class="pr"><a href="17-inject-port-into-child-env.html">#17</a></td><td><code>Command</code> env injection</td><td class="takeaway"><code>Command</code> is a builder that inherits the parent env by default; <code>.env(k, v)</code> layers one variable on before <code>.spawn()</code>.</td></tr>
+      <tr><td class="pr"><a href="19-optional-fields-with-serde.html">#19</a></td><td><code>Option&lt;T&gt;</code> + serde <code>Deserialize</code></td><td class="takeaway"><code>Option&lt;T&gt;</code> is how a field says "may be absent"; serde fills a missing <code>Option</code> with <code>None</code> for you.</td></tr>
+      <tr><td class="pr"><a href="22-serialize-wire-dto-contract.html">#22</a></td><td>serde <code>Serialize</code> + wire DTOs</td><td class="takeaway">Emit public JSON through dedicated DTO types — derive when the shape matches, hand-write <code>impl Serialize</code> to pin an exact contract.</td></tr>
+      <tr><td class="pr"><a href="24-single-flight-boot-gate.html">#24</a></td><td>Single-flight with a per-key lock</td><td class="takeaway">Boot a resource once under concurrent demand: a short map lock hands out a per-name lock, held across the boot while the rest re-check.</td></tr>
+      <tr><td class="pr"><a href="29-deadlines-and-failure-enums.html">#29</a></td><td>Timeouts + custom error enums</td><td class="takeaway">Bound async work with <code>tokio::time::timeout</code> and a <code>deadline: Instant</code>; model <em>why</em> a wait ended as an enum.</td></tr>
+      <tr class="sparse"><td class="pr"><a href="34-fix-landing-page-redirect.html">#34</a> <span class="mark">◦</span></td><td>Client-side redirects</td><td class="takeaway">How a <code>&lt;meta http-equiv="refresh"&gt;</code> redirect works, and why the <code>/</code> in <code>adj.ac/ent</code> is a load-bearing path boundary.</td></tr>
+      <tr class="sparse"><td class="pr"><a href="36-docs-as-config-contract.html">#36</a> <span class="mark">◦</span></td><td>Docs as the config contract</td><td class="takeaway">No Rust — but the ecosystem's answer to doc rot is doctests: <code>cargo test</code> runs the <code>rust</code> examples in your doc comments.</td></tr>
+      <tr><td class="pr"><a href="37-signals-bypass-drop-cleanup.html">#37</a></td><td>Signals bypass <code>Drop</code></td><td class="takeaway">A signal-killed process skips destructors, so external cleanup (unlink a socket) must happen in a <code>tokio::signal</code> handler.</td></tr>
+      <tr><td class="pr"><a href="38-deterministic-async-tests.html">#38</a></td><td>Deterministic async tests</td><td class="takeaway">Assert on observable state you can count, never on timing — and a still-flaky test is a real race, not noise.</td></tr>
+      <tr><td class="pr"><a href="40-serve-https-local-ca.html">#40</a></td><td>Generics + trait bounds</td><td class="takeaway">One <code>serve_plain&lt;S&gt;</code> loop, monomorphized per stream type, drives both TCP and TLS at zero runtime cost.</td></tr>
+      <tr><td class="pr"><a href="41-raw-string-templated-doc.html">#41</a></td><td>Raw strings + <code>format!</code></td><td class="takeaway"><code>r#"…"#</code> bakes a whole doc into the binary verbatim; <code>format!</code>'s <code>{name}</code> capture splices in the dynamic bits.</td></tr>
+      <tr><td class="pr"><a href="43-trait-as-extension-point.html">#43</a></td><td>Implementing a library trait (+ FFI)</td><td class="takeaway">Impl rcgen's <code>RemoteKeyPair</code> so signing calls out to the Keychain — the CA key never enters process memory.</td></tr>
+      <tr><td class="pr"><a href="45-iterator-map-collect-rows.html">#45</a></td><td><code>iter().map().collect()</code></td><td class="takeaway">Turn one collection into another with a lazy pipeline that does nothing until <code>collect</code> drives it.</td></tr>
+      <tr class="sparse"><td class="pr"><a href="46-revamp-landing-positioning-page.html">#46</a> <span class="mark">◦</span></td><td>Repo layout + dual licensing</td><td class="takeaway">The web frontend lives <em>outside</em> the Cargo <code>members</code> list so <code>cargo build</code> never sees it; <code>MIT OR Apache-2.0</code> is the ecosystem default.</td></tr>
+      <tr><td class="pr"><a href="47-integration-tests-separate-crate.html">#47</a></td><td>Integration test layout</td><td class="takeaway">Each file in <code>tests/</code> is its own crate touching only the public API; a binary-only crate drives itself via <code>CARGO_BIN_EXE_adj</code>.</td></tr>
+      <tr><td class="pr"><a href="48-warn-dont-swallow-errors.html">#48</a></td><td>Don't swallow the <code>Err</code></td><td class="takeaway"><code>.unwrap_or(default)</code> throws the error away; <code>.unwrap_or_else(|err| …)</code> hands it to you to surface first.</td></tr>
+      <tr><td class="pr"><a href="49-parse-dont-validate-actionable-errors.html">#49</a></td><td>Parse, don't validate</td><td class="takeaway">Push the check into the parser so a bad value can't exist downstream — and spend a line making the <code>Err</code> tell the user what to do.</td></tr>
+      <tr><td class="pr"><a href="50-weak-refs-self-cleaning-map.html">#50</a></td><td><code>Weak</code> refs + <code>HashMap::retain</code></td><td class="takeaway">Store <code>Weak</code> values so a map garbage-collects itself; <code>retain</code> sweeps the dead entries in one in-place pass.</td></tr>
+      <tr><td class="pr"><a href="51-typed-http-header-values.html">#51</a></td><td>Typed headers as newtypes</td><td class="takeaway">A <code>HeaderValue</code> is a validated byte-string, not a <code>String</code>; fallible construction is how the type blocks header injection.</td></tr>
+      <tr><td class="pr"><a href="52-abort-detached-tokio-tasks.html">#52</a></td><td>Task cancellation</td><td class="takeaway">Dropping a <code>JoinHandle</code> <em>detaches</em> the task; hold it and <code>.abort()</code> — ideally from a <code>Drop</code> guard so it fires on every path.</td></tr>
+      <tr><td class="pr"><a href="53-http-upgrade-stream-splicing.html">#53</a></td><td>HTTP upgrades + <code>copy_bidirectional</code></td><td class="takeaway">An <code>Upgrade</code> trades HTTP framing for the raw stream; claim it with <code>hyper::upgrade::on</code>, then splice both halves.</td></tr>
+      <tr><td class="pr"><a href="55-races-beyond-the-borrow-checker.html">#55</a></td><td>Races the borrow checker can't catch</td><td class="takeaway"><code>Send</code>/<code>Sync</code> kill in-process <em>data</em> races; a TOCTOU race over a port or file is still entirely on you.</td></tr>
+      <tr><td class="pr"><a href="56-split-once-structured-keys.html">#56</a></td><td><code>str::split_once</code></td><td class="takeaway">Cut a string at the first delimiter into two borrowed <code>&amp;str</code> slices, returning <code>Option</code> so "no delimiter" is a case, not a bug.</td></tr>
+      <tr><td class="pr"><a href="60-compile-time-version-stamping.html">#60</a></td><td><code>build.rs</code> + <code>env!</code>/<code>option_env!</code></td><td class="takeaway">A build script emits <code>cargo:rustc-env=…</code> before compile; <code>env!</code>/<code>option_env!</code> bake those into the binary as <code>&amp;'static str</code>.</td></tr>
+      <tr><td class="pr"><a href="63-what-clippy-teaches.html">#63</a></td><td>What clippy teaches</td><td class="takeaway">Each lint names an idiom or a footgun; the honest reply is adopt it or <code>#[allow]</code> it <em>with a reason</em>.</td></tr>
+      <tr class="sparse"><td class="pr"><a href="65-health-files-and-metadata.html">#65</a> <span class="mark">◦</span></td><td>OSS hygiene + crates.io metadata</td><td class="takeaway">No Rust — the crates.io analog of <code>.github/</code> health files is <code>Cargo.toml</code> package metadata (<code>keywords</code>, <code>categories</code>, <code>rust-version</code>).</td></tr>
+      <tr class="sparse"><td class="pr"><a href="68-lean-agent-docs.html">#68</a> <span class="mark">◦</span></td><td>Sometimes there's no lesson</td><td class="takeaway">A ten-line docs deletion. The honest move is to say so — that's the series' principle in action.</td></tr>
+      <tr class="sparse"><td class="pr"><a href="69-distributing-a-rust-cli.html">#69</a> <span class="mark">◦</span></td><td>Distributing a Rust CLI</td><td class="takeaway">Homebrew tap (prebuilt, no toolchain) vs <code>cargo install</code> (compiles to <code>~/.cargo/bin</code>) vs a raw tarball — who eats the complexity.</td></tr>
+      <tr><td class="pr"><a href="75-hand-render-config-to-disk.html">#75</a></td><td>Generating a config file</td><td class="takeaway">Hand-render human-editable TOML so comments survive; write with <code>std::fs::write</code> behind a <code>!path.exists()</code> guard so you never clobber.</td></tr>
+      <tr><td class="pr"><a href="76-derived-env-precedence-order.html">#76</a></td><td>Derived data + precedence order</td><td class="takeaway">Compute a namespace with <code>format!</code> into a <code>Vec&lt;(k, v)&gt;</code>; inject it last so <code>Command::env</code>'s last-writer-wins makes it win.</td></tr>
+      </table>
+      <h2>Reading paths by theme</h2>
+      <ul>
+      <li><strong>Shared state &amp; async concurrency</strong> — <a href="16-supervised-app-with-logs.html">#16</a> → <a href="24-single-flight-boot-gate.html">#24</a> → <a href="50-weak-refs-self-cleaning-map.html">#50</a> → <a href="52-abort-detached-tokio-tasks.html">#52</a> → <a href="55-races-beyond-the-borrow-checker.html">#55</a></li>
+      <li><strong>Error handling</strong> — <a href="29-deadlines-and-failure-enums.html">#29</a> → <a href="48-warn-dont-swallow-errors.html">#48</a> → <a href="49-parse-dont-validate-actionable-errors.html">#49</a></li>
+      <li><strong>Traits &amp; generics</strong> — <a href="40-serve-https-local-ca.html">#40</a> (bounds / static dispatch) → <a href="43-trait-as-extension-point.html">#43</a> (impl / dynamic dispatch)</li>
+      <li><strong>Serde, config &amp; data</strong> — <a href="19-optional-fields-with-serde.html">#19</a> → <a href="22-serialize-wire-dto-contract.html">#22</a> → <a href="75-hand-render-config-to-disk.html">#75</a> → <a href="76-derived-env-precedence-order.html">#76</a></li>
+      <li><strong>The proxy stack</strong> — <a href="24-single-flight-boot-gate.html">#24</a> → <a href="40-serve-https-local-ca.html">#40</a> → <a href="51-typed-http-header-values.html">#51</a> → <a href="53-http-upgrade-stream-splicing.html">#53</a></li>
+      <li><strong>Process lifecycle &amp; env</strong> — <a href="17-inject-port-into-child-env.html">#17</a> → <a href="37-signals-bypass-drop-cleanup.html">#37</a> → <a href="76-derived-env-precedence-order.html">#76</a></li>
+      <li><strong>Strings &amp; slices</strong> — <a href="41-raw-string-templated-doc.html">#41</a> → <a href="45-iterator-map-collect-rows.html">#45</a> → <a href="56-split-once-structured-keys.html">#56</a></li>
+      <li><strong>Testing</strong> — <a href="38-deterministic-async-tests.html">#38</a> → <a href="47-integration-tests-separate-crate.html">#47</a> → <a href="55-races-beyond-the-borrow-checker.html">#55</a></li>
+      <li><strong>Tooling, ecosystem &amp; distribution</strong> — <a href="60-compile-time-version-stamping.html">#60</a> → <a href="63-what-clippy-teaches.html">#63</a> → <a href="65-health-files-and-metadata.html">#65</a> → <a href="69-distributing-a-rust-cli.html">#69</a></li>
+      </ul>
+    </article>
+  </div>
+</body>
+</html>
diff --git a/ent/lessons/lessons.css b/ent/lessons/lessons.css
new file mode 100644
index 0000000..fc20c78
--- /dev/null
+++ b/ent/lessons/lessons.css
@@ -0,0 +1,56 @@
+/* generated by build.mjs; edit docs/lessons/*.md */
+:root {
+  --ink: #0a0a0a; --paper: #ededea; --soft: #b5b5af; --dim: #7a7a74;
+  --rule: #1f1f1d; --accent: #d4a574; --accent-dim: #8a6a44;
+}
+* { box-sizing: border-box; margin: 0; padding: 0; }
+html, body { background: var(--ink); color: var(--paper); font-family: 'JetBrains Mono', ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 15px; line-height: 1.65; -webkit-font-smoothing: antialiased; }
+body { min-height: 100vh; padding: 3rem clamp(1.25rem, 6vw, 5rem); }
+.frame { max-width: 760px; margin: 0 auto; }
+header { display: flex; justify-content: space-between; align-items: baseline; margin-bottom: 3rem; }
+.wordmark { font-weight: 700; font-size: 1.1rem; letter-spacing: -0.03em; text-decoration: none; }
+.wordmark .a { color: var(--paper); } .wordmark .b { color: var(--accent); } .wordmark .slash { color: var(--rule); font-weight: 300; margin: 0 0.1em; }
+.back { font-size: 12px; color: var(--dim); text-transform: uppercase; letter-spacing: 0.1em; text-decoration: none; border-bottom: 1px dotted var(--dim); }
+.back:hover { color: var(--accent); border-color: var(--accent); }
+article h1 { font-size: clamp(1.6rem, 4vw, 2.3rem); font-weight: 700; letter-spacing: -0.02em; line-height: 1.15; margin-bottom: 1.5rem; }
+.lesson-header { border-left: 2px solid var(--accent-dim); padding-left: 1.1rem; margin-bottom: 2.5rem; }
+.lesson-header .lesson { font-size: 1.15rem; font-weight: 300; margin-bottom: 0.75rem; }
+.lesson-header .tags { display: flex; flex-wrap: wrap; gap: 0.4rem; margin-bottom: 0.6rem; }
+.lesson-header .meta { font-size: 12px; color: var(--dim); letter-spacing: 0.04em; }
+article h2 { font-size: 1.25rem; margin: 2.5rem 0 1rem; padding-top: 1.25rem; border-top: 1px solid var(--rule); }
+article h3 { font-size: 1.05rem; margin: 1.75rem 0 0.75rem; }
+article p { margin-bottom: 1rem; color: var(--paper); }
+article ul, article ol { margin: 0 0 1rem 1.4rem; }
+article li { margin-bottom: 0.35rem; }
+article a { color: var(--paper); text-decoration: none; border-bottom: 1px solid var(--accent-dim); }
+article a:hover { color: var(--accent); border-color: var(--accent); }
+code { font-family: inherit; color: var(--accent); font-size: 0.95em; }
+pre { background: rgba(255,255,255,0.02); border: 1px solid var(--rule); border-left: 2px solid var(--accent-dim); padding: 1rem 1.15rem; margin-bottom: 1.25rem; overflow-x: auto; }
+pre code { color: var(--paper); font-size: 13px; line-height: 1.5; }
+.term { font: inherit; background: none; border: none; padding: 0; cursor: pointer; border-bottom: 1px dotted var(--accent); }
+.term:hover, .term:focus-visible { background: rgba(212,165,116,0.1); }
+.tag code { font-size: 0.85em; }
+span.tag { border-bottom: 1px dotted var(--rule); }
+table.index { width: 100%; border-collapse: collapse; margin-bottom: 2.5rem; font-size: 0.9rem; }
+table.index td { border-bottom: 1px solid var(--rule); padding: 0.6rem 0.75rem 0.6rem 0; vertical-align: top; }
+table.index td.pr { white-space: nowrap; }
+table.index td.pr a { color: var(--accent); border: none; }
+table.index td.takeaway { color: var(--soft); }
+table.index tr.sparse td { color: var(--dim); }
+table.index .mark { color: var(--accent-dim); }
+/* Drawer (built by drawer.js) */
+.drawer-scrim { position: fixed; inset: 0; background: rgba(0,0,0,0.4); opacity: 0; pointer-events: none; transition: opacity 0.15s; z-index: 10; }
+.drawer-scrim.open { opacity: 1; pointer-events: auto; }
+.drawer { position: fixed; top: 0; right: 0; height: 100%; width: min(360px, 90vw); background: var(--ink); border-left: 1px solid var(--rule); transform: translateX(100%); transition: transform 0.18s ease-out; z-index: 11; padding: 1.75rem 1.5rem; overflow-y: auto; }
+.drawer.open { transform: none; }
+.drawer .close { position: absolute; top: 1rem; right: 1.1rem; background: none; border: none; color: var(--dim); font: inherit; font-size: 1.2rem; cursor: pointer; }
+.drawer .close:hover { color: var(--accent); }
+.drawer .back-link { background: none; border: none; color: var(--dim); font: inherit; font-size: 12px; letter-spacing: 0.08em; text-transform: uppercase; cursor: pointer; margin-bottom: 1rem; display: none; }
+.drawer.has-history .back-link { display: inline-block; }
+.drawer .d-term { color: var(--accent); font-weight: 700; font-size: 1.1rem; margin-bottom: 0.9rem; word-break: break-word; }
+.drawer .d-label { font-size: 11px; letter-spacing: 0.16em; text-transform: uppercase; color: var(--dim); margin: 1.2rem 0 0.4rem; }
+.drawer .d-short, .drawer .d-why { color: var(--paper); font-size: 0.95rem; }
+.drawer .d-prereqs { display: flex; flex-wrap: wrap; gap: 0.4rem; }
+.drawer .d-prereqs .term { border: 1px solid var(--accent-dim); border-radius: 2px; padding: 0.2rem 0.55rem; }
+.drawer .d-link a { color: var(--accent); font-size: 0.9rem; }
+@media (max-width: 540px) { body { padding: 2rem 1.1rem; } }
diff --git a/justfile b/justfile
index 02734fb..2922ef9 100644
--- a/justfile
+++ b/justfile
@@ -35,7 +35,10 @@ release:
   git tag "$tag"
   git push origin "$tag"
 
-serve:
+build-lessons:
+  node ent/lessons/build.mjs
+
+serve: build-lessons
   npx live-server --port=8081
 
 # Rebuild + re-create the local CA so the macOS keychain ACL trusts the new binary.