Rewrite lessons 1-4 against real code, and revise the plan

.github/workflows/lessons.yml

@@ -0,0 +1,38 @@
+name: Lessons
+
+# The lessons quote the application's source. This checks the quotes are still
+# accurate, so a change to elxrBB that contradicts a lesson fails here rather
+# than in a reader's terminal.
+
+on:
+  push:
+    # Branches are covered by pull_request; this is for merges to main.
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+  schedule:
+    # The application can drift without this repo changing, so check weekly too.
+    - cron: "17 6 * * 1"
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Check out the application the lessons teach
+        uses: actions/checkout@v5
+        with:
+          repository: ephbaum/elxrBB
+          ref: ${{ vars.ELXRBB_REF || 'claude/modernization-implementation-puv702' }}
+          # lessons.exs pins each lesson to the commit that concludes it, so
+          # the checker needs history, not just a tip snapshot.
+          fetch-depth: 0
+          path: .elxrbb
+
+      - uses: erlef/setup-beam@v1
+        with:
+          elixir-version: "1.20.4"
+          otp-version: "28.5.0.6"
+
+      - run: elixir bin/check_lessons.exs --app .elxrbb

README.md

@@ -1,14 +1,56 @@
 # elxrBB-tutorial
 
+Build a forum web application with Elixir and Phoenix, one lesson at a time.
+
+## Start here
+
+| | |
+|---|---|
+| [Outline](docs/00a-outline.md) | The whole series at a glance |
+| [Introduction](docs/00b-introduction.md) | What elxrBB is and what it will do |
+| [Lesson 1](docs/01-setting-up.md) | Environment setup and generating the project |
+| [Lesson 2](docs/02-user-authentication.md) | Accounts, magic-link login, usernames and bios |
+| [Lesson 3](docs/03-forum-functionality.md) | Forums, topics and replies |
+| [Lesson 4](docs/04-threading-and-voting.md) | Threaded replies, sub-topics and voting |
+| [Status](STATUS.md) | Which lessons are written, and which are implemented |
+
+The reference application lives at
+[ephbaum/elxrBB](https://github.com/ephbaum/elxrBB). Lessons 1–4 are written
+against code that is actually in that repository and passes its test suite;
+everything from lesson 5 on is still an outline.
+
+Written against Phoenix 1.8 on Elixir 1.20 / OTP 28, using `mix phx.gen.auth`,
+LiveView, Tailwind 4 and daisyUI.
+
+## Checking the lessons
+
+The lessons quote the application's source, and quoted code goes stale. Blocks
+that name their source file in the fence are checked against it:
+
+    elixir bin/check_lessons.exs --app ../elxrBB
+
+Each lesson is checked against the commit that concludes it, named in
+`lessons.exs` -- lesson 3 shows replies as a flat stream and lesson 4 replaces
+that with a tree, so checking either against the application's HEAD would
+report drift that is really the tutorial doing its job.
+
+Whitespace and whole-line comments are ignored, so a lesson may re-indent or
+reflow an excerpt and leave out a comment it explains in prose. A line of bare
+`...`, or a comment mentioning `...`, stands in for code the lesson is not
+showing. Pass `--strict` to also fail on source blocks that name no file; not
+every block names one yet, so the unannotated count is a backlog, not a bug.
+
+## Where this came from
+
 A (an ambitious) collaborative effort with ChatGPT (GPT-4) to create a tutorial for, and open source, a forum web application
 
-## What?
+### What?
 
 This repo is the result of a recent conversation with [ChatGPT](https://help.openai.com/en/collections/3742473-chatgpt) ([GPT4](https://openai.com/research/gpt-4)). The clever little chatbot suggested in true ChatGPT Dunning-Kruger style, and I figured 🤷‍♂️, okay, maybe we can build a real tutorial from this conversation
 
 Essentially, I asked ChatGPT about how to build a forum web app using Elixir and Phoenix
 
-## Why?
+### Why?
 
 The conversation around ChatGPT right now is wild. There's a lot of [doomers](https://www.reuters.com/technology/musk-experts-urge-pause-training-ai-systems-that-can-outperform-gpt-4-2023-03-29/) out there, [some moreso](https://time.com/6266923/ai-eliezer-yudkowsky-open-letter-not-enough/) than [others](https://astralcodexten.substack.com/p/why-i-am-not-as-much-of-a-doomer).
 
@@ -28,7 +70,7 @@ There is something amazing about working with an always-there (except when you h
 
 ChatGPT is a hell of a "yes-man" and has a pretty wide array of knowledge to draw from-
 
-## How?
+### How?
 
 I am just working with ChatGPT to build both this tutorial and the application
 
@@ -38,6 +80,6 @@ I do hope some folks might [contribute]() in the future, maybe even some folks w
 
 Or maybe it will be another repo gathering dust :shrug:
 
-## Important Note
+### Important Note
 
 I make no warranty. This is a work in progress and I have no idea what I'm doing (probably). ChatGPT and I seem to be having a pretty productive conversation, but this may all be made up bullshit. Do not rely on it until this document suggests otherwise. 

STATUS.md

@@ -1,56 +1,85 @@
 # Tutorial Status
 
-This document tracks the current status of each tutorial lesson and its corresponding implementation in the application repository.
+Tracks each lesson and whether the reference application actually implements it.
 
-## Lesson Status
+Application repository: <https://github.com/ephbaum/elxrBB>
 
-| Lesson | Title | Status | Application Commit | Notes |
-|--------|-------|--------|-------------------|-------|
-| 1 | Setting Up the Environment | ✅ Complete | Not started | Clean, modern instructions |
-| 2 | User Authentication with Pow | ✅ Complete | Not started | Updated configuration |
-| 3 | Forum Functionality | 🚧 Planned | Not started | Implementation plan ready |
-| 4 | Threaded Replies and Voting | 📋 Planned | Not started | Needs merging with lesson 5 |
-| 5 | Sub-topics | 📋 Planned | Not started | Merge with lesson 4 |
-| 6 | Private Messaging and Profiles | 📋 Planned | Not started | Needs modernization |
+## Lessons
 
-## Status Legend
+Numbering follows the revised [outline](docs/00a-outline.md).
 
-- ✅ **Complete** - Lesson is finished and validated
-- 🚧 **Planned** - Implementation plan is ready
-- 📋 **Planned** - Needs work before implementation
-- ❌ **Incomplete** - Not ready for implementation
+| # | Title | Lesson | Implemented |
+|---|---|---|---|
+| 1 | Setting Up the Environment | ✅ Written | ✅ Yes |
+| 2 | User Accounts | ✅ Written | ✅ Yes |
+| 3 | Forums, Topics and Replies | ✅ Written | ✅ Yes |
+| 4 | Threaded Replies, Sub-Topics and Voting | ✅ Written | ✅ Yes |
+| 5 | Real-Time Updates with PubSub | 🚧 Next | 🚧 Next |
+| 6 | Pagination and Search | 📋 Outlined | ❌ No |
+| 7 | Profiles, Avatars and Private Messaging | 📋 Outlined | ⚠️ Profiles shipped in lesson 2 |
+| 8 | Rich Text and Safe Rendering | 📋 Outlined | ❌ No |
+| 9 | Roles, Permissions and Moderation | 📋 Outlined | ❌ No |
+| 10 | Audit Trails and the Admin Dashboard | 📋 Outlined | ❌ No |
+| 11 | Notifications | 📋 Outlined | ❌ No |
+| 12 | Accessible Design | 📋 Outlined | ❌ No |
+| 13 | Testing in Depth | 📋 Outlined | ⚠️ App is tested; lesson not written |
+| 14 | Deploying elxrBB | 📋 Outlined | ❌ No |
+| 15 | Customizing and Extending | 📋 Outlined | ❌ No |
+| A–D | Appendices | 📋 Outlined | ❌ No |
 
-## Implementation Progress
+Legend: ✅ done · 🚧 in progress · ⚠️ partial · 📋 planned · ❌ not started
 
-### Application Repository
-- **Repository**: https://github.com/ephbaum/elxrBB
-- **Current Status**: Fresh start with documentation
-- **Next Step**: Begin Lesson 1 implementation
+## What the application does today
 
-### Tutorial Repository
-- **Repository**: https://github.com/ephbaum/elxrBB-tutorial
-- **Current Status**: Lessons 1-2 cleaned, Lesson 3 planned
-- **Next Step**: Complete remaining lesson plans
+- Accounts: registration, magic-link login, email confirmation, password and
+  email changes, sudo mode for sensitive edits.
+- Profiles: an auto-assigned `GerundAnimal` username (544,116 possible names)
+  plus a bio, both editable from the settings page.
+- Forums: create, edit, delete. Public listing with topic counts.
+- Topics: created inside a forum by a signed-in user. Forum pages list them
+  with reply counts, ordered by most recent activity.
+- Replies: posted from the topic page, nested up to five levels deep, with a
+  sub-reply count on every parent. Authors can edit and delete their own posts;
+  deleting one removes its subtree.
+- Voting: up and down votes on topics and replies, one per user per post,
+  revocable. Threads and forum listings can be sorted by score.
 
-## Validation Process
+231 tests pass on `mix precommit`.
 
-Each lesson will be validated by:
-1. Following the tutorial instructions
-2. Implementing in the application repository
-3. Testing functionality
-4. Updating this status document
-5. Linking to application commits
+## Known gaps in the application
 
-## Historical Context
+These are true of the code today and are scheduled, not forgotten:
 
-- **Original Lessons**: Archived in `docs/archive/original-lessons/`
-- **Original Application**: Archived in `archive/initial-attempt` branch
-- **Project Restart**: January 2025
+- **No pagination.** `list_topics/1` and `list_replies/1` return everything.
+  Lesson 6.
+- **No real-time.** A posted reply or vote appears for its author only; other
+  readers must reload. Lesson 5.
+- **No search.** Lesson 6.
+- **Post bodies render as plain text.** No Markdown, and therefore no
+  sanitization question to answer yet. Lesson 8.
+- **Anyone signed in can create, edit or delete a forum.** Only topics and
+  replies are author-restricted. Roles land in lesson 9.
+- **No rate limiting.** Not on the outline; worth adding before this is ever
+  exposed to the public internet.
 
-## Next Steps
+## Deviations from the original plan
 
-1. **Implement Lesson 1** - Environment setup
-2. **Implement Lesson 2** - User authentication
-3. **Implement Lesson 3** - Forum functionality
-4. **Update remaining lessons** - Modernize and complete
-5. **Validate all lessons** - Ensure tutorial/application alignment
+The outline itself was revised once lessons 1–3 existed; see
+[Revisions to this plan](docs/00a-outline.md#revisions-to-this-plan) for the
+full account. In short: lessons 4 and 5 were one lesson, real-time moved much
+earlier and switched from Channels to PubSub, pagination and search were
+missing entirely, testing moved earlier, the animal-names lesson was dropped
+as superseded by lesson 2, and the vendor-dependent material (payments, SMS,
+browser push) became optional appendices.
+
+## How a lesson gets marked done
+
+1. The lesson is written against code that exists.
+2. The code is in the application repository and `mix precommit` passes.
+3. Every command and snippet in the lesson was run, not assumed.
+4. This file is updated.
+
+## Archive
+
+- Original lessons (2023, ChatGPT-assisted): `docs/archive/original-lessons/`
+- Original application: the `archive/initial-attempt` branch of the app repo