# Field Guide

The guide technicians carry is the PDF:

**`docs/GoodWe-RS485-Field-Guide.pdf`** — 10 pages, A4, print it double-sided.

It covers, in the order the work is done: pre-visit checks, hardware, firmware,
add-on install and configuration, how to read the Web UI, the six commissioning
gates, the e-stop (and the statement a site without one must sign), proving a
maintenance cycle, handover with a sign-off sheet, and troubleshooting.

## Editing it

The text lives in `docs/build_guide.py` — deliberately one source, so a Markdown
copy cannot drift from the PDF someone is holding in a cellar.

```bash
python3 docs/build_guide.py     # regenerates field-guide.html and the PDF
```

Requires Chrome or Chromium (used headless for print-to-PDF). Screenshots live
in `docs/img/` and are base64-embedded, so `field-guide.html` is standalone.

⚠️ **Every section must stay under the A4 printable height** (1039 px at 96 dpi
with the configured margins). Chrome silently spills an over-long section onto a
second page, and the pagination stops matching the step numbers. After editing,
open `field-guide.html` and check:

```js
document.querySelectorAll('.page').forEach(el =>
  console.log(el.getBoundingClientRect().height))   // each must be < 1039
```

The PDF should always come out at exactly **one page per section**.

## Regenerating the screenshots

`docs/img/ui-running.png` and `ui-notready.png` are real captures of the add-on's
own Web UI, taken by running it against stub data. If the UI changes, retake them
— a field guide showing a screen that no longer exists is worse than one with no
screenshots at all.