Add maze module: generator playground, wall-follower, maze-solver integration

New lesson 35 "Navigating a maze" and its interactive tooling, plus the
plumbing to run FRC2713/maze-solver-java in the browser:

- MazePlayground: renders a generated maze (correct recursive-backtracking,
  since the maze-generator npm package's shuffle is broken), with a drivable
  robot, start/goal markers, an animated wall-follower, and "Copy for Java"
  serialization to an int[][] bitmask literal.
- Lesson pages build from "what a maze is" -> robot navigation -> algorithms
  (sense/decide/move) -> the wall follower -> the same algorithm in raw Java
  -> the same algorithm against the maze-solver library's Robot/Cell API.
- Site wiring: `maze` fence (lessons.ts/LessonView), maze-solver.jar on the
  CheerpJ classpath, a CI step + vendor script that build the jar (gitignored,
  never committed).

Also includes the in-flight lessons ordering refactor and module docs
(CONTEXT.md glossary, ADR 0001, ordering-refactor handoff) that were already
in the working tree.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: tytremblay

.claude/settings.json

@@ -0,0 +1,5 @@
+{
+  "enabledPlugins": {
+    "frc2713-skills@frc2713": true
+  }
+}

.github/workflows/deploy-pages.yml

@@ -19,6 +19,26 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+
+      # Build the maze-solver library and vendor its jar into site/public/ so
+      # the Java playground can load the com.frc2713.mazesolver API. Built fresh
+      # each deploy from the library's main; not committed (see site/.gitignore).
+      - uses: actions/checkout@v4
+        with:
+          repository: FRC2713/maze-solver-java
+          ref: main
+          path: maze-solver-java
+      - uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: '21'
+          cache: maven
+      - name: Build maze-solver jar
+        run: |
+          mvn -B -q -DskipTests package
+          cp target/maze-solver.jar "$GITHUB_WORKSPACE/site/public/maze-solver.jar"
+        working-directory: maze-solver-java
+
       - uses: actions/setup-node@v4
         with:
           node-version: 20

CONTEXT.md

@@ -0,0 +1,68 @@
+# Maze Solver Module
+
+Glossary for the maze-solving module of the FRC 2713 training curriculum — a
+series of lessons in which students write Java that solves a maze. This file is
+the shared language for that module only; it is not a spec.
+
+## Language
+
+**Maze**:
+A fixed puzzle the robot must traverse from Start to Goal. The student's program
+is handed the whole maze up front (see _Grid_).
+
+**Grid**:
+The god's-eye representation of a Maze the program receives — the entire layout,
+known in full before the robot moves, as a rectangular 2D array of Cells. Each
+Cell carries its own Wall flags, so the Grid is a `Cell[][]`, not a grid of
+blocked/open squares.
+_Avoid_: map (reserve "map" for a robot-built model, which this module does not use)
+
+**Cell**:
+One square of the Grid — always open and standable. A Cell records a **Wall** on
+each of its four sides (up / down / left / right); those flags, not the Cells
+themselves, are what block movement. Every Cell is reachable to stand on; what
+varies is which of its edges are walled.
+
+**Wall**:
+A **thin** barrier on the edge between two adjacent Cells (or on a Cell's outer
+edge), blocking movement across that edge. Walls live on edges, not whole Cells:
+a Cell is never "a wall". Wall flags are consistent between neighbours — the down
+edge of a Cell is the up edge of the Cell below it.
+
+**Robot**:
+The thing that traverses the Maze by executing a Solution. It has a position on
+the Grid (a Cell) and **no orientation** — it does not face a direction, so every
+Move is an absolute step, not a turn.
+
+**Start**:
+The cell where the Robot begins.
+
+**Goal**:
+The target cell. A Solution **succeeds** if and only if executing it from Start
+leaves the Robot standing on the Goal.
+
+**Solution**:
+The ordered sequence of Moves the student's program emits. Success is judged
+only by whether it finishes the Maze (reaches the Goal). A Move blocked by a Wall
+is not a modeled failure — it simply does nothing; nothing is penalized. The
+module is about *finishing*, not collision avoidance.
+
+**Maze Battle**:
+The module's finale. A student submits one program; it is scored by how many of a
+set of *unseen* Mazes it finishes (a gauntlet), tie-broken by total Moves. The
+format rewards a general algorithm (which clears the whole set) over a hard-coded
+Solution (which finishes only the one Maze it was written for).
+
+**Move** (also **Command**):
+One instruction to the Robot. Exactly four exist: **UP**, **DOWN**, **LEFT**,
+**RIGHT** — absolute, screen-relative directions. Each Move steps the Robot
+**one Cell** in that direction *if that edge is open*; a Move blocked by a Wall
+(or the grid edge) does nothing. There are no turns and no orientation to track.
+_Avoid_: turn, heading, facing, North/South/East/West, "drive to the next junction"
+
+**Helper** (injected):
+Convenience methods the harness puts in scope so students query the Maze without
+hand-indexing Wall flags: `robot.moveUp/moveDown/moveLeft/moveRight()`,
+`robot.canGoUp/canGoDown/canGoLeft/canGoRight()`, `robot.atGoal()`,
+`robot.row()/col()`, plus god's-eye access to the whole `Cell[][]` grid for route
+planning.

docs/adr/0001-derive-lesson-order-from-position.md

@@ -0,0 +1,60 @@
+# 1. Derive lesson order from position
+
+Status: Accepted
+
+Date: 2026-07-20
+
+## Context
+
+A lesson's **absolute position** used to be stored as *content* in three places,
+which made inserting or reordering a lesson a ~250-edit chore:
+
+- `order:` frontmatter was a dense consecutive integer sequence (1, 2, 3, …), so
+  inserting a lesson shifted the `order` of every later lesson.
+- `title:` embedded the ordinal (`"Lesson 20: State machines as diagrams"`).
+- Cross-references named the ordinal in visible link text and prose
+  (`[lesson 12](#/lesson/12-arrays)`, and bare "in lesson 20" mentions) — 103
+  hash-links plus dozens of prose mentions across 34 files.
+
+Sorting is driven **only** by `order` (`site/src/lib/lessons.ts`); the numeric
+prefix on a folder/slug name is cosmetic and never read. So the displayed number
+can be computed from a lesson's position in the sorted list instead of stored.
+
+## Decision
+
+Derive the displayed lesson number from position; get ordinals out of stored
+content. Specifically (Option B — we did **not** rename folders or change any
+`#/lesson/<slug>` href, which was the rejected Option C):
+
+1. **Gapped `order`.** Each lesson's `order` is `position * 10` (1st → 10, 2nd →
+   20, … 34th → 340). Same sequence as before, but with room to insert a lesson
+   between neighbors (e.g. a future maze module at 191–195) without touching any
+   other lesson's `order`.
+2. **Concept-only titles.** The `Lesson N: ` prefix is stripped from all `title:`
+   values (`title: "State machines as diagrams"`).
+3. **Number rendered from position.** The `lessons` array is sorted by `order`;
+   the displayed number is its 1-based index. `lessonNumber(slug)` in
+   `site/src/lib/lessons.ts` is the single source of truth; the index cards,
+   sidebar, and lesson-view header all read it.
+4. **Slug-keyed cross-references.** Cross-reference links carry no stored number.
+   Their visible text uses `{n}` / `{title}` tokens (e.g.
+   `[lesson {n}](#/lesson/09-if-statements)`) that a custom react-markdown link
+   renderer in `LessonView.tsx` fills in from the target's **current**
+   `lessonNumber` / title at render time. Bare-prose "lesson NN" mentions were
+   converted to the same token-link form (or rephrased to a concept reference,
+   e.g. "the Objects lessons").
+
+## Consequences
+
+- Inserting or reordering a lesson touches **only** `order:` values. No title,
+  prose, or cross-reference edits are needed; every displayed number and
+  reference re-labels itself automatically from the new positions.
+- Slugs keep their numeric prefix (`12-arrays`). It is now an opaque, harmless id
+  that users never see — it is not the lesson's displayed number and need not
+  match it. A lesson can sit at any position regardless of its slug prefix.
+- Lesson READMEs remain valid Markdown, but the `{n}` / `{title}` tokens and
+  `#/lesson/<slug>` hrefs only resolve inside the site renderer; on GitHub the
+  tokens render literally and the hash links do not navigate. This was already
+  true of the hash links and is an accepted cost of Option B.
+- Anything that reads a lesson's number must derive it (`lessonNumber`), never
+  parse it from a title or slug.

