feat: add in-app glossary with contextual help popovers (#158)

Add clickable info icons next to DOCSIS technical terms (SNR, Power,
Errors, SC-QAM/OFDM, modulation) that show popover explanations.
All 4 languages (EN/DE/FR/ES) supported including modulation module.

Author: itsDNNS

app/i18n/de.json

@@ -655,5 +655,14 @@
   "connection_failed": "Verbindung fehlgeschlagen",
   "theme_toggle": "Design",
   "invalid_backup": "Ungültige Backup-Datei",
-  "restore_failed": "Wiederherstellung fehlgeschlagen"
+  "restore_failed": "Wiederherstellung fehlgeschlagen",
+  "glossary_snr": "Signal-Rausch-Abstand: misst die Signalklarheit in Dezibel. Hoher SNR bedeutet sauberen Empfang. Niedriger SNR verursacht Paketverluste und langsame Geschwindigkeiten.",
+  "glossary_power": "Signalstärke gemessen in dBmV. Zu hoch oder zu niedrig beeinträchtigt die Verbindung. Der ideale Bereich hängt vom Anbieter ab.",
+  "glossary_correctable": "Datenpakete, die beschädigt ankamen aber automatisch repariert wurden. Viele korrigierbare Fehler sind ein Warnsignal für Kabelprobleme.",
+  "glossary_uncorrectable": "Datenpakete, die verloren gingen und nicht wiederhergestellt werden konnten. Diese verursachen Ruckeln, Abbrüche und langsame Geschwindigkeiten.",
+  "glossary_scqam": "SC-QAM (Single-Carrier QAM): traditionelle DOCSIS 3.0-Technologie mit schmalen 6-8 MHz-Kanälen für einzelne Datenströme.",
+  "glossary_ofdm": "OFDM/OFDMA: DOCSIS 3.1-Technologie mit breiten Kanälen und tausenden Subträgern. Ermöglicht höhere Geschwindigkeiten, ist aber störungsempfindlicher.",
+  "glossary_modulation": "Modulation (QAM-Stufe): höhere Stufen wie 256QAM oder 4096QAM übertragen mehr Daten pro Signal. Niedrige Modulation deutet auf Signalprobleme hin.",
+  "glossary_docsis": "DOCSIS 3.0 nutzt SC-QAM-Kanäle. DOCSIS 3.1 ergänzt OFDM/OFDMA für höhere Geschwindigkeiten. Die meisten Modems nutzen beides gleichzeitig (Mixed Mode).",
+  "glossary_gaming_index": "Gaming-Qualitätsindex: bewertet die Verbindung für Echtzeit-Gaming anhand von Latenz, Jitter und Paketverlust. A/B = super, C = spielbar, D/F = problematisch."
 }

app/i18n/en.json

@@ -655,5 +655,14 @@
   "connection_failed": "Connection failed",
   "theme_toggle": "Theme",
   "invalid_backup": "Invalid backup file",
-  "restore_failed": "Restore failed"
+  "restore_failed": "Restore failed",
+  "glossary_snr": "Signal-to-Noise Ratio: measures signal clarity in decibels. Higher is better. Low SNR causes packet loss and slow speeds.",
+  "glossary_power": "Signal strength measured in dBmV. Too high or too low degrades your connection. The ideal range depends on your ISP.",
+  "glossary_correctable": "Data packets that arrived damaged but were automatically repaired. Many correctable errors are a warning sign for cable issues.",
+  "glossary_uncorrectable": "Data packets that were lost and could not be recovered. These cause buffering, dropouts, and slow speeds.",
+  "glossary_scqam": "SC-QAM (Single-Carrier QAM): traditional DOCSIS 3.0 technology using narrow 6-8 MHz channels for individual data streams.",
+  "glossary_ofdm": "OFDM/OFDMA: DOCSIS 3.1 technology using wide channels with thousands of subcarriers. Enables higher speeds but is more sensitive to interference.",
+  "glossary_modulation": "Modulation (QAM level): higher levels like 256QAM or 4096QAM carry more data per signal. Lower modulation indicates signal degradation.",
+  "glossary_docsis": "DOCSIS 3.0 uses SC-QAM channels. DOCSIS 3.1 adds OFDM/OFDMA for higher speeds. Most modems use both simultaneously (mixed mode).",
+  "glossary_gaming_index": "Gaming Quality Index: rates your connection for real-time gaming based on latency, jitter, and packet loss. A/B = great, C = playable, D/F = problematic."
 }

app/i18n/es.json

@@ -650,5 +650,14 @@
   "connection_failed": "Error de conexión",
   "theme_toggle": "Tema",
   "invalid_backup": "Archivo de respaldo no válido",
