Add Section 1 Mermaid draft, bot-comments figure, two storyboard GIFs

Three deliverables for the parallel Option A / Option B pass:

1. planning/section-1-draft.mdx — working draft of the chapter's opening
   section with four Mermaid diagrams (repository as a filing cabinet,
   branch as a parallel working copy, commit as a snapshot, pull request
   as the formal merge proposal) plus a glossary. Will migrate into the
   main chapter MDX when the chapter is finalized.

2. fig-05-bot-comments — annotated figure showing the three bot comments
   every reviewer needs to recognize on the PR (assigned-reviewers state,
   stage progression, preview deployed). Captured from PR #121 via the
   existing pr-overview.png; coords merged in via the new
   probe-bot-comments.mjs.

3. Two storyboard GIFs (with editable .pptx variants):
   - gif-commit-filter-storyboard: walks through clicking the commit
     selector pill on the Files toolbar and picking the content commit
     to filter out the scaffolding diff (Section 3).
   - gif-changes-since-last-review-storyboard: walks through using
     the commit selector to pick 'Changes since your last review' on
     a backcheck round (Section 7).

Both storyboards use the existing filtered Files-changed capture as the
base, with Pillow-drawn dropdown mocks for the in-between states. The
user re-records these in ScreenToGif against the real UI when ready.

Author: AdamGohs

planning/assets/captures/pr-overview.coords.json

@@ -78,6 +78,25 @@
       "w": 1440,
       "h": 3729
     },
-    "pageHeight": 3729
+    "stageProgression": {
+      "x": 168,
+      "y": 2064,
+      "w": 808,
+      "h": 209
+    },
+    "assignedReviewers": {
+      "x": 168,
+      "y": 1665,
+      "w": 808,
+      "h": 304
+    },
+    "previewDeployed": {
+      "x": 168,
+      "y": 2305,
+      "w": 808,
+      "h": 210
+    },
+    "ciBuild": null,
+    "issueTrackerLabels": null
   }
 }

planning/assets/figure-pptx/fig-05-bot-comments.pptx