docs/handoffs/ordering-refactor.md

@@ -0,0 +1,68 @@
+# Handoff: make lesson ordering cheap to change (Option B)
+
+## Why
+Today, a lesson's **absolute position** is stored as *content* in three places, so
+inserting or moving a lesson is a ~250-edit chore:
+
+- `order:` frontmatter is dense consecutive integers → inserting shifts every later lesson.
+- `title:` embeds the ordinal (`"Lesson 20: State machines as diagrams"`).
+- Cross-references name the ordinal in visible prose and link text
+  (`[lesson 12](#/lesson/12-arrays)`, and bare "in lesson 20" mentions).
+
+Sorting is driven **only** by `order` (`site/src/lib/lessons.ts:92`); the numeric
+prefix on folder names is cosmetic. The fix: **derive the displayed number from a
+lesson's position in the sorted list**, and get ordinals out of stored content.
+
+Measured footprint (lessons 1–34): 34 titles, 103 hash-links, 128 prose "lesson NN"
+mentions, 34 numbered folders.
+
+## Scope: Option B (do), Option C (do NOT)
+**In scope (B):**
+1. **Gapped `order`.** Rewrite each lesson's `order` to `position * 10` (current
+   1st → 10, 2nd → 20, … 34th → 340), preserving today's exact sequence but
+   leaving room to insert. (A future maze module will slot in at, e.g., 191–195
+   between Objects and State Machines — nothing else will need to move.)
+2. **De-numbered titles.** Strip the `Lesson N: ` prefix from all 34 `title:`
+   values → concept only (`title: "State machines as diagrams"`).
+3. **Site renders the number from position.** The `lessons` array is already
+   sorted by `order`; display a 1-based index as the lesson number everywhere a
+   number should appear — index cards (`LessonCard.tsx`), the lesson header
+   (`LessonView`), and the sidebar (`AppSidebar.tsx`, whose `shortTitle` regex on
+   line 18 becomes obsolete — titles no longer carry the prefix; prepend the
+   derived number instead if a number is wanted there). Numbers must stay 1..34
+   in the same order after the refactor — this is a no-visible-reorder change.
+4. **Reorder-proof cross-references.** This is the point of the whole exercise:
+   after this, moving/inserting a lesson must NOT require editing any other
+   lesson's prose. Recommended mechanism: a custom link renderer (the site
+   renders lesson markdown — find the react-markdown/MD renderer in
+   `site/src/`) that, for any `#/lesson/<slug>` link, resolves the target
+   lesson's **current** derived number (and/or title) at render time via
+   `getLesson(slug)` + its index. Convert the 103 existing
+   `[lesson N](#/lesson/<slug>)` links to a canonical slug-keyed form the
+   renderer fills in, so the visible "lesson N" is always computed, never stored.
+   For the bare-prose "lesson NN" mentions that are not links, prefer turning them
+   into such links, or rephrase to a concept reference ("the arrays lesson"). No
+   stored ordinal may remain in prose.
+
+**Out of scope (Option C — do NOT do):**
+- Do **not** rename lesson folders or strip numeric prefixes from slugs.
+- Do **not** change any `#/lesson/<slug>` href target. Slugs stay exactly as they
+  are (their numeric prefix is now a harmless opaque id users never see).
+
+## Deliverables
+- All 34 lessons updated (order + title) and cross-references converted.
+- Site code renders derived numbers and resolves cross-ref numbers at render time.
+- `docs/adr/0001-derive-lesson-order-from-position.md` recording the decision
+  (context: ordinal-as-content churn; decision: derive from position, concept-only
+  titles, slug-keyed cross-refs; consequence: inserts/reorders touch only `order`).
+- `cd site && npm run build && npm run lint` both pass.
+
+## Acceptance check
+- Index and sidebar show lessons 1..34 in the identical order and with the same
+  visible numbers as before this change.
+- Every cross-reference link still resolves, and its visible number matches the
+  target's current position (test by temporarily bumping one lesson's `order`
+  past a neighbor — the reference text should follow automatically, with no
+  content edit — then revert).
+- No `title:` contains `Lesson \d+:`; no lesson prose contains a hard-coded
+  "lesson NN" ordinal.