-  "restore_failed": "Error en la restauración"
+  "restore_failed": "Error en la restauración",
+  "glossary_snr": "Relación señal/ruido: mide la claridad de la señal en decibelios. Un SNR alto significa recepción limpia. Un SNR bajo causa pérdida de paquetes y velocidades lentas.",
+  "glossary_power": "Potencia de la señal medida en dBmV. Demasiado alta o baja degrada la conexión. El rango ideal depende del proveedor.",
+  "glossary_correctable": "Paquetes de datos que llegaron dañados pero se repararon automáticamente. Muchos errores corregibles son una señal de alerta de problemas de cableado.",
+  "glossary_uncorrectable": "Paquetes de datos perdidos que no pudieron recuperarse. Causan interrupciones, cortes y velocidades lentas.",
+  "glossary_scqam": "SC-QAM (Single-Carrier QAM): tecnología tradicional DOCSIS 3.0 que usa canales estrechos de 6-8 MHz para flujos de datos individuales.",
+  "glossary_ofdm": "OFDM/OFDMA: tecnología DOCSIS 3.1 con canales anchos y miles de subportadoras. Permite mayores velocidades pero es más sensible a interferencias.",
+  "glossary_modulation": "Modulación (nivel QAM): niveles altos como 256QAM o 4096QAM transportan más datos por señal. Una modulación baja indica degradación de la señal.",
+  "glossary_docsis": "DOCSIS 3.0 usa canales SC-QAM. DOCSIS 3.1 agrega OFDM/OFDMA para mayores velocidades. La mayoría de los módems usan ambos simultáneamente (modo mixto).",
+  "glossary_gaming_index": "Índice de calidad gaming: evalúa la conexión para juegos en tiempo real según latencia, jitter y pérdida de paquetes. A/B = excelente, C = jugable, D/F = problemático."
 }

app/i18n/fr.json

@@ -647,5 +647,14 @@
   "connection_failed": "Échec de la connexion",
   "theme_toggle": "Thème",
   "invalid_backup": "Fichier de sauvegarde invalide",
-  "restore_failed": "Échec de la restauration"
+  "restore_failed": "Échec de la restauration",
+  "glossary_snr": "Rapport signal/bruit : mesure la clarté du signal en décibels. Un SNR élevé signifie une réception propre. Un SNR faible cause des pertes de paquets.",
+  "glossary_power": "Puissance du signal mesurée en dBmV. Trop élevée ou trop faible, elle dégrade la connexion. La plage idéale dépend du fournisseur.",
+  "glossary_correctable": "Paquets de données endommagés mais réparés automatiquement. De nombreuses erreurs corrigibles sont un signal d'alerte pour des problèmes de câble.",
+  "glossary_uncorrectable": "Paquets de données perdus et non récupérables. Ils causent des saccades, des coupures et des vitesses réduites.",
+  "glossary_scqam": "SC-QAM (Single-Carrier QAM) : technologie DOCSIS 3.0 traditionnelle utilisant des canaux étroits de 6-8 MHz pour des flux de données individuels.",
+  "glossary_ofdm": "OFDM/OFDMA : technologie DOCSIS 3.1 avec des canaux larges et des milliers de sous-porteuses. Permet des vitesses plus élevées mais plus sensible aux interférences.",
+  "glossary_modulation": "Modulation (niveau QAM) : des niveaux élevés comme 256QAM ou 4096QAM transportent plus de données par signal. Une modulation basse indique une dégradation du signal.",
+  "glossary_docsis": "DOCSIS 3.0 utilise des canaux SC-QAM. DOCSIS 3.1 ajoute OFDM/OFDMA pour des vitesses supérieures. La plupart des modems utilisent les deux simultanément (mode mixte).",
+  "glossary_gaming_index": "Indice de qualité gaming : évalue la connexion pour le jeu en temps réel selon la latence, le jitter et la perte de paquets. A/B = excellent, C = jouable, D/F = problématique."
 }

app/modules/modulation/i18n/de.json

@@ -21,5 +21,8 @@
     "click_day_hint": "Klicken Sie auf einen Tagesbalken für Kanaldetails",
     "no_degradation": "Keine Degradation beobachtet",
     "channel_summary": "Kanalzusammenfassung",
-    "protocol_group_label": "Protokollgruppe"
+    "protocol_group_label": "Protokollgruppe",
+    "glossary_health_index": "Gesundheitsindex: ein Gesamtwert (0-100), der die Modulationsqualität aller Kanäle widerspiegelt. Höher bedeutet weniger Signaldegradation.",
+    "glossary_low_qam": "Low-QAM-Anteil: Anteil der Zeit, in der Kanäle auf niedrige Modulationsstufen (QPSK, 16QAM) fallen. Hoher Anteil deutet auf anhaltende Signalprobleme hin.",
+    "glossary_sample_density": "Messabdeckung: Anzahl der gesammelten Polling-Messungen im gewählten Zeitraum. Mehr Messungen bedeuten genauere Statistiken."
 }