@@ -0,0 +1,102 @@
+---
+title: Section 1 Draft — Before you start, why we work this way
+---
+
+{/*
+  Working draft of Section 1 of the rewritten Reviewer Workflow chapter.
+  Mermaid diagrams convey the four core concepts a first-time reviewer
+  needs: repository, branch, commit, pull request. When the chapter is
+  finalized, this content moves into docs/dev/documentation-guide/12-
+  reviewer-workflow.mdx. Until then this is just a sketch — prose can
+  be tightened.
+*/}
+
+# Before you start — why we work this way
+
+Reviewing documentation on GitHub is unfamiliar territory for most engineers. Before clicking anything, this short tour explains the four concepts everything else in this chapter is built on: the **repository**, **branches**, **commits**, and **pull requests**. Read this once and most of the rest of the chapter will feel obvious.
+
+## The site you're reviewing is built from text files in a repository
+
+Every page on the RMC Software Documentation site is generated from a text file. All of those files live together in a single folder we call the **repository** — `RMC-Software-Documentation`. The repository is the source of truth: change a file there, the site updates.
+
+```mermaid
+flowchart TD
+    repo[("📁 RMC-Software-Documentation (the repository)")]
+    repo --> docs[("📁 docs/")]
+    docs --> desktop[("📁 desktop-applications/")]
+    docs --> toolbox[("📁 toolbox-technical-manuals/")]
+    docs --> web[("📁 web-applications/")]
+    desktop --> totalrisk[("📁 rmc-totalrisk/")]
+    totalrisk --> usersGuide[("📁 users-guide/")]
+    usersGuide --> v10[("📁 v1.0/")]
+    usersGuide --> v11[("📁 v1.1/ ← the revision you're reviewing")]
+    v11 --> mdxFiles["01-preface.mdx<br/>02-welcome.mdx<br/>03-overview.mdx<br/>… and so on"]
+```
+
+You will not be editing any of these files. Your job is to read the rendered output and either approve it or leave comments. The author is the one who edits.
+
+## A branch is a parallel copy of the repository
+
+If an author edited the live files directly, every keystroke would be on the published site instantly — typos and all. Instead, the author creates a **branch**: a working copy of the entire repository that they can edit freely without affecting anything readers see.
+
+The main branch — literally called `main` — is the published site. Branches with names like `docs/minor/totalrisk-users-guide-v1.1` are work-in-progress copies.
+
+```mermaid
+gitGraph
+    commit id: "v1.0 published"
+    commit id: "earlier work"
+    branch "docs/minor/totalrisk-users-guide-v1.1"
+    checkout "docs/minor/totalrisk-users-guide-v1.1"
+    commit id: "scaffold v1.1"
+    commit id: "edit preface, GUI..."
+    checkout main
+    commit id: "(meanwhile on main)"
+```
+
+The branch sits off to the side. Anything on `main` is live. Anything on a branch is in progress.
+
+## A commit is a saved snapshot
+
+Authors don't save every keystroke — they save in batches called **commits**. Each commit bundles up a coherent set of changes with a short message describing what was done.
+
+In a typical revision PR you'll see two commits:
+
+```mermaid
+gitGraph
+    commit id: "main HEAD"
+    branch "docs/minor/totalrisk-users-guide-v1.1"
+    commit id: "1. Scaffold v1.1 (boilerplate copy)"
+    commit id: "2. Edit preface, installation, GUI, acronyms"
+```
+
+The first commit is usually **scaffolding** — boilerplate that prepares the new version folder. It's mechanical and not something you need to review carefully. The second commit is the real content edit and is what the author wants your eyes on. Later in this chapter you'll learn how to skip past the scaffolding commit so you only see the changes that matter.
+
+## A pull request is a formal proposal to merge a branch back into main
+
+When an author is ready for review, they open a **pull request** (PR). A PR is a proposal: "please merge this branch into `main` so it goes live." It holds the review conversation in one place — comments, suggested changes, approvals, and the eventual merge button.
+
+```mermaid
+flowchart LR
+    branch["docs/minor/totalrisk-users-guide-v1.1<br/>(author's working branch)"]
+    pr{{"Pull Request #121<br/>Sample Document for Reviewer Training"}}
+    main["main<br/>(the live site)"]
+    branch -->|"author opens PR"| pr
+    pr -->|"reviewers comment, approve"| pr
+    pr -->|"admin merges<br/>after all approvals"| main
+```
+
+Two things matter:
+
+1. **Pull requests are the only way changes reach the live site.** Direct edits to `main` are blocked. Every change goes through this same review process.
+2. **A reviewer's entire job happens inside the pull request.** You will never edit a file directly. You read the rendered preview, leave comments on the PR, and approve when you're happy.
+
+## Glossary
+
+| Term | Plain-English meaning |
+|---|---|
+| **Repository** | The folder of files that the website is built from. |
+| **Branch** | A parallel copy of the repository where someone is making edits without disturbing the live site. |
+| **Commit** | A saved snapshot of one batch of edits, with a short message describing what changed. |
+| **Pull request (PR)** | A formal proposal to merge a branch into `main`. The conversation, the review, and the merge all happen here. |
+| **Merge** | The act of folding a branch's commits into `main`, making them part of the live site. |
+| **Main** | The branch that *is* the live site. Protected — you can only merge into it through a pull request. |

planning/assets/figure-pptx/gif-changes-since-last-review-storyboard.pptx

