From ac94208d8ffb55da439f3012c82022e41bb4af28 Mon Sep 17 00:00:00 2001
From: Michael <michael.dombaugh@gmail.com>
Date: Tue, 2 Jun 2026 18:07:33 +0000
Subject: [PATCH] chore: production-readiness sweep on the help-popover wave
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Drop unused 'from src.i18n import t' from pages 1-9 (the swap to
  render_tool_header(tool_id) means no page calls t() directly anymore).
  Pages 10, 11 and the underscore-prefixed pages were already clean or
  legitimately use t().

- Rewrite PDF Extractor help_md (en + es). The original prose described
  features the tool does NOT have — template drawing, per-source saved
  templates, automatic reuse. The actual tool is a heuristic batch
  scanner (per its own docstring: "No templates, no per-bank
  configuration"). New copy: scan → uncheck → pick date format → enable
  OCR if needed → download. Spanish version tagged with
  '<!-- TODO: review Spanish -->' since the prose is best-effort.

- Document why both stSidebarNavSectionHeader (legacy, streamlit~=1.35)
  and stNavSectionHeader (current, 1.57) testids appear in the chrome
  CSS — requirements floor is streamlit>=1.35,<2 so dropping the legacy
  selector would silently break the lower bound.

- Pin the t()-returns-key-on-miss contract that render_tool_header's
  fallback path depends on, with a comment at the call site.

- Pin the demo's intentional skip of hide_streamlit_chrome (so the
  +/- sidebar swap JS doesn't ever try to load there) with a load-
  bearing comment in app_demo.py.

- Confirmed i18n parity: every tool id has page_title / page_caption /
  description / name / help_md in BOTH packs; help.button_label and
  help.missing_body in both.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 src/gui/app_demo.py                    |  9 +++++++++
 src/gui/components/_legacy.py          | 18 +++++++++++++++++-
 src/gui/pages/1_Deduplicator.py        |  1 -
 src/gui/pages/2_Text_Cleaner.py        |  1 -
 src/gui/pages/3_Format_Standardizer.py |  1 -
 src/gui/pages/4_Missing_Values.py      |  1 -
 src/gui/pages/5_Column_Mapper.py       |  1 -
 src/gui/pages/6_Outlier_Detector.py    |  1 -
 src/gui/pages/7_Multi_File_Merger.py   |  1 -
 src/gui/pages/8_Validator_Reporter.py  |  1 -
 src/gui/pages/9_Pipeline_Runner.py     |  1 -
 src/i18n/packs/en.json                 |  2 +-
 src/i18n/packs/es.json                 |  2 +-
 13 files changed, 28 insertions(+), 12 deletions(-)

diff --git a/src/gui/app_demo.py b/src/gui/app_demo.py
index 0bdb6e6..80d18cb 100644
--- a/src/gui/app_demo.py
+++ b/src/gui/app_demo.py
@@ -132,6 +132,15 @@ st.set_page_config(
 
 # Strip Streamlit chrome that breaks the iframe-embed look on the
 # landing pages.
+#
+# We deliberately do NOT call ``hide_streamlit_chrome()`` from the
+# paid GUI here — that helper drags in the license gate, the sidebar
+# brand block, language selector, and the +/- nav-section indicator
+# script. The demo has no sidebar (we hide it below), no licensing
+# (it's the marketing surface), and a different visual palette (dark
+# theme vs. the paid app's cream paper). Keep this hand-rolled chrome
+# in sync with the demo's own dark palette; do NOT replace it with
+# the paid GUI's chrome helper.
 st.markdown("""
 <style>
 #MainMenu, footer, header { visibility: hidden; }
diff --git a/src/gui/components/_legacy.py b/src/gui/components/_legacy.py
index 47a0125..bb09d3d 100644
--- a/src/gui/components/_legacy.py
+++ b/src/gui/components/_legacy.py
@@ -279,7 +279,13 @@ body, .stApp {
    with class ``st-emotion-cache-…`` inside ``stSidebarNav`` — class
    hashes are unstable across versions, so we lean on the structural
    position (the bare span / h2 directly inside the nav list) rather
-   than emotion classes. */
+   than emotion classes.
+   ``stSidebarNavSectionHeader`` is the LEGACY testid used by
+   Streamlit ~1.35; current Streamlit emits ``stNavSectionHeader``
+   (handled by the dedicated block further down). Both are kept in
+   the selector list because the requirements floor is
+   ``streamlit>=1.35,<2`` — dropping the legacy testid would break
+   the visual treatment on the lower bound. */
 [data-testid="stSidebarNav"] h2,
 [data-testid="stSidebarNav"] h3,
 [data-testid="stSidebarNavSeparator"] span,
@@ -316,6 +322,9 @@ body, .stApp {
 [data-testid="stSidebarNavItems"] > li {
     margin-bottom: 1px !important;
 }
+/* Legacy testid — kept for streamlit~=1.35 (see note above). The
+   tighter padding for the current ``stNavSectionHeader`` is set in
+   the dedicated block further down. */
 [data-testid="stSidebarNavSectionHeader"] {
     padding-top: 10px !important;
     padding-bottom: 2px !important;
@@ -2168,6 +2177,13 @@ def render_tool_header(tool_id: str) -> None:
         # button floats above the big title text.
         st.write("")
         body = _t(f"tools.{tool_id}.help_md")
+        # ``src.i18n.t`` falls back to returning the lookup key itself
+        # on miss (see ``_resolve`` → key-as-string fallback). That's
+        # what we detect here: any tool whose ``help_md`` entry is
+        # absent from both en + es packs shows the generic missing-body
+        # string instead of the raw dotted key. Real help_md content
+        # in the packs starts with ``**When to use**``-style markdown,
+        # so this prefix check is safe.
         if body.startswith("tools."):
             body = _t("help.missing_body")
         with st.popover(
diff --git a/src/gui/pages/1_Deduplicator.py b/src/gui/pages/1_Deduplicator.py
index 2e17329..8c6168c 100644
--- a/src/gui/pages/1_Deduplicator.py
+++ b/src/gui/pages/1_Deduplicator.py
@@ -29,7 +29,6 @@ from src.gui.components import (
     require_feature_or_render_upgrade,
     results_summary,
 )
-from src.i18n import t
 from src.license import FeatureFlag
 
 hide_streamlit_chrome()
diff --git a/src/gui/pages/2_Text_Cleaner.py b/src/gui/pages/2_Text_Cleaner.py
index 3acea63..6e75874 100644
--- a/src/gui/pages/2_Text_Cleaner.py
+++ b/src/gui/pages/2_Text_Cleaner.py
@@ -24,7 +24,6 @@ from src.gui.components import (
     render_hidden_aware_preview,
     require_feature_or_render_upgrade,
 )
-from src.i18n import t
 from src.license import FeatureFlag
 from src.core.text_clean import (
     PRESETS,
diff --git a/src/gui/pages/3_Format_Standardizer.py b/src/gui/pages/3_Format_Standardizer.py
index e1fedb0..08a5686 100644
--- a/src/gui/pages/3_Format_Standardizer.py
+++ b/src/gui/pages/3_Format_Standardizer.py
@@ -23,7 +23,6 @@ from src.gui.components import (
     pickup_or_upload,
     require_feature_or_render_upgrade,
 )
-from src.i18n import t
 from src.core.format_standardize import (
     PRESETS,
     FieldType,
diff --git a/src/gui/pages/4_Missing_Values.py b/src/gui/pages/4_Missing_Values.py
index 2e4a721..e425fd0 100644
--- a/src/gui/pages/4_Missing_Values.py
+++ b/src/gui/pages/4_Missing_Values.py
@@ -23,7 +23,6 @@ from src.gui.components import (
     pickup_or_upload,
     require_feature_or_render_upgrade,
 )
-from src.i18n import t
 from src.core.missing import (
     DEFAULT_SENTINELS,
     MissingOptions,
diff --git a/src/gui/pages/5_Column_Mapper.py b/src/gui/pages/5_Column_Mapper.py
index bc57383..286f43d 100644
--- a/src/gui/pages/5_Column_Mapper.py
+++ b/src/gui/pages/5_Column_Mapper.py
@@ -23,7 +23,6 @@ from src.gui.components import (
     pickup_or_upload,
     require_feature_or_render_upgrade,
 )
-from src.i18n import t
 from src.core.column_mapper import (
     MapOptions,
     PRESETS,
diff --git a/src/gui/pages/6_Outlier_Detector.py b/src/gui/pages/6_Outlier_Detector.py
index 7ba116e..75bc6b0 100644
--- a/src/gui/pages/6_Outlier_Detector.py
+++ b/src/gui/pages/6_Outlier_Detector.py
@@ -18,7 +18,6 @@ from src.gui.components import (
     hide_streamlit_chrome,
     require_feature_or_render_upgrade,
 )
-from src.i18n import t
 from src.license import FeatureFlag
 
 hide_streamlit_chrome()
diff --git a/src/gui/pages/7_Multi_File_Merger.py b/src/gui/pages/7_Multi_File_Merger.py
index 2db0434..2441c07 100644
--- a/src/gui/pages/7_Multi_File_Merger.py
+++ b/src/gui/pages/7_Multi_File_Merger.py
@@ -18,7 +18,6 @@ from src.gui.components import (
     hide_streamlit_chrome,
     require_feature_or_render_upgrade,
 )
-from src.i18n import t
 from src.license import FeatureFlag
 
 hide_streamlit_chrome()
diff --git a/src/gui/pages/8_Validator_Reporter.py b/src/gui/pages/8_Validator_Reporter.py
index f86c122..230b3fe 100644
--- a/src/gui/pages/8_Validator_Reporter.py
+++ b/src/gui/pages/8_Validator_Reporter.py
@@ -18,7 +18,6 @@ from src.gui.components import (
     hide_streamlit_chrome,
     require_feature_or_render_upgrade,
 )
-from src.i18n import t
 from src.license import FeatureFlag
 
 hide_streamlit_chrome()
diff --git a/src/gui/pages/9_Pipeline_Runner.py b/src/gui/pages/9_Pipeline_Runner.py
index 97b4d65..7eb400c 100644
--- a/src/gui/pages/9_Pipeline_Runner.py
+++ b/src/gui/pages/9_Pipeline_Runner.py
@@ -23,7 +23,6 @@ from src.gui.components import (
     pickup_or_upload,
     require_feature_or_render_upgrade,
 )
-from src.i18n import t
 from src.core.pipeline import (
     Pipeline,
     SOFT_DEPENDENCIES,
diff --git a/src/i18n/packs/en.json b/src/i18n/packs/en.json
index 637ac0e..f814545 100644
--- a/src/i18n/packs/en.json
+++ b/src/i18n/packs/en.json
@@ -177,7 +177,7 @@
       "description": "Pull transactions out of bank-statement PDFs into a clean CSV file.",
       "page_title": "PDF to CSV",
       "page_caption": "Pull transactions out of bank-statement PDFs into a clean CSV file.",
-      "help_md": "**When to use**\n- Bank or credit-card statements\n- Vendor invoices with line-item tables\n- Any PDF with a transaction table\n\n**Steps**\n1. Upload a PDF\n2. Draw a box around the table (once per source)\n3. Save the template (e.g. `Chase Checking`)\n4. Reuse the template on every future statement of that type\n5. Export the CSV\n\n**Examples**\n- Chase March statement → 87 transactions extracted\n- Same template auto-runs on April, May, June\n- Batch mode: process 12 months at once\n\n**Tip** Templates are per source (Chase, Wells Fargo, …). Build one per source you receive regularly."
+      "help_md": "**When to use**\n- Bank or credit-card statements\n- Vendor invoices with line-item tables\n- Any PDF with a transaction table\n\n**Steps**\n1. Upload one or more PDFs (batch is fine)\n2. Click **Scan** — rows that look like transactions are pulled out automatically\n3. Uncheck any rows you don't want\n4. Pick your date format (and turn on OCR if the PDF is a scanned image)\n5. Download the CSV\n\n**Examples**\n- Chase March statement → 87 transactions found\n- Drop in 12 months at once and get one combined CSV\n- Image-only scan + OCR → still works if Tesseract is installed\n\n**Tip** If a withdrawal shows as `(4.50)`, leave **Treat (4.50) as negative** on. Turn it off only if your statements use a different convention."
     },
     "11_reconciler": {
       "name": "Reconcile Two Files",
diff --git a/src/i18n/packs/es.json b/src/i18n/packs/es.json
index b6e8f59..ce7a9f4 100644
--- a/src/i18n/packs/es.json
+++ b/src/i18n/packs/es.json
@@ -177,7 +177,7 @@
       "description": "Extrae transacciones de extractos bancarios en PDF a un archivo CSV limpio.",
       "page_title": "PDF a CSV",
       "page_caption": "Extrae transacciones de extractos bancarios en PDF a un archivo CSV limpio.",
-      "help_md": "**Cuándo usarlo**\n- Extractos bancarios o de tarjeta\n- Facturas de proveedor con tablas\n- Cualquier PDF con tabla de transacciones\n\n**Pasos**\n1. Sube un PDF\n2. Dibuja un recuadro alrededor de la tabla (una vez por fuente)\n3. Guarda la plantilla (p. ej. `Chase Cuenta`)\n4. Reutiliza la plantilla en los siguientes extractos del mismo tipo\n5. Exporta el CSV\n\n**Ejemplos**\n- Extracto Chase de marzo → 87 transacciones extraídas\n- La misma plantilla se ejecuta sola en abril, mayo, junio\n- Modo lote: procesa 12 meses de una vez\n\n**Consejo** Las plantillas son por fuente (Chase, Wells Fargo…). Crea una por cada banco que recibas con regularidad."
+      "help_md": "<!-- TODO: review Spanish -->\n**Cuándo usarlo**\n- Extractos bancarios o de tarjeta\n- Facturas de proveedor con tablas\n- Cualquier PDF con tabla de transacciones\n\n**Pasos**\n1. Sube uno o más PDFs (modo lote permitido)\n2. Pulsa **Escanear** — las filas que parecen transacciones se extraen automáticamente\n3. Desmarca las filas que no quieras\n4. Elige el formato de fecha (y activa OCR si el PDF es una imagen escaneada)\n5. Descarga el CSV\n\n**Ejemplos**\n- Extracto Chase de marzo → 87 transacciones detectadas\n- Procesa 12 meses de una vez y obtén un CSV combinado\n- PDF solo-imagen + OCR → funciona si Tesseract está instalado\n\n**Consejo** Si un cargo aparece como `(4,50)`, deja activado **Tratar (4,50) como negativo**. Desactívalo solo si tus extractos usan otra convención."
     },
     "11_reconciler": {
       "name": "Reconciliar dos archivos",