app/modules/modulation/i18n/en.json

@@ -21,5 +21,8 @@
     "click_day_hint": "Click a day bar to view per-channel details",
     "no_degradation": "No degradation observed",
     "channel_summary": "Channel Summary",
-    "protocol_group_label": "Protocol Group"
+    "protocol_group_label": "Protocol Group",
+    "glossary_health_index": "Health Index: an aggregate score (0-100) reflecting overall modulation quality across all channels. Higher means less signal degradation.",
+    "glossary_low_qam": "Low-QAM Exposure: percentage of time channels drop to low modulation levels (QPSK, 16QAM). High exposure indicates persistent signal problems.",
+    "glossary_sample_density": "Sample Density: number of polling samples collected for the selected period. More samples mean more accurate statistics."
 }

app/modules/modulation/i18n/es.json

@@ -0,0 +1,28 @@
+{
+    "title": "Rendimiento de modulación",
+    "upstream": "Upstream",
+    "downstream": "Downstream",
+    "today": "Hoy",
+    "days_label": "Días",
+    "health_index": "Índice de salud",
+    "low_qam_exposure": "Exposición Low-QAM",
+    "low_qam_pct": "Low-QAM %",
+    "sample_density": "Densidad de muestras",
+    "samples": "muestras",
+    "distribution_chart": "Distribución de modulación",
+    "trend_chart": "Tendencia salud & Low-QAM",
+    "no_data": "No hay datos de modulación disponibles para el período seleccionado.",
+    "back_to_overview": "Volver al resumen",
+    "intraday_title": "Detalle del canal",
+    "channels_label": "Canales",
+    "dominant_modulation": "Dominante",
+    "degraded_channels": "degradados",
+    "disclaimer": "Los índices de salud y las estadísticas de modulación son estimaciones basadas en muestras periódicas.",
+    "click_day_hint": "Haga clic en una barra de día para ver los detalles por canal",
+    "no_degradation": "No se observó degradación",
+    "channel_summary": "Resumen de canales",
+    "protocol_group_label": "Grupo de protocolo",
+    "glossary_health_index": "Índice de salud: puntuación global (0-100) que refleja la calidad de modulación en todos los canales. Mayor significa menos degradación.",
+    "glossary_low_qam": "Exposición Low-QAM: porcentaje de tiempo en que los canales caen a niveles bajos de modulación (QPSK, 16QAM). Alta exposición indica problemas de señal persistentes.",
+    "glossary_sample_density": "Densidad de muestras: número de mediciones recopiladas para el período seleccionado. Más muestras significan estadísticas más precisas."
+}

app/modules/modulation/i18n/fr.json

@@ -0,0 +1,28 @@
+{
+    "title": "Performance de modulation",
+    "upstream": "Upstream",
+    "downstream": "Downstream",
+    "today": "Aujourd'hui",
+    "days_label": "Jours",
+    "health_index": "Indice de santé",
+    "low_qam_exposure": "Exposition Low-QAM",
+    "low_qam_pct": "Low-QAM %",
+    "sample_density": "Densité d'échantillons",
+    "samples": "échantillons",
+    "distribution_chart": "Distribution de modulation",
+    "trend_chart": "Tendance santé & Low-QAM",
+    "no_data": "Aucune donnée de modulation disponible pour la période sélectionnée.",
+    "back_to_overview": "Retour à l'aperçu",
+    "intraday_title": "Détail du canal",
+    "channels_label": "Canaux",
+    "dominant_modulation": "Dominante",
+    "degraded_channels": "dégradés",
+    "disclaimer": "Les indices de santé et les statistiques de modulation sont des estimations basées sur des échantillons périodiques.",
+    "click_day_hint": "Cliquez sur une barre de jour pour voir les détails par canal",
+    "no_degradation": "Aucune dégradation observée",
+    "channel_summary": "Résumé des canaux",
+    "protocol_group_label": "Groupe de protocole",
+    "glossary_health_index": "Indice de santé : score global (0-100) reflétant la qualité de modulation sur tous les canaux. Plus élevé signifie moins de dégradation.",
+    "glossary_low_qam": "Exposition Low-QAM : pourcentage de temps où les canaux passent en modulation basse (QPSK, 16QAM). Une exposition élevée indique des problèmes de signal persistants.",
+    "glossary_sample_density": "Densité d'échantillons : nombre de mesures collectées pour la période sélectionnée. Plus de mesures signifie des statistiques plus précises."
+}

app/modules/modulation/templates/modulation_tab.html

