iobroker.autodoc 0.9.36 → 0.9.37

package/README.md

@@ -4,7 +4,7 @@
 
 Automatically generates structured documentation (HTML, Markdown, JSON) for your ioBroker installation — on demand, on a schedule, or when the system changes.
 
-**Version:** 0.9.36
+**Version:** 0.9.37
 
 | | |
 | --- | --- |
@@ -87,6 +87,15 @@ For **roadmap and planning**: [`TODO.md`](TODO.md) (open work at the top, full c
 
 **Admin `common.news`** in `io-package.json` lists only versions **published on npm** (Adapter Checker **E2004**). The detailed sections below are the **user-facing** changelog (Git-era releases plus npm); older entries are in [`CHANGELOG_OLD.md`](CHANGELOG_OLD.md).
 
+### **WORK IN PROGRESS**
+
+- **Release prep:** Draft user-facing bullets here before **`npm run release`** (`CONTRIBUTING.md`). Open work: **[`TODO.md`](TODO.md)** · **[`PLAN.md`](PLAN.md)** · optional **PR** [ioBroker.repositories](https://github.com/ioBroker/ioBroker.repositories) when ready.
+
+### 0.9.37 (2026-05-10)
+
+- **Tooling:** `runPdfExport` initializes the PDF digest map with a typed empty collection so **`npm run check`** (TypeScript) passes; no change to PDF export behavior.
+- **Docs:** Adapter-neutral **[`docs/iobroker-adapter-references.md`](docs/iobroker-adapter-references.md)** linked from **`TODO.md`**, **`CONTRIBUTING.md`**, and the Cursor project rule; **`PLAN.md`** phase **5.x.1** aligned with **`TODO.md`** (MVP complete).
+
 ### 0.9.36 (2026-05-09)
 
 - **npm / Checker:** tarball **0.9.36** matches **`main`**: **`common.news`** lists only npm-published versions (fixes **E2004** stale metadata from first **0.9.35** publish). README **Version:** line synced; no adapter runtime/UI changes.
@@ -109,21 +118,6 @@ For **roadmap and planning**: [`TODO.md`](TODO.md) (open work at the top, full c
 - **PDF export (Phase 5 — first slice):** optional **`puppeteer`** — **`pdfExportAfterGeneration`** in Admin **Advanced** and/or **`action.exportPdf`**; writes **`autodoc-{admin,user,onboarding}.pdf`** alongside HTML under **`/files/`** and mirrors to **Filesystem export path** when set (`lib/htmlToPdf.js`). Same Chromium sandbox flags as Mermaid CLI. Without **`puppeteer`** or on broken headless setups, PDF is skipped; core documentation generation continues.
 - **Admin:** **`jsonConfig`** + **i18n** (EN/DE/FR + English copy elsewhere) for PDF options and extended **export path** hint.
 
-### 0.9.32 (2026-05-08)
-
-- **Documentation for operators:** new **`docs/user-guide/`** — [English README](docs/user-guide/README.md) plus [German scenario walkthrough](docs/user-guide/README.de.md); SVG wireframes and notes for replacing them with screenshots.
-- **Admin UI (`jsonConfig` + i18n):** extended help for **Mermaid** (CDN vs bundled, curated vs auto topology fields), **`documentation.exportHashes`**, documentation **states storage** (`full` vs `metadata`); **placeholders** on long JSON/manual fields where helpful; AI tab trims visible noise when provider is **`none`** or scripts are unchecked.
-- **Repository hygiene:** **`dev` merged into `main`** as default line; **`common.extIcon`** raw URL and Admin **guide links** in i18n use **`main`**; **PNG icon** refreshed (512×512).
-- **CI / tooling:** GitHub **`test-and-release.yml`** concurrency block matches **ioBroker.example** (Adapter Checker **E3009**); **`tsconfig`** / **`tsconfig.check`** exclude accidental local bootstrap paths (`iobroker-data/`, installer stubs) — aligns with ESLint ignores; **`guestHelpContent`** ESLint tidy.
-- **Docs assets:** guide SVG markup fixed so **GitHub’s preview** no longer rejects them as invalid images.
-
-### 0.9.31 (2026-05-07)
-
-- **Score 3 "Dokumentationstiefe" rework:** removed the "instances without room" check entirely from all scores (caused confusion, too many legitimate exceptions). Replaced with two new checks: **"custom documentation chapter has content"** and **"AI provider configured for script enrichment"** (conditional — only shown when scripts exist, auto-passes when no scripts are present).
-- `DEFAULT_UNASSIGNED_INSTANCE_WARN_AT` constant removed; `maintenanceScoreCheckUnassigned` and `maintenanceScoreUnassignedWarnAt` config fields are now unused in score logic (kept in admin config for backward compatibility but have no effect).
-- i18n EN/DE/FR: new keys `checkHasCustomSections`, `checkAiConfigured`, `checkInstancesWithoutRoomInfo`.
-- **Dev / CI (npm):** optional **Mermaid CLI** toolchain + striktes `npm ci` auf Linux (Node 24) — **`package.json` → `overrides`** (`chromium-bidi` → `devtools-protocol@0.0.1107588`) und **devDependencies** `cytoscape`, `d3-selection`, `devtools-protocol`, damit `package-lock.json` vollständig bleibt. Nach Dependency-Änderungen: `npm install` und Lock mit committen (`CONTRIBUTING.md`).
-
 ## License
 
 MIT License

package/admin/i18n/de.json

@@ -1,7 +1,7 @@
 {
 	"autodoc adapter settings": "Adaptereinstellungen für autodoc",
 	"Project name": "Projektname",
-	"Name of the ioBroker project or installation": "Name des ioBroker-Projekts oder der Installation",
+	"Name of the ioBroker project or installation. Shown in exports and notifications. Example: **Demo home** or **Musterhaus Schulweg** (use fictional labels in public screenshots).": "Name des ioBroker-Projekts oder der Installation. Erscheint in Exporten und Benachrichtigungen. Beispiel: **Demo-Zuhause** oder **Musterhaus Schulweg** (fiktive Namen in öffentlichen Screenshots).",
 	"Target system": "Zielsystem",
 	"Usually ioBroker": "Normalerweise ioBroker",
 	"Documentation profile": "Dokumentationsprofil",
@@ -13,6 +13,7 @@
 	"Target audience for Markdown export and default focus. HTML always includes all three profiles (admin, user, onboarding). AI text for User/Onboarding HTML runs whenever a KI provider is set, regardless of this selection.": "Zielgruppe für den Markdown-Export und Standard-Fokus. HTML enthält immer alle drei Profile (Admin, User, Onboarding). KI-Text für User-/Onboarding-HTML wird ausgeführt, sobald ein KI-Anbieter gesetzt ist — unabhängig von dieser Auswahl.",
 	"Project description": "Projektbeschreibung",
 	"Short description of what should be documented": "Kurze Beschreibung dessen, was dokumentiert werden soll",
+	"What does this system do? e.g. 'Single-family home, heating + lighting + security on 3 floors'. Counts toward the optional **documentation setup score** when that row is enabled (Advanced tab — minimum description length).": "Was macht dieses System? z. B. „Einfamilienhaus, Heizung + Licht + Sicherheit auf 3 Etagen“. Zählt für den optionalen **Doku-Setup-Score**, wenn die Zeile aktiv ist (Tab **Erweitert** — Mindestlänge der Beschreibung).",
 	"Additional notes": "Zusätzliche Hinweise",
 	"Optional notes, devices, adapters or special requirements": "Optionale Hinweise, Geräte, Adapter oder besondere Anforderungen",
 	"Generate documentation on adapter start": "Dokumentation beim Start des Adapters erzeugen",
@@ -22,7 +23,7 @@
 	"Read live state values (opt-in)": "Live-Statuswerte lesen (opt-in)",
 	"If enabled, current values for selected state roles are read and shown in User/Onboarding room cards and the Admin device table (badges next to device names). Includes e.g. temperature, blinds (level.blind), dimmers, lights (switch.light), outlets (switch/plug), humidity, power metrics, locks, door/window/contact, motion, alarm. Room members may be channels or devices — matching child states are found automatically. Very custom or empty roles are skipped.": "Wenn aktiviert, werden aktuelle Werte ausgewählter State-Rollen gelesen und in User-/Onboarding-Raumkarten sowie in der Admin-Gerätetabelle angezeigt (Badges neben Gerätenamen). U. a. Temperatur, Rollläden (level.blind), Dimmer, Licht (switch.light), Steckdosen (switch/plug), Luftfeuchtigkeit, Leistungskennzahlen, Schlösser, Tür-/Fenster-/Kontakt, Bewegung, Alarm. Raum-Mitglieder können Kanäle oder Geräte sein — passende Unter-States werden automatisch ermittelt. Sehr spezielle oder leere Roles werden übersprungen.",
 	"Scheduled interval (hours)": "Zeitplan: Intervall (Stunden)",
-	"Optional timer: regenerate every X hours, independent of start and adapter-change options above. 0 = no scheduled runs (events and start still work).": "Optional: zusätzlich alle X Stunden neu erzeugen — unabhängig von Start und „bei Adapteränderungen“ oben. 0 = kein Stunden-Zeitplan (Start und Ereignisse funktionieren trotzdem).",
+	"Optional timer: regenerate every X hours, independent of start and adapter-change options above. 0 = no scheduled runs (events and start still work). Example: **24** = about once per day.": "Optional: zusätzlich alle X Stunden neu erzeugen — unabhängig von Start und „bei Adapteränderungen“ oben. 0 = kein Stunden-Zeitplan (Start und Ereignisse funktionieren trotzdem). Beispiel: **24** ≈ einmal pro Tag.",
 	"Only document enabled instances": "Nur aktivierte Instanzen dokumentieren",
 	"If enabled, only active adapter instances are included in the documentation": "Wenn aktiviert, werden nur aktive Adapter-Instanzen in die Dokumentation aufgenommen",
 	"Hide instance details in markdown": "Instanzdetails im Markdown ausblenden",
@@ -30,11 +31,11 @@
 	"Maximum documented instances": "Maximale Anzahl dokumentierter Instanzen",
 	"Limits how many adapter instances are included in the generated documentation, 0 means unlimited": "Begrenzt, wie viele Adapter-Instanzen in die erzeugte Dokumentation aufgenommen werden, 0 bedeutet unbegrenzt",
 	"ioBroker base URL (optional)": "ioBroker Basis-URL (optional)",
-	"Used for the info.htmlUrl state. Include port, e.g. 192.168.1.100:8081 or http://myserver:8082. Protocol is optional. Leave empty for auto-detection (may fail in Docker).": "Wird für den info.htmlUrl-State verwendet. Port angeben, z.B. 192.168.1.100:8081 oder http://myserver:8082. Protokoll ist optional. Leer lassen für automatische Erkennung (kann in Docker fehlschlagen).",
+	"Used for the info.htmlUrl state and bookmark/QR targets. Include **host and port**, e.g. **http://192.168.1.100:8081** or **https://iobroker.home:443** — **no trailing slash**. Protocol is optional. Leave empty for auto-detection (may fail in Docker).": "Für den State **info.htmlUrl** sowie Lesezeichen- und QR-Ziele. **Hostname und Port** angeben, z. B. **http://192.168.1.100:8081** oder **https://iobroker.home:443** — **ohne** abschließenden **/**. Protokoll optional. Leer lassen für automatische Erkennung (kann in Docker fehlschlagen).",
 	"Maximum stored documentation files": "Maximale Anzahl gespeicherter Dokumentationsdateien",
 	"How many timestamped file sets to keep (per type: .md, .html, .json). Oldest are deleted automatically. 0 = use default (3).": "Wie viele Dateisätze mit Zeitstempel behalten werden sollen (je Typ: .md, .html, .json). Älteste werden automatisch gelöscht. 0 = Standard (3).",
 	"Documentation states storage": "Dokumentation in States",
-	"Documentation states storage help": "Vollständig: Markdown, HTML und JSON zusätzlich in Adapter-States (bisheriges Verhalten, größere Objekt-DB / Redis). Nur Metadaten: vollständige Exporte nur unter Dateien (autodoc-latest.*); States enthalten einen kurzen Platzhalter — schont die Datenbank. Skripte, die documentation.* als Volltext lesen, müssen auf /files/ oder HTTP-URLs umstellen. Download-Aktionen schreiben autodoc.md / .json / .html weiterhin aus den neuesten Dateien. In beiden Modi enthält **`documentation.exportHashes`** **SHA-256**-Prüfsummen (hex) der aktuellen MD-/HTML-/JSON-Exporte zur Änderungserkennung. **Nach erfolgreichem PDF-Export** (optional **`puppeteer`**) enthält derselbe State auch Prüfsummen für **`autodoc-admin.pdf`**, **`autodoc-user.pdf`** und **`autodoc-onboarding.pdf`**, sobald diese Dateien geschrieben wurden.",
+	"Documentation states storage help": "Vollständig: Markdown, HTML und JSON zusätzlich in Adapter-States (bisheriges Verhalten, größere Objekt-DB / Redis). Nur Metadaten: vollständige Exporte nur unter Dateien (autodoc-latest.*); States enthalten einen kurzen Platzhalter — schont die Datenbank. Skripte, die documentation.* als Volltext lesen, müssen auf /files/ oder HTTP-URLs umstellen. Download-Aktionen schreiben autodoc.md / .json / .html weiterhin aus den neuesten Dateien. In beiden Modi enthält **`documentation.exportHashes`** **SHA-256**-Prüfsummen (hex) der aktuellen MD-/HTML-/JSON-Exporte zur Änderungserkennung. **Nach erfolgreichem PDF-Export** (optional **`puppeteer`**) enthält derselbe State auch Prüfsummen für **`autodoc-admin.pdf`**, **`autodoc-user.pdf`** und **`autodoc-onboarding.pdf`**, sobald diese Dateien geschrieben wurden. **Tipp:** **Nur Metadaten** wählen, wenn die Objekt-DB / Redis klein bleiben soll; **Vollständig** behalten, wenn ältere Integrationen Volltext aus `documentation.*` lesen.",
 	"Doc states mode full": "Vollständig (in States — größere DB)",
 	"Doc states mode metadata": "Nur Metadaten (Inhalt nur in /files)",
 	"Manual context (JSON)": "Manueller Kontext (JSON)",
@@ -104,16 +105,15 @@
 	"Contact person": "Ansprechpartner",
 	"Who manages this system? e.g. 'Max Mustermann, Telegram @max' - shown so guests and family know who to ask": "Wer verwaltet dieses System? z.B. 'Max Mustermann, Telegram @max' - wird angezeigt damit Gäste und Familie wissen, wen sie fragen können",
 	"General notes": "Allgemeine Hinweise",
-	"Anything that doesn't fit elsewhere: e.g. 'Backup runs every Sunday, server is in the basement'": "Alles was sonst nirgends passt: z.B. 'Backup läuft jeden Sonntag, Server ist im Keller'",
-	"What does this system do? e.g. 'Single-family home, heating + lighting + security on 3 floors'": "Was macht dieses System? z.B. 'Einfamilienhaus, Heizung + Licht + Sicherheit auf 3 Etagen'",
+	"Anything that doesn't fit elsewhere: e.g. 'Backup runs every Sunday, server is in the basement' — same field for maintenance windows, NAS paths, or hardware quirks.": "Alles, was sonst nirgends passt: z. B. „Backup läuft jeden Sonntag, Server ist im Keller“ — dasselbe Feld auch für Wartungsfenster, NAS-Pfade oder Hardware-Ausnahmen.",
 	"Per-adapter notes": "Adapter-Notizen",
 	"Adapter notes": "Adapter-Notizen",
-	"Add a human-readable note for specific adapters (shown in all profiles)": "Menschenlesbare Notiz für bestimmte Adapter hinzufügen (wird in allen Profilen angezeigt)",
+	"Add a human-readable note for specific adapters (shown in all profiles). Table row example: adapter **hue** — note **Living room scenes — wall switch overrides.**": "Menschenlesbare Notiz für bestimmte Adapter (alle Profile). Tabellenbeispiel: Adapter **hue** — Notiz **Wohnzimmer-Szenen — Wandschalter hat Vorrang.**",
 	"Adapter (e.g. telegram)": "Adapter (z.B. telegram)",
 	"Note": "Notiz",
 	"Per-room notes": "Raum-Notizen",
 	"Room notes": "Raum-Notizen",
-	"Add a human-readable note for specific rooms (shown in User and Onboarding profiles)": "Menschenlesbare Notiz für bestimmte Räume hinzufügen (wird in User- und Onboarding-Profil angezeigt)",
+	"Add a human-readable note for specific rooms (shown in User and Onboarding profiles). Example: room **Kitchen** — note **Gas shutoff — left of sink.**": "Menschenlesbare Notiz für bestimmte Räume (User- und Onboarding-Profil). Beispiel: Raum **Küche** — Notiz **Gas-Abstellhahn — links neben Spüle.**",
 	"Room name": "Raumname",
 	"Generate now hint": "Klicke den Button, um die Dokumentation sofort zu generieren – ohne den Adapter neu starten zu müssen. Alle drei Profile (Admin, User, Onboarding) werden gleichzeitig erstellt.",
 	"Generate documentation now": "Dokumentation jetzt generieren",
@@ -155,11 +155,11 @@
 	"Send notification after documentation generation": "Benachrichtigung nach Dokumentationsgenerierung senden",
 	"If enabled, a message is sent via the configured adapter after each generation": "Wenn aktiviert, wird nach jeder Generierung eine Nachricht über den konfigurierten Adapter gesendet",
 	"Messaging adapter instance": "Messaging-Adapter-Instanz",
-	"Instance to send the notification through, e.g. telegram.0, pushover.0, email.0": "Instanz, über die die Benachrichtigung gesendet wird, z.B. telegram.0, pushover.0, email.0",
+	"Instance to send the notification through, e.g. telegram.0, pushover.0, email.0, signal.0": "Instanz für den Versand, z. B. telegram.0, pushover.0, email.0, signal.0",
 	"Recipient (optional)": "Empfänger (optional)",
-	"Telegram username, Pushover device, or email address — leave empty for adapter default": "Telegram-Benutzername, Pushover-Gerät oder E-Mail-Adresse — leer lassen für Adapter-Standard",
+	"Telegram username, Pushover device, or email address - leave empty for adapter default. Examples: Telegram **@nickname**, email **ops@example.com**, Pushover device **phone**.": "Telegram-Benutzername, Pushover-Gerät oder E-Mail-Adresse — leer lassen für Adapter-Standard. Beispiele: Telegram **@nickname**, E-Mail **ops@example.com**, Pushover-Gerät **phone**.",
 	"Custom message template (optional)": "Eigene Nachrichtenvorlage (optional)",
-	"Use {project}, {summary}, {version}, {trigger} as placeholders. Leave empty for default message.": "Platzhalter: {project}, {summary}, {version}, {trigger}. Leer lassen für Standardnachricht.",
+	"Use {project}, {summary}, {version}, {trigger} as placeholders. Leave empty for default message. Example: **{project} — documentation updated ({trigger}). {summary}**": "Platzhalter: {project}, {summary}, {version}, {trigger}. Leer lassen für Standardnachricht. Beispiel: **{project} — Dokumentation aktualisiert ({trigger}). {summary}**",
 	"AI-Enhanced Documentation": "KI-gestützte Dokumentation",
 	"AI provider": "KI-Anbieter",
 	"Select an AI provider for narrative summaries. Disabled for admin profile (all data is already factual). Not used for admin profile.": "KI-Anbieter für narrative Zusammenfassungen. Wird beim Admin-Profil nicht verwendet (alle Daten sind bereits faktisch).",
@@ -192,7 +192,7 @@
 	"AI context hints": "KI-Kontexthinweise",
 	"AI context hints (owner notes)": "KI-Kontexthinweise (Betreibernotizen)",
 	"AI context hints hint": "Optionale Stichpunkte über das Zuhause für die KI — fließen nur in den KI-Prompt, erscheinen nie in der Dokumentation. Beispiel: '- Licht im Wohnzimmer geht um 22:00 automatisch aus', '- Gäste können Temperatur per Sprachassistent steuern'. Je konkreter, desto besser die KI-Textqualität. — **Gast-Onboarding:** Formulieren Sie Fakten möglichst in Alltagssprache (z. B. „hier wird noch eingerichtet“, „Dokumentation wird ergänzt“). Schreiben Sie dagegen viel IT-/Projekt-Jargon (z. B. „Adapter“, „Repository“, „nicht im Repo“), kann das Modell das wörtlich in den Gasttext übernehmen. Dann ersetzt ein **Sicherheitsfilter** den KI-Gasttext durch einen neutralen Standard — damit Gäste keinen Technik-Wortlaut lesen. Das Verhalten ist so beabsichtigt und lässt sich nicht sinnvoll lockern, ohne den Gästeschutz aufzuweichen. Im **Bewohner-/Familienprofil** gilt diese Einschränkung nicht.",
-	"AI context hints help": "Kurze Stichpunkte, die nur die KI sieht — nicht in der exportierten Dokumentation. Datenschutz: Text wird an den konfigurierten KI-Anbieter gesendet. — **Gastprofil:** Siehe den längeren Infotext oben: technische Wortwahl in den Kontexthinweisen kann den KI-Text für Gäste verworfen und durch Neutraltext ersetzen.",
+	"AI context hints help": "Kurze Stichpunkte, die nur die KI sieht — nicht in der exportierten Dokumentation. Datenschutz: Text wird an den konfigurierten KI-Anbieter gesendet. — **Gastprofil:** Siehe den längeren Infotext oben: technische Wortwahl in den Kontexthinweisen kann den KI-Text für Gäste verworfen und durch Neutraltext ersetzen. Mini-Beispiel: **`- Staubsauger-Roboter pausiert, wenn „Abwesend“ aktiv ist`** — konkrete Fakten schlagen vage Sätze.",
 	"HTML export & extra sections": "HTML-Export & Zusatzkapitel",
 	"Doc layout intro": "Feintuning für generiertes **HTML** (alle drei Profile): festes Hell/Dunkel, ein **Farb-Preset** (ohne rohes CSS), Logo und eigene Markdown-Kapitel. **Schrift** und **zusätzliches CSS** stehen **am Ende** dieses Tabs (nach Sichtbarkeit und eigenen Kapiteln) und sind **optional**. **Kapitelreihenfolge** und **Ausblenden** für das **Admin**-Profil gelten für Admin-HTML und Markdown, wenn das Dokumentationsprofil **Admin** ist. **Ausblenden** für **User/Familie** und **Onboarding** steht **darunter** auf diesem Tab und wirkt auf die jeweiligen HTML-Exporte und das Markdown bei entsprechend gewähltem Profil (z. B. Kapitel-Id `ownerPlaybook`). Zusatzkapitel erscheinen im Markdown mit.",
 	"Doc layout pdf hint": "**PDF-Export:** Einstellungen unter **Erweitert** (unter dem Dateisystem-Exportpfad): optional **PDF nach jedem Lauf**, oder jederzeit per State **`action.exportPdf`** auslösen. Benötigt optional **`puppeteer`** im Adapterordner. Schreibt **`autodoc-{admin,user,onboarding}.pdf`** unter Adapter-**Dateien** und spiegelt sie bei gesetztem Exportpfad mit.",
@@ -210,11 +210,11 @@
 	"HTML theme preset warm": "Warm",
 	"HTML theme preset slate": "Slate",
 	"Sidebar logo URL": "Logo-URL (Seitenleiste)",
-	"Sidebar logo URL help": "Optionales Bild über der Suche im exportierten HTML. **https://…** oder ein Pfad ab **/** (z. B. Datei unter ioBroker `/files/…`). Andere Schemata werden ignoriert.",
+	"Sidebar logo URL help": "Optionales Bild über der Suche im exportierten HTML. **https://…** oder ein Pfad ab **/** — z. B. **`/files/autodoc.0/logo.png`**, nachdem du ein Logo unter Dateien abgelegt hast. Andere Schemata werden ignoriert.",
 	"Font stack (CSS)": "Schrift (CSS font-family)",
 	"Font stack help": "Optionaler `font-family`-Wert, z. B. `Georgia, serif` oder `system-ui, sans-serif`. Zeichen `< > { }` werden aus Sicherheitsgründen entfernt.",
 	"Extra CSS": "Zusätzliches CSS",
-	"Extra CSS help": "Wird an den HTML-`<style>`-Block angehängt (Farben, Abstände). Nur vertrauenswürdige Inhalte einfügen. Kein `</style>` in diesem Feld. Lieber wenige, gezielte Regeln — zu breite Selektoren können nach Updates unerwartete Effekte haben.",
+	"Extra CSS help": "Wird an den HTML-`<style>`-Block angehängt (Farben, Abstände). Nur vertrauenswürdige Inhalte einfügen. Kein `</style>` in diesem Feld. Lieber wenige, gezielte Regeln — zu breite Selektoren können nach Updates unerwartete Effekte haben. Mini-Beispiel: **`a.doc-nav-link:hover { opacity: 0.85; }`** — Variablen wie **`var(--accent)`** aus dem Preset bevorzugen.",
 	"Admin HTML — hide chapters": "Admin-HTML — Kapitel ausblenden",
 	"Admin chapter order hint": "Optional: **Reihenfolge** für **Admin**-HTML und **Admin**-Markdown (Inhaltsverzeichnis + Fließtext) im **ersten** JSON-Feld eintragen (`[]` = eingebaute Reihenfolge). Fehlende Kapitel hängt AutoDoc in **Standard**-Reihenfolge hinten an. **Die vollständige Liste gültiger englischer Kapitel-Ids** steht **nur** in der **Hilfe** dieses Feldes (Tooltip/`?`) — hier nicht wiederholt.",
 	"Admin chapter order (JSON array)": "Reihenfolge Admin-Kapitel (JSON-Array)",
@@ -229,14 +229,14 @@
 	"User/Family HTML — hide chapters": "User/Familie-HTML — Kapitel ausblenden",
 	"User hidden chapters hint": "JSON-Array von Kapitel-Ids für **User/Familie**-HTML und **Markdown** (Profil User). Erlaubt: `manual`, `ai`, `guestHelp`, `atAGlance`, `rooms`, `scripts`, `routines`, `ownerPlaybook`, `mermaid` (manuelles Mermaid-Diagramm), `mermaidAuto` (automatisches Host-Topologie-Diagramm — im Onboarding nie sichtbar), `adapters`, `custom`, `system`, `troubleshooting`.",
 	"User profile — hidden chapter IDs (JSON)": "User-Profil — ausgeblendete Kapitel (JSON)",
-	"User hidden chapters JSON help": "JSON-Array aus Strings. Leer `[]` = alles anzeigen.",
+	"User hidden chapters JSON help": "JSON-Array aus Strings, z. B. `[\"scripts\",\"adapters\"]`. Ungültige Ids werden ignoriert. Leer `[]` = alles anzeigen.",
 	"User chapter order hint": "Optional: Reihenfolge der **User/Familie**-HTML-Kapitel und des **User**-Markdowns anpassen. **Gültige Ids:** `manual`, `ai`, `guestHelp`, `atAGlance`, `rooms`, `scripts`, `routines`, `ownerPlaybook`, `mermaid`, `adapters`, `custom`, `system`, `troubleshooting` – ungenannte Ids werden in Standardreihenfolge angehängt. Leer `[]` = Standardreihenfolge.",
 	"User chapter order (JSON array)": "Reihenfolge User-Kapitel (JSON-Array)",
 	"User chapter order JSON help": "JSON-Array mit Zeichenketten, z. B. `[\"atAGlance\",\"rooms\",\"manual\",\"adapters\"]`. **Gültige Ids:** `manual`, `ai`, `guestHelp`, `atAGlance`, `rooms`, `scripts`, `routines`, `ownerPlaybook`, `mermaid`, `adapters`, `custom`, `system`, `troubleshooting`. Unbekannte Ids ignoriert; fehlende Ids am Ende in Standardreihenfolge. `[]` = eingebaute Reihenfolge.",
 	"Onboarding HTML — hide chapters": "Onboarding-HTML — Kapitel ausblenden",
 	"Onboarding hidden chapters hint": "Blöcke im **Onboarding**-HTML und passende Teile im **Markdown** (Profil Onboarding) ausblenden. Ids: `welcome`, `tips`, `guestHelp`, `stats`, `ai`, `capabilities`, `mermaid` (Diagramm im Begrüßungsbereich), `rooms`, `routines`, `ownerPlaybook`, `automations`, `adapters`, `custom`, `hint`, zusätzlich für Markdown `quickstart`, `system`, `manual`.",
 	"Onboarding profile — hidden chapter IDs (JSON)": "Onboarding-Profil — ausgeblendete Kapitel (JSON)",
-	"Onboarding hidden chapters JSON help": "JSON-Array aus Strings. Leer `[]` = alles anzeigen.",
+	"Onboarding hidden chapters JSON help": "JSON-Array aus Strings, z. B. `[\"adapters\",\"stats\"]`. Ungültige Ids werden ignoriert. Leer `[]` = alles anzeigen.",
 	"Onboarding chapter order hint": "Optional: Reihenfolge der **Onboarding/Gast**-HTML-Kapitel und des **Onboarding**-Markdowns anpassen. **Gültige Ids:** `welcome`, `quickstart`, `tips`, `guestHelp`, `stats`, `ai`, `capabilities`, `mermaid`, `rooms`, `routines`, `ownerPlaybook`, `automations`, `adapters`, `custom`, `hint`, `system`, `manual` – ungenannte Ids werden angehängt. Leer `[]` = Standardreihenfolge.",
 	"Onboarding chapter order (JSON array)": "Reihenfolge Onboarding-Kapitel (JSON-Array)",
 	"Onboarding chapter order JSON help": "JSON-Array mit Zeichenketten, z. B. `[\"quickstart\",\"tips\",\"rooms\",\"adapters\"]`. **Gültige Ids:** `welcome`, `quickstart`, `tips`, `guestHelp`, `stats`, `ai`, `capabilities`, `mermaid`, `rooms`, `routines`, `ownerPlaybook`, `automations`, `adapters`, `custom`, `hint`, `system`, `manual`. Unbekannte Ids ignoriert; fehlende Ids am Ende. `[]` = eingebaute Reihenfolge.",

package/admin/i18n/en.json

@@ -1,7 +1,7 @@
 {
 	"autodoc adapter settings": "Adapter settings for autodoc",
 	"Project name": "Project name",
-	"Name of the ioBroker project or installation": "Name of the ioBroker project or installation",
+	"Name of the ioBroker project or installation. Shown in exports and notifications. Example: **Demo home** or **Musterhaus Schulweg** (use fictional labels in public screenshots).": "Name of the ioBroker project or installation. Shown in exports and notifications. Example: **Demo home** or **Musterhaus Schulweg** (use fictional labels in public screenshots).",
 	"Target system": "Target system",
 	"Usually ioBroker": "Usually ioBroker",
 	"Documentation profile": "Documentation profile",
@@ -13,6 +13,7 @@
 	"Target audience for Markdown export and default focus. HTML always includes all three profiles (admin, user, onboarding). AI text for User/Onboarding HTML runs whenever a KI provider is set, regardless of this selection.": "Target audience for Markdown export and default focus. HTML always includes all three profiles (admin, user, onboarding). AI text for User/Onboarding HTML runs whenever a KI provider is set, regardless of this selection.",
 	"Project description": "Project description",
 	"Short description of what should be documented": "Short description of what should be documented",
+	"What does this system do? e.g. 'Single-family home, heating + lighting + security on 3 floors'. Counts toward the optional **documentation setup score** when that row is enabled (Advanced tab — minimum description length).": "What does this system do? e.g. 'Single-family home, heating + lighting + security on 3 floors'. Counts toward the optional **documentation setup score** when that row is enabled (Advanced tab — minimum description length).",
 	"Additional notes": "Additional notes",
 	"Optional notes, devices, adapters or special requirements": "Optional notes, devices, adapters or special requirements",
 	"Generate documentation on adapter start": "Generate documentation on adapter start",
@@ -22,7 +23,7 @@
 	"Read live state values (opt-in)": "Read live state values (opt-in)",
 	"If enabled, current values for selected state roles are read and shown in User/Onboarding room cards and the Admin device table (badges next to device names). Includes e.g. temperature, blinds (level.blind), dimmers, lights (switch.light), outlets (switch/plug), humidity, power metrics, locks, door/window/contact, motion, alarm. Room members may be channels or devices — matching child states are found automatically. Very custom or empty roles are skipped.": "If enabled, current values for selected state roles are read and shown in User/Onboarding room cards and the Admin device table (badges next to device names). Includes e.g. temperature, blinds (level.blind), dimmers, lights (switch.light), outlets (switch/plug), humidity, power metrics, locks, door/window/contact, motion, alarm. Room members may be channels or devices — matching child states are found automatically. Very custom or empty roles are skipped.",
 	"Scheduled interval (hours)": "Scheduled interval (hours)",
-	"Optional timer: regenerate every X hours, independent of start and adapter-change options above. 0 = no scheduled runs (events and start still work).": "Optional timer: regenerate every X hours, independent of start and adapter-change options above. 0 = no scheduled runs (events and start still work).",
+	"Optional timer: regenerate every X hours, independent of start and adapter-change options above. 0 = no scheduled runs (events and start still work). Example: **24** = about once per day.": "Optional timer: regenerate every X hours, independent of start and adapter-change options above. 0 = no scheduled runs (events and start still work). Example: **24** = about once per day.",
 	"Only document enabled instances": "Only document enabled instances",
 	"If enabled, only active adapter instances are included in the documentation": "If enabled, only active adapter instances are included in the documentation",
 	"Hide instance details in markdown": "Hide instance details in markdown",
@@ -30,11 +31,11 @@
 	"Maximum documented instances": "Maximum documented instances",
 	"Limits how many adapter instances are included in the generated documentation, 0 means unlimited": "Limits how many adapter instances are included in the generated documentation, 0 means unlimited",
 	"ioBroker base URL (optional)": "ioBroker base URL (optional)",
-	"Used for the info.htmlUrl state. Include port, e.g. 192.168.1.100:8081 or http://myserver:8082. Protocol is optional. Leave empty for auto-detection (may fail in Docker).": "Used for the info.htmlUrl state. Include port, e.g. 192.168.1.100:8081 or http://myserver:8082. Protocol is optional. Leave empty for auto-detection (may fail in Docker).",
+	"Used for the info.htmlUrl state and bookmark/QR targets. Include **host and port**, e.g. **http://192.168.1.100:8081** or **https://iobroker.home:443** — **no trailing slash**. Protocol is optional. Leave empty for auto-detection (may fail in Docker).": "Used for the info.htmlUrl state and bookmark/QR targets. Include **host and port**, e.g. **http://192.168.1.100:8081** or **https://iobroker.home:443** — **no trailing slash**. Protocol is optional. Leave empty for auto-detection (may fail in Docker).",
 	"Maximum stored documentation files": "Maximum stored documentation files",
 	"How many timestamped file sets to keep (per type: .md, .html, .json). Oldest are deleted automatically. 0 = use default (3).": "How many timestamped file sets to keep (per type: .md, .html, .json). Oldest are deleted automatically. 0 = use default (3).",
 	"Documentation states storage": "Documentation states storage",
-	"Documentation states storage help": "Full: duplicate markdown, HTML, and JSON in adapter states (legacy, larger object DB / Redis). Metadata only: keep full exports only under Files (autodoc-latest.*); states hold a short placeholder — reduces database size. Scripts that read documentation.* for full text must use /files/ or HTTP URLs instead. Download actions still write autodoc.md / .json / .html from the latest files. In both modes **`documentation.exportHashes`** stores **SHA-256 (hex)** digests of the latest MD / Admin HTML / JSON exports for change detection. **After a successful PDF export** (optional `puppeteer`), the same state also includes **`autodoc-admin.pdf`**, **`autodoc-user.pdf`**, and **`autodoc-onboarding.pdf`** digests when those files are written.",
+	"Documentation states storage help": "Full: duplicate markdown, HTML, and JSON in adapter states (legacy, larger object DB / Redis). Metadata only: keep full exports only under Files (autodoc-latest.*); states hold a short placeholder — reduces database size. Scripts that read documentation.* for full text must use /files/ or HTTP URLs instead. Download actions still write autodoc.md / .json / .html from the latest files. In both modes **`documentation.exportHashes`** stores **SHA-256 (hex)** digests of the latest MD / Admin HTML / JSON exports for change detection. **After a successful PDF export** (optional `puppeteer`), the same state also includes **`autodoc-admin.pdf`**, **`autodoc-user.pdf`**, and **`autodoc-onboarding.pdf`** digests when those files are written. **Tip:** try **Metadata only** when object DB / Redis size matters; keep **Full** if older integrations read full text from `documentation.*` states.",
 	"Doc states mode full": "Full (in states — larger DB)",
 	"Doc states mode metadata": "Metadata only (content in /files only)",
 	"Manual context (JSON)": "Manual context (JSON)",
@@ -103,14 +104,15 @@
 	"Who manages this system? e.g. 'Max Mustermann, Telegram @max' - shown so guests and family know who to ask": "Who manages this system? e.g. 'Max Mustermann, Telegram @max' - shown so guests and family know who to ask",
 	"General notes": "General notes",
 	"General notes about this installation (e.g. special setups, known issues)": "General notes about this installation (e.g. special setups, known issues)",
+	"Anything that doesn't fit elsewhere: e.g. 'Backup runs every Sunday, server is in the basement' — same field for maintenance windows, NAS paths, or hardware quirks.": "Anything that doesn't fit elsewhere: e.g. 'Backup runs every Sunday, server is in the basement' — same field for maintenance windows, NAS paths, or hardware quirks.",
 	"Per-adapter notes": "Per-adapter notes",
 	"Adapter notes": "Adapter notes",
-	"Add a human-readable note for specific adapters (shown in all profiles)": "Add a human-readable note for specific adapters (shown in all profiles)",
+	"Add a human-readable note for specific adapters (shown in all profiles). Table row example: adapter **hue** — note **Living room scenes — wall switch overrides.**": "Add a human-readable note for specific adapters (shown in all profiles). Table row example: adapter **hue** — note **Living room scenes — wall switch overrides.**",
 	"Adapter (e.g. telegram)": "Adapter (e.g. telegram)",
 	"Note": "Note",
 	"Per-room notes": "Per-room notes",
 	"Room notes": "Room notes",
-	"Add a human-readable note for specific rooms (shown in User and Onboarding profiles)": "Add a human-readable note for specific rooms (shown in User and Onboarding profiles)",
+	"Add a human-readable note for specific rooms (shown in User and Onboarding profiles). Example: room **Kitchen** — note **Gas shutoff — left of sink.**": "Add a human-readable note for specific rooms (shown in User and Onboarding profiles). Example: room **Kitchen** — note **Gas shutoff — left of sink.**",
 	"Room name": "Room name",
 	"Generate now hint": "Click the button below to generate the documentation immediately without restarting the adapter. All three profiles (Admin, User, Onboarding) are generated simultaneously.",
 	"Generate documentation now": "Generate documentation now",
@@ -152,11 +154,11 @@
 	"Send notification after documentation generation": "Send notification after documentation generation",
 	"If enabled, a message is sent via the configured adapter after each generation": "If enabled, a message is sent via the configured adapter after each generation",
 	"Messaging adapter instance": "Messaging adapter instance",
-	"Instance to send the notification through, e.g. telegram.0, pushover.0, email.0": "Instance to send the notification through, e.g. telegram.0, pushover.0, email.0",
+	"Instance to send the notification through, e.g. telegram.0, pushover.0, email.0, signal.0": "Instance to send the notification through, e.g. telegram.0, pushover.0, email.0, signal.0",
 	"Recipient (optional)": "Recipient (optional)",
-	"Telegram username, Pushover device, or email address — leave empty for adapter default": "Telegram username, Pushover device, or email address — leave empty for adapter default",
+	"Telegram username, Pushover device, or email address - leave empty for adapter default. Examples: Telegram **@nickname**, email **ops@example.com**, Pushover device **phone**.": "Telegram username, Pushover device, or email address - leave empty for adapter default. Examples: Telegram **@nickname**, email **ops@example.com**, Pushover device **phone**.",
 	"Custom message template (optional)": "Custom message template (optional)",
-	"Use {project}, {summary}, {version}, {trigger} as placeholders. Leave empty for default message.": "Use {project}, {summary}, {version}, {trigger} as placeholders. Leave empty for default message.",
+	"Use {project}, {summary}, {version}, {trigger} as placeholders. Leave empty for default message. Example: **{project} — documentation updated ({trigger}). {summary}**": "Use {project}, {summary}, {version}, {trigger} as placeholders. Leave empty for default message. Example: **{project} — documentation updated ({trigger}). {summary}**",
 	"AI-Enhanced Documentation": "AI-Enhanced Documentation",
 	"AI provider": "AI provider",
 	"Select an AI provider for narrative summaries. Disabled for admin profile (all data is already factual). Not used for admin profile.": "Select an AI provider for narrative summaries. Not used for admin profile (all data is already factual).",
@@ -189,7 +191,7 @@
 	"AI context hints": "AI context hints",
 	"AI context hints (owner notes)": "AI context hints (owner notes)",
 	"AI context hints hint": "Optional bullet-point facts about your home for the AI — used only in the AI prompt, never shown in the documentation. Example: '- Lights in living room auto-off at 22:00', '- Guests can control temperature via voice'. The more specific, the better the AI text quality. — **Guest onboarding:** Prefer everyday wording (e.g. \"we are still setting things up\", \"docs will be expanded\"). If you pack in IT/project jargon (\"adapter\", \"repository\", \"not in the repo\", …), the model may repeat it in guest-facing text. A **safety filter** then replaces the guest AI block with a neutral default so visitors do not read admin-style jargon. That behaviour is intentional; relaxing it would weaken guest-safe output. The **resident / family profile** is not subject to this rule.",
-	"AI context hints help": "Short points only the AI sees — not shown in exported documentation. Privacy: sent to the configured AI provider. — **Guest profile:** See the longer hint above: technical wording in context hints can cause the guest AI text to be discarded and replaced with neutral copy.",
+	"AI context hints help": "Short points only the AI sees — not shown in exported documentation. Privacy: sent to the configured AI provider. — **Guest profile:** See the longer hint above: technical wording in context hints can cause the guest AI text to be discarded and replaced with neutral copy. Mini-example: **`- Vacuum pauses when “Away” is active`** — concrete facts beat vague words.",
 	"HTML export & extra sections": "HTML export & extra sections",
 	"Doc layout intro": "Tune generated **HTML** (all three profiles): optional forced light/dark mode, a **color preset** (no raw CSS), logo, and your own Markdown chapters. **Font** and **extra CSS** are optional expert settings at the **bottom** of this tab (after chapter visibility and custom sections). Admin **chapter order** and **hide list** apply to Admin HTML and Admin-profile Markdown. **Hide lists** for **User/Family** and **Onboarding** (e.g. `ownerPlaybook`) are **below** on this tab and affect those HTML exports and Markdown when that documentation profile is selected. Markdown also uses your custom sections.",
 	"Doc layout pdf hint": "**PDF export:** settings are on the **Advanced** tab (below filesystem export path): optional **PDF after each generation**, or use the **`action.exportPdf`** button state any time. Requires optional **`puppeteer`** in the adapter directory. Writes **`autodoc-{admin,user,onboarding}.pdf`** under adapter **Files** and mirrors them when a filesystem export path is set.",
@@ -207,11 +209,11 @@
 	"HTML theme preset warm": "Warm",
 	"HTML theme preset slate": "Slate",
 	"Sidebar logo URL": "Sidebar logo URL",
-	"Sidebar logo URL help": "Optional image above the search box in exported HTML. Use **https://…** or a same-site path starting with **/** (e.g. a file under ioBroker `/files/…`). Other schemes are ignored.",
+	"Sidebar logo URL help": "Optional image above the search box in exported HTML. Use **https://…** or a same-site path starting with **/** — e.g. **`/files/autodoc.0/logo.png`** after you upload a logo to Files. Other schemes are ignored.",
 	"Font stack (CSS)": "Font stack (CSS)",
 	"Font stack help": "Optional `font-family` value for body text, e.g. `Georgia, serif` or `system-ui, sans-serif`. Characters `< > { }` are stripped for safety.",
 	"Extra CSS": "Extra CSS",
-	"Extra CSS help": "Appended to the HTML `<style>` block. For branding (accent colours, spacing). You control this CSS — avoid pasting untrusted content. Do not close `</style>` inside this field. Prefer small rules; overly broad selectors can break the page after updates.",
+	"Extra CSS help": "Appended to the HTML `<style>` block. For branding (accent colours, spacing). You control this CSS — avoid pasting untrusted content. Do not close `</style>` inside this field. Prefer small rules; overly broad selectors can break the page after updates. Mini-example: **`a.doc-nav-link:hover { opacity: 0.85; }`** — prefer variables such as **`var(--accent)`** from the preset.",
 	"Admin HTML — hide chapters": "Admin HTML — hide chapters",
 	"Admin chapter order hint": "Optional: reorder **Admin** HTML and **Admin** Markdown. Enter **chapter ids** in the JSON field below (`[]` = built-in order). Ids you omit are appended in the default product order at the end. The **full list of valid English ids** appears **only** in that field’s help (click the `?` tooltip) — it is not repeated here.",
 	"Admin chapter order (JSON array)": "Admin chapter order (JSON array)",
@@ -226,14 +228,14 @@
 	"User/Family HTML — hide chapters": "User/Family HTML — hide chapters",
 	"User hidden chapters hint": "JSON array of chapter ids to hide in **User/Family** HTML and in **Markdown** when the documentation profile is User. Example: `[\"scripts\",\"adapters\"]`. Valid ids: `manual`, `ai`, `guestHelp`, `atAGlance`, `rooms`, `scripts`, `routines`, `ownerPlaybook`, `mermaid` (user-defined Mermaid diagram), `mermaidAuto` (auto-generated host topology — not shown in Onboarding), `adapters`, `custom`, `system`, `troubleshooting`.",
 	"User profile — hidden chapter IDs (JSON)": "User profile — hidden chapter IDs (JSON)",
-	"User hidden chapters JSON help": "JSON array of strings. Empty `[]` shows all.",
+	"User hidden chapters JSON help": "JSON array of strings, e.g. `[\"scripts\",\"adapters\"]`. Invalid ids are ignored. Empty `[]` shows all.",
 	"User chapter order hint": "Optional: reorder **User/Family** HTML and **User** Markdown chapters. Enter **chapter ids** below in the desired order. **Valid ids:** `manual`, `ai`, `guestHelp`, `atAGlance`, `rooms`, `scripts`, `routines`, `ownerPlaybook`, `mermaid`, `adapters`, `custom`, `system`, `troubleshooting` — any id you omit is appended in the default order. Empty `[]` = default order.",
 	"User chapter order (JSON array)": "User chapter order (JSON array)",
 	"User chapter order JSON help": "JSON array of strings, e.g. `[\"atAGlance\",\"rooms\",\"manual\",\"adapters\"]`. **Valid ids:** `manual`, `ai`, `guestHelp`, `atAGlance`, `rooms`, `scripts`, `routines`, `ownerPlaybook`, `mermaid`, `adapters`, `custom`, `system`, `troubleshooting`. Unknown ids are skipped; ids you do not name are added at the end in default order. Empty `[]` = built-in order.",
 	"Onboarding HTML — hide chapters": "Onboarding HTML — hide chapters",
 	"Onboarding hidden chapters hint": "Hide blocks in **Onboarding** HTML and matching parts of **Markdown** (profile Onboarding). Valid ids: `welcome`, `tips`, `guestHelp`, `stats`, `ai`, `capabilities`, `mermaid` (owner diagram in the welcome area), `rooms`, `routines`, `ownerPlaybook`, `automations`, `adapters`, `custom`, `hint`, plus for Markdown also `quickstart`, `system`, `manual` (project description/contact in welcome + manual chapter subsections).",
 	"Onboarding profile — hidden chapter IDs (JSON)": "Onboarding profile — hidden chapter IDs (JSON)",
-	"Onboarding hidden chapters JSON help": "JSON array of strings. Empty `[]` shows all.",
+	"Onboarding hidden chapters JSON help": "JSON array of strings, e.g. `[\"adapters\",\"stats\"]`. Invalid ids are ignored. Empty `[]` shows all.",
 	"Onboarding chapter order hint": "Optional: reorder **Onboarding/Guest** HTML and **Onboarding** Markdown chapters. **Valid ids:** `welcome`, `quickstart`, `tips`, `guestHelp`, `stats`, `ai`, `capabilities`, `mermaid`, `rooms`, `routines`, `ownerPlaybook`, `automations`, `adapters`, `custom`, `hint`, `system`, `manual` — any id you omit is appended in the default order. Empty `[]` = default order.",
 	"Onboarding chapter order (JSON array)": "Onboarding chapter order (JSON array)",
 	"Onboarding chapter order JSON help": "JSON array of strings, e.g. `[\"quickstart\",\"tips\",\"rooms\",\"adapters\"]`. **Valid ids:** `welcome`, `quickstart`, `tips`, `guestHelp`, `stats`, `ai`, `capabilities`, `mermaid`, `rooms`, `routines`, `ownerPlaybook`, `automations`, `adapters`, `custom`, `hint`, `system`, `manual`. Unknown ids are skipped; ids you do not name are added at the end. Empty `[]` = built-in order.",

package/admin/i18n/es.json

@@ -1,7 +1,6 @@
 {
 	"autodoc adapter settings": "Ajustes del adaptador para autodoc",
 	"Project name": "Project name",
-	"Name of the ioBroker project or installation": "Name of the ioBroker project or installation",
 	"Target system": "Target system",
 	"Usually ioBroker": "Usually ioBroker",
 	"Documentation profile": "Documentation profile",
@@ -22,7 +21,6 @@
 	"Read live state values (opt-in)": "Read live state values (opt-in)",
 	"If enabled, current values for selected state roles are read and shown in User/Onboarding room cards and the Admin device table (badges next to device names). Includes e.g. temperature, blinds (level.blind), dimmers, lights (switch.light), outlets (switch/plug), humidity, power metrics, locks, door/window/contact, motion, alarm. Room members may be channels or devices — matching child states are found automatically. Very custom or empty roles are skipped.": "If enabled, current values for selected state roles are read and shown in User/Onboarding room cards and the Admin device table (badges next to device names). Includes e.g. temperature, blinds (level.blind), dimmers, lights (switch.light), outlets (switch/plug), humidity, power metrics, locks, door/window/contact, motion, alarm. Room members may be channels or devices — matching child states are found automatically. Very custom or empty roles are skipped.",
 	"Scheduled interval (hours)": "Scheduled interval (hours)",
-	"Optional timer: regenerate every X hours, independent of start and adapter-change options above. 0 = no scheduled runs (events and start still work).": "Optional timer: regenerate every X hours, independent of start and adapter-change options above. 0 = no scheduled runs (events and start still work).",
 	"Only document enabled instances": "Only document enabled instances",
 	"If enabled, only active adapter instances are included in the documentation": "If enabled, only active adapter instances are included in the documentation",
 	"Hide instance details in markdown": "Hide instance details in markdown",
@@ -30,11 +28,10 @@
 	"Maximum documented instances": "Maximum documented instances",
 	"Limits how many adapter instances are included in the generated documentation, 0 means unlimited": "Limits how many adapter instances are included in the generated documentation, 0 means unlimited",
 	"ioBroker base URL (optional)": "ioBroker base URL (optional)",
-	"Used for the info.htmlUrl state. Include port, e.g. 192.168.1.100:8081 or http://myserver:8082. Protocol is optional. Leave empty for auto-detection (may fail in Docker).": "Used for the info.htmlUrl state. Include port, e.g. 192.168.1.100:8081 or http://myserver:8082. Protocol is optional. Leave empty for auto-detection (may fail in Docker).",
 	"Maximum stored documentation files": "Maximum stored documentation files",
 	"How many timestamped file sets to keep (per type: .md, .html, .json). Oldest are deleted automatically. 0 = use default (3).": "How many timestamped file sets to keep (per type: .md, .html, .json). Oldest are deleted automatically. 0 = use default (3).",
 	"Documentation states storage": "Documentation states storage",
-	"Documentation states storage help": "Full: duplicate markdown, HTML, and JSON in adapter states (legacy, larger object DB / Redis). Metadata only: keep full exports only under Files (autodoc-latest.*); states hold a short placeholder — reduces database size. Scripts that read documentation.* for full text must use /files/ or HTTP URLs instead. Download actions still write autodoc.md / .json / .html from the latest files. In both modes **`documentation.exportHashes`** stores **SHA-256 (hex)** digests of the latest MD / Admin HTML / JSON exports for change detection. **After a successful PDF export** (optional `puppeteer`), the same state also includes **`autodoc-admin.pdf`**, **`autodoc-user.pdf`**, and **`autodoc-onboarding.pdf`** digests when those files are written.",
+	"Documentation states storage help": "Full: duplicate markdown, HTML, and JSON in adapter states (legacy, larger object DB / Redis). Metadata only: keep full exports only under Files (autodoc-latest.*); states hold a short placeholder — reduces database size. Scripts that read documentation.* for full text must use /files/ or HTTP URLs instead. Download actions still write autodoc.md / .json / .html from the latest files. In both modes **`documentation.exportHashes`** stores **SHA-256 (hex)** digests of the latest MD / Admin HTML / JSON exports for change detection. **After a successful PDF export** (optional `puppeteer`), the same state also includes **`autodoc-admin.pdf`**, **`autodoc-user.pdf`**, and **`autodoc-onboarding.pdf`** digests when those files are written. **Tip:** try **Metadata only** when object DB / Redis size matters; keep **Full** if older integrations read full text from `documentation.*` states.",
 	"Doc states mode full": "Full (in states — larger DB)",
 	"Doc states mode metadata": "Metadata only (content in /files only)",
 	"Manual context (JSON)": "Manual context (JSON)",
@@ -99,12 +96,10 @@
 	"General notes about this installation (e.g. special setups, known issues)": "General notes about this installation (e.g. special setups, known issues)",
 	"Per-adapter notes": "Per-adapter notes",
 	"Adapter notes": "Adapter notes",
-	"Add a human-readable note for specific adapters (shown in all profiles)": "Add a human-readable note for specific adapters (shown in all profiles)",
 	"Adapter (e.g. telegram)": "Adapter (e.g. telegram)",
 	"Note": "Note",
 	"Per-room notes": "Per-room notes",
 	"Room notes": "Room notes",
-	"Add a human-readable note for specific rooms (shown in User and Onboarding profiles)": "Add a human-readable note for specific rooms (shown in User and Onboarding profiles)",
 	"Room name": "Room name",
 	"Generate now hint": "Click the button below to generate the documentation immediately without restarting the adapter. All three profiles (Admin, User, Onboarding) are generated simultaneously.",
 	"Generate documentation now": "Generate documentation now",
@@ -146,11 +141,8 @@
 	"Send notification after documentation generation": "Send notification after documentation generation",
 	"If enabled, a message is sent via the configured adapter after each generation": "If enabled, a message is sent via the configured adapter after each generation",
 	"Messaging adapter instance": "Messaging adapter instance",
-	"Instance to send the notification through, e.g. telegram.0, pushover.0, email.0": "Instance to send the notification through, e.g. telegram.0, pushover.0, email.0",
 	"Recipient (optional)": "Recipient (optional)",
-	"Telegram username, Pushover device, or email address — leave empty for adapter default": "Telegram username, Pushover device, or email address — leave empty for adapter default",
 	"Custom message template (optional)": "Custom message template (optional)",
-	"Use {project}, {summary}, {version}, {trigger} as placeholders. Leave empty for default message.": "Use {project}, {summary}, {version}, {trigger} as placeholders. Leave empty for default message.",
 	"AI-Enhanced Documentation": "AI-Enhanced Documentation",
 	"AI provider": "AI provider",
 	"Select an AI provider for narrative summaries. Disabled for admin profile (all data is already factual). Not used for admin profile.": "Select an AI provider for narrative summaries. Not used for admin profile (all data is already factual).",
@@ -183,7 +175,7 @@
 	"AI context hints": "AI context hints",
 	"AI context hints (owner notes)": "AI context hints (owner notes)",
 	"AI context hints hint": "Optional bullet-point facts about your home for the AI — used only in the AI prompt, never shown in the documentation. Example: '- Lights in living room auto-off at 22:00', '- Guests can control temperature via voice'. The more specific, the better the AI text quality. — **Guest onboarding:** Prefer everyday wording (e.g. \"we are still setting things up\", \"docs will be expanded\"). If you pack in IT/project jargon (\"adapter\", \"repository\", \"not in the repo\", …), the model may repeat it in guest-facing text. A **safety filter** then replaces the guest AI block with a neutral default so visitors do not read admin-style jargon. That behaviour is intentional; relaxing it would weaken guest-safe output. The **resident / family profile** is not subject to this rule.",
-	"AI context hints help": "Short points only the AI sees — not shown in exported documentation. Privacy: sent to the configured AI provider. — **Guest profile:** See the longer hint above: technical wording in context hints can cause the guest AI text to be discarded and replaced with neutral copy.",
+	"AI context hints help": "Short points only the AI sees — not shown in exported documentation. Privacy: sent to the configured AI provider. — **Guest profile:** See the longer hint above: technical wording in context hints can cause the guest AI text to be discarded and replaced with neutral copy. Mini-example: **`- Vacuum pauses when “Away” is active`** — concrete facts beat vague words.",
 	"HTML export & extra sections": "HTML export & extra sections",
 	"Doc layout intro": "Tune generated **HTML** (all three profiles): optional forced light/dark mode, a **color preset** (no raw CSS), logo, and your own Markdown chapters. **Font** and **extra CSS** are optional expert settings at the **bottom** of this tab (after chapter visibility and custom sections). Admin **chapter order** and **hide list** apply to Admin HTML and Admin-profile Markdown. **Hide lists** for **User/Family** and **Onboarding** (e.g. `ownerPlaybook`) are **below** on this tab and affect those HTML exports and Markdown when that documentation profile is selected. Markdown also uses your custom sections.",
 	"Doc layout pdf hint": "**PDF export:** settings are on the **Advanced** tab (below filesystem export path): optional **PDF after each generation**, or use the **`action.exportPdf`** button state any time. Requires optional **`puppeteer`** in the adapter directory. Writes **`autodoc-{admin,user,onboarding}.pdf`** under adapter **Files** and mirrors them when a filesystem export path is set.",
@@ -201,11 +193,11 @@
 	"HTML theme preset warm": "Warm",
 	"HTML theme preset slate": "Slate",
 	"Sidebar logo URL": "Sidebar logo URL",
-	"Sidebar logo URL help": "Optional image above the search box in exported HTML. Use **https://…** or a same-site path starting with **/** (e.g. a file under ioBroker `/files/…`). Other schemes are ignored.",
+	"Sidebar logo URL help": "Optional image above the search box in exported HTML. Use **https://…** or a same-site path starting with **/** — e.g. **`/files/autodoc.0/logo.png`** after you upload a logo to Files. Other schemes are ignored.",
 	"Font stack (CSS)": "Font stack (CSS)",
 	"Font stack help": "Optional `font-family` value for body text, e.g. `Georgia, serif` or `system-ui, sans-serif`. Characters `< > { }` are stripped for safety.",
 	"Extra CSS": "Extra CSS",
-	"Extra CSS help": "Appended to the HTML `<style>` block. For branding (accent colours, spacing). You control this CSS — avoid pasting untrusted content. Do not close `</style>` inside this field. Prefer small rules; overly broad selectors can break the page after updates.",
+	"Extra CSS help": "Appended to the HTML `<style>` block. For branding (accent colours, spacing). You control this CSS — avoid pasting untrusted content. Do not close `</style>` inside this field. Prefer small rules; overly broad selectors can break the page after updates. Mini-example: **`a.doc-nav-link:hover { opacity: 0.85; }`** — prefer variables such as **`var(--accent)`** from the preset.",
 	"Admin HTML — hide chapters": "Admin HTML — hide chapters",
 	"Admin chapter order hint": "Optional: reorder **Admin** HTML and **Admin** Markdown. Enter **chapter ids** in the JSON field below (`[]` = built-in order). Ids you omit are appended in the default product order at the end. The **full list of valid English ids** appears **only** in that field’s help (click the `?` tooltip) — it is not repeated here.",
 	"Admin chapter order (JSON array)": "Admin chapter order (JSON array)",
@@ -220,10 +212,20 @@
 	"User/Family HTML — hide chapters": "User/Family HTML — hide chapters",
 	"User hidden chapters hint": "JSON array of chapter ids to hide in **User/Family** HTML and in **Markdown** when the documentation profile is User. Example: `[\"scripts\",\"adapters\"]`. Valid ids: `manual` (project description/contact/notes only), `ai`, `guestHelp`, `atAGlance` (Quick overview from discovery; User HTML + User Markdown), `rooms`, `scripts`, `routines`, `ownerPlaybook`, `adapters`, `custom`, `system`, `troubleshooting`.",
 	"User profile — hidden chapter IDs (JSON)": "User profile — hidden chapter IDs (JSON)",
-	"User hidden chapters JSON help": "JSON array of strings. Empty `[]` shows all.",
+	"User hidden chapters JSON help": "JSON array of strings, e.g. `[\"scripts\",\"adapters\"]`. Invalid ids are ignored. Empty `[]` shows all.",
 	"Onboarding HTML — hide chapters": "Onboarding HTML — hide chapters",
 	"Onboarding hidden chapters hint": "Hide blocks in **Onboarding** HTML and matching parts of **Markdown** (profile Onboarding). Valid ids: `welcome`, `tips`, `guestHelp`, `stats`, `ai`, `capabilities`, `rooms`, `routines`, `ownerPlaybook`, `automations`, `adapters`, `custom`, `hint`, plus for Markdown also `quickstart`, `system`, `manual` (project description/contact in welcome + manual chapter subsections).",
 	"Onboarding profile — hidden chapter IDs (JSON)": "Onboarding profile — hidden chapter IDs (JSON)",
-	"Onboarding hidden chapters JSON help": "JSON array of strings. Empty `[]` shows all.",
-	"copyForForum": "Copy for Forum"
+	"Onboarding hidden chapters JSON help": "JSON array of strings, e.g. `[\"adapters\",\"stats\"]`. Invalid ids are ignored. Empty `[]` shows all.",
+	"copyForForum": "Copy for Forum",
+	"Name of the ioBroker project or installation. Shown in exports and notifications. Example: **Demo home** or **Musterhaus Schulweg** (use fictional labels in public screenshots).": "Name of the ioBroker project or installation. Shown in exports and notifications. Example: **Demo home** or **Musterhaus Schulweg** (use fictional labels in public screenshots).",
+	"What does this system do? e.g. 'Single-family home, heating + lighting + security on 3 floors'. Counts toward the optional **documentation setup score** when that row is enabled (Advanced tab — minimum description length).": "What does this system do? e.g. 'Single-family home, heating + lighting + security on 3 floors'. Counts toward the optional **documentation setup score** when that row is enabled (Advanced tab — minimum description length).",
+	"Anything that doesn't fit elsewhere: e.g. 'Backup runs every Sunday, server is in the basement' — same field for maintenance windows, NAS paths, or hardware quirks.": "Anything that doesn't fit elsewhere: e.g. 'Backup runs every Sunday, server is in the basement' — same field for maintenance windows, NAS paths, or hardware quirks.",
+	"Optional timer: regenerate every X hours, independent of start and adapter-change options above. 0 = no scheduled runs (events and start still work). Example: **24** = about once per day.": "Optional timer: regenerate every X hours, independent of start and adapter-change options above. 0 = no scheduled runs (events and start still work). Example: **24** = about once per day.",
+	"Used for the info.htmlUrl state and bookmark/QR targets. Include **host and port**, e.g. **http://192.168.1.100:8081** or **https://iobroker.home:443** — **no trailing slash**. Protocol is optional. Leave empty for auto-detection (may fail in Docker).": "Used for the info.htmlUrl state and bookmark/QR targets. Include **host and port**, e.g. **http://192.168.1.100:8081** or **https://iobroker.home:443** — **no trailing slash**. Protocol is optional. Leave empty for auto-detection (may fail in Docker).",
+	"Add a human-readable note for specific adapters (shown in all profiles). Table row example: adapter **hue** — note **Living room scenes — wall switch overrides.**": "Add a human-readable note for specific adapters (shown in all profiles). Table row example: adapter **hue** — note **Living room scenes — wall switch overrides.**",
+	"Add a human-readable note for specific rooms (shown in User and Onboarding profiles). Example: room **Kitchen** — note **Gas shutoff — left of sink.**": "Add a human-readable note for specific rooms (shown in User and Onboarding profiles). Example: room **Kitchen** — note **Gas shutoff — left of sink.**",
+	"Instance to send the notification through, e.g. telegram.0, pushover.0, email.0, signal.0": "Instance to send the notification through, e.g. telegram.0, pushover.0, email.0, signal.0",
+	"Telegram username, Pushover device, or email address - leave empty for adapter default. Examples: Telegram **@nickname**, email **ops@example.com**, Pushover device **phone**.": "Telegram username, Pushover device, or email address - leave empty for adapter default. Examples: Telegram **@nickname**, email **ops@example.com**, Pushover device **phone**.",
+	"Use {project}, {summary}, {version}, {trigger} as placeholders. Leave empty for default message. Example: **{project} — documentation updated ({trigger}). {summary}**": "Use {project}, {summary}, {version}, {trigger} as placeholders. Leave empty for default message. Example: **{project} — documentation updated ({trigger}). {summary}**"
 }

package/admin/i18n/fr.json

@@ -1,7 +1,7 @@
 {
 	"autodoc adapter settings": "Paramètres d'adaptateur pour autodoc",
 	"Project name": "Nom du projet",
-	"Name of the ioBroker project or installation": "Nom du projet ou de l'installation ioBroker",
+	"Name of the ioBroker project or installation. Shown in exports and notifications. Example: **Demo home** or **Musterhaus Schulweg** (use fictional labels in public screenshots).": "Nom du projet ou de l’installation ioBroker. Affiché dans les exports et les notifications. Exemple : **Maison démo** ou **Maison témoin Rue-École** (libellés fictifs sur les captures publiques).",
 	"Target system": "Système cible",
 	"Usually ioBroker": "Généralement ioBroker",
 	"Documentation profile": "Profil de documentation",
@@ -10,6 +10,7 @@
 	"Language for the generated documentation": "Langue de la documentation générée",
 	"Project description": "Description du projet",
 	"Short description of what should be documented": "Courte description de ce qui doit être documenté",
+	"What does this system do? e.g. 'Single-family home, heating + lighting + security on 3 floors'. Counts toward the optional **documentation setup score** when that row is enabled (Advanced tab — minimum description length).": "Que fait ce système ? p. ex. « Maison unifamiliale, chauffage + éclairage + sécurité sur 3 niveaux ». Compte pour le **score de configuration** (optionnel) lorsque la ligne est activée (onglet **Avancé** — longueur minimale de la description).",
 	"Additional notes": "Notes supplémentaires",
 	"Optional notes, devices, adapters or special requirements": "Notes optionnelles, appareils, adaptateurs ou exigences particulières",
 	"Generate documentation on adapter start": "Générer la documentation au démarrage de l'adaptateur",
@@ -19,7 +20,7 @@
 	"Read live state values (opt-in)": "Lire les valeurs d'état en direct (opt-in)",
 	"If enabled, current values for key states (temperature, door/window, alarm) are read and shown in Onboarding profile": "Si activé, les valeurs actuelles des états clés (température, porte/fenêtre, alarme) sont lues et affichées dans le profil Onboarding",
 	"Scheduled interval (hours)": "Intervalle planifié (heures)",
-	"Optional timer: regenerate every X hours, independent of start and adapter-change options above. 0 = no scheduled runs (events and start still work).": "Optionnel : régénérer toutes les X heures, indépendamment du démarrage et des changements d’adaptateur ci-dessus. 0 = pas de planification horaire (démarrage et événements restent actifs).",
+	"Optional timer: regenerate every X hours, independent of start and adapter-change options above. 0 = no scheduled runs (events and start still work). Example: **24** = about once per day.": "Optionnel : régénérer toutes les X heures, indépendamment du démarrage et des changements d’adaptateur ci-dessus. 0 = pas de planification horaire (démarrage et événements restent actifs). Exemple : **24** ≈ une fois par jour.",
 	"Only document enabled instances": "Documenter uniquement les instances activées",
 	"If enabled, only active adapter instances are included in the documentation": "Si activé, seules les instances d'adaptateur actives sont incluses dans la documentation",
 	"Hide instance details in markdown": "Masquer les détails des instances dans le markdown",
@@ -27,11 +28,11 @@
 	"Maximum documented instances": "Nombre maximum d'instances documentées",
 	"Limits how many adapter instances are included in the generated documentation, 0 means unlimited": "Limite le nombre d'instances d'adaptateur incluses dans la documentation générée, 0 = illimité",
 	"ioBroker base URL (optional)": "URL de base ioBroker (optionnel)",
-	"Used for the info.htmlUrl state. Include port, e.g. 192.168.1.100:8081 or http://myserver:8082. Protocol is optional. Leave empty for auto-detection (may fail in Docker).": "Utilisé pour l'état info.htmlUrl. Inclure le port, ex. 192.168.1.100:8081. Laisser vide pour la détection automatique.",
+	"Used for the info.htmlUrl state and bookmark/QR targets. Include **host and port**, e.g. **http://192.168.1.100:8081** or **https://iobroker.home:443** — **no trailing slash**. Protocol is optional. Leave empty for auto-detection (may fail in Docker).": "Pour l’état **info.htmlUrl** et les cibles signets / QR. Indiquer **hôte et port**, ex. **http://192.168.1.100:8081** ou **https://iobroker.home:443** — **sans** barre oblique finale. Protocole optionnel. Laisser vide pour détection automatique (peut échouer sous Docker).",
 	"Maximum stored documentation files": "Nombre maximum de fichiers de documentation stockés",
 	"How many timestamped file sets to keep (per type: .md, .html, .json). Oldest are deleted automatically. 0 = use default (3).": "Nombre de jeux de fichiers horodatés à conserver (par type). Les plus anciens sont supprimés automatiquement. 0 = défaut (3).",
 	"Documentation states storage": "Stockage des états de documentation",
-	"Documentation states storage help": "Complet : markdown, HTML et JSON dupliqués dans les états de l’adaptateur (comportement classique, base d’objets / Redis plus lourde). Métadonnées seulement : export complet uniquement sous Fichiers (autodoc-latest.*) ; les états contiennent un court texte de renvoi — réduit la taille de la base. Les scripts qui lisent documentation.* comme texte intégral doivent utiliser /files/ ou les URLs HTTP. Les actions de téléchargement écrivent toujours autodoc.md / .json / .html à partir des derniers fichiers. Dans les deux modes, l’état **`documentation.exportHashes`** enregistre des empreintes **SHA-256 (hex)** des derniers exports MD / HTML admin / JSON pour détecter les changements. **Après un export PDF réussi** (`puppeteer` optionnel), le même état inclut aussi les empreintes **`autodoc-admin.pdf`**, **`autodoc-user.pdf`** et **`autodoc-onboarding.pdf`** lorsque ces fichiers sont écrits.",
+	"Documentation states storage help": "Complet : markdown, HTML et JSON dupliqués dans les états de l’adaptateur (comportement classique, base d’objets / Redis plus lourde). Métadonnées seulement : export complet uniquement sous Fichiers (autodoc-latest.*) ; les états contiennent un court texte de renvoi — réduit la taille de la base. Les scripts qui lisent documentation.* comme texte intégral doivent utiliser /files/ ou les URLs HTTP. Les actions de téléchargement écrivent toujours autodoc.md / .json / .html à partir des derniers fichiers. Dans les deux modes, l’état **`documentation.exportHashes`** enregistre des empreintes **SHA-256 (hex)** des derniers exports MD / HTML admin / JSON pour détecter les changements. **Après un export PDF réussi** (`puppeteer` optionnel), le même état inclut aussi les empreintes **`autodoc-admin.pdf`**, **`autodoc-user.pdf`** et **`autodoc-onboarding.pdf`** lorsque ces fichiers sont écrits. **Astuce :** choisir **Métadonnées seulement** si la taille de la base d’objets / Redis pose problème ; garder **Complet** si d’anciennes intégrations lisent le texte intégral dans les états `documentation.*`.",
 	"Doc states mode full": "Complet (dans les états — base plus lourde)",
 	"Doc states mode metadata": "Métadonnées seulement (contenu dans /files uniquement)",
 	"Manual context (JSON)": "Contexte manuel (JSON)",
@@ -102,14 +103,15 @@
 	"Name or contact for this ioBroker installation": "Nom ou contact pour cette installation ioBroker",
 	"General notes": "Notes générales",
 	"General notes about this installation (e.g. special setups, known issues)": "Notes générales sur cette installation (ex. configurations spéciales, problèmes connus)",
+	"Anything that doesn't fit elsewhere: e.g. 'Backup runs every Sunday, server is in the basement' — same field for maintenance windows, NAS paths, or hardware quirks.": "Ce qui ne rentre pas ailleurs : p. ex. « Sauvegarde chaque dimanche, serveur au sous-sol » — même champ pour les fenêtres de maintenance, chemins NAS ou particularités matérielles.",
 	"Per-adapter notes": "Notes par adaptateur",
 	"Adapter notes": "Notes d'adaptateur",
-	"Add a human-readable note for specific adapters (shown in all profiles)": "Ajouter une note lisible pour des adaptateurs spécifiques (affichée dans tous les profils)",
+	"Add a human-readable note for specific adapters (shown in all profiles). Table row example: adapter **hue** — note **Living room scenes — wall switch overrides.**": "Note lisible pour certains adaptateurs (tous profils). Exemple de ligne : adaptateur **hue** — note **Scènes salon — interrupteur mural prioritaire.**",
 	"Adapter (e.g. telegram)": "Adaptateur (ex. telegram)",
 	"Note": "Note",
 	"Per-room notes": "Notes par pièce",
 	"Room notes": "Notes de pièce",
-	"Add a human-readable note for specific rooms (shown in User and Onboarding profiles)": "Ajouter une note lisible pour des pièces spécifiques (affichée dans les profils User et Onboarding)",
+	"Add a human-readable note for specific rooms (shown in User and Onboarding profiles). Example: room **Kitchen** — note **Gas shutoff — left of sink.**": "Note lisible pour certaines pièces (profils User et Onboarding). Exemple : pièce **Cuisine** — note **Coupure gaz — à gauche de l’évier.**",
 	"Room name": "Nom de la pièce",
 	"Generate now hint": "Cliquez sur le bouton pour générer la documentation immédiatement sans redémarrer l'adaptateur. Les trois profils (Admin, User, Onboarding) sont générés simultanément.",
 	"Generate documentation now": "Générer la documentation maintenant",
@@ -145,11 +147,11 @@
 	"Send notification after documentation generation": "Envoyer une notification après la génération de documentation",
 	"If enabled, a message is sent via the configured adapter after each generation": "Si activé, un message est envoyé via l'adaptateur configuré après chaque génération",
 	"Messaging adapter instance": "Instance d'adaptateur de messagerie",
-	"Instance to send the notification through, e.g. telegram.0, pushover.0, email.0": "Instance pour envoyer la notification, ex. telegram.0, pushover.0, email.0",
+	"Instance to send the notification through, e.g. telegram.0, pushover.0, email.0, signal.0": "Instance pour envoyer la notification, ex. telegram.0, pushover.0, email.0, signal.0",
 	"Recipient (optional)": "Destinataire (optionnel)",
-	"Telegram username, Pushover device, or email address - leave empty for adapter default": "Nom d'utilisateur Telegram, appareil Pushover ou adresse e-mail — laisser vide pour le défaut",
+	"Telegram username, Pushover device, or email address - leave empty for adapter default. Examples: Telegram **@nickname**, email **ops@example.com**, Pushover device **phone**.": "Utilisateur Telegram, appareil Pushover ou e-mail — laisser vide pour le défaut. Exemples : Telegram **@pseudo**, e-mail **ops@example.com**, appareil Pushover **phone**.",
 	"Custom message template (optional)": "Modèle de message personnalisé (optionnel)",
-	"Use {project}, {summary}, {version}, {trigger} as placeholders. Leave empty for default message.": "Utiliser {project}, {summary}, {version}, {trigger} comme espaces réservés. Laisser vide pour le message par défaut.",
+	"Use {project}, {summary}, {version}, {trigger} as placeholders. Leave empty for default message. Example: **{project} — documentation updated ({trigger}). {summary}**": "Espaces réservés {project}, {summary}, {version}, {trigger}. Laisser vide pour le message par défaut. Exemple : **{project} — documentation mise à jour ({trigger}). {summary}**",
 	"AI-Enhanced Documentation": "Documentation améliorée par IA",
 	"AI provider": "Fournisseur IA",
 	"Select an AI provider for narrative summaries. Not used for admin profile (all data is already factual).": "Sélectionner un fournisseur IA pour les résumés narratifs. Non utilisé pour le profil admin.",
@@ -181,7 +183,7 @@
 	"AI context hints": "Indices de contexte IA",
 	"AI context hints (owner notes)": "Indices de contexte IA (notes opérateur)",
 	"AI context hints hint": "Faits optionnels sur le logement pour l'IA — uniquement dans l'invite au modèle, jamais dans la documentation exportée. Exemple : « - Lumières salon éteintes à 22 h ». **Onboarding invités :** préférez un langage courant (« nous finissons l'installation »). Du jargon IT/projet (« adapter », « repository »…) peut être recopié par le modèle ; un **filtre de sécurité** remplace alors le bloc IA invités par un texte neutre — comportement voulu. Le profil **résidents** n'a pas cette contrainte.",
-	"AI context hints help": "Points courts vus par l'IA seulement — pas dans la doc exportée. Confidentialité : envoyé au fournisseur IA. **Profil invités :** voir l'indication détaillée ci-dessus.",
+	"AI context hints help": "Points courts vus par l'IA seulement — pas dans la doc exportée. Confidentialité : envoyé au fournisseur IA. **Profil invités :** voir l'indication détaillée ci-dessus. Mini-exemple : **`- Aspirateur en pause quand « Absent » est actif`** — des faits précis valent mieux que des phrases vagues.",
 	"Filesystem export path (optional)": "Filesystem export path (optional)",
 	"Export path hint": "Optionnel : copie supplémentaire vers un chemin disque réel hors base ioBroker. Laisser vide pour désactiver. Les trois profils HTML y sont écrits ; si l’export PDF est activé et **puppeteer** est installé dans le dossier de l’adaptateur, les **autodoc-*.pdf** y sont aussi copiés.",
 	"Advanced section pdf export": "Export PDF (Puppeteer / Chromium optionnel)",
@@ -202,11 +204,11 @@
 	"HTML theme preset warm": "Chaud",
 	"HTML theme preset slate": "Ardoise",
 	"Sidebar logo URL": "URL du logo (barre latérale)",
-	"Sidebar logo URL help": "Image optionnelle au-dessus de la recherche dans le HTML. **https://…** ou chemin commençant par **/** (ex. fichier sous `/files/…`). Autres schémas ignorés.",
+	"Sidebar logo URL help": "Image optionnelle au-dessus de la recherche dans le HTML exporté. **https://…** ou chemin commençant par **/** — p. ex. **`/files/autodoc.0/logo.png`** après avoir déposé un logo dans Fichiers. Autres schémas ignorés.",
 	"Font stack (CSS)": "Police (font-family CSS)",
 	"Font stack help": "Valeur `font-family` optionnelle, ex. `Georgia, serif`. Les caractères `< > { }` sont supprimés.",
 	"Extra CSS": "CSS supplémentaire",
-	"Extra CSS help": "Ajouté à la fin du bloc `<style>` du HTML. N'insérez pas de `</style>`. Préférez des règles ciblées ; des sélecteurs trop larges peuvent surprendre après une mise à jour.",
+	"Extra CSS help": "Ajouté à la fin du bloc `<style>` du HTML. N'insérez pas de `</style>`. Préférez des règles ciblées ; des sélecteurs trop larges peuvent surprendre après une mise à jour. Mini-exemple : **`a.doc-nav-link:hover { opacity: 0.85; }`** — privilégiez **`var(--accent)`** du préréglage.",
 	"Admin HTML — hide chapters": "HTML admin — masquer des chapitres",
 	"Admin chapter order hint": "Facultatif : ordre des chapitres du HTML **admin** (et sommaire / corps Markdown **admin**) dans le **premier** champ JSON (`[]` = ordre intégré). Les ids omis sont ajoutés après, dans l'ordre produit par défaut. **La liste complète des ids anglais valides** figure **uniquement** dans l'**aide** de ce champ (icône `?`) — pas de doublon ici.",
 	"Admin chapter order (JSON array)": "Ordre des chapitres admin (JSON)",
@@ -221,11 +223,11 @@
 	"User/Family HTML — hide chapters": "HTML utilisateur/famille — masquer des chapitres",
 	"User hidden chapters hint": "Tableau JSON d'ids pour le HTML **utilisateur/famille** et le **Markdown** (profil utilisateur). Ex. `[\"scripts\"]`. Ids : `manual`, `ai`, `guestHelp`, `atAGlance` (aperçu rapide d’après la découverte ; HTML + Markdown utilisateur), `rooms`, `scripts`, `routines`, `ownerPlaybook`, `mermaid` (diagramme Mermaid sous informations manuelles), `adapters`, `custom`, `system`, `troubleshooting`.",
 	"User profile — hidden chapter IDs (JSON)": "Profil utilisateur — chapitres masqués (JSON)",
-	"User hidden chapters JSON help": "Tableau JSON de chaînes. `[]` = tout afficher.",
+	"User hidden chapters JSON help": "Tableau JSON de chaînes, ex. `[\"scripts\",\"adapters\"]`. Ids invalides ignorés. `[]` = tout afficher.",
 	"Onboarding HTML — hide chapters": "HTML onboarding — masquer des chapitres",
 	"Onboarding hidden chapters hint": "Masquer des blocs dans l'HTML **onboarding** et le **Markdown** (profil onboarding). Ids : `welcome`, `tips`, `guestHelp`, `stats`, `ai`, `capabilities`, `mermaid` (diagramme dans l’accueil), `rooms`, `routines`, `ownerPlaybook`, `automations`, `adapters`, `custom`, `hint`, plus pour le Markdown `quickstart`, `system`, `manual`.",
 	"Onboarding profile — hidden chapter IDs (JSON)": "Profil onboarding — chapitres masqués (JSON)",
-	"Onboarding hidden chapters JSON help": "Tableau JSON de chaînes. `[]` = tout afficher.",
+	"Onboarding hidden chapters JSON help": "Tableau JSON de chaînes, ex. `[\"adapters\",\"stats\"]`. Ids invalides ignorés. `[]` = tout afficher.",
 	"User chapter order hint": "Optionnel : reordonner les chapitres du HTML **utilisateur** et du **Markdown** (profil utilisateur). Ids valides : `manual`, `ai`, `guestHelp`, `atAGlance`, `rooms`, `scripts`, `routines`, `ownerPlaybook`, `mermaid`, `adapters`, `custom`, `system`, `troubleshooting`.",
 	"User chapter order (JSON array)": "Ordre des chapitres utilisateur (tableau JSON)",
 	"User chapter order JSON help": "Tableau JSON, ex. `[\"atAGlance\",\"rooms\",\"manual\"]`. Ids : `manual`, `ai`, `guestHelp`, `atAGlance`, `rooms`, `scripts`, `routines`, `ownerPlaybook`, `mermaid`, `adapters`, `custom`, `system`, `troubleshooting`. `[]` = ordre par defaut.",