Update Fb Docs

Update function block docs

The mechanical parts of docs/FunctionBlocks/*.md are generated from src/Exports/PLCopen.xml, so they cannot drift from the code they document. Two regions per page are machine-owned — never hand-edit inside them:

<!-- fb-badge:start -->      the MQTT Discovery badge, if the block has one
<!-- fb-badge:end -->

<!-- fb-interface:start -->  block diagram, inputs, outputs, methods
<!-- fb-interface:end -->

docs/AdditionalFunctionality/MQTT_General.md has a third, <!-- gvl:start -->, holding the GVL_MQTT global variable list.

Everything else — General, callouts, MQTT behaviour tables, code examples, wiring — is hand-written and left alone.

Commands

Run from the repo root. On Windows use py rather than python3: the python.org build that winget installs ships no python3.exe, and the bare name hits the Microsoft Store alias instead. ./tools/ai/codesys.ps1 doctor reports whether a usable interpreter is present, and the codesys-loop skill has the install command.

--check exits non-zero and names what is stale. Use it to answer "do the docs still match the code?" without touching the working tree.

Where descriptions live

Only 2% of pins carry <documentation> in the export, so descriptions cannot be generated. The generated region is their store. Each run rebuilds the structure from the export and carries existing descriptions across by name:

• a pin or parameter that gains a description keeps it across regenerations
• one that disappears from the code takes its description with it
• a new one arrives as _TODO: describe this._, so gaps are obvious

Two mechanisms cut the amount of hand-writing, both in the script:

• GLOSSARY — descriptions for things that mean the same on every block (pMqttPublishQueue, Device, Invert, DeviceClass…). A page-specific description always wins. This is why a new function block is already documented for all its standard MQTT plumbing the moment it is scaffolded. Key an entry Method.param to scope it, or param to apply anywhere.
• Wildcards — a trailing number is matched by *, so one VALVE_* entry covers VALVE_1 … VALVE_8.

Workflow

1. Confirm the export is current. The script reads PLCopen.xml, not the .project binary. If someone changed a block in CODESYS without re-exporting, the output reflects the export:

   git log -1 --format=%cd -- src/Exports/PLCopen.xml src/HomeAutomation.project

   If the export is behind, say so and stop — regenerating would bake in stale pins. Re-exporting is a manual CODESYS step (see docs/CONTRIBUTING.md).

2. Run the generator, or --check first if only a report is wanted.

3. Deal with what it reports.

   • MISSING DESCRIPTIONS — write them, or add the term to GLOSSARY if it recurs across blocks.
   • ORPHANED — a page has a generated region for a block no longer in the export. Establish which happened before advising: a deliberate removal, or an export taken without the block. Check whether the call sites still reference it — a declared instance points at a bad export, commented-out call sites point at a real removal. Nothing is deleted automatically.
   • HA YAML on a discovery-capable block — blocks that publish discovery configs do not need the hand-written YAML fallback; it is schema-volatile and drifts. Remove the ### **Home Assistant YAML** section.
   • SCAFFOLD DRIFT — see below. Not fixed automatically, and it fails --check.

4. Verify. Re-run with --check; it should pass. Confirm nothing outside the markers moved: git diff -- docs/.