@@ -18,17 +18,17 @@ <h2 style="margin:0; flex:1;">{{ t.get('docsight.modulation.title', 'Modulation
         <!-- KPI Cards (aggregate) -->
         <div class="modulation-kpi-row" id="modulation-kpis">
             <div class="chart-card modulation-kpi-card">
-                <div class="modulation-kpi-label">{{ t.get('docsight.modulation.health_index', 'Health Index') }}</div>
+                <div class="modulation-kpi-label">{{ t.get('docsight.modulation.health_index', 'Health Index') }} <span class="glossary-hint"><i data-lucide="info"></i><div class="glossary-popover">{{ t.get('docsight.modulation.glossary_health_index', '') }}</div></span></div>
                 <div class="modulation-kpi-value" id="mod-kpi-health">—</div>
                 <div class="modulation-kpi-sub" id="mod-kpi-health-delta"></div>
             </div>
             <div class="chart-card modulation-kpi-card">
-                <div class="modulation-kpi-label">{{ t.get('docsight.modulation.low_qam_exposure', 'Low-QAM Exposure') }}</div>
+                <div class="modulation-kpi-label">{{ t.get('docsight.modulation.low_qam_exposure', 'Low-QAM Exposure') }} <span class="glossary-hint"><i data-lucide="info"></i><div class="glossary-popover">{{ t.get('docsight.modulation.glossary_low_qam', '') }}</div></span></div>
                 <div class="modulation-kpi-value" id="mod-kpi-lowqam">—</div>
                 <div class="modulation-kpi-sub" id="mod-kpi-lowqam-hint"></div>
             </div>
             <div class="chart-card modulation-kpi-card">
-                <div class="modulation-kpi-label">{{ t.get('docsight.modulation.sample_density', 'Sample Density') }}</div>
+                <div class="modulation-kpi-label">{{ t.get('docsight.modulation.sample_density', 'Sample Density') }} <span class="glossary-hint"><i data-lucide="info"></i><div class="glossary-popover">{{ t.get('docsight.modulation.glossary_sample_density', '') }}</div></span></div>
                 <div class="modulation-kpi-value" id="mod-kpi-density">—</div>
                 <div class="modulation-kpi-sub" id="mod-kpi-density-hint"></div>
             </div>

app/static/css/glossary.css

@@ -0,0 +1,98 @@
+/* glossary.css — Contextual help popovers for DOCSIS terms */
+
+.glossary-hint {
+  display: inline-flex;
+  align-items: center;
+  cursor: pointer;
+  position: relative;
+  margin-left: 4px;
+  vertical-align: middle;
+}
+
+.glossary-hint > i,
+.glossary-hint > svg {
+  width: 13px;
+  height: 13px;
+  color: var(--text-muted);
+  opacity: 0.6;
+  transition: opacity 0.2s, color 0.2s;
+}
+
+.glossary-hint:hover > i,
+.glossary-hint:hover > svg {
+  opacity: 1;
+  color: var(--amethyst-light);
+}
+
+.glossary-popover {
+  display: none;
+  position: absolute;
+  left: 50%;
+  top: calc(100% + 8px);
+  transform: translateX(-50%);
+  width: max-content;
+  max-width: 320px;
+  padding: 12px 16px;
+  background: var(--surface);
+  border: 1px solid var(--glass-border);
+  border-radius: var(--radius-sm);
+  box-shadow: var(--shadow-md);
+  color: var(--text-secondary);
+  font-size: 0.8rem;
+  font-weight: 400;
+  line-height: 1.5;
+  z-index: 500;
+  pointer-events: auto;
+  white-space: normal;
+}
+
+/* Flip above when near bottom */
+.glossary-popover.above {
+  top: auto;
+  bottom: calc(100% + 8px);
+}
+
+/* Arrow */
+.glossary-popover::before {
+  content: '';
+  position: absolute;
+  left: 50%;
+  top: -5px;
+  transform: translateX(-50%) rotate(45deg);
+  width: 8px;
+  height: 8px;
+  background: var(--surface);
+  border-left: 1px solid var(--glass-border);
+  border-top: 1px solid var(--glass-border);
+}
+
+.glossary-popover.above::before {
+  top: auto;
+  bottom: -5px;
+  border-left: none;
+  border-top: none;
+  border-right: 1px solid var(--glass-border);
+  border-bottom: 1px solid var(--glass-border);
+}
+
+/* Open state */
+.glossary-hint.open .glossary-popover {
+  display: block;
+}
+
+/* Mobile: full width */
+@media (max-width: 768px) {
+  .glossary-popover {
+    position: fixed;
+    left: 16px;
+    right: 16px;
+    top: auto;
+    bottom: calc(var(--bottom-nav-h) + 16px);
+    transform: none;
+    width: auto;
+    max-width: none;
+  }
+  .glossary-popover::before {
+    display: none;
+  }
+}