[flowcool]

Behavior

Document the naming conventions discussed in #24 and the identity findings in #42. The guide explains the current upstream fields, the separate roles of technical names, entity names, MQTT prefixes and label text, and the migration risks for installed devices.

It distinguishes current behavior from a future model with stable device keys, function-only entity names and separate human/screen names. It also explains that normal-page titles still come from the label PNG in upstream. No firmware defaults or existing identities change.

Related to #24 and #42. This does not close the identity implementation findings in #42.

Verification

• Checked package fields and rendering against upstream V2R1 at 90a3be6.
• Checked MQTT discovery formulas and defaults against the installed ESPHome 2026.9.0 source. The guide links that exact source version.
• Sphinx 8.2.3: sphinx-build -W --keep-going -b html docs/source <output> passed.
• Local Markdown links resolve. Existing CRLF line endings in programming.rst are preserved.
• git -c core.whitespace=cr-at-eol diff --check passed. Only three documentation files change.

No compile, deployment or HA registry operation is needed for this documentation change. Revert this commit to remove the guide and its two entry links.

AI assistance

Codex assisted the writing and source checks. The author checked the documented field names, discovery behavior, links, line endings and final diff. No physical validation or maintainer approval is claimed.