@@ -0,0 +1,45 @@
+"""
+Annotated "PR bot comments" figure for the reviewer-workflow chapter.
+
+Teaches reviewers to recognize the three automated comments that show up
+on every PR. Together they tell the reviewer everything they need without
+clicking around:
+  1. Assigned reviewers state — who's responsible for the current stage
+  2. Stage progression — which lane this PR is in, what review is needed
+  3. Preview deployed — the URL to read the rendered document on
+
+Source:
+  planning/assets/captures/pr-overview.png   (full-page capture)
+  planning/assets/captures/pr-overview.coords.json
+"""
+
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from annotate_lib import annotate_and_crop  # noqa: E402
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+SRC = REPO_ROOT / "planning" / "assets" / "captures" / "pr-overview.png"
+COORDS = REPO_ROOT / "planning" / "assets" / "captures" / "pr-overview.coords.json"
+OUT = REPO_ROOT / "static" / "figures" / "dev" / "reviewer-workflow" / "fig-05-bot-comments.png"
+PPTX = REPO_ROOT / "planning" / "assets" / "figure-pptx" / "fig-05-bot-comments.pptx"
+
+elements = json.loads(COORDS.read_text())["elements"]
+assigned = elements["assignedReviewers"]
+stage = elements["stageProgression"]
+preview = elements["previewDeployed"]
+
+# Crop to span all three bot comments with a little context above and below.
+top = min(assigned["y"], stage["y"], preview["y"]) - 50
+bottom = max(assigned["y"] + assigned["h"], stage["y"] + stage["h"], preview["y"] + preview["h"]) + 60
+CROP = (80, top, 1340, bottom)
+
+callouts = [
+    (assigned["x"], assigned["y"], assigned["w"], assigned["h"], "tl", 1),
+    (stage["x"], stage["y"], stage["w"], stage["h"], "tl", 2),
+    (preview["x"], preview["y"], preview["w"], preview["h"], "tl", 3),
+]
+
+annotate_and_crop(SRC, callouts, CROP, OUT, pptx_out=PPTX)

planning/assets/figure-pptx/gif-commit-filter-storyboard.pptx

