Add screenshot annotation support and update related documentation

- Introduced `annotate.sh` script to render annotated screenshots into build/images/
- Added `annotations/README.md` to explain the annotation process and types
- Updated `README.md` to include details about screenshot annotations
- Modified `install.sh` to include dependencies for annotation rendering
- Enhanced `build.sh` and `build-web.sh` to utilize annotated images if available
- Updated `.gitignore` to exclude build artifacts and added new annotation files
- Created example annotation file `status.yaml` for reference

Author: OnlineDynamic

.gitignore

@@ -7,6 +7,9 @@
 # Generated web edition (staged docs + built static site)
 /web/
 
+# Annotated screenshots baked from images/ + annotations/ at build time
+/build/
+
 # Reference source material (fetched on demand, not distributed here)
 tools/v9manual.pdf
 tools/v9manual.txt

CLAUDE.md

@@ -32,6 +32,7 @@ done:**
 - an image referenced by a chapter (`images/`)
 - build configuration: `metadata.yaml`, `tools/reference.docx`, `tools/build.sh`,
   `mkdocs.yml`, `tools/build-web.sh`
+- a screenshot annotation under `annotations/` (see *Annotating screenshots* below)
 
 `generate.sh` / `generate-web.sh` do **not** require a running FPP. A missing
 screenshot is a non-fatal warning (Pandoc substitutes the image's caption text;
@@ -50,6 +51,31 @@ Word styling automatically — there is no separate PDF stylesheet to maintain.
 LibreOffice isn't installed the PDF step is skipped with a hint and the `.docx`
 still builds; run `PDF=0 ./generate.sh` to skip the PDF deliberately.
 
+## Annotating screenshots (arrows, callouts, redactions)
+
+Screenshots can be marked up **declaratively** so `capture.sh` can still re-shoot
+the raw images: `images/` stays pristine and annotations are baked on at build time
+into `build/images/`, which every deliverable then uses. When the maintainer asks to
+annotate an image (e.g. "put an arrow on the Save button and number the tabs on
+`status.png`"):
+
+1. **Read the source image** (`images/<name>.png`) to find pixel coordinates —
+   the Read tool shows it to you; coordinates are pixels from the top-left.
+2. **Write/edit the sidecar** `annotations/<name>.yaml` (same stem as the image).
+   Supported types: `box`, `circle`, `marker` (numbered badge), `arrow`,
+   `highlight`, `text`, `blur` (redaction). Full format + an example are in
+   `annotations/README.md`.
+3. **Preview and verify placement**: run `./annotate.sh`, then Read
+   `build/images/<name>.png` and adjust coordinates until it looks right. Iterate
+   here rather than rebuilding the whole manual each time.
+4. **Rebuild the deliverables** (`./generate.sh` and `./generate-web.sh`) — both
+   apply annotations automatically.
+
+Rendering is `tools/annotate.py` (Pillow + PyYAML). If those libs are missing the
+build falls back to un-annotated images with a warning, so the manual still builds;
+`./install.sh` installs them (`python3-pil`, `python3-yaml`). `annotations/` is the
+source of truth (committed); `build/` is a git-ignored artifact.
+
 ## Conventions
 
 - Chapters are combined in **filename order**; the numeric prefixes (`00-`, `02-`,

README.md

@@ -14,16 +14,19 @@ from a running FPP web UI, and rendered to `.docx` with Pandoc.
 install.sh          Install the build/capture dependencies (Debian/Ubuntu)
 generate.sh         Build FPP_Manual_v10.docx (+ .pdf) from the chapters (no FPP needed)
 generate-web.sh     Build the browsable web edition into web/site/ (no FPP needed)
+annotate.sh         Render annotated screenshots into build/images/ for preview
 capture.sh          (Re)capture screenshots from a running FPP web UI
 metadata.yaml       Title-page metadata for the document
 mkdocs.yml          MkDocs config for the web edition (theme, nav, search)
 OUTLINE.md          Chapter plan / structure
 chapters/           The manual, one Markdown file per chapter (combined in
                     filename order, e.g. 00-*, 02-*, 20-* ...)
-images/             Screenshots referenced by the chapters
+images/             Raw screenshots referenced by the chapters (kept pristine)
+annotations/        Optional YAML sidecars that mark up screenshots (see README there)
 tools/
   build.sh          Pandoc build (invoked by generate.sh)
   build-web.sh      MkDocs build (invoked by generate-web.sh)
+  annotate.py       Bakes annotations/ onto images/ at build time (Pillow)
   shoot.py          Headless-Chromium screenshot driver (Chrome DevTools
                     Protocol; Python standard library only)
   shotlist.txt      The list of pages to screenshot
@@ -78,6 +81,29 @@ Enable it once under **repo Settings → Pages → Build and deployment → Sour
 "GitHub Actions"**; the site then goes live at the `site_url` in `mkdocs.yml`
 (<https://falconchristmas.github.io/fpp-manual-generator/>).
 
+## Annotating screenshots
+
+Screenshots can be marked up with arrows, boxes, numbered callouts, highlights,
+text labels, and blur/redactions — **without touching the raw images**. The raw
+captures in `images/` stay pristine (so `capture.sh` can re-shoot them); the markup
+lives in small YAML sidecars under `annotations/` and is baked on at build time into
+`build/images/`, which the `.docx`, `.pdf`, and web builds all use automatically.
+
+```bash
+# 1. describe the overlays for images/status.png in annotations/status.yaml
+# 2. preview placement:
+./annotate.sh                 # renders build/images/*.png (images/ untouched)
+# 3. rebuild the deliverables (they apply annotations for you):
+./generate.sh
+./generate-web.sh
+```
+
+Coordinates are pixels from the top-left of the source screenshot. The full sidecar
+format, the list of annotation types, and an example are in
+[`annotations/README.md`](annotations/README.md). Rendering needs `python3-pil` and
+`python3-yaml` (installed by `./install.sh`); if they're missing the build falls
+back to un-annotated images with a warning, so the manual still builds.
+
 ## Requirements
 
 - **pandoc** – Markdown → `.docx`.
@@ -86,8 +112,10 @@ Enable it once under **repo Settings → Pages → Build and deployment → Sour
   and skips the PDF (or run `PDF=0 ./generate.sh` to skip it deliberately).
 - **mkdocs-material** – builds the web edition (`./generate-web.sh`). Only needed
   for the web output; the `.docx`/`.pdf` build doesn't use it.
+- **python3-pil** / **python3-yaml** – render the screenshot annotations. Only
+  needed if `annotations/` is used; the build degrades to raw images without them.
 - **chromium** – headless screenshots. Started detached by `shoot.py`.
-- **python3** – build/capture scripts (standard library only; no `pip` needed).
+- **python3** – build/capture scripts.
 - **poppler-utils** – only used when refreshing content from a reference PDF.
 - A **running FPP** reachable over HTTP is required for `capture.sh` (not for
   `generate.sh`).

annotate.sh

@@ -0,0 +1,13 @@
+#!/bin/bash
+# Render annotated screenshots into build/images/ for preview.
+#
+# Annotations live in annotations/<image-stem>.yaml and are drawn onto the raw
+# screenshots from images/. This standalone run is handy for checking placement
+# (render, then open build/images/<name>.png) — but you don't have to run it by
+# hand: generate.sh and generate-web.sh apply annotations automatically.
+#
+# Needs python3-pil + python3-yaml (see ./install.sh).
+set -e
+HERE="$(cd "$(dirname "$0")" && pwd)"
+python3 "$HERE/tools/annotate.py" "$HERE/images" "$HERE/annotations" "$HERE/build/images"
+echo "Annotated images in build/images/ (raw screenshots in images/ are untouched)."

annotations/README.md

@@ -0,0 +1,44 @@
+# Screenshot annotations
+
+Declarative overlays (arrows, boxes, numbered callouts, highlights, redactions)
+for the manual's screenshots. The raw screenshots in `../images/` stay pristine so
+`../capture.sh` can always re-shoot them; annotations are baked on at build time
+into `build/images/` and flow into the `.docx`, `.pdf`, and web outputs.
+
+## How it works
+
+- One YAML sidecar per image, named after the image: `status.yaml` annotates
+  `../images/status.png`. Files without a sidecar are used unchanged.
+- Coordinates are **pixels from the top-left** of the source image. Open the
+  screenshot to read them off (in Claude Code, the Read tool shows the image).
+- Preview with `../annotate.sh` (writes `../build/images/`), then rebuild with
+  `../generate.sh` and/or `../generate-web.sh`. Both apply annotations
+  automatically — `annotate.sh` is only for checking placement.
+
+## Annotation types
+
+| type        | keys                                             | draws |
+|-------------|--------------------------------------------------|-------|
+| `box`       | `at: [x1,y1,x2,y2]`, optional `label`            | rectangle outline (+ numbered badge at the corner if `label`) |
+| `circle`    | `at: [cx,cy]`, `radius`, optional `label`        | circle outline (+ badge at centre if `label`) |
+| `marker`    | `at: [x,y]`, `label`                             | filled numbered callout badge |
+| `arrow`     | `from: [x,y]`, `to: [x,y]`                       | arrow (head at `to`) |
+| `highlight` | `at: [x1,y1,x2,y2]`                              | translucent filled rectangle |
+| `text`      | `at: [x,y]`, `text: "…"`                         | text with a white halo for legibility |
+| `blur`      | `at: [x1,y1,x2,y2]`, optional `radius`           | Gaussian-blur redaction of the region |
+
+Shared optional keys on any annotation: `color` (name like `red`, `#rrggbb`, or
+`[r,g,b]`; default red) and `width` (stroke thickness in px; default auto-scales to
+the image size).
+
+## Example
+
+`status.yaml` (annotating `../images/status.png`):
+
+```yaml
+annotations:
+  - {type: box,    at: [40, 70, 420, 130], color: red, label: "1"}
+  - {type: arrow,  from: [600, 300], to: [470, 150], color: red}
+  - {type: marker, at: [820, 96], label: "2"}
+  - {type: blur,   at: [1150, 20, 1420, 60]}   # hide the hostname/IP
+```

annotations/status.yaml

@@ -0,0 +1,30 @@
+# Annotations for images/status.png (1440 x 1071).
+#
+# This is a WORKED STARTER you can copy for other images. The active annotations
+# below number the six elements of the header bar, matching the numbered list in
+# chapters/20-status-page.md ("The header bar"). Coordinates are pixels from the
+# top-left; read the screenshot to find them (in Claude Code, the Read tool shows
+# the image). Preview with ./annotate.sh, then look at build/images/status.png.
+#
+# Every annotation type is shown as a commented reference at the bottom.
+
+annotations:
+  # Numbered callouts sitting just below each header-bar element (left -> right),
+  # so the elements themselves stay visible.
+  - {type: marker, at: [135, 72],  label: "1"}   # FPP logo + version
+  - {type: marker, at: [993, 72],  label: "2"}   # host name
+  - {type: marker, at: [1063, 72], label: "3"}   # player state
+  - {type: marker, at: [1122, 72], label: "4"}   # sensors (CPU temp)
+  - {type: marker, at: [1240, 72], label: "5"}   # IP addresses
+  - {type: marker, at: [1322, 72], label: "6"}   # time
+
+  # --- Reference: the other annotation types (uncomment / adapt as needed) -----
+  # - {type: box,       at: [x1, y1, x2, y2], color: red, label: "A"}  # outline (+badge)
+  # - {type: circle,    at: [cx, cy], radius: 40, color: "#1e88e5"}    # ring
+  # - {type: arrow,     from: [x1, y1], to: [x2, y2], color: red}      # pointer
+  # - {type: highlight, at: [x1, y1, x2, y2], color: yellow}          # translucent fill
+  # - {type: text,      at: [x, y], text: "Label", color: red}        # haloed caption
+  # - {type: blur,      at: [x1, y1, x2, y2]}                          # redact (hide IP etc.)
+  #
+  # Shared optional keys on any annotation: color (name / #rrggbb / [r,g,b]) and
+  # width (stroke px). See annotations/README.md for the full reference.

chapters/20-status-page.md

@@ -12,11 +12,18 @@ is running in, **Player** or **Remote**, the screen looks a little different.
 
 ## The header bar
 
-The header appears on every page and gives at‑a‑glance status: the FPP **logo**
-and **version** (the version links to the *System Upgrade* page), the **host
-name**, the current **player state**, **sensors** (such as CPU temperature), the
-device's **IP addresses**, and the **time**. *Press F1 for help* opens
-context‑sensitive help for the current page.
+The header appears on every page and gives at‑a‑glance status. The numbered
+callouts above correspond to:
+
+1. **Logo and version** – the FPP logo with the version number beside it; the
+   version links to the *System Upgrade* page.
+2. **Host name** – the device's configured host name.
+3. **Player state** – whether FPP is idle or playing.
+4. **Sensors** – readings such as CPU temperature.
+5. **IP addresses** – the device's active network addresses.
+6. **Time** – the device's current date and time.
+
+*Press F1 for help* (top right) opens context‑sensitive help for the current page.
 
 ## Player Status Page
 

install.sh

@@ -9,7 +9,9 @@
 #   chromium       - headless browser used to screenshot the FPP web UI
 #   poppler-utils  - pdftotext/pdfinfo, used only when refreshing content from a
 #                    reference PDF (optional; safe to keep)
-#   python3        - runs the build and screenshot scripts (standard library only)
+#   python3        - runs the build and screenshot scripts
+#   python3-pil    - Pillow: draws screenshot annotations (annotations/ -> images)
+#   python3-yaml   - reads the annotation sidecar files
 #
 # Works on the FPP OS image (Debian) and other Debian/Ubuntu systems.
 set -e
@@ -20,14 +22,15 @@ if [ "$(id -u)" -ne 0 ]; then SUDO="sudo"; fi
 echo "Updating package lists..."
 $SUDO apt-get update
 
-echo "Installing pandoc, poppler-utils, python3, chromium, libreoffice-writer, mkdocs-material..."
+echo "Installing pandoc, poppler-utils, python3, python3-pil, python3-yaml, chromium, libreoffice-writer, mkdocs-material..."
 # libreoffice-writer (not the full suite) is enough for the headless docx->pdf
 # conversion and is much smaller.
 # mkdocs-material builds the web edition; it pulls in mkdocs itself as a dep.
+# python3-pil (Pillow) + python3-yaml render the screenshot annotations.
 # The Chromium package is named 'chromium' on Debian and 'chromium-browser' on
 # some Ubuntu releases; try both.
-$SUDO apt-get install -y pandoc poppler-utils python3 libreoffice-writer mkdocs-material chromium \
-  || $SUDO apt-get install -y pandoc poppler-utils python3 libreoffice-writer mkdocs-material chromium-browser
+$SUDO apt-get install -y pandoc poppler-utils python3 python3-pil python3-yaml libreoffice-writer mkdocs-material chromium \
+  || $SUDO apt-get install -y pandoc poppler-utils python3 python3-pil python3-yaml libreoffice-writer mkdocs-material chromium-browser
 
 echo
 echo "Install complete."