[codex] Complete Dash/Plotly migration, parity remediation, and runtime/library stabilization

.ai/AGENTS.md

@@ -0,0 +1,86 @@
+# Agent Workflow Guide
+
+This repository uses a context-first vibecoding workflow.
+
+## Primary operating model
+
+- Prefer one primary agent per task.
+- Do not simulate a company org chart such as PM -> Architect -> Developer -> QA handoffs.
+- If parallel exploration is needed, use it only to gather alternatives or inspect different parts of the codebase, then merge the findings back into one implementation path.
+- Preserve continuity through repository files, not chat memory.
+
+## Files to read before making changes
+
+Read these before planning or editing code:
+
+1. `README.md`
+2. `AGENTS.md`
+3. `.ai/SESSION.md`
+4. `.ai/TASK.md`
+5. `.ai/DECISIONS.md`
+6. `Cursor.md`
+
+If one of these files is missing or clearly stale, say so explicitly.
+
+## Required pre-change behavior
+
+Before changing code:
+
+1. Read the relevant context files.
+2. Inspect the files most likely involved in the task.
+3. Summarize your understanding in 5 bullets.
+4. State assumptions, risks, and missing information.
+5. Propose the smallest useful next step.
+
+Do not start with a broad rewrite when a smaller validated slice is possible.
+
+## Implementation rules
+
+- Prefer small, testable patches over large rewrites.
+- Reuse existing patterns before inventing new abstractions.
+- Keep functions and modules focused.
+- Avoid touching unrelated modalities unless the task requires it.
+- Explain why a structural change is necessary before making it.
+- Preserve working flows while extending unfinished ones.
+
+## Verification rules
+
+After a meaningful code change:
+
+- Check for import errors.
+- Check the directly affected execution path.
+- Note likely regressions or edge cases.
+- Report what was verified and what was not verified.
+
+## Handoff rules
+
+At the end of a meaningful work session, update:
+
+- `.ai/SESSION.md` with current status, blockers, next step, and touched files.
+- `.ai/DECISIONS.md` with any durable technical decision and the reason for it.
+
+Keep those files short, current, and specific.
+
+## Task sizing
+
+Break work into slices with clear acceptance criteria.
+
+Good:
+- add DTA page shell
+- wire upload flow
+- render first valid plot
+- add invalid-file error path
+
+Bad:
+- finish entire Dash migration
+
+## Review mode
+
+When asked to review, critique, or verify:
+
+- look for broken assumptions
+- identify edge cases
+- name regression risks
+- suggest the smallest correction first
+
+Do not default to rewriting everything.

.ai/BUGS.md