@@ -0,0 +1,137 @@
+"""
+Storyboard GIF: viewing only what's new since your last review
+(Section 7 — the backcheck round).
+
+After the reviewer submits a Comment-style review and the author pushes
+new commits, the Files-changed toolbar gains a "Changes since your last
+review" option in the commit-range dropdown. This storyboard walks
+through that flow.
+
+Frames:
+  1. After your first review, the author has pushed more commits
+  2. Click the commit selector to open the dropdown
+  3. The "Changes since your last review" option is at the top — pick it
+  4. The diff narrows to only what's new
+
+The state where this UI appears requires both a prior review and new
+commits, which the sandbox PR doesn't naturally produce. The storyboard
+mocks the dropdown overlay; the user re-records with ScreenToGif against
+a real backcheck PR when one shows up.
+"""
+
+import io
+from pathlib import Path
+from PIL import Image, ImageDraw, ImageFont
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+SRC = REPO_ROOT / "planning" / "assets" / "captures" / "pr-files-changed.png"
+OUT_GIF = REPO_ROOT / "static" / "figures" / "dev" / "reviewer-workflow" / "gif-changes-since-last-review-storyboard.gif"
+OUT_PPTX = REPO_ROOT / "planning" / "assets" / "figure-pptx" / "gif-changes-since-last-review-storyboard.pptx"
+
+CROP = (20, 200, 1340, 700)
+
+ACCENT = (74, 124, 155, 255)
+WHITE = (255, 255, 255, 255)
+RED = (200, 30, 30, 255)
+LABEL_BG = (255, 248, 220, 250)
+BLUE_HOVER = (221, 244, 255, 255)
+
+
+def load_font(size):
+    for p in ("C:/Windows/Fonts/segoeuib.ttf", "C:/Windows/Fonts/arialbd.ttf"):
+        if Path(p).exists():
+            return ImageFont.truetype(p, size)
+    return ImageFont.load_default()
+
+
+def caption(draw, x, y, text, font):
+    bb = draw.textbbox((0, 0), text, font=font)
+    tw, th = bb[2] - bb[0], bb[3] - bb[1]
+    pad = 12
+    rect = [x, y, x + tw + pad * 2, y + th + pad * 2]
+    draw.rounded_rectangle([rect[0] - 2, rect[1] - 2, rect[2] + 2, rect[3] + 2], radius=12, fill=WHITE)
+    draw.rounded_rectangle(rect, radius=10, fill=LABEL_BG, outline=(50, 90, 115, 255), width=2)
+    draw.text((x + pad - bb[0], y + pad - bb[1]), text, font=font, fill=(40, 40, 40, 255))
+
+
+def draw_dropdown(draw, x, y, items, highlighted=None):
+    item_h = 44
+    w = 560
+    h = item_h * len(items) + 16
+    draw.rounded_rectangle([x, y, x + w, y + h], radius=8, fill=(255, 255, 255, 255), outline=(208, 215, 222, 255), width=1)
+    f_title = load_font(13)
+    f_sub = load_font(11)
+    for i, (title, subtitle) in enumerate(items):
+        iy = y + 8 + i * item_h
+        if i == highlighted:
+            draw.rectangle([x + 4, iy, x + w - 4, iy + item_h], fill=BLUE_HOVER)
+        draw.text((x + 14, iy + 4), title, font=f_title, fill=(36, 41, 47, 255))
+        draw.text((x + 14, iy + 22), subtitle, font=f_sub, fill=(101, 109, 118, 255))
+
+
+def render_frame(base, n):
+    img = base.copy()
+    overlay = Image.new("RGBA", img.size, (0, 0, 0, 0))
+    d = ImageDraw.Draw(overlay)
+    f_cap = load_font(18)
+    f_step = load_font(28)
+
+    # Step indicator
+    d.rounded_rectangle([20, 18, 130, 56], radius=8, fill=ACCENT)
+    d.text((35, 24), f"Step {n}", font=f_step, fill=WHITE)
+
+    pill_xy = (60, 78, 140, 24)  # commit selector in cropped frame
+    px, py, pw, ph = pill_xy
+
+    dropdown_items = [
+        ("Changes since your last review", "only the new commits the author just pushed"),
+        ("All commits", "everything in the PR"),
+        ("Scaffold v1.1 of RMC TotalRisk Users Guide", "commit 85e53a4 — boilerplate"),
+        ("Update preface, installation, GUI, and acronyms for v1.1", "commit 7ae2022 — the content edits"),
+    ]
+
+    if n == 1:
+        caption(d, 160, 24, "1. You've already reviewed. The author has pushed new commits. Come back to the PR.", f_cap)
+    elif n == 2:
+        caption(d, 160, 24, "2. On Files changed, click the commit selector pill.", f_cap)
+        d.rectangle([px - 3, py - 3, px + pw + 3, py + ph + 3], outline=RED, width=4)
+    elif n == 3:
+        caption(d, 160, 24, "3. Pick \"Changes since your last review\" at the top of the dropdown.", f_cap)
+        d.rectangle([px - 3, py - 3, px + pw + 3, py + ph + 3], outline=RED, width=4)
+        draw_dropdown(d, px, py + ph + 8, dropdown_items, highlighted=0)
+    elif n == 4:
+        caption(d, 160, 24, "4. The diff narrows to only the new changes — backcheck just those.", f_cap)
+        # Highlight the file tree + diff area
+        d.rectangle([13, 184, 308, 344], outline=RED, width=4)
+        d.rectangle([336, 380, 1316, 470], outline=RED, width=4)
+
+    return Image.alpha_composite(img.convert("RGBA"), overlay).convert("RGB")
+
+
+def main():
+    OUT_GIF.parent.mkdir(parents=True, exist_ok=True)
+    OUT_PPTX.parent.mkdir(parents=True, exist_ok=True)
+
+    base = Image.open(SRC).convert("RGBA").crop(CROP)
+    frames = [render_frame(base, i) for i in range(1, 5)]
+    frames[0].save(OUT_GIF, save_all=True, append_images=frames[1:], duration=2400, loop=0, optimize=True)
+    print(f"Wrote {OUT_GIF} ({base.size[0]}x{base.size[1]}, {len(frames)} frames)")
+
+    from pptx import Presentation
+    from pptx.util import Inches
+    prs = Presentation()
+    prs.slide_width = Inches(base.size[0] / 96)
+    prs.slide_height = Inches(base.size[1] / 96)
+    blank = prs.slide_layouts[6]
+    for frm in frames:
+        slide = prs.slides.add_slide(blank)
+        buf = io.BytesIO()
+        frm.save(buf, format="PNG")
+        buf.seek(0)
+        slide.shapes.add_picture(buf, 0, 0, prs.slide_width, prs.slide_height)
+    prs.save(str(OUT_PPTX))
+    print(f"Wrote {OUT_PPTX} ({len(frames)} slides)")
+
+
+if __name__ == "__main__":
+    main()