lessons/01-flowcharts/README.md

@@ -1,7 +1,7 @@
 ---
-title: "Lesson 1: Programs are step-by-step"
+title: "Programs are step-by-step"
 goal: "See a program as a flowchart of blocks and watch the computer evaluate it one step at a time."
-order: 1
+order: 10
 section: "Programming with Blocks"
 ---
 

lessons/02-conditionals/README.md

@@ -1,7 +1,7 @@
 ---
-title: "Lesson 2: Making decisions"
+title: "Making decisions"
 goal: "Use a condition to make a program choose between two paths."
-order: 2
+order: 20
 section: "Programming with Blocks"
 ---
 
@@ -30,7 +30,7 @@ asks `a > b?` — that's `true` here (`7 > 4`) — so the program follows the
 Press **▶ Run step by step**. Watch the diamond answer `true` and the program
 head down the `true` arrow — while the other branch **grays out and gets
 skipped**. Those blocks never run. This fork is exactly what Java writes as
-`if / else` — you'll type it yourself in lesson 9.
+`if / else` — you'll type it yourself in [lesson {n}](#/lesson/09-if-statements).
 
 ```blocks
 preset: cond-demo

lessons/03-loops/README.md

@@ -1,7 +1,7 @@
 ---
-title: "Lesson 3: Doing things over and over"
+title: "Doing things over and over"
 goal: "Use a loop to repeat a step many times without copying it out by hand."
-order: 3
+order: 30
 section: "Programming with Blocks"
 ---
 

lessons/04-functions/README.md

@@ -1,7 +1,7 @@
 ---
-title: "Lesson 4: Reusable blocks"
+title: "Reusable blocks"
 goal: "Package a flowchart into a named block you can reuse instead of rebuilding it."
-order: 4
+order: 40
 section: "Programming with Blocks"
 ---
 

lessons/05-what-is-java/README.md

@@ -1,14 +1,14 @@
 ---
-title: "Lesson 5: What is Java?"
+title: "What is Java?"
 goal: "Recognize Java's basic punctuation and program shape before writing or running any code."
-order: 5
+order: 50
 section: "Java Fundamentals"
 ---
 
 # A language, not a magic spell
 
 You've been building programs already — as flowcharts of blocks
-([lesson 1](#/lesson/01-flowcharts) onward). From here on we write those same
+([lesson {n}](#/lesson/01-flowcharts) onward). From here on we write those same
 ideas as **text**, in a language called **Java**. It's the language FRC robot
 code is written in, and one of the most widely used languages in the world.
 
@@ -72,7 +72,7 @@ public class Main {
 
 Don't worry about memorizing this — the playground writes it for you for now,
 and you'll learn to write it yourself in
-[lesson 11](#/lesson/11-writing-methods). For today, just recognize the shapes
+[lesson {n}](#/lesson/11-writing-methods). For today, just recognize the shapes
 in it with the vocabulary from above:
 
 - `public class Main { ... }` — a **class** named `Main`, with everything it