@@ -0,0 +1,285 @@
+# Bugs — MaterialScope
+
+Tracked defects and suspected problems. **Root cause is never “proven” here without evidence**—update fields as facts change.
+
+## Status definitions (use exactly these meanings)
+
+
+| Status        | Meaning                                                                                      |
+| ------------- | -------------------------------------------------------------------------------------------- |
+| **Suspected** | Not yet reproduced or otherwise confirmed; hypothesis or report only.                        |
+| **Open**      | Reproduced **or** otherwise confirmed; **not fixed** yet.                                    |
+| **Fixed**     | A fix **was applied**; still **needs verification** (tests and/or agreed manual check).      |
+| **Closed**    | Fix **verified**; no further work on this entry unless it regresses (then open a new entry). |
+
+
+Do **not** use alternate labels (e.g. “mitigated”, “in progress”) in new entries—fold that into **Open** or **Fixed** per the table.
+
+**Workflow / verification discipline:** `**.cursor/rules/00-workflow.mdc`**.
+
+---
+
+## Entry template (copy below the line)
+
+```
+### Title
+<short name>
+
+### Status
+Suspected | Open | Fixed | Closed
+
+### Symptoms
+Observable facts only.
+
+### Repro steps
+Numbered steps; note branch/environment/data when relevant.
+
+### Likely cause
+Hypotheses; update after evidence.
+
+### Files involved
+Known paths, or “unknown until traced”.
+
+### Next check
+Smallest test, log, or experiment to advance status.
+```
+
+---
+
+## BUG-006 — i18n key namespace leakage across DSC, DTA, TGA Dash pages
+
+### Title
+
+DSC/DTA processing history labels borrowed TGA i18n keys; TGA quality/metadata/summary labels borrowed DSC keys
+
+### Status
+
+**Closed**
+
+### Symptoms
+
+- DSC processing history card showed TGA-namespaced keys (`dash.analysis.tga.processing.*`) for history title, undo button, status text.
+- DTA processing history card used the same TGA-namespaced keys.
+- TGA quality card, raw metadata panel, and analysis summary used DSC-namespaced keys (`dash.analysis.dsc.quality.*`, `dash.analysis.dsc.raw_metadata.*`, `dash.analysis.dsc.summary.*`).
+- TR locale users would see correct translations only if the borrowed namespace happened to have the same values; semantically incorrect ownership.
+
+### Repro steps
+
+1. Open DSC analysis page; switch locale to TR; observe processing history labels.
+2. Check source: `rg "dash.analysis.tga.processing." dash_app/pages/dsc.py dash_app/pages/dta.py`.
+3. Open TGA analysis page; observe quality card and metadata labels.
+4. Check source: `rg "dash.analysis.dsc.quality." dash_app/pages/tga.py`.
+
+### Likely cause
+
+During initial DSC/DTA history card implementation, TGA processing history i18n keys were reused as a shortcut. During TGA page buildout, DSC quality/metadata/summary keys were reused similarly. No regression tests existed to catch cross-namespace borrowing.
+
+### Files involved
+
+- `utils/i18n.py` — 28 new keys added (7 DSC, 7 DTA, 5 TGA quality, 3 TGA raw metadata, 6 TGA summary)
+- `dash_app/pages/dsc.py` — 7 key references swapped
+- `dash_app/pages/dta.py` — 7 key references swapped
+- `dash_app/pages/tga.py` — 18 key references swapped
+- `tests/test_dsc_dash_page.py` — 2 new regression tests
+- `tests/test_dta_dash_page.py` — 2 new regression tests
+- `tests/test_tga_dash_page.py` — 2 new regression tests
+
+### Next check
+
+Regression tests now guard against re-introduction: source-grep tests assert no leaked namespace literals; monkeypatch tests assert correct namespace in rendered output.
+
+---
+
+## BUG-001 — Possible parity gaps during Streamlit → Dash migration
+
+### Title
+
+Possible parity / behavior gaps between legacy Streamlit flows and Dash + Plotly surfaces
+
+### Status
+
+**Suspected**
+
+### Symptoms
+
+Users **may** see mismatches (missing views, different defaults, divergent plots/metrics, inconsistent file/workspace handling) **if** Streamlit and Dash paths diverge. No specific workflow is confirmed in this entry.
+
+### Repro steps
+
+1. Pick a workflow that **actually exists** on both paths (verify in app/docs).
+2. Same inputs (project, files, settings); compare outputs/affordances; record differences.
+
+*(If no dual path exists, note that—do not force a repro.)*
+
+### Likely cause
+
+**Unknown** until a concrete case exists; candidates include UI duplication, incomplete callbacks, API differences, or intentionally deferred features.
+
+### Files involved
+
+**Unknown** until traced; usual suspects live under `dash_app/`, `backend/`, `core/`, and any remaining Streamlit entrypoints—confirm, do not guess.
+
+### Next check
+
+One workflow: document parity with evidence, **or** promote a **narrow** child entry to **Open** with a confirmed repro and file pointers.
+
+---
+
+## BUG-002 — Saved analysis figures missing in exports/project persistence
+
+### Title
+
+Saved results intermittently lacked persisted analysis figures in shared state
+
+### Status
+
+**Closed**
+
+### Symptoms
+
+- Graph visible in Dash analysis page but missing in exported PDF/DOCX.
+- Saved result artifacts lacked reliable figure linkage.
+- Project save/load did not consistently carry figure payloads forward.
+
+### Repro steps
+
+1. Run real Dash app (`python -m dash_app.server`) on branch `web-dash-plotly-migration`.
+2. Execute analysis and save result.
+3. Export report (DOCX/PDF) and inspect figure presence.
+4. Save/load project and check `figure_count` + result artifacts linkage.
+
+### Likely cause
+
+Shared figure persistence depended too heavily on UI capture callback success; backend save path did not guarantee figure registration at result-save time.
+
+### Files involved
+
+- `backend/app.py`
+- `core/figure_render.py`
+- `dash_app/components/analysis_page.py`
+- `dash_app/pages/dta.py`
+
+### Next check
+
+Monitor for regressions in additional modalities during future Dash slices.
+
+---
+
+## BUG-003 — Branding logo upload lacked immediate pre-save feedback
+
+### Title
+
+No immediate UI confirmation after logo selection before Save Branding
+
+### Status
+
+**Closed**
+
+### Symptoms
+
+- Selecting a logo file showed no visible uploaded/selected state until Save Branding completed.
+
+### Repro steps
+
+1. Open Export page branding panel.
+2. Select a logo file in upload control.
+3. Observe no pending selection indicator before saving.
+
+### Likely cause
+
+Preview area was populated only by backend-loaded persisted branding state; no callback rendered pending upload contents.
+
+### Files involved
+
+- `dash_app/pages/export.py`
+
+### Next check
+
+Keep pending/saved branding distinction consistent if additional branding fields get staged UI behavior.
+
+---
+
+## BUG-004 — FTIR science chain produced misleading baseline, flat normalized trace, and silent zero peaks
+
+### Title
+
+FTIR preprocessing / peak detection / matching produced scientifically misleading results without diagnostic context
+
+### Status
+
+**Closed**
+
+### Symptoms
+
+- Baseline was a straight line between first and last data points even for `asls`/`rubberband` methods, producing obviously wrong sloped baselines.
+- Normalization could collapse into a near-flat line around zero with no explanation.
+- Peak count was 0 for transmittance data because troughs were never inverted.
+- Query / smoothed / normalized traces were semantically misaligned (peak detection ran on normalized even when it was broken).
+- No diagnostic context when preprocessing failed; "No Match" hid deeper science problems.
+
+### Repro steps
+
+1. Import FTIR dataset with transmittance unit or with strong spectral features.
+2. Run analysis with default `ftir.general` template.
+3. Observe baseline overlay, normalized trace, and peak count in results.
+
+### Likely cause
+
+- `_estimate_spectral_baseline` claimed to support `asls`/`rubberband` but only drew a linear line.
+- `_normalize_spectral_signal` had no guard-rails for zero-range or near-flat input.
+- No absorbance/transmittance role detection; pipeline always looked for positive maxima.
+- `_detect_spectral_peaks` used a hand-rolled local-maximum scanner instead of `scipy.signal.find_peaks`.
+- Failure modes were silent; no diagnostics propagated to validation or UI.
+
+### Files involved
+
+- `core/batch_runner.py`
+- `backend/library_cloud_service.py`
+- `backend/models.py`
+- `backend/app.py`
+- `dash_app/pages/ftir.py`
+
+### Next check
+
+Monitor for regressions in Raman (shares `_execute_spectral_batch`) and future peak-detector extensions.
+
+---
+
+## BUG-005 — Raman Dash inherited generic literature/reasoning path and FTIR warning wording
+
+### Title
+
+Raman used generic scientific-context path and could surface FTIR-labelled spectral warnings
+
+### Status
+
+**Closed**
+
+### Symptoms
+
+- Raman literature compare path did not use Raman-specialized query/compare semantics.
+- Raman scientific context could fall back to generic placeholder reasoning.
+- Shared spectral warnings could contain FTIR-prefixed wording on Raman runs.
+
+### Repro steps
+
+1. Run Raman analysis and inspect literature context/reasoning payload outputs.
+2. Trigger warning-producing Raman spectral conditions (e.g., baseline suppression / normalization skip).
+3. Observe terminology and dispatch behavior.
+
+### Likely cause
+
+Raman was still wired through generic literature/reasoning branches in core logic, and shared spectral warning strings were hardcoded with FTIR label text.
+
+### Files involved
+
+- `core/raman_literature_query_builder.py`
+- `core/literature_compare.py`
+- `core/scientific_reasoning.py`
+- `core/batch_runner.py`
+- `dash_app/pages/raman.py`
+- `utils/i18n.py`
+
+### Next check
+
+Covered by targeted tests for Raman Dash page, literature compare, and scientific reasoning; watch for regressions when shared spectral helpers change.