diff --git a/.claude/hooks/language_check.py b/.claude/hooks/language_check.py
new file mode 100644
index 00000000..a32491ba
--- /dev/null
+++ b/.claude/hooks/language_check.py
@@ -0,0 +1,246 @@
+#!/usr/bin/env python3
+"""Stop hook: does the final message contain vocabulary the user never reads?
+
+**Log-only for now. It blocks nothing.** The patterns it carries were measured
+against saved build screens, not live messages, and every checker written for
+this framework so far has needed two to five corrections before it stopped
+misfiring. Doing that in front of a user is not acceptable, so the first
+deployment records what it *would* have blocked and lets the turn through.
+
+To enforce, set "enforce": true in .claude/language.json. The hook then exits 2
+with the offending term, which feeds back to the model as a reason to restate --
+it cannot rewrite the message silently, only ask for another.
+
+Known false positive, unfixed on purpose: the rules govern volunteered
+narration, and CONTEXT.md is explicit that "none of this governs what you say
+when asked directly." A user who asks what the gate is should get an answer
+containing the word. The log will show how often that happens before anything
+starts blocking on it.
+"""
+import json
+import re
+import sys
+from datetime import datetime
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+CATALOG = ROOT / ".claude" / "language.json"
+LOG = ROOT / ".claude" / "language-violations.jsonl"
+BEAT = ROOT / ".claude" / "language-check-ran"
+
+
+# The evaluation harness interviews a finished build about how it went. Those
+# answers are addressed to the harness, not to the user, and discuss the
+# framework's own mechanics by design -- the first violation this hook ever
+# logged was a debrief answer naming `interview` and `preflight`, which is
+# correct English for what it was doing. Enforcing here would have blocked every
+# debrief and read as the model failing to comply.
+#
+# The harness writes this marker into the session before it asks anything, so
+# the boundary is already in the transcript. Real users never see it.
+DEBRIEF_MARKER = "DEBRIEF-BEGIN-8f2c1a"
+
+
+def in_debrief(transcript: Path) -> bool:
+    """Has the harness started interviewing this session?
+
+    The marker has to be found in something the *user* said. It used to be a
+    substring test over the whole file, and this file is tracked -- so it ships
+    into every build's clone, and a session that read its own hook would put the
+    marker in a tool result and exempt itself from every check for the rest of
+    the run, silently and with a clean log. No build has done it (0 of 61 read
+    .claude/hooks at all), which is why it was still here to find rather than
+    something already lost.
+
+    The harness sends the debrief as user input. Reading a file does not.
+    """
+    try:
+        lines = transcript.read_text(encoding="utf-8",
+                                     errors="replace").splitlines()
+    except OSError:
+        return False
+    for line in lines:
+        line = line.strip()
+        if not line or DEBRIEF_MARKER not in line:
+            continue
+        try:
+            event = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if event.get("type") != "user":
+            continue
+        content = (event.get("message") or {}).get("content")
+        if isinstance(content, str):
+            if DEBRIEF_MARKER in content:
+                return True
+        elif isinstance(content, list):
+            for b in content:
+                # A tool result is carried inside a user event too, and that is
+                # exactly the path a file read takes. Only spoken text counts.
+                if isinstance(b, dict) and b.get("type") == "text"                         and DEBRIEF_MARKER in (b.get("text") or ""):
+                    return True
+    return False
+
+
+def last_assistant_text(transcript: Path) -> str:
+    """The final assistant message, which is what the user just read."""
+    said: list = []
+    for line in transcript.read_text(encoding="utf-8", errors="replace").splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            event = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        kind = event.get("type")
+        content = (event.get("message") or {}).get("content")
+
+        if kind == "user":
+            spoke = False
+            if isinstance(content, str) and content.strip():
+                spoke = True
+            elif isinstance(content, list):
+                spoke = any(isinstance(b, dict) and b.get("type") == "text"
+                            and (b.get("text") or "").strip() for b in content)
+            if spoke:
+                said = []          # a new turn begins; the rest is read
+            continue
+
+        if kind != "assistant":
+            continue
+        if isinstance(content, str):
+            if content.strip():
+                said.append(content)
+        elif isinstance(content, list):
+            parts = [b.get("text", "") for b in content
+                     if isinstance(b, dict) and b.get("type") == "text"]
+            if any(p.strip() for p in parts):
+                said.append("\n".join(parts))
+        # Asking IS the boundary. In a driven build the answer to an
+        # AskUserQuestion comes back as a tool result, not as typed text,
+        # so resetting only on a typed message left the whole build as one
+        # unbroken turn: 0907-0518-t3q reported the same two sentences five
+        # times, once per later question. What the reader has in front of
+        # them when a question appears is what was said since the previous
+        # question -- so the last one recorded ends the stretch.
+        if isinstance(content, list) and any(
+                isinstance(b, dict) and b.get("type") == "tool_use"
+                and b.get("name") == "AskUserQuestion" for b in content):
+            said = []
+    return "\n".join(said)
+
+
+def beat(event: str = "?") -> None:
+    """Record that the hook ran, before anything can return early.
+
+    This is proof of invocation, so it must not sit behind a check that can
+    skip it. Placed after the transcript checks it recorded one turn out of
+    eight -- the other seven returned early and looked identical to the hook
+    never having run, which is the exact ambiguity it exists to remove. That
+    was diagnosed once and left in place; this is the correction.
+    """
+    try:
+        n = 0
+        if BEAT.exists():
+            n = int(BEAT.read_text(encoding="utf-8").split()[0] or 0)
+        BEAT.write_text(f"{n + 1} turns checked ({event}), last "
+                        f"{datetime.now().isoformat(timespec='seconds')}\n",
+                        encoding="utf-8")
+    except Exception:
+        pass
+
+
+def main() -> int:
+    # Read first, then beat -- the beat records which event fired, and a
+    # payload that fails to parse still gets a beat below.
+    try:
+        payload = json.loads(sys.stdin.read() or "{}")
+    except json.JSONDecodeError:
+        beat("unparseable")
+        return 0
+    beat(payload.get("hook_event_name") or "?")
+
+    transcript = payload.get("transcript_path")
+    if not transcript or not Path(transcript).exists() or not CATALOG.exists():
+        return 0
+
+    try:
+        catalog = json.loads(CATALOG.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return 0
+    if in_debrief(Path(transcript)):
+        return 0          # answers to the harness, not to the user
+
+    said = last_assistant_text(Path(transcript))
+
+    # On `Stop` the turn ended in prose and that prose is the whole of what
+    # the user read. On `PreToolUse`/`AskUserQuestion` the turn ends in a
+    # question, and the question -- its header, its option labels, their
+    # descriptions -- is read just as closely as the narration above it. A
+    # `Stop` hook never sees either half: measured over the last twelve
+    # builds, every one of the 34 vocabulary and setup findings sat on a
+    # screen that ended in a question or in setup, and none on a screen the
+    # `Stop` hook could reach.
+    if payload.get("tool_name") == "AskUserQuestion":
+        parts = [said]
+        for q in (payload.get("tool_input") or {}).get("questions") or []:
+            parts.append(str(q.get("question") or ""))
+            parts.append(str(q.get("header") or ""))
+            for opt in q.get("options") or []:
+                parts.append(str(opt.get("label") or ""))
+                parts.append(str(opt.get("description") or ""))
+        said = chr(10).join(x for x in parts if x)
+
+    if not said.strip():
+        return 0
+
+    hits = []
+    for flags, key in ((re.I, "case_insensitive"), (0, "case_sensitive")):
+        for pattern, instead in catalog.get(key, {}).items():
+            try:
+                found = list(re.finditer(pattern, said, flags))
+            except re.error:
+                continue          # one bad pattern must not silence the rest
+            for m in found:
+                hits.append({"term": m.group(0), "instead": instead})
+
+    if not hits:
+        return 0
+
+    try:
+        with LOG.open("a", encoding="utf-8") as fh:
+            fh.write(json.dumps({
+                "at": datetime.now().isoformat(timespec="seconds"),
+                "session": payload.get("session_id", ""),
+                "event": payload.get("hook_event_name", ""),
+                "tool": payload.get("tool_name", ""),
+                "hits": hits,
+                "said": said[:400],
+            }, ensure_ascii=False) + "\n")
+    except Exception:
+        pass
+
+    if not catalog.get("enforce"):
+        return 0
+
+    terms = ", ".join(sorted({h["term"] for h in hits}))
+    instead = "; ".join(sorted({h["instead"] for h in hits}))
+    print(f"That turn used vocabulary the user never reads: {terms}. "
+          f"Say instead: {instead}. Restate it in their terms.", file=sys.stderr)
+    return 2
+
+
+if __name__ == "__main__":
+    # A hook that raises fires on every turn. This one guards the session; it
+    # must not be able to damage it. A bad regex, an unreadable catalog, a
+    # transcript in an unexpected shape -- none of those are reasons to
+    # interrupt the user, so anything unhandled means "allow" rather than
+    # "crash". The only non-zero exit this file may produce is the deliberate
+    # 2 from an enforced violation.
+    try:
+        sys.exit(main())
+    except SystemExit:
+        raise
+    except BaseException:
+        sys.exit(0)
diff --git a/.claude/language.json b/.claude/language.json
new file mode 100644
index 00000000..02386351
--- /dev/null
+++ b/.claude/language.json
@@ -0,0 +1,29 @@
+{
+  "_comment": [
+    "The vocabulary a user never reads. One source of truth: the Stop hook",
+    "in .claude/hooks/language_check.py enforces it.",
+    "Each entry maps a pattern to what the user should read instead."
+  ],
+  "case_insensitive": {
+    "\\bharvest(?:ed|ing)?\\b": "your notebook already tested this -- I'll reuse its numbers",
+    "\\bcell class(?:es)?\\b": "what each step does",
+    "\\bdemo shortcut\\b": "quote the line: `df.head(5)`, cell 9",
+    "\\bgolden value(?:s)?\\b": "checked it still gives your notebook's answers",
+    "\\bthe probe\\b": "measuring what each setting does",
+    "\\bmasking\\b|\\bmasked by\\b": "these two interact",
+    "\\bfilter_defaults\\b|\\blink identifier\\b": "which spectrum the plot opens on",
+    "\\bthe gate\\b|\\bgate (?:passed|failed|found)\\b": "(say the finding, not the check)",
+    "\\bscreenshot\\b": "(say nothing -- open their browser)",
+    "\\bWorkflowManager\\b|\\bpython tool\\b|\\bstage skill\\b": "(internal -- name the page or the analysis)",
+    "\\bAppTest\\b|\\biframe\\b|\\bInsight component\\b": "the panel",
+    "\\bdesign round\\b|\\binterview\\b|\\bpersona\\b": "(internal -- just ask)",
+    "\\bmode=auto\\b|\\bprior evidence\\b|\\bsuggestion axis\\b": "(internal)",
+    "\\bmateriality threshold\\b|\\beffect size\\b": "how much it moves the result",
+    "\\bpreflight\\b": "(say nothing, or: setting up -- a minute)",
+    "\\bbrowser (?:control|setup|side|probe)\\b|\\bdriving the browser\\b": "(internal -- never narrate the browser)"
+  },
+  "case_sensitive": {
+    "\\bHARDCODE\\b|\\bADVANCED\\b|\\bDASHBOARD CONTROL\\b": "keep it / hide it / put it on the results page",
+    "\\bDEFAULTS\\b|\\bOUTPUTS\\b": "the settings / what it produces"
+  }
+}
diff --git a/.claude/settings.json b/.claude/settings.json
new file mode 100644
index 00000000..a66f50bd
--- /dev/null
+++ b/.claude/settings.json
@@ -0,0 +1,38 @@
+{
+  "_comment": [
+    "The Stop hook checks what the last turn said. See",
+    ".claude/hooks/language_check.py; the vocabulary lives in",
+    ".claude/language.json.",
+    "The command probes for an interpreter rather than naming one. Bare",
+    "`python` on a default Windows box is the Microsoft Store stub, which",
+    "prints a notice and EXITS 0 -- so the hook silently never ran and its",
+    "empty log looked exactly like a clean session. An exit-code chain",
+    "cannot catch that, so each candidate is tested by whether it prints.",
+    "The project venv comes first because on such a machine it is the only",
+    "real interpreter present.",
+    "PreToolUse/AskUserQuestion covers what Stop structurally cannot. A Stop hook fires only on a turn that ends in prose; in a build most turns end in a question, and all 34 findings measured across twelve builds sat on those screens. Same script, same catalog, same log."
+  ],
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "for p in \"$CLAUDE_PROJECT_DIR/.venv/Scripts/python.exe\" \"$CLAUDE_PROJECT_DIR/.venv/bin/python\" \"$HOME/.local/bin/python.exe\" \"$HOME/.local/bin/python\" py python3 python; do if [ \"$(\"$p\" -c 'print(1)' 2>/dev/null)\" = \"1\" ]; then \"$p\" \"$CLAUDE_PROJECT_DIR/.claude/hooks/language_check.py\"; exit $?; fi; done; exit 0"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "AskUserQuestion",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "for p in \"$CLAUDE_PROJECT_DIR/.venv/Scripts/python.exe\" \"$CLAUDE_PROJECT_DIR/.venv/bin/python\" \"$HOME/.local/bin/python.exe\" \"$HOME/.local/bin/python\" py python3 python; do if [ \"$(\"$p\" -c 'print(1)' 2>/dev/null)\" = \"1\" ]; then \"$p\" \"$CLAUDE_PROJECT_DIR/.claude/hooks/language_check.py\"; exit $?; fi; done; exit 0"
+          }
+        ]
+      }
+    ]
+  }
+}
\ No newline at end of file
diff --git a/.claude/skills/add-presets.md b/.claude/skills/add-presets/SKILL.md
similarity index 53%
rename from .claude/skills/add-presets.md
rename to .claude/skills/add-presets/SKILL.md
index 1260a0c6..64f8c5db 100644
--- a/.claude/skills/add-presets.md
+++ b/.claude/skills/add-presets/SKILL.md
@@ -1,3 +1,8 @@
+---
+name: add-presets
+description: Use when adding named parameter presets to a TOPP workflow, or when users need one-click parameter sets such as 'High Sensitivity' or 'Fast'.
+---
+
 # Add Parameter Presets
 
 Add or modify parameter presets for a TOPP workflow in `presets.json`.
@@ -25,18 +30,37 @@ Add or modify parameter presets for a TOPP workflow in `presets.json`.
         "algorithm:section:param_name": value
       },
       "_general": {
-        "custom-widget-key": value
+        "custom-widget-key": value,
+        "<script>.py:<param>": value
       }
     }
   }
 }
 ```
 
+**The second `_general` form is the one that gets missed.** `input_python()`
+prefixes every key with the script filename, so a python tool's parameter is
+`my_tool.py:threshold`, not `threshold` — and a preset written against the bare
+name is valid JSON, loads without error, and sets nothing at all.
+
+This was already stated below, in the checklist that verifies a finished
+`presets.json`. Two builds wrote their presets after that was added and still
+derived the form by reading `CommandExecutor.run_python` and
+`ParameterManager.apply_preset` — because a build reads the schema at the moment
+it writes the file, and reads the checklist, if at all, afterwards. So it is
+here, in the block being copied.
+
 4. **Verify the result** by checking that:
    - Workflow name key matches the name passed to `WorkflowManager.__init__()` (lowercased, hyphenated)
    - TOPP tool names match those used in `input_TOPP()` calls
    - Parameter paths use colon-separated format matching the TOPP tool's .ini structure
    - `_general` keys match widget keys from `input_widget()` calls
+- **A python tool's parameters are keyed `<script>.py:<param>`**, still under
+  `_general`. `input_python()` prefixes every key with the script filename, so a
+  preset written against the bare parameter name silently sets nothing. Three
+  builds on three notebooks each derived this by reading
+  `CommandExecutor.run_python` and `ParameterManager.apply_preset`, because this
+  list described `_general` only in terms of `input_widget()`.
    - JSON is valid
 
 ## Schema Rules
@@ -51,6 +75,12 @@ Add or modify parameter presets for a TOPP workflow in `presets.json`.
 ## How Presets Work at Runtime
 
 1. Preset buttons auto-appear in `parameter_section()` via `StreamlitUI.preset_buttons()`
+   — **so never call `preset_buttons()` yourself.** It is the one `ui.*` method
+   the framework already invokes, and the rest of the family being yours to call
+   is exactly why two builds on two notebooks added it to the end of
+   `configure()` anyway. One rendered the presets twice; the other crashed the
+   Configure page on duplicate widget keys. If presets are not appearing, the
+   fault is `presets.json` or the workflow name in it — never a missing call.
 2. Only presets matching the current workflow name are displayed
 3. Clicking a preset updates `params.json` in the workspace and refreshes the UI
 4. If no `presets.json` exists or no presets match, no buttons are shown
@@ -96,3 +126,24 @@ For a workflow initialized as `super().__init__("Feature Analysis", ...)`:
 - [ ] TOPP tool names match exactly
 - [ ] Parameter paths use colon-separated format
 - [ ] `presets.json` is valid JSON
+
+
+## When a preset does not move the widget
+
+The symptom: the preset writes the right values into `params.json`, and the
+number on screen does not change.
+
+The cause is not the preset. `apply_preset` works by *deleting* the matching
+session-state keys so the widgets re-initialise from the file — and a widget
+left at `widget_type="auto"` for a numeric, selectbox or multiselect type
+prefixes its session key twice, so the delete misses it and the stale value
+overwrites the preset on the next rerun.
+
+**The fix is in the parameter, not in the mechanism:** give every parameter a
+preset should drive an explicit `widget_type`. The legal values are `text`,
+`textarea`, `number`, `selectbox`, `slider`, `checkbox`, `multiselect`,
+`password`, `auto` — and anything else renders nothing at all.
+
+Do not rewrite `apply_preset`. It is template code shared with every other app
+built from this template; see `scaffold-workflow-app`, "The template's code is
+not yours to change".
diff --git a/.claude/skills/add-python-tool.md b/.claude/skills/add-python-tool/SKILL.md
similarity index 77%
rename from .claude/skills/add-python-tool.md
rename to .claude/skills/add-python-tool/SKILL.md
index 90e35cb3..2d1a951c 100644
--- a/.claude/skills/add-python-tool.md
+++ b/.claude/skills/add-python-tool/SKILL.md
@@ -1,3 +1,8 @@
+---
+name: add-python-tool
+description: Use when adding a custom Python analysis script to src/python-tools, or when a workflow step needs parameter widgets generated from a DEFAULTS list.
+---
+
 # Add a Python Analysis Tool
 
 Add a custom Python analysis script for MS data processing to `src/python-tools/` with auto-generated UI.
@@ -100,9 +105,19 @@ self.executor.run_python("tool_name", {"in": input_files})
 | `min` | No | number | Minimum value for numeric inputs |
 | `max` | No | number | Maximum value for numeric inputs |
 | `step_size` | No | number | Step size for numeric inputs |
-| `widget_type` | No | str | Override widget type: `"slider"`, `"textarea"`, `"number"`, `"text"`, etc. |
+| `widget_type` | No | str | Exactly one of `text`, `textarea`, `number`, `selectbox`, `slider`, `checkbox`, `multiselect`, `password`, `auto`. **Anything else renders nothing at all** — the dispatch is a run of `elif`s with no final `else` (`StreamlitUI.py:593`). Not Streamlit's function names: `number_input` is not one of these. |
 | `advanced` | No | bool | If `True`, only shown when user expands advanced parameters |
 
+**Every key you name here is stored as `<script>.py:<key>`.** `input_python()`
+prefixes it with the script filename, under `_general`. It matters the moment
+anyone writes a preset or reads `params.json`: a preset written against the bare
+key is valid JSON, loads without error, and sets nothing.
+
+`add-presets` has said this for four builds and four builds derived it again
+from `ParameterManager.apply_preset` and `StreamlitUI.input_python` — because
+they were writing a tool, not reading a preset skill. It is one line, so it
+lives in both places.
+
 ## Reference Files
 
 - Example tool: `src/python-tools/example.py`
diff --git a/.claude/skills/add-visualization.md b/.claude/skills/add-visualization/SKILL.md
similarity index 94%
rename from .claude/skills/add-visualization.md
rename to .claude/skills/add-visualization/SKILL.md
index 075476b1..9d3bce40 100644
--- a/.claude/skills/add-visualization.md
+++ b/.claude/skills/add-visualization/SKILL.md
@@ -1,3 +1,8 @@
+---
+name: add-visualization
+description: Use when adding a plot, chart or mass spectrometry visualization to an OpenMS Streamlit page with pyopenms-viz or plotly.
+---
+
 # Add MS Data Visualization
 
 Add mass spectrometry data visualizations using pyopenms-viz or OpenMS-Insight components.
@@ -116,7 +121,8 @@ def results(self) -> None:
 ## Reference Files
 
 - Display utilities: `src/common/common.py` — `show_fig()`, `show_table()`
-- Dependencies: `requirements.txt` — `pyopenms-viz`, `openms-insight`
+- Dependencies: the **app's** `requirements.txt` — `pyopenms-viz` is in the
+  template's; `openms-insight` is not, and belongs to the app that uses it
 - Example workflow results: `src/Workflow.py` — `results()` method
 
 ## Library Repositories
diff --git a/.claude/skills/build-insight-dashboard/SKILL.md b/.claude/skills/build-insight-dashboard/SKILL.md
new file mode 100644
index 00000000..e4e1f80c
--- /dev/null
+++ b/.claude/skills/build-insight-dashboard/SKILL.md
@@ -0,0 +1,327 @@
+---
+name: build-insight-dashboard
+description: Use when building or changing an OpenMS Streamlit results page with OpenMS-Insight components, when panels must be linked so clicking one filters another, or when a results page needs a table, mirror plot, heatmap or volcano plot.
+---
+
+# Build an Insight dashboard
+
+Turn a processing step's declared `OUTPUTS` into a results page of linked panels.
+Works standalone against an app that already has results.
+
+## The rule
+
+**Build one panel at a time, look at it, and design it with the user before
+building the next.**
+
+## 1. Link graph
+
+**Establish Insight before you map anything.** It is a dependency of the app you
+are building, never of the template — so put it in the app's own
+`requirements.txt`, sync the app's venv, and confirm the import:
+
+```
+ensure   openms-insight>=0.2.0 in <app>/requirements.txt
+sync     the app's .venv from that file
+verify   python -c "import openms_insight"
+```
+
+**Verify by importing, not by assuming.** A run wrote a whole dashboard without
+ever checking, on a machine where the package was absent, because nothing here
+told it to look. The framework had no install step at all: the package is not in
+the template's `requirements.txt` and no skill in the chain added it, so it
+worked only where a venv happened to carry it already.
+
+Then read `OUTPUTS` and map each `role` to its component. **This is a lookup, not
+a judgement:**
+
+| role | component |
+|---|---|
+| `table` | `Table` |
+| `mirror` | `MirrorPlot` |
+| `peakmap` | `Heatmap` |
+| `chromatogram` | *(none — pyopenms-viz)* |
+
+**`LinePlot` is a stick plot, whatever its name says.** Its own docstring reads
+*"Interactive stick plot component"* and *"Stick-style peak visualization
+(vertical lines from baseline)"*. A build read the name, mapped a chromatogram
+onto it, and drew a 156-point elution profile as a comb of 156 vertical bars.
+Insight ships eight components and not one of them draws a continuous trace, so
+`chromatogram` is the role that legitimately has no component: it takes
+pyopenms-viz, and the reason it carries is *no component fits* — never *the
+import failed*.
+
+`StateManager` wires the links; it is not something a role maps to. A role **in**
+this table gets what its row names — there is no choice to make, and for
+`chromatogram` what the row names is pyopenms-viz. A role **not** in the table
+falls back too, and so does every role when the import above failed. The lookup
+is the row, not the membership.
+
+```
+psms.parquet          role=table   -> Table         sets    'psm'
+mirror_peaks.parquet  role=mirror  -> MirrorPlot    filters 'psm'
+                                   -> VolcanoPlot   SKIPPED, no groups
+```
+
+State skipped components explicitly — a component with no matching output is a
+decision, not an omission.
+
+**A fallback carries its reason, and there are exactly two.** Either Insight has
+no component for this role, or the import failed. Write which:
+
+```
+row names a component  ->  use it
+row names none, or the
+  role is not in the    ->  pyopenms-viz via show_fig()
+  table at all               reason: no component for this role
+import failed          ->  pyopenms-viz via show_fig(), every panel
+                             reason: unavailable
+```
+
+**Never let "unavailable" reach the user dressed as design.** A run whose import
+had failed told its user *"the mirror plot is drawn with pyopenms-viz, the same
+backend your notebook used"* — true, and it reads as a considered choice about
+continuity. Both of that run's roles were `table` and `mirror`, which are in the
+table above; nothing about them failed to fit. The environment fact appeared
+nowhere in the transcript, and its own later self would have read the wireframe
+as a design decision.
+
+Where outputs are **parallel** rather than chained, no panel inherits the link
+identifier. Choose one and say why — usually the table, being what a user looks at
+first.
+
+## 2. Wireframe
+
+Approve placement, sizes, and what each panel sets and filters on, **before
+writing code**.
+
+**Every panel in the wireframe names the role it came from and the component it
+uses.** This is required, and it is what makes §1 impossible to skip: you cannot
+fill it in without having done the mapping. A run produced no link graph at all —
+*"not one line reached the user or my own reasoning"* — and went straight to a
+wireframe, which is how the catalogue above never got consulted.
+
+```
+[ Identifications ]   role=table   -> Table
+[ Mirror plot     ]   role=mirror  -> MirrorPlot
+[ Coverage        ]   role=coverage -> pyopenms-viz, no component for this role
+```
+
+A fallback panel carries its reason here, in the user's own terms and in one
+clause — *"drawn with static plots, because I couldn't install the interactive
+components on this machine"*. That clause is the whole of what is said about it;
+it is not a turn of its own, and nothing else about the machinery is named.
+
+**The panel count for the gate comes from this graph.** `--expect-components` is
+what the mapping says the page should have, and a short count means a panel is
+missing. **Lowering the number until the gate passes is the one thing you may
+never do** — a run took a real 9/10 failure, changed `2` to `1`, and recorded a
+green 10/10 on a page that was missing its table.
+
+**A panel behind an inactive tab is hidden, not missing, and the two are not the
+same finding.** A build accepted a two-tab layout in its design round and the
+gate's total fell from 5 to 4, because an inactive tab's iframe reports 0x0 —
+leaving it with a rule that forbade the only number that could pass. Count what
+one screen shows: **gate each tab separately, with the count for that tab.** The
+number never drops to accommodate a panel that failed to render; it is scoped to
+what is on screen when the gate looks. If you cannot say which of the two you are
+doing, you are doing the forbidden one.
+
+## 3. Panels, one at a time — each with a design round
+
+One round:
+
+1. Render it, and have it **on screen in the user's browser**. Screenshot it for
+   yourself — that is how you see the truncated header and the flattened axis —
+   and never mention having done so. Taking a screenshot is not news; the panel
+   is.
+
+   **A panel that renders unchanged after you changed it is a stale cache, not a
+   failed edit.** Insight keys its cache by config hash under `cache_path`, so
+   the first suspect is the cache and the first move is to clear it — before
+   re-reading the config, before doubting the change, before restarting
+   anything. Runs lose whole stretches to this by debugging the edit instead,
+   and it is the same symptom as the un-restarted server (`rounds.md`): what you
+   see is the previous configuration, faithfully served.
+2. **Resolve every candidate to its edit before offering it.** In thinking, name
+   the file and the change that implements it. A candidate whose edit you cannot
+   name is dropped; one whose edit turns out bigger or smaller than the wording
+   implied is reworded to match before anyone sees it. This is the only defence
+   against walking a suggestion back after it has been accepted — and the cost of
+   that is not one suggestion, it is the user's trust in every one that follows.
+3. Ask them **one at a time**, best first — a question, not a list. At most
+   three per round, one per axis: three is a ceiling, not a quota, and it is
+   never a ceiling on a single screen. Three at once is a pile rather than a
+   choice, and a user holding three open decisions makes none of them.
+4. Offer a free field and an exit, both always, at every step.
+5. Apply, restart the server, tell them to refresh, offer another round. Without
+   the restart you show the user their unchanged panel — Streamlit does not
+   re-import an edited `src/` module.
+
+   **A round that keeps failing says once that it is still going.** One line, in
+   their terms, naming the panel and nothing about the fault — *"Still on the
+   peptide table — a couple more minutes."* It is spent from the build's
+   four-to-six progress lines (`notebook-to-webapp`), not added to them.
+
+   A build described this loop exactly: *"each iteration was edit → clear the
+   Insight cache → restart → render → read the screenshot, and each one ended in
+   a fault I am specifically told not to describe — phantom-wrapped rows,
+   truncated headers, a column-not-found on the sort field, a failed restart —
+   so the rule that keeps instrument language off the screen also guarantees
+   that the stretch with the most going wrong is the one with nothing said."*
+   Four builds reported that inversion, in three different skills. Saying you
+   are still on it describes no fault; it answers the only question the silence
+   leaves them.
+
+   **A restart that fails is yours to fix, not theirs to watch.** The harness
+   prints the outcome of every background command, so a failing one narrates
+   itself: one build put `Background command "Restart the app" failed with exit
+   code 1` on screen three times across three turns, and the reader flagged the
+   screen as more than they could take in each time. Diagnose it in the
+   foreground, where nothing is printed until you speak. What reaches them is
+   the panel, or one sentence saying it is not ready yet — never the attempts.
+
+| axis | means | example |
+|---|---|---|
+| **data** | what the panel shows | "each row carries retention-time bounds; they explain what the 3D view draws" |
+| **layout** | how it is arranged | "this header truncates at the width you gave it" |
+| **behaviour** | interaction, or the state before any | "a row click selects the feature the 3D panel draws" |
+
+Three is a ceiling, not a quota. Every suggestion must point at something the
+user can see — except the first panel's behaviour suggestion, which by definition
+points at a panel that does not exist yet and must name it. If only two axes have
+anything real to say, offer two and name the third as clean. Offering none is
+legitimate — but only after you have rendered the panel and opened its
+screenshot; in the final round, only after the gate has run as well.
+
+The first panel has nothing to link to yet, so name the panel its behaviour
+suggestion is preparing for, or it reads as arbitrary.
+
+## Answering the free field
+
+Where a user with a design opinion spends every round. **Check the request against
+the component and the data before attempting it**, then answer in one of five
+shapes — the failure is conflating them:
+
+| shape | when |
+|---|---|
+| **yes** | component and data both support it |
+| **yes, and here is what you lose** | possible, but it costs a property the panel has — name the cost first |
+| **not as stated** | a hard constraint forbids it — give the number, offer what fits |
+| **yes, but it reopens an earlier stage** | the data does not exist; say which stage and what re-running costs |
+| **no** | the component cannot express it; offer the nearest thing it can |
+
+Real examples: *colour peaks by ion type* → **no** (`highlight_column` is binary
+and already carries `matched`); *add a protein column* → **reopens capture** (the
+tool never computed one); *table beside the mirror plot* → **not as stated**
+(these headers measure ~645px at this font; half-width is ~320px); *two spectra at once* → **yes,
+losing** observed-vs-theoretical.
+
+**Never silently substitute.** A refusal with a reason beats a substitution every
+time.
+
+## 4. The final round, on the whole page
+
+Run the usability gate **first**, then open a round using what it and the
+screenshot found.
+
+**Never name the gate, and never give its score.** Not as a finding, not as
+reassurance, not as `11/11`. It is a check this framework runs on itself; the
+user is looking at their own results page and has no idea a gate exists. The same
+goes for the screenshot — saying you took one is narrating machinery.
+
+| state | what they read |
+|---|---|
+| checks pass · picture shows 2 problems | two things I'd change |
+| checks pass · picture clean | *(neither is mentioned — describe the page)* |
+| truncated header found | that column title is cut off |
+
+The left column is shorthand for your own state, never a sentence to adapt. A
+run that read *"The gate is clean but the picture shows three things worth
+fixing"* had reassembled row one into prose — the shape survives being told not
+to name the gate, because the contrast is what carries it. **There is no
+user-facing sentence in which the two halves appear together.**
+
+Measured in **4 builds of 8**, always in the same shape: a pass count, then a
+contrast between what the checks caught and what the picture showed. The rule
+above this used to govern *findings* only, so a status report about the check
+itself walked straight through it — and the paragraph below used to say *"say
+exactly that"* about a green gate, which reads as permission to name it.
+
+Phrase what the gate found for a user, not a log: *"nothing is selected when the
+page opens, so the 3D panel is empty on arrival"*.
+
+Only this round can catch: the summary strip, column ratios between panels, one
+colour meaning one thing throughout, and what the page looks like before anything
+is selected.
+
+Repeat until the user ships it — or, when nothing on the page is worth changing,
+say so **in the page's own terms** and offer to ship, not a report on what
+passed. A clean page is the goal, not a failure to find fault with.
+
+**Offer to ship; do not ask an open question.** *"Shall we call it done, or is
+there something you'd change?"* asks them to decide with nothing to select, and
+a run that used it as its last turn was judged worse than the build before it
+for exactly that. The offer names what you would do — ship it — and leaves the
+alternative as something they can pick, not something they must compose. When
+this round is also the last turn of the run, `scaffold-workflow-app/handover.md`
+governs it, and endings there never end on a question.
+
+## Component rules that are not obvious
+
+| rule | consequence if ignored |
+|---|---|
+| **Pass an explicit `height=`** | `MirrorPlot` renders its iframe at height **0** — mounted, correct data, invisible |
+| **Every `filters` entry needs a `filter_defaults`** unless another panel is guaranteed to have set it | The panel sits on **"Loading…" forever** and the gate used to score it a pass. Pick a default useful on arrival — and check whether capture handed you a hint: a hardcoded selection in the notebook's plotting cell (`exp[12]`) tells you *what the author wanted seen first*, and that intent belongs here rather than on the config page. Carry the intent, never the literal — `exp[12]` is an index into their development file. **A default on a data-dependent identifier must be computed from this run's data** (`df.loc[df.score.idxmax(), "psm_id"]`), never a literal id carried over from a development dataset — an id absent from the user's run filters to nothing and loads forever, which is the failure this rule exists to prevent. A literal is only safe for a value the schema guarantees, such as the `observed` / `theoretical` sides the tool emits every time |
+| **`filters_top` / `filters_bottom` must use disjoint identifiers** | `ValueError`. To drive both halves from one selection, publish the column twice: `interactivity={"psm_top": "psm_id", "psm_bottom": "psm_id"}` |
+| **Pin a constant per side** with an identifier nothing sets, plus `filter_defaults_*` | How one long-format table feeds both halves: filter on `side`, defaults `observed` / `theoretical` |
+| **Budget the header text, not the column count** | No column count is the right rule — a six-column table still truncated `Matched i…`. Fit depends on the header text, the font, and the width you assigned. Widths summing over the **content width** also make Tabulator wrap onto a phantom second row — and that width is a property of the page you built, not a constant. **Measure it in the gate's viewport, not the browser you are driving.** The gate is what judges the page, and it runs at 1280px; the browser you drive is whatever size the user's window happens to be. One build measured 704px of table in a 1568px window, sized five columns to 695px, and folded onto the phantom row in the gate where that panel is about 400px. Observed fits **for a full-width panel**: 810, 830 and 864px. Those are the whole panel, so a table inside an `st.columns` split gets a fraction of one — two builds sized against the full figure and measured ~310px and ~450px in practice, then spent four and five gate cycles converging. Divide before you start, then compute each column rather than guessing at it:
+
+> **`width = 45 + 8 × len(header_text)`**
+
+45px is the sort arrow and padding; 8px is one character of the header font. Measured, not assumed: rendering ten real headers at the table's own 14px semibold system sans gives a mean of **6.86 px/char** and a worst case of **7.52** — short headers cost more per character than long ones, so the mean is the wrong figure to build on. 8 clears the worst case with margin, and erring wide is the right direction because a column that is too narrow wraps and a column that is too wide does not.
+
+Sum those widths and compare against the panel width. **Measure that width; do not infer it from the viewport.** One build sized eight columns with the formula above, summed 881px against an assumed panel, folded, and spent four gate cycles converging — then read the real width in one command and settled it in a single pass:
+
+```python
+# against the running app, in the gate's viewport width
+page.set_viewport_size({"width": 1280, "height": 900})
+page.goto(url); page.wait_for_timeout(3000)
+print(page.frame_locator("iframe").first.locator("body")
+      .evaluate("e => e.clientWidth"))
+```
+
+Only then shorten headers if the total overflows. Three builds on two notebooks had the 45px figure and the observed panel fits and still converged by trial across four and five gate cycles, because nothing here turned a panel width into a column width. A fourth had the formula and converged anyway, because the formula is only the numerator.
+
+**And do not buy the fit by dropping a column.** The same build removed one to make the sum work and disclosed it in its closing turn, which is the one place `handover.md` says a decision must never first appear. A column that does not fit is a question, not a silent edit.
+
+**The gate does not see the wrap.** A build reported *"875 wrapped onto a phantom row, 800 clipped 'Score', 815 fit"* and added that only the screenshot showed it — the gate returned 11/11 on the wrapped page. So a green gate is not evidence the table fits; the screenshot is. Read it before believing the count, and never treat a passing gate as the check for this. This rule used to name a fixed figure for a 1280px window until two builds on two notebooks sized their columns against it and wrapped anyway: one measured ~830px at a 1280px window, the other 864px with the wrap at a 865px sum. Both then re-derived the budget from a screenshot and repeated gate runs, which is the cost of a number that was one layout's measurement rather than something to compute. `verify-webapp-usability` measures the real property and fails on it; shorten a long header rather than widening its column |
+| **Normalise per side before a mirror plot** | The halves share one symmetric axis; raw counts (~7e4) against theoretical intensities (~1) flatten one onto the baseline |
+| **`highlight_column` is what makes annotations appear** | Without it, `annotation_column` labels nothing |
+| **Insight caches by config hash** under `cache_path` | A stale cache serves the previous configuration. Clear it when a config change appears to do nothing |
+
+`SequenceView` matches fragments inside the component from `sequence_data` +
+`peaks_data` — do not precompute them.
+
+## Style contract
+
+Enforced by `verify-webapp-usability`.
+
+- **Layout** — a summary strip of 3–5 headline numbers first; no panel taller than
+  the viewport; column ratios follow panel role, never a default even split.
+- **Semantics** — one colour per concept in every panel. **No raw column name
+  reaches the user**, in either place it can: table column `title`s *and* plot
+  axis labels (`mz` → `m/z`, `rt` → `Retention time (s)`). A reader given this as
+  "axis labels carry units" renamed the table headers and left the mirror plot's
+  axes as they came.
+- **States** — nothing-selected shows an instruction; no-results-yet names the Run
+  page; a traceback never reaches the UI. Write these first: they are the only
+  thing on screen until a run finishes.
+- **Theme** — primary, secondary and font in `.streamlit/config.toml`.
+
+## Common mistakes
+
+- Reloading the browser after editing a `src/` module. Restart the server.
+- Debugging a blank panel by guessing. Print the selection state and filter the
+  parquet with `filter_and_collect_cached` — that separates data from render in one
+  step.
+- Putting a number in both the summary strip and a table column.
diff --git a/.claude/skills/capture-notebook-workflow/SKILL.md b/.claude/skills/capture-notebook-workflow/SKILL.md
new file mode 100644
index 00000000..3c45c738
--- /dev/null
+++ b/.claude/skills/capture-notebook-workflow/SKILL.md
@@ -0,0 +1,286 @@
+---
+name: capture-notebook-workflow
+description: Use when turning a Jupyter notebook into an OpenMS Streamlit app, when a notebook's analysis must become a tested standalone script, or when notebook code needs isolating from its plotting so it can run headless in a workflow.
+---
+
+# Capture a notebook workflow
+
+Derive a testable processing step from a source notebook. Capture is not copying:
+it classifies, isolates, and **proves the extraction reproduces the original**.
+
+Vocabulary: `CONTEXT.md`. Rationale: `docs/notebook-to-webapp-design.md`.
+
+## The rule
+
+**Never write the extracted script before the source notebook has run.**
+
+Without golden values a faithful extraction cannot be told from a plausible one,
+and transcription errors in numeric code are invisible on inspection. If you
+extracted first, throw it away and run the notebook.
+
+## Sequence
+
+1. **Find a Python.** Probe: active virtualenv → `python`/`python3`/`py` ≥3.10 →
+   conda → `uv` → Docker. Report the one you chose, not the search. On Windows
+   `python` on `PATH` is often a Microsoft Store stub that prints help and exits.
+2. Classify every code cell statically, show the summary, and get confirmation
+   before going further. **Not because execution is slow** — it usually is not.
+   A teaching notebook runs in seconds precisely because it truncates. Nor
+   because execution depends on the split: step 4 runs the notebook
+   *unmodified*, so a wrong split wastes nothing there. The gate exists for the
+   user. It is their first sight of their own notebook through this framework,
+   every later stage inherits the reading, and a misread is cheapest to correct
+   while it is still one table rather than a scaffolded app.
+3. Pre-stage inputs, don't rewrite them. Copy data files beside a copy of the
+   notebook; download cells guarded by `os.path.exists` become no-ops. Rewriting
+   input cells invalidates the golden run.
+4. **Execute once**, unmodified, `allow_errors=True`, and keep the executed copy.
+   `nbclient` needs a kernelspec in the environment you chose.
+   Report the runtime with its cause: `<runtime> — but only <n> of <total>
+   spectra ran, because of the truncation` — never the number alone, which reads
+   as "this analysis is cheap" when it means the opposite. Every number in that
+   sentence comes from the run you just did. If you cannot say which line of the
+   trace a figure came from, it does not go in.
+5. Refine the classification against the execution trace, report only what
+   changed, and confirm again if anything did. The trace sees which branch ran and
+   which output is empty; static reading cannot. A cell producing no output is not
+   automatically dead.
+6. **Extract** the processing cells into `src/python-tools/<name>.py`.
+7. **Generate the test** from the golden values and run it. It must pass. Say so
+   as *"the extracted script reproduces your notebook"* — not *"extraction
+   reproduces the notebook — 7/7 golden checks pass"*, which names this skill's
+   stage and counts this skill's tests. The check total is how you know; that it
+   reproduces their notebook is what they asked for.
+8. Collect findings as one batch — do not interrupt to ask about them — and
+   route each to the stage that owns it: shortcuts and suspicious constants to
+   `interview-parameters`, hardcoded selections and display constants to the
+   dashboard stage, exercise-cell sweeps to the interview as prior evidence.
+
+If the user rejects part of the split, re-derive it. Re-read the cells named,
+report what changed *and what did not*, and disagree with a line number as your
+reason where you still disagree. Do not restate, and do not adopt a correction
+without checking — a cell mixing scoring into plotting is genuinely ambiguous and
+both of you can be half right. Then re-check whatever you classified by the same
+reasoning.
+
+## The summary
+
+One table, shown before execution, and it is the whole turn. Rows are **steps of
+the analysis, not cells** — a reader made to count cells to follow their own
+notebook has been handed the framework's bookkeeping. Say what each step does and
+where it lands in the app, in the same row; those are the two things the user
+needs, and splitting them across a summary and a classification makes them do the
+join.
+
+```
+<notebook>.ipynb — here is how I read it:
+
+  loads the raw files and a sample sheet     ->  Upload page
+  detects features in each run               ->  the analysis
+  links them across runs                     ->  the analysis
+  plots the intensity comparison             ->  Results page
+  writes a per-protein summary               ->  Results page
+  a parameter exercise at the end            ->  dropped, but I'll reuse
+                                                 the numbers it printed
+
+Look right? Then I'll run it once and come back with what needs deciding.
+```
+
+Contiguous cells doing one job are **one row**. Cell numbers appear only when the
+user asks for them, or inside a finding that points at a specific line.
+
+No number here may require having run the notebook — write "a feature table",
+never a count of what is in it. And do not preview the findings: they arrive next turn with
+their evidence and a recommendation attached, and naming them here spends the
+budget twice to say the same thing worse.
+
+## Cell classification
+
+**This table is internal.** The `destination` column is written for you, not for the user: `code dropped, output harvested` is jargon. Classify with it, then say what the summary above
+says: what the step does, and which page it becomes.
+
+| class | destination | signals |
+|---|---|---|
+| `setup` | dropped | imports, version prints, `%matplotlib` |
+| `input` | upload page | file loads, downloads, `os.path.exists` guards |
+| `processing` | the python tool | transforms data into something an output is built from |
+| `visualization` | dashboard stage | builds a figure, calls `.plot`/`.show` |
+| `exercise` | code dropped, **output harvested** | teaching loops printing comparisons |
+| `demo shortcut` | **review batch** | see findings below |
+
+Not every notebook is a chain. An exploration notebook branches — a peak
+count, a TIC, a spectrum — none downstream of another. Capture the shared prefix
+once, emit each branch as its own output, and **say the outputs are parallel**:
+that is what tells the dashboard stage the link identifier must be chosen rather
+than inherited.
+
+## Findings to collect (never fix silently)
+
+| finding | how to detect | why it matters |
+|---|---|---|
+| truncation | `.head(n)` or a slice after a filter | ships an app that analyses a handful of whatever the user uploads |
+| intent comment | "for this tutorial / demonstration" | code never meant to run in production |
+| **discarded result** | an expression statement calling a non-mutating method (`sort_values`, `dropna`, `astype`) | the line does nothing; a bare `df.sort_values()` before `head(5)` silently changes *which* rows are analysed |
+| suspicious constant | domain sanity check against units | a tolerance given as a *relative* `0.1` is 10%, where MS works in ppm |
+| **hardcoded selection** | an index picking *which rows* to analyse — `exp[12]`, `df.iloc[0]`, a window used to **subset the data** before plotting | never a config parameter. The author picked one spectrum because a notebook shows one; an app shows whichever is clicked. It becomes a **link identifier** and a `filter_defaults` value. Followed literally, the app ships pinned to spectrum 12 forever |
+| **display constant** | a literal encoding an assumption about the *magnitude* of the data — a marker-size divisor (`s=intensity/1e4`), a fixed colour-scale limit, a hand-set axis range or zoom window that changes only the **view**, not which rows are used, a log offset | tuned to one dataset's dynamic range and silently wrong on another: markers vanish or swamp the plot, a heatmap saturates. Not analysis, so it never reaches the tool; not a selection, so it is not a link identifier. Hand it to the dashboard stage to **derive from the data at render time**, or expose as a display control. Distinguish from a *layout* constant — `height=520`, `page_size=10` size the widget, not the data, and are correctly fixed |
+
+Report each as a decision answerable in one word: **their line of code, where it
+is, what it does to the app, and what you recommend.** Name what needs attention
+rather than counting it — *"2 findings need review"* is a progress line wearing a
+review's clothes. The cost is a parenthetical, never the lead —
+
+```
+Your notebook analyses only the first <n> of <total> spectra — `df.head(<n>)`,
+cell <k>. Remove that for the app?   (recommended: yes, together with the
+                            tolerance below — at the notebook's settings the
+                            whole file takes <slow>, at <corrected> it takes
+                            <fast>)
+```
+
+not *"the truncation costs <delta> to remove"*, which prices a decision the user
+has not been shown and names nothing they wrote. Both sentences carry the
+runtime, and it must stay: whether a truncation can be dropped still depends on
+what it costs, and where corrected parameters turn seconds into minutes the user
+has to hear that before agreeing. The difference is which of the two the sentence
+is *about*.
+
+The angle brackets are the point. Fill them from **this** run — never from an
+example, and never from another notebook. Carrying a figure across notebooks is
+how a report ends up confidently wrong.
+
+Scan all six cell classes, not just the ones you are extracting. A hardcoded
+selection lives in a `visualization` cell by nature, and that is a cell you are
+about to drop — scan only `processing` and the class never fires. Where a finding
+lands in a dropped cell, hand it to the stage that owns the cell: `visualization`
+to the dashboard as a proposed `filter_defaults`, `exercise` to the interview as
+prior evidence.
+
+## Harvest an exercise cell before dropping it
+
+Dropping the code is not discarding the result. A cell that sweeps a value and
+prints a comparison is a sensitivity measurement the notebook already ran on real
+data — the experiment `interview-parameters` is about to reproduce, for free.
+
+Record which parameter it varied, over what range, and what moved. Keep it
+distinct from golden values: a golden value says what the notebook produced, this
+says how sensitive it was.
+
+A flat sweep is a finding, not a null result. A teaching notebook will often ask
+its reader to predict the effect of narrowing a tolerance while a default set a
+few cells earlier already makes that sweep flat — so the exercise demonstrates
+the opposite of what it means to teach. Tell the user that, in their own
+numbers.
+
+Never pass a flat sweep on as evidence of inertness. It is **masking until proven
+otherwise**, and `interview-parameters` treats it that way. If a sweep cannot be
+read this way, say so rather than guessing at it.
+
+**A harvested sweep is never re-run.** Reading numbers the notebook already
+printed costs nothing; reproducing them costs the longest wait in the framework,
+to arrive at what is already on the screen. An exercise cell is there to teach —
+it was written to be run once, by a student, as a demonstration. Take its result
+as evidence about the parameter and drop the cell. Where its range is too narrow
+to conclude from, say what it does not cover rather than sweeping it again.
+
+## Isolation requirements
+
+The emitted script imports no Streamlit and touches no `st.session_state` — online
+mode runs it in an RQ worker that has neither. It takes a JSON parameter file as
+`argv`, reads inputs from paths, writes outputs as files, exits nonzero on
+failure, and declares `DEFAULTS` and `OUTPUTS` at module level.
+
+`OUTPUTS` declares each file, its `role`, its `columns`, and the identifier it
+links on. The dashboard stage reads it without executing anything, so it must be
+accurate; the generated test asserts a real run matches it.
+
+**Use exactly these keys.** They are a contract with two later readers, not a
+description you may paraphrase:
+
+```python
+OUTPUTS = [
+    {
+        "key": "hits",                      # short, stable, unique in this list
+        "file": "hits.parquet",             # written into the out dir
+        "role": "table",                    # from the fixed vocabulary below
+        "columns": ["item_id", "label", "score"],
+        "links_on": "item_id",              # or None where nothing links
+    },
+]
+```
+
+Written as prose, this went 18 different ways across 57 builds. Only `role` and
+`columns` were universal; the linking identifier was `links_on` in 31 builds and
+`links` in 18, and eleven other names appeared — `sets`, `filters`, `id`, `help`,
+`title`, `note`. `key` was declared in 11 builds of 57 and `interview-parameters`
+reads it on every numeric output, so **39 builds wrote an `OUTPUTS` their own
+parameter probe raises `KeyError` on**. Nobody saw it, because the probe runs
+inside a stage that reports its findings and not its crashes.
+
+`links_on` is the name, and the column it names is one of your own — the example
+above is shaped like an entry, not filled with identifiers to copy. Write `None`
+rather than omitting it when an output links on nothing — an absent key and a declared "nothing" read the same to a human and
+differently to the dashboard stage.
+
+**`role` comes from a fixed vocabulary, because the dashboard stage looks it up
+rather than interpreting it:**
+
+```
+table         a row per record, the thing a user scans and clicks
+mirror        two spectra face to face
+peakmap       retention time against m/z, as a density
+chromatogram  a signal against retention time  (drawn with pyopenms-viz —
+              Insight has no component that draws a continuous trace)
+```
+
+An output that is none of these may coin a new role — but **say so in the
+declaration**, because a coined role has no component waiting for it and the
+dashboard will draw it with pyopenms-viz instead. `chromatogram` is on the list
+and drawn that way too: being in the vocabulary is what makes the dashboard's
+choice a lookup, not a promise that Insight has something for it. Reaching for a new word when
+one of these four fits is how a page loses the component it should have had: the
+vocabulary was undocumented until a run mapped nothing at all and every role it
+had was on this list.
+
+**`widget_type` is a closed list:** `text`, `textarea`, `number`, `selectbox`,
+`slider`, `checkbox`, `multiselect`, `password`, `auto`. Anything else renders
+nothing at all — the dispatch is a run of `elif`s with no final `else`. Not
+Streamlit's function names: `number_input` is not one of these, and two builds
+wrote it here, from Streamlit's API, while composing `DEFAULTS` in this file.
+
+**Every key you name in `DEFAULTS` is stored as `<script>.py:<key>`**, under
+`_general` — `input_python()` prefixes it with the script filename. Anything
+written against the bare key later (a preset, a read of `params.json`) is valid
+JSON, loads without error, and sets nothing.
+
+Both facts are also in `add-python-tool`, which is where the tool is registered.
+They are repeated here because `DEFAULTS` is *written* here, and four builds
+proved that a fact in the neighbouring skill is a fact nobody reads.
+
+Give every numeric entry in `DEFAULTS` an explicit `min` and `max`. Without them
+the parameter probe invents bounds — `lo = 0` for a positive value — and sweeps a
+value the tool rejects. The failed run is dropped from the effect calculation, so
+the effect reads *lower* than the truth, which is the direction that produces
+HARDCODE. A charge parameter swept to 0 is the case that found this.
+
+## Golden values
+
+Record per processing stage: row counts, column schemas, checksums over sorted
+numeric columns. Record them **before** resolving any finding, so they describe
+the notebook as written.
+
+A printed golden value is formatted, not raw. `f"{x:.0f}"` *rounds*, so a
+notebook printing `65094` may hold `65093.91`. Assert with `round()`, never
+`int()` — truncating a correct extraction fails a test on working code, and the
+obvious next move is to "fix" the extraction. Record the format spec beside the
+value.
+
+## Common mistakes
+
+- **Serialising pyOpenMS objects.** Notebooks park `MSSpectrum` objects in
+  DataFrame cells; none of it is serialisable. Converting to long-format parquet
+  is genuine design — propose the shape, don't invent it silently.
+- Extracting an exercise cell's code, or **discarding its output**. Two
+  separate decisions, and the second is usually wrong.
+- Silently dropping a truncation. It changes the golden values and the
+  runtime. It is a finding, not a cleanup.
diff --git a/.claude/skills/configure-app-settings.md b/.claude/skills/configure-app-settings/SKILL.md
similarity index 93%
rename from .claude/skills/configure-app-settings.md
rename to .claude/skills/configure-app-settings/SKILL.md
index fac4c7d3..26a74aeb 100644
--- a/.claude/skills/configure-app-settings.md
+++ b/.claude/skills/configure-app-settings/SKILL.md
@@ -1,3 +1,8 @@
+---
+name: configure-app-settings
+description: Use when changing an OpenMS app's name, version, deployment mode, workspaces, thread limits, analytics or legal links in settings.json.
+---
+
 # Configure App Settings
 
 Set up app-level configuration (settings, Dockerfile, README) for a new or forked OpenMS streamlit app. Run before `configure-docker-compose-deployment` or `configure-k8s-deployment`.
diff --git a/.claude/skills/configure-docker-compose-deployment.md b/.claude/skills/configure-docker-compose-deployment/SKILL.md
similarity index 87%
rename from .claude/skills/configure-docker-compose-deployment.md
rename to .claude/skills/configure-docker-compose-deployment/SKILL.md
index 2fe8d0f7..c67cfa75 100644
--- a/.claude/skills/configure-docker-compose-deployment.md
+++ b/.claude/skills/configure-docker-compose-deployment/SKILL.md
@@ -1,3 +1,8 @@
+---
+name: configure-docker-compose-deployment
+description: Use when deploying an OpenMS Streamlit app with docker-compose, or when choosing between the full OpenMS image and the pyOpenMS-only one.
+---
+
 # Configure Docker Compose Deployment
 
 Set up docker-compose-specific configuration for a new or forked OpenMS streamlit app.
diff --git a/.claude/skills/configure-k8s-deployment.md b/.claude/skills/configure-k8s-deployment/SKILL.md
similarity index 52%
rename from .claude/skills/configure-k8s-deployment.md
rename to .claude/skills/configure-k8s-deployment/SKILL.md
index 556c54af..7917073c 100644
--- a/.claude/skills/configure-k8s-deployment.md
+++ b/.claude/skills/configure-k8s-deployment/SKILL.md
@@ -1,3 +1,8 @@
+---
+name: configure-k8s-deployment
+description: Use when deploying an OpenMS Streamlit app to Kubernetes, or when working with the kustomize base, overlays or the separate storage root.
+---
+
 # Configure Kubernetes Deployment
 
 Conduct a short interview, then edit the Kustomize overlay (and optionally the workspace PVC) so a forked OpenMS Streamlit app is ready to deploy to the OpenMS Kubernetes cluster.
@@ -16,8 +21,10 @@ These are facts about the target cluster, not steps for you to execute. Mention
 
 - Traefik ingress controller installed in the cluster (handles `IngressRoute` CRDs).
 - Cluster has read access to GHCR for pulling the app image.
-- A storage class compatible with `cinder-csi` (or equivalent `ReadWriteOnce` provider). For live PVC grows, the storage class needs `allowVolumeExpansion: true`.
-- Worker nodes labelled `openms.de/memory-tier=low` and `openms.de/memory-tier=high`. The memory-tier components add the matching `nodeSelector`.
+- A storage class that provisions `ReadWriteOnce` volumes (de.NBI: `cinder-csi`). That is the **backing** volume for the storage tier, not the claim the app mounts. For live grows of it, the class needs `allowVolumeExpansion: true`.
+- The fork's storage tier (`k8s/storage/`) already applied, publishing the `ReadWriteMany` StorageClass the workspaces PVC names, and `mount.nfs` present on every node. Applied in the other order, every pod sits `Pending` on a class that does not exist yet.
+- **No node labels, of any kind.** Nothing under `k8s/` selects a node any more: the scheduler places pods and the manifests only declare how big a worker is. The `openms.de/memory-tier` labels the older components matched are gone, and CI fails any manifest that reintroduces a `nodeSelector`, `nodeName` or `nodeAffinity` (`assert_no_node_pinning_anywhere`).
+- Room for `<replicas> x <worker size>` (Q5 and Q6) across the cluster's nodes. A worker is Guaranteed QoS, so its request is reserved for as long as the pod runs, queue empty or not.
 - DNS for `*.webapps.openms.de` and `*.webapps.openms.org` pointing at the cluster's Traefik load balancer.
 
 ## Step 1 — Recon the fork
@@ -27,16 +34,17 @@ Before asking the user anything, read a small known set of files directly (do no
 1. `git remote get-url origin` and the repo name → seeds the slug and GHCR ref defaults.
 2. `k8s/overlays/prod/kustomization.yaml` — if anything has already been edited away from the template stub, treat those values as the user's prior choices to confirm rather than overwrite blindly.
 3. `k8s/base/kustomization.yaml`, `k8s/base/streamlit-deployment.yaml`, `k8s/base/rq-worker-deployment.yaml`, `k8s/base/workspace-pvc.yaml` — confirm the layout still matches the template:
-   - PVC `metadata.name` is `workspaces-pvc`.
+   - PVC `metadata.name` is `workspaces-nfs-pvc`, `ReadWriteMany`, on a `storageClassName` this fork's `k8s/storage/` publishes.
    - Deployments reference `image: openms-streamlit` (the placeholder Kustomize swaps).
-   - `streamlit-deployment.yaml` has `claimName: workspaces-pvc`. (Co-location of the workspace-using pods is enforced by the shared RWO PVC mount, not by a pod-affinity rule.)
+   - `streamlit-deployment.yaml` and `rq-worker-deployment.yaml` both carry `claimName: workspaces-nfs-pvc`. Being RWX, that claim constrains placement not at all: the workspace-using pods are placed independently by the scheduler, not co-located, and there is no pod-affinity rule pulling them together either.
+   - `rq-worker-deployment.yaml` has a fixed `replicas` and a `topologySpreadConstraints` block over `kubernetes.io/hostname` with `maxSkew: 1`. Read the replica count from here — it is the default you propose in Q6.
 4. `.github/workflows/build-and-test.yml` — confirm which tags CI publishes (the OpenMS template publishes `<branch>-full`, `<branch>-simple`, `<tag>-full`, `<tag>-simple`, plus `latest` on `main`-full pushes).
 
 If any of those files are missing, renamed, or significantly restructured, stop and ask the user how to proceed. Do not pattern-match the standard answers onto an unknown layout.
 
 ## Step 2 — Interview the user
 
-Ask the user the questions below in 2–3 batched `AskUserQuestion` turns rather than one long sequential interrogation. Group related questions together (slug + subdomain + GHCR ref make a coherent first batch).
+Ask the user the questions below in 3 batched `AskUserQuestion` turns rather than one long sequential interrogation. Group related questions together: slug + subdomain + GHCR ref + tag make a coherent identity batch, and worker size + replica count + storage size make a coherent capacity batch — they trade against each other and against the same cluster.
 
 Each question must include:
 
@@ -67,17 +75,26 @@ The user confirms or overrides each one. Do not omit the "what this controls" li
 - *What this controls:* the public URL users type into a browser. The IngressRoute always wires up **both** `<sub>.webapps.openms.de` and `<sub>.webapps.openms.org` (one IngressRoute, two `Host(...)` matchers OR-ed together), so users land on the same app regardless of which TLD they remember.
 - *Default:* the slug. But ask — `OpenDIAKiosk` chose subdomain `opendia` (different from its slug `opendiakiosk`) for a shorter URL, so this is not always identical to the slug.
 
-### Q5. Memory tier
+### Q5. Worker size
+
+- *What this controls:* how much memory and CPU **one RQ worker** reserves. This is a pod size, not a node selection — the component sets `requests` equal to `limits`, so the number is simultaneously what the scheduler reserves and the hard ceiling the kernel enforces, and Kubernetes then places the pod wherever it fits. Too small and TOPP tools are OOMKilled mid-workflow; too large and the worker either sits `Pending` or reserves most of a node it never uses.
+- *Default:* `memory-tier-low` — 16Gi / 4 cpu per worker, correct for ~90% of template forks.
+- *Override prompt:* "Does this app run DIA spectral-library construction, OpenSwath peak picking, DIA-LFQ, or comparable heavy OpenMS workloads?" If yes → `memory-tier-high`, 180Gi / 20 cpu, which is most of a high-memory node held for as long as the worker lives.
+- *If neither number fits:* edit `k8s/components/memory-tier-<tier>/worker-resources.yaml` and keep `requests` **equal to** `limits` on both memory and cpu. Splitting them drops the pod to Burstable QoS and back near the top of the node's OOM-kill list; CI fails that (`assert_worker_qos_guaranteed`). The cluster-side ceiling is the `LimitRange` in `k8s/base/limitrange.yaml`.
+- *What it no longer controls:* placement. Nothing schedules by node label any more — a tier is a size. A fork that needs one specific machine has to take that up with the cluster operator, not encode it here.
+
+### Q6. Worker replica count
 
-- *What this controls:* which set of cluster nodes the app's pods are eligible to schedule on. `memory-tier-low` targets the standard worker nodes (correct for ~90% of template forks). `memory-tier-high` targets the high-memory nodes reserved for heavy DIA / OpenSwath workloads. Picking the wrong tier means either pods stuck `Pending` (overflowed low tier) or starving other heavy apps off the high tier.
-- *Default:* `memory-tier-low`.
-- *Override prompt:* "Does this app run DIA spectral-library construction, OpenSwath peak picking, DIA-LFQ, or comparable heavy OpenMS workloads?" If yes → `memory-tier-high`.
+- *What this controls:* how many workflows the deployment runs at once — RQ takes one job per worker process, so N workers is N concurrent workflows and nothing else. It is also what actually spends a second node: the workers carry `topologySpreadConstraints` with `maxSkew: 1` over `kubernetes.io/hostname`, so replicas are placed one per node before any node takes a second.
+- *Default:* whatever `k8s/base/rq-worker-deployment.yaml` already says (2 — one per node on the two-node OpenMS cluster). Propose a different number only when the answer to "how many nodes can hold a worker of the Q5 size" is not 2.
+- *Cost of raising it:* `replicas x Q5 size` is reserved cluster-wide for as long as the workers run, queued jobs or not. A replica with nowhere to fit stays `Pending` rather than doubling up on a node — `whenUnsatisfiable: DoNotSchedule` — so over-provisioning is visible in `kubectl get pods` rather than silent.
+- *Do not answer 1* unless serialized workflows are genuinely wanted: a single worker leaves every other node with nothing to run, which is the state this deployment was in before.
 
-### Q6. Workspace storage size
+### Q7. Workspace storage size
 
 - *What this controls:* the persistent disk allocated for Streamlit session workspaces, uploaded files, intermediate analysis outputs, and any reference data the app seeds at startup. Too small → users hit "no space left" mid-analysis; too large → wasted cluster storage budget.
-- *Default:* **500 Gi** (matches the stock base, so the default needs zero file edits).
-- *Note on naming (do not ask the user):* the PVC base name stays `workspaces-pvc` for every fork. Kustomize's `namePrefix: <slug>-` automatically scopes it to `<slug>-workspaces-pvc` in the cluster, so cross-fork name collisions are impossible. Override the size only — never rename the PVC.
+- *Default:* **400 Gi** (matches the stock base, so the default needs zero file edits).
+- *Note on naming (do not ask the user):* the PVC base name stays `workspaces-nfs-pvc` for every fork. Kustomize's `namePrefix: <slug>-` automatically scopes it to `<slug>-workspaces-nfs-pvc` in the cluster, so cross-fork name collisions are impossible. Override the size only — never rename the PVC.
 
 ## Step 3 — Apply the answers to `k8s/overlays/prod/kustomization.yaml`
 
@@ -91,7 +108,7 @@ resources:
   - ../../base
 
 components:
-  - ../../components/memory-tier-<tier>          # Q5: low | high
+  - ../../components/memory-tier-<tier>          # Q5: low | high — worker SIZE, not node selection
 
 namePrefix: <slug>-                              # Q1
 
@@ -138,26 +155,49 @@ Substitution map:
 - `<sub>` → Q4 answer (note: `<sub>` is independent of `<slug>`).
 - `<tier>` → `low` or `high` from Q5.
 
+Q6 needs a file edit **only if the answer differs from the base default**. If it does, add one more patch to the same `patches:` list. Patch the overlay, never `k8s/base/rq-worker-deployment.yaml`, so the fork's capacity choice stays in the one file this skill owns and a template rebase cannot quietly revert it:
+
+```yaml
+  - target:
+      kind: Deployment
+      name: rq-worker
+    patch: |
+      - op: replace
+        path: /spec/replicas
+        value: <N>                                 # Q6
+```
+
+Leave the `topologySpreadConstraints` in the base alone either way. It is what puts those replicas on different nodes, and it is scoped to this fork only because kustomize copies `commonLabels.app` into the constraint's `labelSelector` — dropping `commonLabels` from the overlay silently widens it to every fork's workers in the namespace.
+
 About `images[0].name: openms-streamlit` — **this is the match key, not a value the user picks.** Kustomize's `images:` transformer is find-and-replace: `name` is the literal image string Kustomize searches for in the rendered manifests, and `newName`/`newTag` are what it substitutes. Both base Deployments (`streamlit-deployment.yaml`, `rq-worker-deployment.yaml`) reference `image: openms-streamlit`; the overlay's `name: openms-streamlit` matches that literal and rewrites it to `<ghcr-ref>:<tag>`. If you change this field, no rewrite happens and the cluster pulls a non-existent `openms-streamlit:latest` and gets `ImagePullBackOff`. Leave it alone.
 
 About the `||` in the IngressRoute match — both TLDs always go in. The OpenMS infra publishes apps on both `.de` and `.org` so users land on the same app no matter which they remember. One IngressRoute, two `Host(...)` matchers OR-ed together is the right shape; do not split into two IngressRoute objects.
 
 ## Step 4 — Optional storage resize
 
-Skip this step if the user accepted the 500 Gi default.
+Skip this step if the user accepted the 400 Gi default.
 
-Otherwise, edit `k8s/base/workspace-pvc.yaml` and change a single line:
+Otherwise **two** claims move together, because the app no longer mounts a volume directly — it claims space out of the one the NFS server exports:
 
 ```yaml
+# 1. k8s/storage/nfs-backing-pvc.yaml — the Cinder volume Ganesha exports
 spec:
   resources:
     requests:
-      storage: <size>     # Q6: e.g. 100Gi, 1Ti, 3Ti
+      storage: <backing size>
+
+# 2. k8s/base/workspace-pvc.yaml — what the app claims out of it
+spec:
+  resources:
+    requests:
+      storage: <size>     # Q7: e.g. 100Gi, 1Ti, 3Ti
 ```
 
-Do **not** rename the PVC, the base `kustomization.yaml` resource list, or the `claimName` in `streamlit-deployment.yaml`. Kustomize's `namePrefix` already gives the in-cluster PVC a unique per-fork name; renaming the base creates a 3-file cascade for no benefit.
+The app's claim must stay **materially below** the backing volume, and the backing volume grows first. nfs-provisioner `statfs()`es the export on every provision and refuses outright any claim larger than the *free* space it finds there — unconditionally, not gated on quotas — and a fresh filesystem never reports its full nominal size. The stock pair is 400Gi against 500Gi; keep a comparable margin, or the claim never binds and every pod stays `Pending` behind it.
+
+Do **not** rename either PVC, the base `kustomization.yaml` resource list, or the `claimName` in `streamlit-deployment.yaml` / `rq-worker-deployment.yaml`. Kustomize's `namePrefix` already gives the in-cluster workspaces PVC a unique per-fork name; renaming the base creates a multi-file cascade for no benefit.
 
-Operator caveat (mention in handoff, not your job to verify): in-place expansion of an *already-deployed* PVC requires the StorageClass to have `allowVolumeExpansion: true`. If the operator's `cinder-csi` class does not allow expansion, growing a live PVC requires recreation, not a manifest edit. Resizing on first deploy is unaffected.
+Operator caveat (mention in handoff, not your job to verify): in-place expansion of an *already-deployed* PVC requires the StorageClass to have `allowVolumeExpansion: true`, and that applies to the backing `cinder-csi` claim. If the class does not allow expansion, growing a live volume requires recreation, not a manifest edit. Sizing on first deploy is unaffected.
 
 ## Step 5 — Handoff
 
@@ -165,14 +205,15 @@ After committing the edits, tell the user the next steps belong to a human opera
 
 1. Open a PR with the overlay edits and have it reviewed.
 2. Merge to `main`. CI (`build-and-test.yml`) rebuilds and pushes the image to GHCR with the tag from Q3. The kind integration jobs (`test-nginx`, `test-traefik`) auto-discover slug and Traefik hostnames from the overlay output, so no workflow edits are needed for fork-specific values.
-3. Cluster operator runs `kubectl apply -k k8s/overlays/prod/` against the OpenMS cluster.
-4. Operator verifies with `kubectl -n openms rollout status deployment/<slug>-streamlit` and a browser check on `https://<sub>.webapps.openms.de`.
+3. Cluster operator applies the fork's storage tier first (`kubectl kustomize --enable-helm k8s/storage/ | kubectl apply -f -`), then `kubectl apply -k k8s/overlays/prod/`. That order matters — the overlay's PVC names a StorageClass the storage tier publishes.
+4. Operator verifies with `kubectl -n openms rollout status deployment/<slug>-streamlit` and a browser check on `https://<sub>.webapps.openms.de`, then `kubectl -n openms get pods -o wide -l component=rq-worker` to confirm the workers came up on **different** nodes, each with `.status.qosClass` of `Guaranteed`.
 
 ## Reference files
 
 - Overlay: `k8s/overlays/prod/kustomization.yaml`
-- Memory-tier components: `k8s/components/memory-tier-{low,high}/`
+- Worker/Streamlit sizing components: `k8s/components/memory-tier-{low,high}/` — `worker-resources.yaml` + `streamlit-resources.yaml`, pod sizes only, no node selection
 - Base manifests: `k8s/base/*.yaml`
+- Storage tier: `k8s/storage/` — NFS-Ganesha serving the RWX workspace volume
 - CI workflow: `.github/workflows/build-and-test.yml` (build + lint + kind integration)
 - In-app reference: the "Developers Guide: Kubernetes Deployment" Documentation page in the running Streamlit app.
 
@@ -183,7 +224,9 @@ After committing the edits, tell the user the next steps belong to a human opera
 - [ ] `namePrefix`, `commonLabels.app`, `images[0].newName`, `images[0].newTag` written in the overlay
 - [ ] IngressRoute patch written: both `.de` and `.org` hostnames, plus the `<slug>-streamlit` service reference
 - [ ] Redis URL written in both Deployment patches (`streamlit` and `rq-worker`)
-- [ ] Memory-tier component selected
-- [ ] Storage size in `k8s/base/workspace-pvc.yaml` updated only if the user picked a non-default size; PVC name and `claimName` untouched
+- [ ] Worker size component selected (Q5)
+- [ ] Worker replica count (Q6) patched into the overlay only if it differs from the base default; the base Deployment left untouched
+- [ ] No `nodeSelector`, `nodeName`, `nodeAffinity` or `openms.de/memory-tier` anywhere in the overlay or the components — `assert_no_node_pinning_anywhere` fails the PR on any of them
+- [ ] Storage sizes in `k8s/storage/nfs-backing-pvc.yaml` and `k8s/base/workspace-pvc.yaml` changed together, backing volume materially larger, and only if the user picked a non-default size; PVC names and `claimName`s untouched
 - [ ] `.github/workflows/build-and-test.yml` uses dynamic overlay discovery (no `template-app` / `template.webapps.openms.*` literals); patched in if the fork's workflow was on the old hardcoded shape
 - [ ] Changes committed on a feature branch (no PR opened unless the user asked for one)
diff --git a/.claude/skills/connect-browser-control/SKILL.md b/.claude/skills/connect-browser-control/SKILL.md
new file mode 100644
index 00000000..9a2dd5f3
--- /dev/null
+++ b/.claude/skills/connect-browser-control/SKILL.md
@@ -0,0 +1,619 @@
+---
+name: connect-browser-control
+description: Use when a session needs to drive a browser rather than merely open one - taking screenshots of a page, clicking through it, or reading its DOM - and control is not yet known to work.
+---
+
+# Connect browser control
+
+Ends in one of two states, and the caller branches on which:
+
+- **control, confirmed** — a browser you have driven, which loaded a page this
+  machine served on loopback. The user's app opens in it.
+- **no control, declined** — you asked, and they said no. Page checks fall to the
+  gate's headless browser, the app opens in their default browser, and rounds put
+  their eyes on one named thing at a time.
+
+**There is no third ending, and a run never settles for the headless browser on
+its own judgement.** The only thing that puts a run there is a user who was asked
+and said no. Every road that does not reach confirmed control reaches the ask,
+and the notebook question waits behind it. What waits is that question, not the
+rest of setup, and not the run's own looking: while they act, preflight finishes
+and the browser list is watched.
+
+## What this stage says out loud
+
+Decide from the probe and the marker, then produce the matching row. **This
+table is the whole of what setup volunteers.** Every other sentence this skill
+puts in front of a user is prescribed by name where it belongs — the *"carry on
+without it?"* follow-up, the one line on a decline, *"it's open at `<url>`"*,
+and the request to reopen a browser whose device has gone. Nothing outside those
+is spoken, and none of this governs what you say when asked directly.
+
+| what you found | what they read |
+|---|---|
+| it answers, and the marker comes back | *(nothing)* |
+| it answers, the marker fails, and a Chromium browser is on this machine | the click, in that browser |
+| it answers *"not connected"* | the click, in the browser already there |
+| no schema at all | the click, and the restart |
+| no Chromium browser on this machine at all | the request to install one |
+| they have already said no | *(nothing further — the decline had its one line, and it is settled)* |
+
+**Silence here is not the user hearing nothing.** After a visible ask they
+acted on, the acknowledgement rides on the next question rather than becoming a
+turn of its own — *"Thanks — what's the path to your notebook?"* That sentence
+belongs to the question following this stage, not to this skill, so it costs the
+table above nothing. A run that instead wrote *"Setup's done."* explained itself
+honestly: two visible turns of trouble had just happened, and silence read to it
+as the request having gone nowhere. That pressure is real and this is what answers it. What is still never
+said is anything **about** control.
+
+**Nothing reports that setup finished.** The one line permitted before the first
+question is the forward-looking one `notebook-to-webapp` names — *"Setting up —
+a minute, then I'll ask about your notebook."* — and it is optional. It tells
+them what is happening and what comes next. What is never written is the other
+direction: a line accounting for work already done.
+
+This is a slot, not a vocabulary. Three builds on three different notebooks
+each opened by filling it, each with wording the last rule did not cover:
+
+| what the user read first | direction |
+|---|---|
+| a heading naming the machinery setup was about to run | backward — names the work |
+| a sentence reporting that setup had finished | backward — reports it ended |
+| a sentence confirming control and naming the next internal step | backward, twice over |
+| *"Setting up — a minute, then I'll ask about your notebook."* | **forward — this one is fine** |
+
+Only the last is written out. **A skill that spells out the sentence it forbids
+is handing over a usable line** — three builds reproduced `notebook-to-webapp`'s
+`test_gui.py` anti-example almost verbatim, and it stopped on the first build
+after that example was removed.
+
+The first three ran with the rules the one before them earned, and each found a
+phrasing around them, because the pressure is not the words. It is that setup took real
+time and finished, and saying nothing about it feels like saying nothing at
+all. **The user did not know setup had started, so its ending is not news to
+them.** An opening line that accounts for it is the whole failure, whatever it
+is made of — and *"nothing to ask"* is that failure at its purest, a sentence
+whose entire content is that there was no sentence to write.
+
+**And "preflight" is your word, not theirs.** The anecdote above was written up
+as a run saying *"Setup's done."* and left there; a later run, with all of this
+in front of it, opened with *"Preflight's done. Let me read your notebook."* —
+the same turn, one word worse, because nothing here forbade the word and the
+rule above only reaches things said about control. Setup finishing is not news:
+the user did not know it had started. `preflight`, `marker`, `the gate` and
+`browser` name machinery they were never shown, and a stage ending is not a
+turn. If setup produced something they must act on, ask for it; otherwise the
+next question is the whole of what they read.
+
+**Your prose is not the only thing they read.** A build kept the table above in
+prose and still put the whole preflight on screen twice, by two routes neither
+this rule nor the reader distinguishes: a heading naming the browser half of
+setup, and a background command whose description named the gate. The lines are
+described rather than quoted, for the reason at the end of this section.
+
+The first was a heading written before the work rather than about it — still a
+turn, still about control. The second was not the run talking at all: it was the
+description handed to a background Bash call, printed back by the harness when
+the command finished. **Name a background command for the thing they are waiting
+on, never for the machinery** — `Install dependencies`, not `Install headless
+browser for the gate`. A description carrying `gate`, `browser`, `preflight` or
+`marker` reaches the screen exactly as a sentence would.
+
+**Silence is earned by confirmed control, or by a decline. Nothing else earns
+it.** An earlier table had three silent rows and a run walked one of them: the
+probe answered, the marker failed, it said nothing and carried on — while a
+Chromium browser sat installed and extension-free at `/usr/bin/google-chrome`,
+one click from working. The user asked twice what was happening before anything
+surfaced. That row asserted no repair existed instead of going to look for one.
+Rows two and four here exist because the repair did.
+
+**What is never said is the topology.** *"The browser reachable from this session
+lives on another machine, so I can't look at your finished pages myself — I'll
+check them in a local headless browser"* was a real turn, and it is retired. It
+obeyed every rule this skill then had — cost stated once, in their terms, the
+extension unnamed — and it still told a mass spectrometrist about the deployment
+of their coding assistant and the inventory of browsers behind it. Each row above
+is a click, a restart, or an install: something to do. None of them is an
+explanation.
+
+**Where the browser runs is never a finding.** Claude Code is routinely a shell
+on one machine and a browser on another, and the user picked neither. Where it
+runs may route your next command; it never reaches the user, and there is no
+machine to suggest they move to. What decides whether you drive it is one thing
+only: whether it can load a page you serve on loopback.
+
+**Attached is not theirs.** The extension answering proves a browser exists
+somewhere you can reach — not that it can reach *you*. A run drove one for an
+entire preflight, screenshotting pages the user could not see, and learned the
+difference only when they said so. The marker separates those two: a browser
+that answers, from a browser that loads what this host serves.
+
+**What the marker cannot separate is presence.** It says the pair works; it
+cannot say a human is in front of that window, and nothing available can. `switch_browser` claims to — *"sends a connection
+request to every Chrome browser with the extension installed and waits for the
+user to click Connect"* — and it was measured: it **excludes the browser you are
+already attached to**. With one browser connected it returns *"No other browsers
+available to switch to"* in under six seconds. With two, and the user sitting at
+the attached one, it timed out at ~124 seconds three times running while that
+user watched their own Chrome and reported *"Nothing appears.."*. There was
+nothing to click. **Do not reach for it to confirm the browser you already
+hold** — it is structurally incapable of prompting that one.
+
+**Loopback reach is the closest thing to *their* window this framework can
+establish, and it is treated as such on purpose.** So where the rest of this file
+says the app opens in the user's window, it means the window that loaded what
+this host served — the best available proxy, and the only one. It is never a
+claim that someone is sitting at it.
+
+**Chromium only, but that is a wide family.** Claude Code registers its native
+messaging host for Chrome, Edge, Chromium, Brave, Arc, Opera and Vivaldi — check
+the machine rather than assuming, since the list is the installer's and can
+grow:
+
+```
+Windows:  HKCU:\Software\**\NativeMessagingHosts\com.anthropic.claude_code_browser_extension
+macOS:    ~/Library/Application Support/*/NativeMessagingHosts/
+Linux:    ~/.config/*/NativeMessagingHosts/
+```
+
+**Those paths list registrations, not installations.** They say which browsers
+the installer wrote a host manifest for, which is not which browsers are on the
+machine: a Windows box registering Chromium and Vivaldi had neither installed —
+only Edge — and a Linux box carried manifests in five browser directories with
+one browser on `PATH`. Read them to ask whether a browser you *found* is
+driveable. Never to find one.
+
+**There is no Firefox extension and there will not be one from here.** The host
+manifest declares a `chrome-extension://` origin, which Firefox cannot load, and
+no `Mozilla` registration is written. An earlier version of this rule said the
+host was registered "for Chrome, Edge and Chromium alone"; that was wrong, and
+it would have had you skip a Brave or Vivaldi install that works.
+
+**With control, open the app by driving to it.** Navigate the browser you
+already hold; it is the window that just proved it can load what you serve, and
+no other window has proved anything. That matters: otherwise a design round
+discusses two renderings of the same page, and a header truncated in one sits
+fine in the other.
+
+**With control, never launch anything to do it.** `start <url>`, `open <url>`
+and `xdg-open <url>` all open the *default* browser, which is how a user who had
+just installed the extension in Chrome was shown their app in Firefox. Naming a
+local executable instead does not fix it — the browser you drive need not be on
+this filesystem at all, so the path you found here can name a browser nobody is
+sitting at. Navigating the browser under control has neither failure: there is
+no default to resolve and no path to be wrong about.
+
+**Before you point it at the app, check the port is yours.** From the command
+line, not the PID. The app runs on this host and you started it, so confirm
+from the shell that the port is held by the process this run launched. A port
+you did not verify is a page you cannot vouch for. If it is not yours, take
+another port and relaunch rather than navigating at it.
+
+**The executable path cannot tell two builds apart.** A venv's python re-execs
+as the shared base interpreter, so another build's Streamlit has a
+byte-identical executable to yours and a PID check reads it as your own. Match
+on the command line — it carries the app path and the `--server.port` you
+passed. Two builds hit this: one confirmed a listening PID and moved on, the
+other took what it thought was a free port after a failed restart and got a
+`200` back from a different build's app still running on this machine. Both were
+about to judge someone else's page.
+
+**Once they have declined, open their default and say nothing about why.**
+Nothing is being protected now, so `start` / `open` / `xdg-open` is exactly
+right: they get their app in a window. You simply cannot see it, so never imply
+you can.
+
+Say only *"it's open at <url>"*. **That URL is always `localhost:<port>`** —
+whatever address you had to use to reach the app yourself is machinery, and
+theirs resolves from where they are sitting.
+
+And later, on that same road, **opening a page starts a browser** — but only a
+Chromium one is driveable.
+Opening the app after a decline opens their *default*, and re-probing after that
+finds nothing when there is nothing there to find. So a page opening is worth a
+re-probe only when what opened was a Chromium browser; the ask has its own
+re-check, and this rule does not govern it.
+
+**Their default is whatever they set it to, so look rather than assume.** An
+earlier version of this rule asserted that Edge ships as the default on Windows
+and that `start <url>` therefore reopens the browser you just launched. It is
+false — a Windows machine with Edge installed was measured defaulting to
+Firefox — and it did damage before it was caught: a run on Linux read it as
+licence to expect `xdg-open` to resolve to the Chrome it had launched moments
+earlier. It resolved to Firefox. When it matters what a page you opened landed
+in, ask the machine:
+
+```
+Windows:  HKCU:\Software\Microsoft\Windows\Shell\Associations\
+            UrlAssociations\http\UserChoice   ->  ProgId
+Linux:    xdg-settings get default-web-browser
+macOS:    the LaunchServices http handler
+```
+
+Chromium means that page just started something worth probing again. Anything
+else means there is nothing there to find.
+
+## Find a Chromium browser
+
+**Whenever control is not confirmed.** Not only when the probe came back empty —
+also when it answered for a browser that failed the marker, which is the case
+that most needs the search, and the case an earlier gate excluded. Something
+being attached is not a reason to stop looking: a browser on this machine that
+the extension is not in is one click from being the one you drive.
+
+Any browser from the family above. Windows keeps them under `Program Files`;
+elsewhere try the executable name on `PATH`. Edge ships with Windows, so on a
+Windows machine the answer is almost always yes.
+
+What you find decides which row of the table you are on: a browser here means
+the click; nothing here means the request to install one.
+
+## Connect control, by using it
+
+Its tools are deferred MCP
+tools, so they do not appear until asked for:
+
+```
+ToolSearch  select:mcp__claude-in-chrome__tabs_context_mcp,
+                      mcp__claude-in-chrome__navigate,
+                      mcp__claude-in-chrome__computer,
+                      mcp__claude-in-chrome__get_page_text,
+                      mcp__claude-in-chrome__list_connected_browsers,
+                      mcp__claude-in-chrome__select_browser
+mcp__claude-in-chrome__tabs_context_mcp   {"createIfEmpty": true}
+```
+
+`createIfEmpty` opens a **tab in a running browser**. It does not launch a
+closed one, and the extension is what answers the probe — so with the
+browser shut, control is unavailable and the probe rightly says so.
+
+**`tabs_context_mcp` answers for the MCP tab group, not for the browser.** Its
+own description says it returns the tabs *"inside the group"*, and that is
+literal: a tab opened by launching the browser executable at a URL does not
+appear in it. Measured, the tab list came back byte-identical after a launch
+whose page had demonstrably been fetched. So it can confirm nothing you opened
+by other means, and a run read it as *"the browser's tabs"* for an entire
+session before a measurement corrected it.
+
+**An empty probe is a step, not the answer.** Control is worth real effort —
+it is what puts the app in the window that proved it can load what you serve,
+instead of a second rendering
+of it — so the next move after an empty probe is a command, never another
+probe:
+
+```
+no schema?    ->  control does not exist in this session at all. There is
+                     no probe to run and launching a browser will not create
+                     one -- but still search, because the store page has to
+                     open somewhere and the last row of the ask cannot be
+                     chosen without knowing. Then go to the ask.
+probe empty?  ->  launch the browser found above, wait ~5s, probe again
+                     PowerShell:  Start-Process '<path found above>'
+                     POSIX shell: "<path found above>" >/dev/null 2>&1 &
+still empty?  ->  the extension is missing from that browser.
+```
+
+**Two failure shapes, and they are not the same.** A schema that loads
+and answers *"not connected"* means control exists and the browser is
+shut or the extension missing from it — fixable here. `ToolSearch`
+returning **no schema** means this session has no browser control to
+connect to at all: there is no probe to run, launching a browser cannot
+create one, and a session started afterwards is what picks the tools up.
+
+## Read the browser list, never show it
+
+`list_connected_browsers` returns every browser on the account —
+`deviceId`, `name`, `osPlatform`, `connectedAt`, `isLocal`. Read it to route
+yourself. **It does not reach the user.** Its own description mandates an
+`AskUserQuestion` listing every browser with its `deviceId` in the label, and
+that turn is the topology this skill retired — a mass spectrometrist reading
+UUIDs and operating-system names to fix a coding assistant. The mandate lives in
+that description alone; `select_browser` carries none of it, and says only
+*"select a specific Chrome browser by deviceId... without broadcasting a pairing
+request."* So a run may read the list and act on it without ever rendering it.
+
+**Only `deviceId` is stable. The names are positional.** The same device was
+`"Browser 2"` in one listing and `"Browser 1"` in the next, and the list
+renumbers as membership changes. Two orderings fit every listing measured and
+neither could be separated from the other, so do not infer one. Select by
+`deviceId`, and never carry a name from one listing to the next.
+
+**Nothing in the list says which browser you are attached to.** There is no such
+field, and `tabs_context_mcp` does not carry one either — a run that reported
+*"the session was attached to the wrong one"* had inferred it by elimination
+from a list holding exactly one non-local device, and could not have with two.
+You do not need it: the marker tells you whether the browser you hold can reach
+you, and that is the whole question.
+
+## Confirm by driving, not by probing
+
+A probe that returns is not proof.
+
+**Confirm it can reach *this* machine, with a page you serve.** A browser
+that answers is not the same as a browser that can load what you are serving,
+and the difference is invisible: a run drove a browser successfully for an
+entire build, pointed it at `localhost:8577`, and read **a different Streamlit
+app** on that port — reporting its pages back as this run's. Most likely an
+earlier build of the user's own, still running over there. The cause never
+mattered; only that the pixels belonged to different software. Nothing in the
+tab context distinguishes them — it reads `"New Tab" chrome://newtab/` either
+way. Only a page you serve can:
+
+```
+write  <tmp>/<token>.txt containing that token
+serve  <the interpreter you resolved> -m http.server <random port>
+         --bind 127.0.0.1 --directory <tmp>
+check  curl the URL from this shell first -- the token must come back
+drive  browser -> http://127.0.0.1:<port>/<token>.txt
+read   get_page_text, and match the token exactly
+see    computer screenshot, on that same page
+
+token + shot ->  both tools answer. Use it, and say nothing.
+token, no shot ->  it reaches you but you cannot see it. Drive it and read it;
+                  never say you have looked at a page.
+neither      ->  it cannot reach you. Go to the ask.
+```
+
+**The screenshot is a second verdict, not decoration.** This table read on the
+token alone until a session re-selected a re-attached device, passed the marker,
+drove pages and read their text — and had every `computer` call fail. On the old
+table that is *"it can reach you, say nothing"*, so the run went on believing it
+could see. Reading a page and looking at one are different capabilities and they
+fail apart; a run that cannot screenshot can still build, but every judgement
+that needs eyes — a truncated header, a flattened axis, a panel that did not
+render — is one it must stop claiming to have made.
+
+**One navigation proves both tools.** The screenshot goes on the marker page and
+not on a page of its own — measured, `computer` returns *"Successfully captured
+screenshot (1470x751, jpeg)"* on the served `text/plain` page, with the token
+legible in the image. An earlier version sent a run to "any ordinary web page"
+first, and a live run skipped that step as redundant, correctly: the marker is
+strictly the stronger check. Putting the screenshot on the page the run already
+had to load makes it unskippable and costs nothing. Point neither at
+`about:blank` — the screenshot tool refuses browser-internal URLs with *"Can't
+interact with browser-internal or unparseable URLs"*, so a blank tab fails the
+check while control is in fact working.
+
+**The token is at least ten characters, after trimming.** Nine fails. This was
+bisected on a live server, same tab, same `Content-type: text/plain`, varying
+only the body: `abcdefghij` passes, `abcdefghi` fails, and padding the nine with
+newlines or spaces still fails — the threshold applies to the trimmed text. A
+trailing newline is free. A run lost its marker to a nine-character token and
+diagnosed the extractor instead.
+
+**Never `python` here — use the interpreter you already resolved.** Bare
+`python` on `PATH` is a Microsoft Store stub on a default Windows box: it prints
+help and exits, so the server never starts and the marker fails as though
+control were broken. `capture-notebook-workflow` probes for a real interpreter
+and `notebook-to-webapp` names this trap twice; this recipe walked into it
+anyway, and a build following the line as written lost the check to it. Use
+`sys.executable`, the venv's python, or whatever the probe returned.
+
+**Write the bind out.** `python -m http.server` defaults to `0.0.0.0`, so
+dropping the flag does not narrow the bind, it widens it — and the wide bind is
+the one command the auto-mode classifier refuses, denied on two of four trials
+here and on every trial elsewhere. `--bind 127.0.0.1` is the only bind that can
+be assumed available on any host.
+
+**Loopback is the only candidate.** There is no walk. A routable interface has
+never once returned a token in any recorded run, the classifier's treatment of
+named routable addresses differs by host, and a browser that needs a routable
+hop to reach you is not the local one. WSL forwards localhost by default and
+`docker -p` publishes to it, so the ordinary deployments still pass here.
+
+**Curl before you drive, or you cannot read the answer.** A dead server and an
+unreachable browser produce the same browser-side error. A run picked a port
+that was already in use, its server died with `Address already in use`, and it
+navigated at the corpse and read the error page as a marker failure — four
+wasted calls chasing a browser that was fine. The `curl` separates them: it
+passes, and every later browser failure is evidence about the browser.
+
+**Pick the port at random and mean it.** Three separate builds all used 8791,
+which is how one of them collided.
+
+**Never read the token from the URL or the tab title.** Tab context echoes back
+the URL you *requested* — token and all — even when the navigation totally
+failed, so a token seen there is your own input read back as proof. Titles are
+worse: a `text/plain` page has none, and the title is stale for a beat after
+navigating. The token has to come out of the page body.
+
+**A candidate you cannot test is a candidate that failed.** A sandbox that
+blocks the navigation has not left you an open question — it has left you
+without the evidence, which lands in the same place as evidence against. A run
+treated that gap as a third state, reported *"I can't yet trust it"*, promised
+itself a retest later, and drove nothing in the meantime. There are two verdicts
+here and no others.
+
+**A browser that fails the marker is never driven.** Not for the smoke run, not
+for a design round, not once. It renders *some* app on that port convincingly,
+and a screenshot of the wrong app is worse than no screenshot: it is a finding
+about different software, delivered to your user as one about theirs.
+
+## When it breaks later
+
+Control is confirmed once, at preflight, and then used. There is no re-check
+between rounds — but the confirmation can stop being true, and **it stops
+silently in the success direction**, which is why the recovery below exists.
+
+A user closed their browser mid-session. Their device left
+`list_connected_browsers` on its own, the session was **silently re-attached to
+a browser on another machine**, and `navigate` went on returning *"Navigated to
+`<url>`"* — success, every call — while rendering somewhere nobody was sitting.
+No error surfaced. Only serving a page and failing to read it back revealed it.
+
+**Two things are not evidence, and both look like it.** `pgrep` counted three
+live Chrome processes after that device had already left the list, so a running
+browser is not a connected device. And a successful `navigate` return says the
+call was accepted, not that anything you recognise is on screen.
+
+**When a page comes back wrong, re-enumerate — do not re-probe.**
+`tabs_context_mcp` answers for whatever you are attached to now and will look
+perfectly healthy on the wrong browser. `list_connected_browsers` is what shows
+the device is gone. A run re-probed twice after its user acted, saw the same
+healthy answer both times, and missed a browser that had appeared five calls
+earlier.
+
+**The repair is one action and it is theirs: reopen the browser.** Measured —
+the device returns to the list on its own with a fresh `connectedAt`, with no
+reinstall, no sign-in and nothing else asked of them. Then `select_browser` by
+`deviceId`, and marker it again before you show them anything.
+
+**`tabGroupId` is per-attachment, not per-device.** Reattaching to the *same*
+device yields a new group, so a change tells you only that something moved,
+never what. If you have one recorded, unchanged means you are still on the
+attachment you verified; changed means re-marker. It never means reselect.
+
+## The ask
+
+**Take them to it; do not offer to mention it later.** You cannot finish this
+yourself — the extension comes from the store, in their browser, under their
+claude.ai account, and the click and the sign-in are theirs. Everything up to
+that is yours. Open `https://claude.ai/chrome` **in the browser you found, by
+naming it**, say the one thing to click, and scale the request to the row you
+are on:
+
+```
+PowerShell:  Start-Process '<path found above>' 'https://claude.ai/chrome'
+POSIX shell: "<path found above>" 'https://claude.ai/chrome' >/dev/null 2>&1 &
+```
+
+**Never `start`, `open` or `xdg-open` here.** The extension goes into *one*
+browser, and those three resolve the *default*, which is a different browser
+until proven otherwise. A run did every earlier step correctly — searched the
+family, found `/usr/bin/google-chrome`, launched it, probed — and then opened
+the store page with `xdg-open`. It landed in Firefox, which cannot install a
+`chrome-extension://` origin at all, and the run told the user *"I've opened a
+page in your Chrome"* on no evidence whatever.
+
+Measured, naming the executable hands the URL to an **already-running** instance
+rather than starting a second one: the command returned in 94ms, the served
+page's own log showed a `/favicon.ico` fetch that `curl` never makes, and the
+browser process count rose by exactly one — a renderer, not a second window.
+**Do not confirm it with `tabs_context_mcp`**, which came back byte-identical
+after that same launch. Nothing needs to confirm it: the watch below is what
+says whether the extension arrived, and that is the only outcome that matters.
+
+```
+marker failed, browser here  ->  the command above opens the store page in it,
+                                    launching it if it is not running:
+                                    "one click to add the Claude browser
+                                    extension and I can check the finished
+                                    pages myself."
+schema, not connected        ->  the same click, in the browser already there.
+no schema at all             ->  the click, then: "one click to add it, then
+                                    start me again -- nothing's been decided
+                                    yet, so there's nothing to lose."
+no Chromium browser at all   ->  ask them to install one -- Chrome, Edge,
+                                    Brave, any of the family -- once, plainly,
+                                    and as something they may say no to.
+```
+
+**Preflight stops here until they answer — but what stops is the question, not
+the work.** The notebook question does not go out, and neither does anything
+else that moves the run *past* them; asking and pressing on regardless is how a
+run reaches the headless browser without a decline, which is the thing that must
+not happen. Setup that has to happen anyway does not stop. Finish the rest of
+preflight while they click — the gate's headless browser is the slow one, and it
+is already sequenced after this step.
+
+**Then look for the device yourself. Do not wait to be told.** The extension
+announces itself by appearing in `list_connected_browsers`. Their words are not
+the signal and never were:
+
+```
+end of preflight  ->  list_connected_browsers, once
+   device there?  ->  select by deviceId, marker it, say nothing
+   nothing yet?   ->  look again every 15 seconds
+```
+
+Keep looking until the device appears or they say something. A run that waited
+for a turn instead had its user type *"continue"* to unstick it — and that
+device's `connectedAt` proved it had connected **before** they typed. The entire
+wait was invented. Nothing here ever forbade a loop; the wording simply
+described enumeration as a response to their reply, which pinned it to a turn
+boundary instead of to the clock.
+
+**There is nothing to watch on the no-schema road.** `list_connected_browsers`
+is one of the tools that did not load, so there is no list to poll and no device
+that can appear in *this* session — which is precisely why that row of the ask
+asks for a restart and not for a click alone. Watch on every road where the
+schema loaded. On that one road the ask is the end of what this session can do,
+and pretending to watch is how a run would sit polling a tool it does not have.
+
+**Only an explicit no is a decline.** If they speak before the watch has found
+anything, read the list before reading their words: whatever they reply,
+re-enumerate, re-select and re-marker once, and if control now answers, use it
+and say nothing further. Their click may have created a
+device that was not there when you asked — one appeared nineteen minutes into a
+preflight, and the run that only re-probed did not see it for five more calls.
+If control still does not answer and they have not plainly declined — they said
+*"done"*, or *"later"*, or answered with their notebook path — ask once, short:
+*"carry on without it?"* That is the only follow-up, and their answer to it
+settles the run either way.
+
+**Then it is settled and it is never raised again.** Not at the first design
+round, not at the gate, not when a page would have been easier to check.
+*"Happy to point you at the setup for next time"* is the failure — it converts a
+one-click fix available right now into homework. So is raising it later — *"I'd
+have to ask you to set that up"*, landing mid-decision, which is the thing this
+step exists to prevent.
+
+**Name the extension only to act on it.** Naming it to explain a limitation is
+plumbing talk — *"your Chrome extension isn't connected, so I can't check the
+pages"* tells a mass spectrometrist about this framework's wiring and gives them
+nothing to do. Naming it inside a request is different, because it comes with an
+action and a reason. After they decline, it is not named again.
+
+**On the decline, one line, and it is about them.** *"I'll ask you to look at a
+page or two as we go."* That is the whole of it: what they will be asked to do.
+Not what you cannot see, not what the headless browser does instead, not why.
+The run then behaves exactly as that line promised — rounds put one named thing
+in front of them, in the words of the page: *"the header on the left column —
+does that read right to you?"*
+
+**Check that it started; `start` on Windows does not.** A measured run
+issued `cmd /c start "" "<path>"`, saw its own `launched` echo, probed,
+and moved on — and no browser had opened. `start` hands off and returns
+whether or not anything ran. **This governs the bare launch that precedes a
+probe** — the one under "an empty probe is a step" — because a browser that never
+started and a browser missing the extension produce the same empty probe, and
+nothing afterwards tells them apart. Both forms in that block were verified to
+leave a process behind, and you confirm the process anyway, because the form that
+failed was a third one. A live process is still not a connected device: the probe
+decides. **The store-page launch is not this case** — nothing there waits on a
+probe, and the watch is what settles it.
+
+
+## What is said, and what is not
+
+**No preamble, ever.** Nothing said *ahead of the ask* about what you will need
+from them later, no reason offered, no tour of which browser checks what.
+Stating the cost *once, early* was itself a rule here, and it was wrong: it
+guaranteed a turn whose only content was the framework describing itself to
+someone who had asked for an app. **A preamble is speech before they have
+chosen**, which is what makes two sentences here not preamble at all: the ask,
+which is a request for a click that the table licenses, and the one line after a
+decline, which follows their own answer and tells them what they just chose.
+
+**If control is real, nothing is said about it at all.** Announcing control
+*before* driving anything is how a session ends up claiming a capability it has
+not established, or disclaiming one it has.
+
+**The setup summary claims nothing you have not done.** A summary exists only
+where something else licenses one — a direct question, or the orchestrator's
+optional one-line *"setting up"*. Nothing here licenses volunteering one; this
+governs the wording of a summary already licensed elsewhere. A run ended preflight
+with *"Everything's set up ... and I can open pages in your Chrome and check
+them myself"*, and had to retract the second half later: *"Correct — I can't."*
+Opening and checking have different requirements, so a sentence joining them is
+half true at best. Until you have driven a page and seen your own marker come
+back, the summary says what was installed and nothing about checking.
+
+**Asked directly, answer fully.** *"What about driving Chrome?"* is a question
+about the machinery from someone who wants the machinery, and every rule above
+governs what you *volunteer*, not what you answer. Say what was probed, what was
+served, what came back, what it means and what would change it — plainly, and
+without hedging. What a direct question does not license is the third state: a
+run answered one with *"I can't yet trust it, I'll retest later"*, which was
+neither verdict and left the user holding a browser nobody had decided about.
diff --git a/.claude/skills/create-page.md b/.claude/skills/create-page/SKILL.md
similarity index 92%
rename from .claude/skills/create-page.md
rename to .claude/skills/create-page/SKILL.md
index 063d1c43..7245c407 100644
--- a/.claude/skills/create-page.md
+++ b/.claude/skills/create-page/SKILL.md
@@ -1,3 +1,8 @@
+---
+name: create-page
+description: Use when adding a standalone Streamlit page to an OpenMS app, or when a page needs tracked parameters backed by default-parameters.json.
+---
+
 # Create a New Streamlit Page
 
 Add a new page to the OpenMS web application.
diff --git a/.claude/skills/create-workflow.md b/.claude/skills/create-workflow/SKILL.md
similarity index 69%
rename from .claude/skills/create-workflow.md
rename to .claude/skills/create-workflow/SKILL.md
index 07856db2..382131f6 100644
--- a/.claude/skills/create-workflow.md
+++ b/.claude/skills/create-workflow/SKILL.md
@@ -1,3 +1,8 @@
+---
+name: create-workflow
+description: Use when creating a TOPP Workflow Framework workflow that chains OpenMS TOPP tools through upload, configure, execute and results pages.
+---
+
 # Create a TOPP Workflow
 
 Create a complete mass spectrometry data processing workflow: a WorkflowManager subclass and its 4 associated content pages.
@@ -44,22 +49,31 @@ class MyWorkflow(WorkflowManager):
         with t[1]:
             self.ui.input_TOPP("ToolName2")
 
-    def execution(self) -> None:
+    def execution(self) -> bool:
+        # Must return True on success, False on any failure - see "Execution" below.
         if not self.params["mzML-files"]:
             self.logger.log("ERROR: No input files selected.")
-            return
+            return False
 
         in_files = self.file_manager.get_files(self.params["mzML-files"])
         self.logger.log(f"Processing {len(in_files)} files...")
 
         # Step 1
         out_step1 = self.file_manager.get_files(in_files, "featureXML", "step1")
-        self.executor.run_topp("ToolName1", input_output={"in": in_files, "out": out_step1})
+        if not self.executor.run_topp(
+            "ToolName1", input_output={"in": in_files, "out": out_step1}
+        ):
+            return False
 
         # Step 2
         in_step2 = self.file_manager.get_files(out_step1, collect=True)
         out_step2 = self.file_manager.get_files("result.consensusXML", set_results_dir="step2")
-        self.executor.run_topp("ToolName2", input_output={"in": in_step2, "out": out_step2})
+        if not self.executor.run_topp(
+            "ToolName2", input_output={"in": in_step2, "out": out_step2}
+        ):
+            return False
+
+        return True
 
     @st.fragment
     def results(self) -> None:
@@ -111,8 +125,14 @@ The 4 pages call these methods respectively:
 - `self.file_manager.get_files("name.ext", set_results_dir="dir")` — single result file
 
 ### Execution
-- `self.executor.run_topp("ToolName", input_output={"in": [...], "out": [...]})` — run a TOPP tool
-- `self.executor.run_python("script_name", {"in": [...]})` — run a Python tool from `src/python-tools/`
+- `self.executor.run_topp("ToolName", input_output={"in": [...], "out": [...]})` — run a TOPP tool; returns `False` if any command failed
+- `self.executor.run_python("script_name", {"in": [...]})` — run a Python tool from `src/python-tools/`; returns `False` if the script is missing or exited non-zero
+- **`execution()` must be annotated `-> bool` and return `True` only when every step
+  succeeded**, `False` on bad input or a failed tool. `workflow_process()` logs the
+  `WORKFLOW FINISHED` marker only for a truthy return, and a missing marker is classified
+  as an error — so an `execution()` that returns nothing renders "Errors occurred, check
+  log file." after a perfectly good run. Gate every `run_topp` / `run_python` call on its
+  return value too, or a tool that fails halfway is still reported as a success.
 
 ### UI widgets
 - `self.ui.upload_widget(key, name, file_types, fallback)` — file upload with example data fallback
@@ -120,10 +140,31 @@ The 4 pages call these methods respectively:
 - `self.ui.input_TOPP("ToolName", custom_defaults={})` — auto-generated TOPP parameter UI
 - `self.ui.input_python("script_name")` — auto-generated Python tool parameter UI
 - `self.ui.input_widget(key, default, label)` — single custom widget
+- `select_input_file`, `input_TOPP` and `input_widget` accept `reactive=True` to rerun `configure()` when the widget changes (for conditional UI — see below)
 
 ### Logging
 - `self.logger.log("message")` — log progress during execution
 
+## Conditional UI (reactive)
+
+Parameter widgets are isolated in an `st.fragment` by default, so a change reruns only that
+widget and can't show/hide other widgets. Pass `reactive=True` to render the widget in the
+parent scope instead — a change then reruns `configure()`. Read the live value from
+`st.session_state` (not `self.params`, which is stale within the rerun) using
+`self.parameter_manager.param_prefix` for custom-widget keys or `topp_param_prefix` for TOPP
+keys of the form `"<Tool>:1:<param path>"`.
+
+```python
+@st.fragment
+def configure(self) -> None:
+    pm = self.parameter_manager
+    # changing the tool's `type` selectbox reruns configure()
+    self.ui.input_TOPP("IsobaricAnalyzer", reactive=True)
+    iso_type = st.session_state.get(f"{pm.topp_param_prefix}IsobaricAnalyzer:1:type", "")
+    if iso_type.startswith("tmt"):
+        self.ui.input_widget("tmt-channels", 10, "TMT channels", widget_type="number")
+```
+
 ## Reference Files
 
 - Example workflow: `src/Workflow.py`
@@ -143,7 +184,9 @@ The 4 pages call these methods respectively:
 - [ ] Workflow class in `src/` subclassing `WorkflowManager`
 - [ ] `__init__` calls `super().__init__("Name", st.session_state["workspace"])`
 - [ ] `upload()`, `configure()`, `execution()`, `results()` implemented
+- [ ] `execution()` annotated `-> bool`, returning `True` on success and `False` on any failure
 - [ ] `@st.fragment` on `configure()` and `results()`
+- [ ] `reactive=True` on any widget whose value controls other widgets' visibility
 - [ ] 4 content pages created in `content/`
 - [ ] All 4 pages registered as a group in `app.py`
 - [ ] Default parameters added to `default-parameters.json` if needed
diff --git a/.claude/skills/interview-parameters/SKILL.md b/.claude/skills/interview-parameters/SKILL.md
new file mode 100644
index 00000000..2c4445ab
--- /dev/null
+++ b/.claude/skills/interview-parameters/SKILL.md
@@ -0,0 +1,346 @@
+---
+name: interview-parameters
+description: Use when deciding which parameters of a captured notebook or python tool belong on an app's configuration page, when a DEFAULTS list needs curating, or when notebook constants must be triaged into user-facing settings and fixed values.
+---
+
+# Interview parameters
+
+Decide which values the app's user gets to change: from **where in the notebook
+each value came from**, and from measurement wherever one is about to be
+*hidden*. Runs as **one batch review** after capture, never as a stream of
+questions mid-extraction.
+
+## The rule
+
+**A parameter is never recommended `HARDCODE` on the evidence of a one-at-a-time
+sweep.**
+
+Parameters interact. A sweep that moves nothing may be measuring a parameter
+another has swamped, and reporting that as "no effect" hardcodes the setting the
+user most needs. Re-probe with each other numeric parameter driven to its neutral
+value first.
+
+Masking is a **comparison** between the masked and unmasked effect, never a test
+for zero — an inert parameter still registers a few percent of noise.
+
+*Worked:* a notebook passes both an absolute and a relative tolerance into a
+closeness test of the form `|a-b| <= atol + rtol*|b|`. The relative one is left at
+a value that alone opens a window orders of magnitude wider than the absolute one
+ever reaches, so sweeping the absolute across its entire usable range moves the
+result by a fraction of a percent. A naive probe reports that as inert and
+recommends hardcoding the most important parameter in the notebook; with the
+relative one neutralised, the same sweep moves the result completely. Correct
+output: *keep both, and say they interact*.
+
+## Two sections, in this order
+
+### 1. Shortcuts and suspicious constants
+
+Everything capture collected — truncations, intent comments, discarded results,
+constants failing a domain sanity check. Each gets **drop / promote to parameter /
+keep as written**, arriving as a one-word decision with the recommendation already
+made, the user's own line quoted, and the runtime it costs at full scale in the
+parenthetical. `capture-notebook-workflow` has the exact shape.
+
+First, because **the probe in section 2 is invalid until this resolves**: a
+truncation caps the output, so every sweep beneath it measures the cap.
+
+Represent a resolved truncation as a parameter whose default reproduces the
+notebook, then change the default — equivalence stays provable and the decision is
+one line in `DEFAULTS`.
+
+### 2. Config parameters
+
+**Every row arrives already decided.** The user's work is disagreeing, not
+choosing from nothing — so what they are asked is whether the decision stands,
+not what they would like. Not a stream of questions, and not a wait.
+
+Rank by provenance — named constants and default arguments > `setValue` arguments
+> inline literals > untouched algorithm parameters — and pre-tick what a mass
+spectrometrist would expose: tolerances, score and intensity thresholds, charge
+and length ranges, the enzyme where the sample varies.
+
+Capture's harvested sweeps arrive as **prior evidence** and move rows up that
+ranking: a parameter its author swept is one they thought mattered enough to
+teach, so pre-tick it. And **a flat sweep is a masking candidate** before a single
+probe runs — never read one as *this does nothing*. What to say instead is below.
+
+**Ask once, whole.** The list is already decided; what the user is being asked
+is whether that decision stands — and most of the time it does. So the first
+question is the only one most runs need. Show the split, then offer three ways
+out of it:
+
+```
+I'd expose these on the config page, and fix the rest at your notebook's values:
+
+  exposed   precursor tolerance · fragment tolerance · enzyme ·
+            missed cleavages · peptide length
+  fixed     max. fragment charge · b/y ions · limit on spectra searched
+
+The two tolerances interact — if either is exposed, both are.
+```
+> *Take it as it stands* · *Let me change some* · *Measure what each one
+> actually moves first (~90 s)*
+
+**Those three are options the user selects — not a line they read.** A list of
+rows with `[x]` beside them is a form drawn into a transcript: nothing can be
+ticked, so disagreeing with one row means retyping all of them — right rows and a
+right recommendation, with nothing to act on.
+
+**Only *let me change some* opens the list**, and then in groups, not rows —
+tolerances, digestion, ion generation, limits. Nine rows do not fit one screen of
+options; four groups do, and someone who wants one row different almost always
+wants its neighbours left alone. A group they open resolves row by row.
+
+Say which rows came from the notebook's own sweeps; the person who wrote that
+cell should recognise their own numbers.
+
+**The probe does not run by default.** It is the longest wait in the framework —
+O(n²), and the skill's own arithmetic puts 43 parameters at 6.2 hours — spent to
+produce recommendations that provenance already gives correctly for every verdict
+except one. Offer it; run it when asked, or when a `HARDCODE` is on the table.
+
+**Offer it in the user's words, not in this skill's.** *Masking*, *the probe*,
+*the sweep*, `HARDCODE` — this page is full of them because they are how the work
+is thought about, and every one of them is invisible to a mass spectrometrist.
+`masking` is on the forbidden list in `notebook-to-webapp` and still reaches
+users, because the sentence gets written from **this** page.
+
+| here | on screen |
+|---|---|
+| run the probe | measure what each setting actually changes |
+| the masking re-probe | check whether one setting is swamping another |
+| a flat sweep | changing it barely moves the result |
+| `HARDCODE` | fix it at your notebook's value |
+| the masking above | what I described — *"the wide window above"* |
+
+**The last row is the one that gets missed.** The first three are verbs, and a
+verb is easy to translate because you are about to describe an action anyway. The
+leak that survived was a **label**: having explained the effect properly — *"adds
+10% of the peptide mass, a ~150 Da window, so the Da tolerance never gets to
+decide anything"* — the next bullet referred back to it as *"the masking above"*.
+
+Refer back by what it **does**, never by what this skill calls it. If a phrase
+would need the reader to have read this page, it is the wrong phrase, and that is
+true of a one-word back-reference just as much as of an instruction.
+
+## An unmeasured parameter may be exposed, never hidden
+
+This is what makes the probe optional without giving up what it was for.
+
+Exposing a parameter that turns out not to matter costs one row on a config page.
+Hiding one that does matter is the failure this skill exists to prevent, and the
+user cannot recover from it — they cannot see what was taken away.
+
+| verdict | needs a measurement first |
+|---|---|
+| KEEP, ADVANCED | no — provenance and domain sense are sufficient |
+| DASHBOARD CONTROL | no — a display constant is one by inspection |
+| **HARDCODE** | **yes**, and the masking re-probe with it |
+
+The masked case above is the proof this is the *safer* default and not the looser
+one. The naive probe measured a fraction of a percent on the absolute tolerance
+and recommended hardcoding the most important parameter in the notebook. Provenance ranks that parameter first — it is
+a default argument to the matching call — and exposes it having measured nothing.
+The probe's unique power is only ever the negative verdict, and the negative
+verdict is the only one that needs it.
+
+## Explaining a flat sweep
+
+A flat sweep is where the user is most likely to be handed a question they cannot
+answer. *"The sweep is flat across a 100-fold range. How should I treat it?"* asks
+them to know this skill's central finding in order to reply.
+
+Say what they wrote, what it looks like, what it actually is, and what you would
+do:
+
+```
+Your <exercise> varies the precursor tolerance across <range> and the number of
+candidate peptides barely moves — <before> to <after>.
+
+That usually means a setting does nothing and can be fixed. Here it means the
+opposite: the *relative* tolerance set <k> cells earlier already opens a window
+far wider than that, so the tolerance being varied never gets to decide anything.
+
+I'd keep both and show them together on the config page.
+```
+
+## When measurement is asked for, or a HARDCODE is on the table
+
+Probe the shortlist, never the full surface:
+
+```bash
+python probe.py --script src/python-tools/<name>.py \
+    --inputs <input files> --budget-key <limiting param> --budget 30
+```
+
+It sweeps each parameter across `min`/default/`max` (booleans both ways, options
+exhaustively), reduces `OUTPUTS` to metrics, and re-probes anything below the
+materiality threshold for masking. Give it `--budget-key` or a probe on real data
+takes minutes per sweep.
+
+**The budget key must limit work before the expensive step, not after it.** A
+resolved truncation is the obvious candidate and often the wrong one: `max-features`
+on a tool whose cost is feature detection buys no time at all *and* pins
+`features.rows`, so every effect size measures the cap rather than the parameter —
+the same failure as probing before shortcuts resolve, wearing a different hat, and
+it looks like the right answer. When nothing genuinely limits work early, budget by
+shrinking the **input** instead: crop the mzML to a short RT window.
+
+`probe.py` verifies this rather than trusting the choice — it times a run at the
+budget and at a quarter of it, and warns loudly if the smaller one is not
+meaningfully faster.
+
+**A sweep that lost points has no verdict.** When a run fails, its point is
+dropped from the effect calculation, so the effect is measured over fewer values
+and reads lower than the truth — again the direction that produces HARDCODE.
+`probe.py` reports such a parameter as `INCOMPLETE` rather than giving it a
+recommendation. The usual cause is a numeric `DEFAULTS` entry with no declared
+`min`/`max`, so the sweep invents bounds and probes a value the tool rejects; fix
+the declaration and re-probe rather than accepting the reading.
+
+**Say what it will cost before starting, and never leave the user watching
+nothing.** This is the longest wait in the framework. `probe.py` times its
+baseline, prints an estimate, names each parameter as it starts, and narrates the
+masking re-probe. Relay the estimate; if it is long, say what `--budget` buys. A
+user who asks "what is it doing?" has already been failed.
+
+## Resolving each row
+
+| effect | recommendation |
+|---|---|
+| masked by another parameter | **KEEP**, and keep the masking parameter too |
+| large | **KEEP**, on the config page |
+| small but real | **ADVANCED** (`"advanced": True`) |
+| none, and not masked | **HARDCODE** (omit from `DEFAULTS`) |
+| display-time only | **DASHBOARD CONTROL**, hand to the dashboard stage |
+
+**ADVANCED is hiding, so it is offered and not applied.** The other verdicts
+change what the app computes; this one changes only what the user can see, and
+that makes it theirs. Three builds on two notebooks put parameters behind an
+`advanced` toggle on the strength of a small effect size and told the user
+afterwards — *"under `advanced`: peptide length min/max, limit on spectra
+searched"* — and all three readers flagged the same thing: they were being shown
+a decision, not asked one. This page already says an unmeasured parameter may be
+exposed and never hidden; a measured-small one is no different, because *small*
+is a property of the sweep and *worth seeing* is a property of the person.
+
+Put the ADVANCED candidates in the interview beside the rest, name the effect
+that puts them there, and let anything come back out.
+
+Propose a widget type with every kept parameter, and give an **explicit**
+`widget_type` to anything a preset should drive — auto-typed numeric, selectbox
+and multiselect widgets double-prefix their session key, so presets silently fail
+on them.
+
+## When the user says to skip it
+
+*"They look fine, just use the notebook's values"* is a waiver of something they
+have not been shown — and section 1 is the half they cannot guess at: a
+`head(5)`, a tolerance that is a defect, a constant that is really a selection.
+**Show the batch, then let them clear it in one word.** Accepting every
+recommendation at once is theirs to do; skipping the presentation is not, because
+the rows they would be accepting are the ones they have not seen.
+
+This is where *never ask for what you can determine* stops. That a constant is
+**suspicious** is determinable, and saying so costs the user nothing. Whether it
+is a setting, a shortcut, or a defect is theirs. A reader under this pressure
+collapsed the batch to "one pass, no interview" and cited the determinable rule
+to justify it.
+
+`mode=auto` is the sanctioned way to take every recommendation without blocking,
+and it still emits the batch to the transcript. A human-facing run always shows it.
+
+## Every effect size carries the scope it was measured under
+
+A masking verdict is only valid over the parameter set it was computed on.
+`probe.py` re-probes against the other entries in `DEFAULTS`, not the algorithm's
+full surface — so "each other numeric parameter" means *each one in the set being
+probed*.
+
+An extracted tool exposes the parameters its author named; the library calls
+underneath it expose many more. **11 named, 43 in all, 32 of them hidden.** A row reading `fragment tolerance 97.2% KEEP` was measured with
+those 32 pinned at values nobody chose. Widen the set and the row stops being
+evidence.
+Say what the numbers were measured over every time you show them, and re-probe
+rather than carrying old figures forward beside new parameters.
+
+The probe is O(n²) — bound it first. At ~4s per run: 11 parameters is 2.3 min
+of sweeps and up to 0.4 hours of masking; 43 is 8.8 min and **6.2 hours**.
+`probe.py` estimates this and refuses a pass predicted over an hour without
+`--allow-long`.
+
+**Crop first; the choices below are for when a cropped pass is still refused.**
+That is the ordinary outcome and it is why this table is rarely reached: measured,
+3 of 3 readers priced the full pass at ~2 hours, named the refusal, cropped the
+mzML to a five-minute window, and finished in fifteen. Reaching for the table
+before cropping offers the user a menu of compromises they did not need. It
+applies where bounding cannot get there — a parameter set large enough that even a
+short window leaves hours, or an input that cannot be cropped without flooring the
+metric.
+
+When a bounded pass is still refused, put the four choices to the user rather than
+picking one:
+
+| choice | what it costs |
+|---|---|
+| `--params a,b,c` | probe a shortlist; the rest get **no verdict** |
+| `--budget <smaller>` | faster and coarser; effect sizes carry that scope |
+| `--no-masking` | minutes instead of hours, but it **cannot distinguish inert from masked** — the single error this skill exists to prevent. Say that plainly whenever you offer it |
+| `--allow-long` | run it as-is; say how long |
+
+A parameter the probe never measured has no verdict *of the kind a probe gives*:
+no effect size, and never `HARDCODE`. It still carries the provenance
+recommendation every row in the batch carries — that is precisely what makes the
+probe optional — but the two must never be dressed as each other. Mark the
+unmeasured ones, keep them out of the effect-size table rather than listing them
+at 0%, and offer a probing pass. **Never show an unmeasured parameter beside
+measured ones without saying which is which** — 0% next to 97.2% reads as "no
+effect" when it means "never tested".
+
+(Before the probe became opt-in this read *"they cannot be given a
+recommendation"*, which was right when every row was measured and, left standing,
+forbids the batch in §2 outright.)
+
+## Never hardcode a parameter whose value depends on a visible one
+
+A masked pair is indivisible. Freezing one half while exposing the other is
+never valid, and the reason is usually a reasonable-sounding request to simplify
+the config page.
+
+Measured: hide `precursor-tolerance-abs` at the notebook's 0.1 Da, leave
+`precursor-tolerance-ppm` visible, and a user asking for a tight 10 ppm — a
+0.017 Da window — gets **367 spectra with candidates instead of 94**. The hidden
+control is six times wider than the one requested, so it wins. **A hidden
+parameter that overrides a visible one is worse than an extra visible parameter**;
+the user can at least see the extra one.
+
+When a budget cannot be met without splitting a pair, offer the three real options
+rather than picking silently:
+
+| option | what it costs |
+|---|---|
+| **keep both** | budget becomes N+1; usually right |
+| **hardcode both**, coherently together | the control is lost, but nothing on screen lies |
+| **collapse into one derived control** | most work; expose ppm and derive the absolute, as production search engines do |
+
+Generally: **if hiding a parameter would let it contradict one that stays visible,
+it cannot be hidden.** Hardcoding is safe only for a parameter nothing visible
+interacts with. A user constraint is not a reason to break an invariant the probe
+was run to establish — honour it if you can, price it if you cannot, and let them
+decide. They asked for a simple page, not a lying one.
+
+## Common mistakes
+
+- Probing before shortcuts are resolved. Every sweep measures the truncation.
+- Treating "past the zero threshold" as "has an effect" — **once masking has
+  been ruled out**. 0.7% across a parameter's whole usable range is inert in
+  practice only when nothing was swamping it; the same fraction of a percent on a
+  masked parameter is this skill's flagship case. The reading alone never
+  decides.
+- Reporting the first masking parameter found. Check all, report the strongest.
+- Silently fixing a suspicious constant. It is a finding with a
+  recommendation, not a repair — changing it re-derives the golden values.
+- Forgetting a parameter can produce nothing. A strict tolerance may
+  legitimately identify zero rows; the tool must still emit its declared schema so
+  panels render an empty state instead of a traceback.
diff --git a/.claude/skills/interview-parameters/probe.py b/.claude/skills/interview-parameters/probe.py
new file mode 100644
index 00000000..e1208bb6
--- /dev/null
+++ b/.claude/skills/interview-parameters/probe.py
@@ -0,0 +1,374 @@
+"""Measure what each parameter of a python tool actually does.
+
+Runs the tool repeatedly on a downsampled input, sweeping one parameter at a
+time, and reports the measured effect on its declared OUTPUTS.
+
+A parameter that shows no effect in isolation is re-probed with every other
+numeric parameter driven to its neutral value. If an effect appears, the
+parameter is MASKED, not inert -- reporting those as inert is how a probe ends
+up recommending that the most important parameter in a notebook be hardcoded.
+
+Usage:
+  python probe.py --script identify.py --inputs a.fasta b.mzML \
+      --budget-key max-spectra --budget 40
+"""
+from __future__ import annotations
+
+import argparse
+import importlib.util
+import json
+import subprocess
+import sys
+import tempfile
+import time
+from pathlib import Path
+
+import pandas as pd
+
+# A metric must move by more than this fraction to count as any effect at all.
+EFFECT_THRESHOLD = 0.02
+
+# Below this, a parameter is not yet worth surfacing on its own evidence, so it
+# is a candidate for masking. Masking is a COMPARISON between the masked and
+# unmasked effect, never an absolute test for zero: Task 2's precursor tolerance
+# measures 4.2% as shipped -- past a zero test, but still inert across its whole
+# usable range, because another parameter opens a window 1700x wider.
+MATERIAL_THRESHOLD = 0.25
+
+# Unmasking must reveal an effect at least this many times larger to be reported
+# as masking rather than noise.
+MASKING_RATIO = 3.0
+# Refuse to start a masking pass predicted to run longer than this without
+# --allow-long. O(n^2) is fine at 11 parameters and an overnight job at 43.
+LONG_PROBE_HOURS = 1.0
+
+
+def load_tool(script: Path):
+    spec = importlib.util.spec_from_file_location("tool_under_probe", script)
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    return mod
+
+
+def sweep_values(param):
+    """Three probe points for a parameter, or None if it is not probeable."""
+    value = param.get("value")
+    if isinstance(value, bool):
+        return [False, True]
+    if isinstance(value, (int, float)):
+        lo = param.get("min", 0 if value >= 0 else value * 2)
+        hi = param.get("max", value * 4 if value else 1)
+        pts = sorted({lo, value, hi})
+        if isinstance(value, int) and not isinstance(value, bool):
+            pts = sorted({int(round(x)) for x in pts})
+        return pts if len(pts) > 1 else None
+    if param.get("options"):
+        return list(param["options"])
+    return None
+
+
+def neutral_value(param):
+    """The value at which a parameter stops contributing."""
+    value = param.get("value")
+    if isinstance(value, bool):
+        return False
+    if isinstance(value, (int, float)):
+        return param.get("min", 0)
+    return value
+
+
+def run_once(script: Path, base: dict, overrides: dict, outputs) -> dict | None:
+    """Run the tool once and reduce its outputs to a metric dict."""
+    with tempfile.TemporaryDirectory() as tmp:
+        out_dir = Path(tmp) / "out"
+        out_dir.mkdir()
+        params = dict(base)
+        params.update(overrides)
+        params["out"] = [str(out_dir)]
+
+        pfile = Path(tmp) / "params.json"
+        pfile.write_text(json.dumps(params), encoding="utf-8")
+
+        proc = subprocess.run(
+            [sys.executable, str(script), str(pfile)],
+            capture_output=True,
+            text=True,
+        )
+        if proc.returncode != 0:
+            return None
+
+        metrics = {}
+        for spec in outputs:
+            path = out_dir / spec["file"]
+            if not path.exists():
+                continue
+            # Two assumptions this made about a contract described only in
+            # prose, both measured across 57 builds on disk:
+            #
+            #   spec["key"]  declared by 11 of them. The other 39 that reach
+            #                this line raise KeyError -- inside a stage that
+            #                reports findings and not crashes, so it never
+            #                surfaced. The file stem is what the declaring
+            #                builds put there anyway.
+            #   .parquet     never required by capture-notebook-workflow; 17
+            #                builds write .tsv and the probe skipped every one,
+            #                reporting no measurable effect for every parameter
+            #                rather than reporting that it measured nothing.
+            key = spec.get("key") or path.stem
+            try:
+                if path.suffix == ".parquet":
+                    df = pd.read_parquet(path)
+                elif path.suffix in (".tsv", ".csv"):
+                    df = pd.read_csv(path, sep="	" if path.suffix == ".tsv" else ",")
+                else:
+                    continue
+            except Exception:
+                continue
+            metrics[f"{key}.rows"] = float(len(df))
+            for col in df.select_dtypes("number").columns:
+                if len(df):
+                    metrics[f"{key}.{col}.mean"] = float(df[col].mean())
+        return metrics
+
+
+def effect_size(runs: list[dict | None]) -> float:
+    """Largest relative spread of any metric across a sweep."""
+    good = [r for r in runs if r]
+    if len(good) < 2:
+        return 0.0
+    worst = 0.0
+    for key in good[0]:
+        vals = [r.get(key) for r in good if r.get(key) is not None]
+        if len(vals) < 2:
+            continue
+        lo, hi = min(vals), max(vals)
+        if hi == lo:
+            continue
+        denom = max(abs(lo), abs(hi)) or 1.0
+        worst = max(worst, (hi - lo) / denom)
+    return worst
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--script", required=True, type=Path)
+    ap.add_argument("--inputs", nargs="+", required=True)
+    ap.add_argument("--budget-key", default=None,
+                    help="Parameter that limits work, set to --budget while probing.")
+    ap.add_argument("--budget", type=int, default=40)
+    ap.add_argument("--allow-long", action="store_true",
+                    help="Run a masking pass predicted to exceed "
+                         "LONG_PROBE_HOURS.")
+    ap.add_argument("--no-masking", action="store_true",
+                    help="Sweep only. CANNOT distinguish inert from "
+                         "masked -- the error this tool exists to catch.")
+    ap.add_argument("--params", default=None, help="Comma-separated subset.")
+    args = ap.parse_args()
+
+    tool = load_tool(args.script)
+    defaults = {d["key"]: d for d in tool.DEFAULTS}
+    outputs = tool.OUTPUTS
+
+    base = {"in": [str(Path(x).resolve()) for x in args.inputs]}
+    if args.budget_key:
+        base[args.budget_key] = args.budget
+
+    skip = {"in", "out", args.budget_key}
+    wanted = set(args.params.split(",")) if args.params else None
+    targets = [
+        d for k, d in defaults.items()
+        if k not in skip and not d.get("hide")
+        and (wanted is None or k in wanted) and sweep_values(d)
+    ]
+
+    print(f"probing {len(targets)} parameters, budget {args.budget_key}={args.budget}\n")
+
+    # Time the baseline so the cost can be stated before the wait, not after it.
+    # A multi-minute silence reads as a hang, and the masking re-probe below is
+    # nested -- it can be much longer than the sweeps that precede it.
+    t0 = time.time()
+    baseline = run_once(args.script, base, {}, outputs)
+    per_run = max(time.time() - t0, 0.01)
+    if baseline is None:
+        print("ERROR: tool failed at default parameters", file=sys.stderr)
+        return 1
+
+    # A budget key that does not actually limit work is worse than none: it caps
+    # every metric effect_size reads while looking like a speed-up. The classic
+    # case is a truncation that sits AFTER the expensive step -- max-features on a
+    # tool whose cost is feature detection buys nothing and pins features.rows.
+    # Trusting the caller to pick correctly is how a whole probe gets invalidated,
+    # so measure it: a real budget key makes a quarter-budget run meaningfully
+    # faster.
+    if args.budget_key:
+        small = max(1, args.budget // 4)
+        t1 = time.time()
+        probe_small = run_once(args.script, {**base, args.budget_key: small}, {}, outputs)
+        small_run = max(time.time() - t1, 0.01)
+        speedup = per_run / small_run
+        if probe_small is None:
+            print(f"  WARNING: the tool failed at {args.budget_key}={small}; "
+                  f"cannot verify the budget key limits work", flush=True)
+        elif speedup < 1.25:
+            print(f"\n  WARNING: {args.budget_key} does not appear to limit work.")
+            print(f"    {args.budget_key}={args.budget} took {per_run:.1f}s, "
+                  f"={small} took {small_run:.1f}s ({speedup:.2f}x).")
+            print( "    A budget key applied AFTER the expensive step buys no time")
+            print( "    and caps every metric this probe reads -- every effect size")
+            print( "    below would measure the cap, not the parameter.")
+            print( "    Budget by shrinking the INPUT instead (crop the mzML).\n",
+                  flush=True)
+        else:
+            print(f"  {args.budget_key} verified: {speedup:.1f}x faster at "
+                  f"{small} than at {args.budget}", flush=True)
+
+    planned = sum(len(sweep_values(p)) for p in targets)
+    # The masking pass is O(n^2): every low-effect parameter is re-swept against
+    # every other one. At 11 parameters that is minutes; at 43 it is an overnight
+    # job, and nothing used to say so until you were already inside it.
+    worst_masking = sum(
+        len(sweep_values(p)) * max(len(targets) - 1, 0) for p in targets
+    )
+    worst_hours = per_run * worst_masking / 3600
+    print(f"  one run takes {per_run:.1f}s")
+    print(f"  {planned} sweep runs planned  ->  about "
+          f"{per_run * planned / 60:.1f} min")
+    print(f"  masking re-probe is O(n^2): worst case {worst_masking} more runs "
+          f"-> up to {worst_hours:.1f} hours")
+    print(f"  raise --budget to trade accuracy for time\n", flush=True)
+
+    if worst_hours > LONG_PROBE_HOURS and not args.allow_long:
+        print(f"REFUSING to start: the masking pass could run {worst_hours:.1f} "
+              f"hours (limit {LONG_PROBE_HOURS}).", file=sys.stderr)
+        print("Choose one:", file=sys.stderr)
+        print("  --params a,b,c     probe a shortlist", file=sys.stderr)
+        print(f"  --budget <smaller> shrink each run "
+              f"(currently {args.budget_key}={args.budget})", file=sys.stderr)
+        print("  --no-masking       sweep only -- NOTE this cannot tell inert "
+              "from masked, which is the error this tool exists to catch",
+              file=sys.stderr)
+        print("  --allow-long       run it anyway", file=sys.stderr)
+        return 2
+
+    results = []
+    started = time.time()
+    for i, param in enumerate(targets, 1):
+        key = param["key"]
+        values = sweep_values(param)
+        print(f"  [{i}/{len(targets)}] {key:30s} sweeping {len(values)} values "
+              f"({per_run * len(values):.0f}s)", flush=True)
+        runs = [run_once(args.script, base, {key: v}, outputs) for v in values]
+        eff = effect_size(runs)
+        failures = sum(1 for r in runs if r is None)
+
+        record = {
+            "key": key, "values": values, "effect": eff,
+            "failures": failures, "masked_by": None,
+        }
+
+        if eff < MATERIAL_THRESHOLD and not args.no_masking:
+            # Not convincing on its own evidence. Before recommending against it,
+            # check whether another parameter is swamping it. Keep the strongest
+            # unmasking found, not merely the first.
+            candidates = [
+                o for o in targets
+                if o["key"] != key and neutral_value(o) != o.get("value")
+            ]
+            print(f"        effect {eff:.1%} is under {MATERIAL_THRESHOLD:.0%} -- "
+                  f"re-probing against {len(candidates)} other parameter(s) "
+                  f"({per_run * len(candidates) * len(values):.0f}s) before "
+                  f"concluding anything", flush=True)
+            best_unmask = None
+            for other in targets:
+                if other["key"] == key:
+                    continue
+                neutral = neutral_value(other)
+                if neutral == other.get("value"):
+                    continue
+                print(f"        ... with {other['key']} neutralised", flush=True)
+                re_runs = [
+                    run_once(args.script, base, {key: v, other["key"]: neutral}, outputs)
+                    for v in values
+                ]
+                re_eff = effect_size(re_runs)
+                if (
+                    re_eff > MATERIAL_THRESHOLD
+                    and re_eff >= MASKING_RATIO * max(eff, EFFECT_THRESHOLD)
+                    and (best_unmask is None or re_eff > best_unmask[1])  # pylint: disable=unsubscriptable-object
+                ):
+                    best_unmask = (other["key"], re_eff)
+            if best_unmask:
+                record["masked_by"], record["effect_unmasked"] = best_unmask
+
+        results.append(record)
+        tag = (
+            f"MASKED by {record['masked_by']} "
+            f"(effect {record.get('effect_unmasked', 0):.1%} once unmasked)"
+            if record["masked_by"]
+            else ("inert" if eff <= EFFECT_THRESHOLD else f"effect {eff:.1%}")
+        )
+        if failures:
+            tag += (f"   [{failures}/{len(values)} sweep points FAILED - "
+                    f"effect measured over {len(values) - failures}]")
+        print(f"        -> {tag}", flush=True)
+
+    print(f"\n  probed in {time.time() - started:.0f}s")
+    print("\n" + "=" * 74)
+    print(f"{'parameter':32s} {'effect':>9s}  recommendation")
+    print("=" * 74)
+    for r in sorted(results, key=lambda x: -x["effect"]):
+        if r["masked_by"]:
+            rec = f"KEEP - masked by {r['masked_by']}, not inert"
+            eff = f"{r['effect_unmasked']:.1%}*"
+        elif r["effect"] > 0.25:
+            rec = "KEEP - large effect"
+            eff = f"{r['effect']:.1%}"
+        elif r["effect"] > EFFECT_THRESHOLD:
+            rec = "ADVANCED - small but real effect"
+            eff = f"{r['effect']:.1%}"
+        elif r["failures"]:
+            # A sweep that lost points did not measure inertness, it measured
+            # less. Recommending HARDCODE here is the exact error this whole
+            # skill exists to prevent, arrived at by arithmetic rather than by
+            # masking.
+            rec = (f"INCOMPLETE - {r['failures']} of {len(r['values'])} runs "
+                   f"failed, no verdict")
+            eff = f"{r['effect']:.1%}?"
+        else:
+            rec = "HARDCODE - no measurable effect"
+            eff = f"{r['effect']:.1%}"
+        print(f"{r['key']:32s} {eff:>9s}  {rec}")
+    print("\n* effect measured with the masking parameter neutralised")
+
+    incomplete = [r for r in results if r["failures"]]
+    if incomplete:
+        print(f"\nWARNING: {len(incomplete)} parameter(s) had sweep points fail. "
+              "A failed point is")
+        print("         dropped silently by the effect calculation, so the effect "
+              "is measured")
+        print("         over fewer values and reads LOWER than the truth - the "
+              "direction that")
+        print("         produces HARDCODE. Common cause: an int/float parameter "
+              "with no declared")
+        print("         min/max, so the sweep invents bounds and probes an "
+              "invalid value.")
+        for r in incomplete:
+            print(f"           {r['key']:30s} tried {r['values']}")
+
+    # The scope travels with the numbers, or the numbers get reused outside it.
+    # These effect sizes were measured with every parameter NOT in this set
+    # pinned at whatever the tool defaults to; widen the set and they stop being
+    # evidence.
+    print(f"\nSCOPE: measured over these {len(targets)} parameter(s) only, with "
+          f"all others held at their defaults.")
+    print("       Exposing further parameters invalidates these figures - "
+          "re-probe rather than carrying them forward.")
+    if args.no_masking:
+        print("\nWARNING: --no-masking was used. An 'inert' reading here may be a "
+              "masked parameter;")
+        print("         this run cannot tell the difference.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/.claude/skills/notebook-to-webapp/SKILL.md b/.claude/skills/notebook-to-webapp/SKILL.md
new file mode 100644
index 00000000..02c74351
--- /dev/null
+++ b/.claude/skills/notebook-to-webapp/SKILL.md
@@ -0,0 +1,501 @@
+---
+name: notebook-to-webapp
+description: Use when someone wants to turn a Jupyter notebook into a web application, when a notebook analysis should become an OpenMS Streamlit app, or when asked to build an app from a notebook by describing it in natural language.
+---
+
+# Notebook to webapp
+
+Turn a source notebook into an OpenMS Streamlit application. This skill owns the
+ordering, the handoffs and the opening; each stage is a skill of its own that also
+works standalone.
+
+Most users arrive by pasting the entry prompt from the app's Quickstart page,
+having never read any of this. Assume no knowledge of the template, of Insight, or
+of the vocabulary.
+
+Vocabulary: `CONTEXT.md`. Rationale: `docs/notebook-to-webapp-design.md`.
+
+## The rule
+
+**Run the stages in order, and never skip a review.**
+
+Capture must execute the notebook before anything is extracted, or a faithful
+extraction cannot be told from a plausible one. Shortcuts must be resolved before
+parameters are probed, or every sweep measures a truncation instead of a
+parameter.
+
+**In order means by dependency, not by wall clock.** What a stage consumes is
+what fixes its position: capture must execute before extraction, and shortcuts
+must be resolved before parameters are probed. Work that depends on nothing
+downstream may start early — the dashboard's link graph and wireframe read
+`OUTPUTS` alone, so they can be drawn while the interview is still open, and only
+the panels need a running app. Say so when you do it, and never let early work
+become a reason to skip what it was waiting on.
+
+**A user may accept every recommendation at once; they may not skip seeing them.**
+*"Skip the interview, the parameters look fine"* is a waiver of something they
+have not been shown — including the suspicious constants, which are the half of
+that review they cannot guess at. Present it, and let them clear it in one word.
+
+That is also the boundary against *never ask for what you can determine* below:
+**determinable is not the same as yours to decide.** That a constant is suspicious
+is determinable; whether it is a setting, a shortcut, or a defect is the user's.
+Under pressure to skip ahead, this is the rule that gets crossed — a reader given
+this skill collapsed the interview to "one pass, no interview" and cited the
+determinable rule to justify it.
+
+## What the user sees
+
+**A user-facing turn is at most 200 words of prose.** Past that a reader skims,
+and a skimmed recommendation is an unmade decision. The work is not what has to
+shrink — classifying, probing, cross-checking, reading the screenshot all still
+happen, in thinking. What reaches the screen is a **progress line** while
+something slow runs, an **interview** when something *measured* needs deciding,
+and a **design round** when something *rendered* does. Those three are what
+reaches the screen *unprompted*. Everything else a user reads is prescribed by
+name somewhere in this file — the notebook question, the confirmation of the
+summary, the browser ask and its decline line, the handover — and nothing outside
+the named set is volunteered.
+
+**A line when a stage starts, and a line when it produces something they can
+check — never one per step.** The stages are the five in the
+table near the end of this file, and nothing else is one — a line goes out when
+a stage starts, and the wording is whatever a user would recognise as a piece of
+their own work: pulling the analysis out, building the app. The workflow class,
+the page registration, the template cleanup and the three test lists are four
+steps of *one* stage, and four lines saying so is the framework thinking out
+loud:
+
+```
+Now pulling the analysis out into a script.
+Verified it reproduces your notebook.
+Now building the app.
+Now the Results page. Here's what I'd build:
+```
+
+Four lines. The same build narrated step by step runs to eight: a line for the
+extracted file, one for the golden test, one for the workflow class and its
+pages, one for registering them, one for the template cleanup, one for the test
+lists. Each is a step inside a stage, and the last of them reads a phrase
+straight out of `cleanup.md` — a step that only exists because this framework
+has a rule about it is not a step the user is waiting on.
+
+**The bad version is described here and not written out, deliberately.** It used
+to sit in a left-hand column beside the four above, spelled out in full. Three
+builds on two notebooks then produced its `test_gui.py` line almost verbatim —
+*"Now test_gui.py…"*, *"Now updating test_gui.py — all three of its
+hand-written lists."* A well-formed sentence in a skill is a sentence that can
+be copied, whichever column it is in, and the anti-example was the most
+copyable thing on the page.
+
+**Count the outcome line, not just the opening one.** This rule read *"one
+progress line per stage"* until two builds on two notebooks followed it exactly
+and reported the two longest silences in their runs — capture covering the
+script, the golden test and a real transcription bug on a single line, scaffold
+covering the workflow class, four pages, registration, the template cleanup,
+three test lists and the dashboard on another. One of them put it plainly:
+*"nothing in it says what to do when a single stage runs long."* The count was
+wrong against this skill's own example, which gives capture two: it opens, and
+then *"Verified it reproduces your notebook"* — a result the user can check.
+That second line is not narration, it is the answer to the question the silence
+is making them ask.
+
+Where a stage genuinely produces nothing checkable until it ends, it gets the
+one line and the next question closes the gap. Do not fill it. A stage running
+long is not a reason to say more about the stage; it is a reason to make sure
+the thing it produces is announced the moment it exists.
+
+**Setup is not one of the five, so it gets no progress line at all.** What it
+may say is governed by *what the sentences are*, not by how many there are.
+
+Counting them was the rule here for five generations — ban the word, forbid the
+turn, narrow it to one forward-looking line, declare setup not a stage — and it
+never once held: builds wrote two or three anyway, in essentially every run
+measured. It also turned out to be defending nothing. Across 165 things the
+reader actually objected to in the corpus, **two** were on the setup screen and
+**163** were later; and both of those two were about *vocabulary* —
+`Playwright`, `Chromium`, `headless browser` — never about there being more than
+one sentence. A rule that cannot be followed and protects nothing measurable is
+not a rule, so the count is gone and the constraint that earned its place stays.
+
+**Each sentence says what the user is about to be asked, or what they will
+have. These are the only things they hear before the first question, so they are
+theirs.** Write them as a time and a next step:
+
+> Setting up — a minute, then I'll ask about your notebook.
+
+The shape that keeps replacing it is `Now <internal mechanism>.` — a report of
+what you are touching this second. **41 builds opened with one, including every
+one of the last twelve**, and each time the noun was different, because each ban
+was answered with a fresh noun for the same machinery. That is why this says what
+the sentence *is* instead of listing what it may not contain: a reader who knows
+what the slot is for does not need the list, and the list is what the previous
+four generations of this rule consisted of.
+
+The test is whether the sentence would still make sense to someone who does not
+know this app is being generated. If it names a thing only you can see, it is the
+wrong sentence, however the noun is spelled.
+
+Two builds on two notebooks, both carrying every rule here, wrote three of them
+anyway: a heading for the browser probe, a sentence reporting control confirmed
+and naming what came back, and one that numbered the setup steps.
+
+That last is the tell: it numbers something the user never knew had
+steps. Setup is not in the table at the end of this file, and the sentence above
+it — *the stages are the five, and nothing else is one* — already forbade this;
+both runs read past it because setup genuinely takes time and a stage that takes
+time gets a line. It is not a stage. **If you are about to write a progress line,
+name which of the five it belongs to; if the answer is "setup", you have your
+answer.**
+
+**A stage in trouble may say once that it is still going, and that line is not
+counted.** One per stage, never two, and only for a stage actually stuck. It names what
+they are waiting for and nothing about the fault: *"Still on the results page —
+a few more minutes."*
+
+Written first as a line *taken from* the four to six, on the reasoning that a
+permission which adds is a permission that gets stretched. A build then spent it
+and reported the result: *"spending it made the next silence longer, not
+shorter — I said 'Still on the results page' once during the peak-map rebuild
+and then held the rest of that stage silent through seventeen shell commands
+because a second line would have broken the count."* Rationing the relief with
+the budget it relieves is worse than either. One per stage, uncounted, bounds it
+without that.
+
+Two builds on two notebooks reported the same inversion, and one stated it
+exactly: *"the stretch where I had least to report was the stretch where I was
+busiest, and the user saw nothing for longest precisely when something was
+wrong."* The longest run in one was a held port, an unsupported widget type and
+three silent server exits. Every rule here correctly forbids narrating those,
+and *"a fault with no user-visible symptom is a reason to say less"* then makes
+the busiest stretch the quietest by construction. Saying you are still going is
+not describing the fault; it is the one fact the silence is making them guess
+at.
+
+**Count them: a whole build is four to six progress lines.** Five stage
+openings, plus an outcome line for each stage that produces a result before it
+ends — and only capture reliably does. The permission above is for *that* line,
+not for a line per thing you finish.
+
+This bound is not decoration. The first build to run with the outcome line
+permitted wrote **eleven** progress lines where the same notebook had written
+six the build before, and among them was *"Now test_gui.py — all three of its
+lists."* — the exact line the bad column above is annotated for. One permission
+read as licence doubled the count and brought back the failure the whole rule
+exists to prevent. **If you have written a seventh, you are narrating steps**;
+go back and find the stage the extra lines belong inside.
+
+**A findings list is bounded by rows, not words: at most five.** The budget and
+*"every question carries the thing it is about, quoted, and a recommendation"*
+would otherwise contradict each other, and the second one wins: four constants,
+each with the user's own line, its consequence and a recommendation, come to
+about 240 words with every word working. A list is *meant* to be skimmed — the
+reader scans for the row they disagree with — so prose stays under 200 and rows
+are counted instead. Past five rows, the review is too big to
+decide in one pass — put the five that matter and offer the rest.
+
+**Talk like a mass spectrometrist, not like this framework.** Cell classes,
+harvesting, sweeps, probes, gates, screenshots, `DEFAULTS`, `OUTPUTS`, masking —
+all of it is how the work is done, and none of it belongs in a user-facing turn.
+The leak is rarely a slip; it is an internal table shown verbatim — capture's
+classification table has a *destination* column reading `code dropped, output
+harvested`, written for an agent.
+
+| what the framework calls it | what the user is told |
+|---|---|
+| harvested the exercise cell's output | your notebook already tested this — I'll reuse its numbers |
+| the probe reports a fraction of a percent across the sweep | changing this barely moves the result |
+| a `filter_defaults` value on the link identifier | which spectrum the plot opens on |
+| took a screenshot of the Results page | *(nothing — open their browser instead)* |
+| the gate found a truncated header | that column title is cut off |
+| extraction reproduces the notebook — 7/7 golden checks pass | the extracted script reproduces your notebook |
+
+**A number belongs in a user-facing turn only if it is theirs.** `7/7 golden
+checks`, `233 tests pass`, `11/11` are the framework reassuring itself; *"the
+same four peptides"*, *"<n> features"* are their own result handed back. This
+holds in every turn, not only the last one.
+
+**Every question carries the thing it is about, quoted, and a recommendation.**
+Not a summary of the evidence — the specific line, the value, the cell. *"Your
+notebook analyses only the first <n> of <total> spectra — `df.head(<n>)`, cell
+<k>. Remove that for the app?"* is answerable; *"the truncation costs <delta> to
+remove"* is a fact about a decision the user has not been shown. A question they
+would have to go and look something up to answer gets answered *"whatever you
+think"*, and that is not consent.
+
+## Talking to the user
+
+Two mechanisms, not interchangeable:
+
+| | **interview** | **design round** |
+|---|---|---|
+| when | you measured something | there is nothing to measure |
+| shape | one batch, many rows | one thing, repeated |
+| user | adjudicates evidence | picks a direction |
+| where | capture findings, config parameters | Upload, Configure, Results |
+| how | options they select | one suggestion, then the next |
+
+**An interview is asked, not drawn.** A checklist typed into the transcript is a
+decision the user cannot make: to answer it they would have to retype it. Rows
+reach them as options they select. Where there are more rows than one screen of
+options holds, ask whether the recommendation stands **before** asking about any
+single row — most of the time it does, and the whole list closes in one click.
+Every row can be right and the whole thing still unreachable.
+
+Six habits:
+
+- Show it before you ask about it. A question about something the user cannot
+  see is one they must imagine an answer to.
+- Carry a recommendation into every fork. "I suggest X because Y" — not "what
+  would you like?"
+- **Never resolve a fork yourself and report it as applied.** The shape to
+  refuse: a turn that says *"two calls before I build the config page"*, lays
+  out the evidence for both, offers nothing to select, and is followed by
+  *"Applied: … now defaults to 0, … to 20 ppm."* Every word of the evidence can
+  be right and the user has still not decided anything — and the run then spends
+  a later turn explaining the consequence of a value they never chose. Naming
+  something a decision and then making it is worse than never raising it: it
+  reads as consultation and works as an announcement. If it is genuinely yours
+  to settle, settle it silently and say so once it is done; if it is theirs, it
+  arrives with a recommendation and something to click.
+- Report conclusions, not process. Name the interpreter you chose, not the
+  five you probed. Name what needs attention, not how many things do.
+- Never ask for what you can determine. Ask only what is genuinely the
+  user's: the name, what belongs on the config page, how a page should look.
+- **After every answer, say what is now under way.** A user who has just decided
+  something is owed the consequence of deciding it. An answer followed by silence
+  reads as the framework having wandered off, and the longer the silence the more
+  it reads that way — the stretch after the app name is the longest in the whole
+  run. One line, naming the next thing and the one after it: *"Right — pulling
+  the analysis out into a script, then checking it still gets your notebook's
+  numbers."* Without it the user is left guessing what is happening, and says
+  so.
+
+When a decision is rejected, re-derive it — do not restate it, and do not
+simply adopt the correction. Restating repeats the call they rejected, louder.
+Capitulating looks agreeable and is worse: they can be mistaken, and a framework
+that folds on contact cannot be trusted when it agrees. Re-read the specific thing
+named, report what changed *and what did not*, hold a disagreement with a line
+number as evidence, then re-check whatever was decided by the same reasoning — a
+misclassification is usually systematic.
+
+## Opening
+
+1. **Set up everything that needs setting up, before the first question.**
+   Clone into a neutral folder — the app is not named yet — find a Python,
+   install the dependencies, and confirm you can drive a browser. Probe order and
+   the Windows Store-stub trap: `capture-notebook-workflow`.
+
+   **Opening a browser and driving one are different capabilities, and only the
+   second needs tooling.** Conflating them costs the user the thing they most
+   want to see:
+
+   | | needs | used for |
+   |---|---|---|
+   | **open** a page, any browser | nothing — `start <url>`, `open <url>`, `xdg-open <url>` | every design round, and the handover |
+   | **open** a page in **one** browser | that browser's executable path | the extension store page |
+   | **drive** a page | browser control | the usability gate: screenshots, clicking, reading the DOM |
+
+   **The middle row is a whole failure on its own.** Those three commands
+   resolve the *default* browser, which is fine when any window will do and
+   wrong when a specific one must receive the page. A run opened the extension
+   store with `xdg-open` after finding and launching Chrome, and it landed in
+   Firefox, where that extension cannot be installed at all.
+
+   So a page always opens. Saying "my browser extension isn't connected" instead of opening the page fails twice: it withholds the app, and it names this framework's plumbing to a mass spectrometrist.
+
+   Browser **control** is not needed until the gate, but set it up here. An
+   install prompt arriving mid-flow lands on a user who was in the middle of a
+   decision, and asks a scientist to configure tooling for a framework they
+   should never have had to see.
+
+   **Preflight checklist, all of it before the first question:**
+
+   1. Clone into a neutral folder — the app is not named yet.
+   2. Find a Python and install the dependencies. Probe order and the Windows
+      Store-stub trap: `capture-notebook-workflow`.
+   3. **Open `connect-browser-control` now** — before the first question. It
+      connects control and confirms it by driving a page this machine serves,
+      or it asks them for the one click that would. Its rules are there and not
+      here, including the one that holds the notebook question until they
+      answer.
+   4. Install the gate's headless browser. It runs the gate's hard assertions
+      either way — what it never becomes is where a run quietly settles for
+      judging pages the user cannot see.
+
+   **An ask at step 3 stops the question, not step 4.** What must never go out
+   ahead of their answer is the notebook question and anything else that moves
+   the run *past* them. Setup that has to happen regardless keeps going, and the
+   ordering above is why: step 4 is the slow one, so it runs while they click.
+   Then look for the device — `connect-browser-control` owns how, and the short
+   version is that you look rather than wait to be told. A run that waited for a
+   turn made its user type *"continue"* at a browser that had already connected.
+
+   Where the browser runs, what is checking what, and what you can or cannot see
+   are this framework's plumbing, and none of it is something they can act on.
+   **Never let any of it stop you opening their app**, which needs none of it.
+
+   **This stage produces at most three user-facing turns, and no others:**
+
+   1. Optionally one line saying you are setting up — *"Setting up — a minute,
+      then I'll ask about your notebook."*
+   2. **The ask, whenever step 3 earns one.** A click, a restart, or a browser
+      to install; `connect-browser-control` has the wording and the table that
+      picks between them. This turn is required when earned, no rule on this
+      page suppresses it, and **the notebook question waits behind it** — a run
+      that asks and presses on regardless has taken the answer for them.
+   3. **One line if they decline** — *"I'll ask you to look at a page or two as
+      we go."* What they will be asked to do, and nothing about why.
+
+   Nothing else. The failure this keeps meeting is a fourth turn that names the
+   machinery setup is about to run — the phase, the probe, the browser, whatever
+   this framework calls the thing it is doing this second. Written out here as
+   examples to avoid, that failed in **ten consecutive builds**, each one
+   answering the banned noun with a fresh one, so the examples are gone and the
+   test is the one above: a turn that would not make sense to someone who does
+   not know this app is being generated is not one of the three.
+2. **Ask for the notebook's path.** One question, no list. **If they were
+   visibly asked for something in preflight and did it, this question carries
+   the thanks** — *"Thanks — what's the path to your notebook?"* — and that is
+   the whole acknowledgement. It is not a turn of its own, and it says nothing
+   about the browser. Silence right after a user has done what you asked reads
+   as the request having gone nowhere, and a run that felt that pull invented
+   *"Setup's done."* to fill it. Do not scan the folder
+   the prompt was pasted in, and never the clone's parent. A user who pastes a
+   prompt into a working directory has not invited an inventory of it, and the
+   parent scan reports their other projects back to them. Listing their notebooks and the webapps beside them reads as snooping.
+
+   Reading the directory the user *names* is different, and stays — capture has
+   to find the notebook's data files to pre-stage them.
+3. Analyze statically, show the summary, and **wait for the user to confirm it
+   before running anything.** Showing is not asking. This is a gate and it is
+   separate from step 4: a reader who folds the two together presents the reading,
+   asks for the app name in the same breath, and then executes — so the user is
+   never given the chance to say the reading is wrong, which is the one thing
+   every later stage inherits. Measured: **3 of 3 readers did exactly that** when
+   this step said only "show the summary".
+   Format and the no-numbers-yet rule: `capture-notebook-workflow`.
+   Then run it, and **report the runtime from the trace, never from the code**:
+   `<runtime>, over <n> of the <total> spectra`. You executed it; the count is a
+   fact you hold, not one to infer from what a variable happens to be called.
+4. Once the reading is confirmed, ask what to call it, then derive everything and
+   show the derivation.
+
+| from `UPS1 Quantification` | |
+|---|---|
+| folder, `repository-name` | `ups1-quantification-app` |
+| `app-name`, `app.py` section | `UPS1 Quantification` |
+| `WorkflowManager` subclass | `UPS1QuantificationWorkflow` |
+| workflow slug | `ups1-quantification` |
+| pages | `ups1_quantification_{file_upload,parameter,execution,results}.py` |
+| python tool, dashboard, test | `ups1_quantification.py`, `test_ups1_quantification.py` |
+
+Derive every row. The tool name is the one that bites — it appears as a **string
+literal** in `input_python()` and `run_python()`, so renaming files leaves them
+dangling. Measured: tests still pass 7/7 and every module parses, then the app
+throws on the Configure page. Grep for the old stem afterwards.
+
+Rename the clone before the app is ever launched. Workspaces live in
+`../workspaces-<repository-name>`, and the slug owns the workflow directory, the
+`presets.json` key and every session-state prefix.
+
+**Rename it from the parent directory, then list the parent and confirm the new
+name is there.** You are inside the clone, and a directory cannot be renamed out
+from under the shell sitting in it: one build got `Device or resource busy` and
+had to kill a helper process, and a second got **no error at all** — `Rename-Item`
+returned quietly, the folder kept its old name, and the whole run continued
+against the wrong one. So an error is the good case here. The check is the
+listing, not the exit code.
+
+## Stages
+
+| # | skill | produces | review |
+|---|---|---|---|
+| 1 | `capture-notebook-workflow` | python tool with `DEFAULTS` + `OUTPUTS`, golden test, findings, prior evidence from exercise cells, any hardcoded selection | confirm the split |
+| 2 | `interview-parameters` | shortcuts, then config parameters | interview |
+| 3 | `scaffold-workflow-app` | `WorkflowManager` subclass, 4 pages, registration, template pages hidden, **smoke run** | rounds on Upload, Configure |
+| 4 | `build-insight-dashboard` | link graph, wireframe, panels | round per panel |
+| 5 | `verify-webapp-usability` | browser gate + screenshot critique — **internal** | feeds the final page round |
+
+Announce each stage as a progress line — **except stage 5**, which has nothing of
+the user's to name. Checking the page is not news, and what the check finds
+arrives inside the round that follows. Do not say what the next stage will
+consume either: that is a handoff between stages, and the user is not one of
+them.
+
+**No design round opens before the smoke run passes.** A round asks the user to
+look at a page; a page that has never had data in it, or that throws, is not a
+design question but a bug wearing one. Upload → configure → execute → results,
+once, with the notebook's own data, then open their browser.
+
+## Handoffs
+
+Each stage consumes a **declared artifact**, never a conversation. The
+producer is not always the preceding stage — capture feeds the dashboard
+directly, and the gate feeds back into it:
+
+- opening → capture: notebook path, chosen Python, app identity
+- capture → interview: findings, `DEFAULTS`, and **prior evidence** harvested from
+  exercise cells — sweeps the notebook already ran
+- interview → scaffold: the resolved `DEFAULTS`, and the notebook's own resolved
+  values as a named preset — `add-presets` owns `presets.json`
+- capture → dashboard: `OUTPUTS`, read without running anything, plus any
+  **hardcoded selection** from a visualization cell, as a proposed
+  `filter_defaults` rather than a config parameter
+- dashboard → verify → dashboard: panel count, then gate findings as material for
+  the final round
+
+If a stage needs something the previous one did not declare, that is a defect in
+the earlier contract. Fix it there.
+
+## Non-interactive mode
+
+Every stage supports `mode=auto`: take the recommendation and the first
+suggestion, never block. For the self-improvement loop and scripted personas only
+— a human-facing run always shows every review.
+
+## Adding a second notebook
+
+Run the orchestrator again inside the app. One notebook produces one workflow; a
+second adds another rather than merging.
+
+## Common mistakes
+
+- Quoting numbers in the analysis summary before the notebook has run.
+- Naming the app for the user because they paused.
+- Renaming the folder after the first launch — it strands the workspace.
+- Running a design round on a page the user does not have open.
+- Reporting success from a green gate without opening the screenshot.
+- **Showing an internal table because it was already written.** Every register
+  leak so far has been an agent-facing table — a classification, a probe result,
+  a gate report — pasted rather than translated.
+- **Narrating the machinery.** "Taking a screenshot", "running the gate",
+  "starting the masking re-probe" describe the framework working, which is not
+  news. The progress line names the *user's* thing: their notebook running, their
+  app starting.
+- **Slipping into instrument language when something goes wrong.** This is where
+  the rule above actually breaks: a build that hit a page error narrated its own
+  investigation four turns running — *"a JS page error the gate reports as
+  `undefined`"*, *"both come from the table iframe as unhandled Tabulator promise
+  rejections"*, *"let me look at the screenshot before I show you the page"* —
+  every one of them a status line, none of them a finding. Trouble is still
+  user-facing, and the register does not change: they hear what is wrong with
+  **their page**, never what your instrument reported. If the fault has no
+  user-visible symptom yet, that is a reason to say less, not to describe tools.
+  **The template's own source is machinery too.** A later build explained a
+  preset that would not refresh as *"`StreamlitUI.preset_buttons` →
+  `ParameterManager.apply_preset:661` clears the widget state, and widgets
+  generated from a Python tool don't pick that up"*. The decision behind it was
+  right — it moved the button rather than patching shared code — and the
+  sentence still handed a mass spectrometrist two class names and a line
+  number. What reaches them is the symptom and the choice: the numbers did not
+  change until the page reloaded, so the button now lives in their workflow.
+- **Drawing a decision instead of asking it.** Tick-boxes, arrows and numbered
+  recommendations printed into the transcript. Everything the user is meant to
+  decide arrives as something they can select.
+- **Stacking suggestions.** Three at once is not a choice, it is a pile. One,
+  then the next.
+- **Offering a change you have not costed.** A suggestion is resolved to its edit
+  in thinking before it is shown, or it is not shown.
+- **Asking for an install after the run has started.** Everything installs in
+  step 1.
diff --git a/.claude/skills/scaffold-workflow-app/SKILL.md b/.claude/skills/scaffold-workflow-app/SKILL.md
new file mode 100644
index 00000000..2d1e5f2f
--- /dev/null
+++ b/.claude/skills/scaffold-workflow-app/SKILL.md
@@ -0,0 +1,181 @@
+---
+name: scaffold-workflow-app
+description: Use when wiring a python tool into an OpenMS Streamlit app, when creating a WorkflowManager subclass and its upload/configure/run/results pages, or when a new workflow must be registered in app.py and settings.json.
+---
+
+# Scaffold a workflow app
+
+Wire a processing step into the TOPP Workflow Framework: a `WorkflowManager`
+subclass, four content pages, registration, and app identity.
+
+The route for a **captured python tool**. For a workflow chaining TOPP tools use
+`create-workflow`; for a standalone page, `create-page`.
+
+## The rule
+
+**`execution()` is annotated `-> bool` and returns `True` only when every step
+succeeded, and every `run_topp` / `run_python` call is gated on its return value.**
+
+Both callers write the `WORKFLOW FINISHED` marker from that return value, and the
+marker is the only thing the Run page reads. Returning `None`, or ignoring an
+executor result, reports a run whose third tool died as a success.
+
+## Files
+
+```
+src/<Name>Workflow.py            WorkflowManager subclass
+src/python-tools/<name>.py       the processing step (from capture)
+src/dashboards/<name>.py         results rendering (from the dashboard stage)
+content/<name>_file_upload.py    4 thin pages, one call each
+content/<name>_parameter.py
+content/<name>_execution.py
+content/<name>_results.py
+tests/test_<name>.py             golden values
+```
+
+Each page is four lines: `page_setup()`, construct the workflow, call one of
+`show_file_upload_section()` / `show_parameter_section()` /
+`show_execution_section()` / `show_results_section()`.
+
+**`<name>` is one stem**, derived from the app name and used in every file above —
+not a free choice per file. It also appears as a **string literal** in
+`input_python("<name>")` and the tool argument to `run_python()`, so a rename
+touching only filenames leaves those dangling. Measured: the golden tests still
+pass 7/7 and every module parses, because the tests run the tool as a subprocess
+and never construct the workflow — then the app throws an `stException` on the
+**Configure** page. No test in the generated app catches it, and the reason is
+worth knowing: `test_gui.py` names the pages it launches **by hand**
+(`test_gui.py:22-36`), and that list still holds the template's pages. Unless the
+four new pages are added to it, the suite launches pages the app no longer
+registers and never launches the ones it does. **Add yours and remove theirs**,
+in the same edit that hides the pages from `app.py` — the list has two halves and
+fixing one is not fixing it. Measured on a real build: the four new pages were
+added and the hidden template pages were left behind, so the suite passed while
+launching three pages the sidebar no longer offers. Until then only opening the page can catch this. After any
+rename, grep for the old stem and expect zero hits outside comments.
+
+## Dependencies
+
+**An app declares what it imports.** Anything the generated code imports that the
+template's own `requirements.txt` does not already list goes into the app's,
+pinned. The template stays as it is — it is a template, and the app is what has
+the dependency.
+
+Measured: two consecutive builds shipped apps whose dashboard did
+`from openms_insight import ...` while their `requirements.txt` never mentioned
+it. Both ran, because the venv on that machine already carried the package; a
+clean `pip install -r requirements.txt` of either produces an app that dies on
+import. Three earlier apps carry the line, so this is something that stopped
+happening rather than something never done.
+
+## Non-negotiables
+
+Each is a way to produce an app that looks fine and is broken.
+
+- **`page_setup()` runs before the workflow is constructed.** The constructor
+  dereferences `st.session_state["workspace"]`, and upload widgets need
+  `location` / `previous_dir` / `local_dir`, which `page_setup()` sets.
+- **Decorate `configure()` and `results()` with `@st.fragment` — both, every
+  time.** Without it, a widget inside the method reruns the whole page script
+  instead of the method: `page_setup()` again, the workflow constructed again,
+  every panel redrawn. On Results that is the difference between clicking a table
+  row and redrawing one panel, and clicking a table row and rebuilding the page.
+  It is the only bullet here whose damage is invisible in a screenshot — the page
+  looks right, it is just wrong to use. Measured: 1 build in 4 decorated
+  `configure()` and forgot `results()`, and every test still passed. The
+  template's own example decorates both (`src/Workflow.py:29` and `:119`).
+- **`input_python()` requires `st.session_state["advanced"]`**, created only by
+  `parameter_section()` — calling it elsewhere raises `KeyError`.
+- Nothing reachable from `execution()` may touch `st.session_state`. Online
+  mode runs it in an RQ worker that has none; worker and UI share state only
+  through the workspace filesystem.
+- Guard the user's selection before `get_files()` — it raises `ValueError` on
+  an empty list.
+- Choose the workflow slug once. It is load-bearing in three places at once
+  (workflow directory, `presets.json` key, every session-state prefix); renaming
+  orphans presets and abandons existing parameters.
+
+## Registering
+
+Add a section to the `pages` dict in `app.py`, and set `app-name`,
+`repository-name`, `github-user` **and `version`** in `settings.json`.
+
+`version` is the one field that arrives already wrong. The clone inherits the
+template's own version, so a brand-new app introduces itself in the sidebar at
+whatever release the template happens to be on — a first-ever run reporting
+`1.1.1` claims a history it does not have. Set it to `1.0.0`. It is the user's
+app now, and this is its first version. Python-tool parameters do
+**not** go in `default-parameters.json` — that belongs only to the simple-page
+system.
+
+## Clearing the template's pages, and rewriting Documentation
+
+**Open `cleanup.md` now** — when you are about to edit `app.py` or `content/documentation.py`, its rules are there and
+not here. It is a few hundred words and it is the difference
+between remembering this section and having it in front of you.
+
+## The smoke run, and handing the app over
+
+**Open `handover.md` now** — when the app boots and you are about to show it to anyone, its rules are there and
+not here. It is a few hundred words and it is the difference
+between remembering this section and having it in front of you.
+
+## Design rounds on Upload and Configure
+
+**Open `rounds.md` now** — when you are about to put a page in front of the user and ask what they would change, its rules are there and
+not here. It is a few hundred words and it is the difference
+between remembering this section and having it in front of you.
+
+## The template's code is not yours to change
+
+A generated app is a **clone**, and clones get merged with upstream. So
+`src/workflow/`, `src/common/` and the template's own `tests/` are code you have
+inherited, not code you own. Changing them there is not a local fix: every future
+rebase carries it, and nobody reviewing the app sees a diff against the template
+that was supposed to be identical.
+
+**The page list in the root `test_gui.py` is not in that set.** `tests/` above
+means the directory; `test_gui.py` is a root file and a different suite, and its
+hand-written list is the app's page registry written out a second time. It
+changes when the registry changes — adding yours and removing the template's is
+required above, and it is not a template edit. Read the two rules together and
+this is the seam between them.
+
+There is exactly **one** sanctioned edit in that area, and it is named in Common
+mistakes below: `run_python()` spawning `sys.executable` instead of the literal
+`"python"`. Everything else is a finding, not a task.
+
+**When the template looks wrong, say so and route around it.** Report the
+symptom, the file and the line, and what it costs the user — then take the local
+option. What you must not do is patch the shared module and then edit the
+template's tests so they still pass: the tests are the only thing that would have
+caught the change, so changing them to match converts a visible divergence into
+an invisible one.
+
+Measured on a real build. Asked to add a preset button, the framework found the
+preset mechanism did not move an already-mounted widget, rewrote `apply_preset`
+in `ParameterManager.py` from delete-keys to assign-values, adjusted
+`StreamlitUI.py` to match, and then rewrote `tests/test_parameter_presets.py` so
+the suite went green. The diagnosis was good. The two shared modules were the
+wrong place to put it, and the test rewrite removed the evidence.
+
+## Common mistakes
+
+- Editing a `src/` module and expecting the running app to notice. Streamlit
+  reruns the page script but does not re-import modules already in `sys.modules`.
+  This costs more debugging time than anything else here: the app keeps reporting
+  an error you already fixed.
+- **A fork whose `run_python()` still spawns the literal `"python"`.** It must
+  spawn `sys.executable` — the interpreter already running the app. *"Launch with
+  the environment active"* was the standing advice here and **it does not work**:
+  measured with the venv first on `PATH` and the parent process being that venv's
+  own `python.exe`, the child still resolved to a different interpreter
+  (`…/uv/python/cpython-3.12/python.exe`) and died on `import numpy`. Three
+  variants of activating the environment made no difference; one line did.
+  Generated apps are **full clones**, so fixing the template reaches none of the
+  apps already produced — grep every `src/workflow/CommandExecutor.py` you own.
+  This was found by the first end-to-end execution ever attempted, at tick 098,
+  after ninety ticks of a corpus scoring 1.000 without it.
+- Passing `input_output` keys the tool does not declare. They merge into the
+  tool's parameter JSON; a typo becomes an unused key and the tool silently falls
+  back to its default.
diff --git a/.claude/skills/scaffold-workflow-app/cleanup.md b/.claude/skills/scaffold-workflow-app/cleanup.md
new file mode 100644
index 00000000..e9630868
--- /dev/null
+++ b/.claude/skills/scaffold-workflow-app/cleanup.md
@@ -0,0 +1,85 @@
+# Clearing the template's pages, and rewriting Documentation
+
+Part of `scaffold-workflow-app`. Read this when you are about to edit `app.py` or `content/documentation.py`.
+
+The template ships **16 pages in five sections** (`grep -c st.Page app.py`); the
+captured workflow adds four, so the user's app would be 4 pages of 20 and theirs
+would not be the first in the sidebar. Hide **every** template section by
+commenting it out of the `pages` dict in `app.py`:
+
+| section | pages | |
+|---|---|---|
+| `TOPP Workflow Framework` | 4 | the template's example workflow |
+| `pyOpenMS Workflow` | 4 | a second example workflow |
+| `pyOpenMS Toolbox` | 4 | digest, m/z, isotope pattern, fragment ions |
+| `Others Topics` | 2 | `Simple Workflow`, `Run Subprocess` |
+| `Quickstart` | 1 | the page that generates an app — they just did |
+
+Five rows, fifteen pages — not five *sections*. `Quickstart` is one page inside
+the app-name section it shares with `Documentation`, so hiding it removes a row
+rather than a whole section, and that section is the sixth. Fifteen hidden leaves
+`Documentation` plus the workflow's four: **five live pages** of the sixteen the
+template shipped. The `pyOpenMS Toolbox` utilities go too. They are working tools, which
+is exactly why keeping them is tempting — but the user asked for their notebook
+as an app, not for their notebook plus four calculators, and every row in that
+sidebar is a row they have to rule out before they find their own.
+
+**`Documentation` stays, and its body is replaced.** Shipped as-is it is the
+*template's developer guide* — "How to build app based on this template", "TOPP
+Workflow Framework", "Kubernetes Deployment" — so a scientist who clicks
+Documentation in their own app gets instructions for building Streamlit
+templates. Rewrite `content/documentation.py` from the notebook's **markdown
+cells**: the author already explained what the analysis does, in their own words,
+next to the code that does it. That is the documentation this app should ship
+with, and it costs nothing to write because it is already written.
+
+Two things make this less mechanical than it sounds:
+
+- **A markdown cell is not a chapter.** Cells with no heading continue the
+  previous section, and one cell often carries several `#` headings. Split the
+  concatenated markdown at its headings, not at cell boundaries — splitting per
+  cell produced 23 "chapters" from a notebook with 8 real sections, most titled
+  `Section 11`.
+- **Not all of it is documentation.** A teaching notebook carries explanation
+  (keep), environment scaffolding — *"Install dependencies (for Google Colab)"* —
+  and troubleshooting appendices — *"Error: ModuleNotFoundError"*, *"Output:
+  scores = [0, 0, 0]"*. The last two exist because the notebook must run on a
+  stranger's machine during a workshop. The app has neither problem: it ships its
+  environment and nobody runs its cells. Carrying them over swaps one kind of
+  irrelevant documentation for another.
+
+**Update `test_gui.py` in the same edit — all three of its hand-written lists.**
+
+1. **The launch list** (`test_gui.py:22-36`) names every page it opens. Add your
+   four (Results excepted — see `verify-webapp-usability`) **and remove the ones
+   you just hid**. Two halves, and doing one is not doing it: add the new pages while leaving the hidden ones and the suite passes while launching pages the sidebar no longer offers.
+2. **The page-specific tests below it**, which are easy to miss because the
+   launch list looks like the whole job. `test_file_upload_load_example`,
+   `test_view_raw_ms_data` and `test_run_workflow` each name a page you have
+   just hidden. Comment them out with their decorators — same reason the pages
+   are commented rather than deleted: un-hiding a page should bring its test
+   back with it.
+
+   A list of two is not a list of one with an obvious extension: an enumerated
+   list is read as the scope.
+3. **The chapter list** (`test_gui.py:50-61`) names the eight documentation
+   chapters by hand, so replacing the chapters without replacing that list fails
+   eight tests whose message says nothing about documentation.
+
+The same trap three times, and one cause: the file lists what it tests instead
+of discovering it. No list updates itself and no failure names its reason.
+
+**Comment out; do not delete.** One line brings a page back, and `test_gui.py`
+lists every page **by hand** (`test_gui.py:22-36`) instead of globbing `content/`
+— delete a file without editing that list and CI fails at collection, before a
+single test runs. Hiding needs no test change at all.
+
+Because it is reversible it is not a question. One line, **said here, while you
+are doing it**: *"Hid the template's own 15 example pages, and rewrote
+Documentation from your notebook's notes — the originals are still in `content/`
+if you want any back."*
+
+**Not saved for the sign-off.** A line that explains what you are doing is worth saying while you do it
+and worth nothing afterwards, because by then it explains something already
+done. `handover.md` has what the ending is for.
+
diff --git a/.claude/skills/scaffold-workflow-app/handover.md b/.claude/skills/scaffold-workflow-app/handover.md
new file mode 100644
index 00000000..4ef57567
--- /dev/null
+++ b/.claude/skills/scaffold-workflow-app/handover.md
@@ -0,0 +1,165 @@
+# The smoke run, and handing the app over
+
+Part of `scaffold-workflow-app`. Read this when the app boots and you are about to show it to anyone.
+
+Before the first design round, drive the whole app yourself once: upload the
+notebook's own input files, take the resolved defaults, execute, open Results.
+Then start the user's browser on it — `start <url>` / `open <url>` /
+`xdg-open <url>`. No browser tooling is involved; that is only needed to *drive*
+a page, and the gate is the only thing that drives one.
+
+A design round asks someone to look at a page and say what should change. A page
+that has never held data, or that raises on arrival, is not a design question but
+a bug wearing one, and the round gets spent on it. Every panel rule in
+`build-insight-dashboard` assumes something rendered.
+
+Report the outcome in one line, not the steps in four:
+`upload → configure → run → results   OK (<runtime>)`. If it fails, fix it before
+opening the browser — the user never needs to know a round was waiting on it.
+
+### Restart, then smoke-run again, before you hand over
+
+Streamlit imports a `src/` module once per server process and never again. Every
+later edit — a design round applying a change, a dashboard panel, a fix to the
+tool — leaves the running server holding the **old** module object while a new
+one sits on disk. Two things break, and only one of them is visible to you:
+
+- the page renders the unchanged version, which you will notice within seconds;
+- **`Run` raises `PicklingError: <class '…Logger.Logger'> … is not the same
+  object as …Logger.Logger`**, which you will not, because the workflow only
+  spawns a process when someone clicks Run. On Windows that spawn pickles the
+  manager, pickling checks that each class still matches the one importable at
+  its own path, and after a reload two versions of that class exist. The app the
+  user opens is the app that crashes on the first thing they do with it.
+
+So the **last** action before handover is: stop the server, start it again, and
+drive the smoke run once more on the restarted process. A smoke run from before
+the final `src/` edit is evidence about a different app.
+
+**Stopping it is the part that fails silently.** `pkill` is not in this shell —
+one build got `pkill: command not found`, another got a clean exit that killed
+nothing — and in both the replacement server then failed to bind while `curl`
+kept returning 200 from the process still holding the old modules. A run that
+does not notice judges its next page against code it already replaced.
+
+Find the listener by port and stop it by PID, then confirm the port is free
+before starting anything. Ask Windows for the connection **as an object** —
+never by matching words in `netstat` output:
+
+```powershell
+$owner = (Get-NetTCPConnection -LocalPort <port> -State Listen `
+          -ErrorAction SilentlyContinue).OwningProcess
+if ($owner) { Stop-Process -Id $owner -Force }
+Get-NetTCPConnection -LocalPort <port> -State Listen `
+    -ErrorAction SilentlyContinue        # must return nothing
+```
+
+The last line is the check, and it has to be a check that can fail. This rule
+first said `netstat -ano | grep ":<port>.*LISTENING"`, which cannot work on a
+localised Windows: the machine it was written on prints `ABHÖREN`, so the grep
+matched zero lines — and zero lines is exactly what "the port is free" looks
+like. The build that hit it got an empty PID, a `Stop-Process` that failed, and
+a verification line that reported success. It then judged pages served by the
+process it had not stopped.
+
+`netstat` is a localised text report. `Get-NetTCPConnection` returns objects
+whose fields do not change with the display language, and an empty result is a
+real absence rather than a failed match.
+
+
+### The closing turn
+
+The last thing they read is short, and it celebrates:
+
+```
+🎉 Your app is ready!
+
+  ..\.venv\Scripts\python -m streamlit run app.py
+
+✅ It reproduces your notebook's numbers — same features, same peptides.
+```
+
+Someone has just watched their notebook become an application. Say so like it is
+good news. A couple of emoji at the end are worth more than a paragraph of
+detail: they mark the ending as an ending, which a wall of facts does not. Two or
+three, not a row of them — 🎉 for the arrival, ✅ for the thing that reassures.
+
+**Everything else was already decided with them.** Which filter default ships,
+the button that restores the notebook's value, which pages are hidden, what the
+Documentation page holds — each was a question they answered while the app was
+being built. Repeating it at the end is a changelog of a conversation they were
+in, and this is the turn most likely to be read by someone who was not.
+
+An ending can be six paragraphs of true facts and still be unreadable, because
+true and already-agreed are not the same thing.
+
+What earns a place at the end:
+
+- **that it works**, in their terms — their own numbers, reproduced;
+- **how to start it again**, the one thing they cannot work out for themselves;
+- **at most one offer**, if there is a real next step — *"want me to commit
+  it?"*, *"shall I pull that file back out?"*. An offer names the thing you
+  would do next; a question that does not is a round re-opened.
+
+**Never end on an open question.** *"Shall we call it done, or is there
+something on it you'd change?"* was a real ending, and it asks the user to
+decide with nothing to select — the one shape this framework refuses everywhere
+else. It also undoes the round you just closed: they already said the page was
+right. A blind judge, comparing that ending against an older one, picked the
+older one and gave this as a reason. If you have nothing concrete to offer, the
+ending simply stops.
+
+A number belongs here only if it is theirs. "233 tests pass" is the framework
+reassuring itself; "the same four peptides" is the user's own result handed back.
+
+**The cleanup line does not belong here.** *"I also hid the template's example
+pages and rewrote Documentation — the originals are still in `content/`"* is the
+right sentence in the wrong turn: `cleanup.md` gives it to you to say **while
+you are doing that work**, and a run that saves it for the sign-off ends on
+housekeeping instead of on their result. Having already said it is what makes
+the ending short.
+
+If something genuinely new turned up — something you found that they have not
+already seen — say that, in one sentence. **"They haven't seen it yet" does not
+qualify work you simply never mentioned.** A run that skipped the cleanup line
+reached the ending, noticed the user did not know about the hidden pages, and
+opened with *"One thing you haven't seen yet:"* — the escape hatch is this
+clause, and the fix for a missed line is not to append it here. New means new to
+*you*: something the run turned up that neither of you could have known at the
+start. Anything they chose, they already know.
+And if they want the detail, they will ask; answering then costs one turn, while
+volunteering it costs the ending.
+
+### If you commit, check that the app is in the commit
+
+Nothing here asks you to commit. If the user asks for one, or you offer and they
+accept, then **verify what went in** — `git status` clean is not the same as the
+app being committed, because a file that is ignored never shows as uncommitted.
+
+The specific way this bites: a bare `python*` in `.gitignore`. Git matches that against **every path segment**, so
+`src/python-tools/` was ignored, and `git add -A` silently refused the analysis
+script — the one file the whole port exists to produce. The app's own tests
+passed, the working tree looked clean, and a fresh clone would have installed an
+app whose Configure page throws, because `input_python()` could not find its
+tool.
+
+The existing tools escaped only because they were committed before the rule
+mattered; `.gitignore` does not apply to files already tracked. So this is
+invisible in the template and appears the first time a generated app adds a file.
+
+After committing:
+
+```
+git ls-files src/python-tools/ src/dashboards/ content/
+```
+
+Every file the port created should be listed. If one is missing, find the ignore
+rule (`git check-ignore -v <path>`) and say so rather than working around it —
+an ignore rule that swallows a generated file is a template defect, and
+`scaffold-workflow-app` has what to do with those.
+
+**Report the commit the way you report everything else: in their terms.** A
+commit confirmation is still an ending, so the rule above still applies — *a
+number belongs here only if it is theirs.* *"Working tree clean, 229 tests passing"* is a count of the framework's own
+tests in the one sentence the user was going to read. `git status` and a test total are how **you** know it worked.
+What they need is the branch, and what is on it.
diff --git a/.claude/skills/scaffold-workflow-app/rounds.md b/.claude/skills/scaffold-workflow-app/rounds.md
new file mode 100644
index 00000000..fa5c5f23
--- /dev/null
+++ b/.claude/skills/scaffold-workflow-app/rounds.md
@@ -0,0 +1,73 @@
+# Design rounds on Upload and Configure
+
+Part of `scaffold-workflow-app`. Read this when the smoke run has passed and you are opening a round.
+
+Run is a log and a button; Results belongs to `build-insight-dashboard`. The other
+two are pages the user touches on **every run**, and a generated form is not a
+design.
+
+Once the app boots, take Upload then Configure through design rounds. Full round
+mechanics are in `build-insight-dashboard`; the parts that matter here:
+
+- Open the page in the **user's browser** before opening a round — literally,
+  with `start <url>` on Windows, `open <url>` on macOS, `xdg-open <url>` on
+  Linux. This needs no browser tooling: opening a page and driving one are
+  different capabilities, and a round that cannot be driven can still be opened.
+  Not a
+  screenshot described to them — the screenshot is how *you* check the page, and
+  saying you took one narrates machinery.
+- **Bounded to what the template already does.** These two pages have a shape
+  the template chose, not this app. A suggestion is in bounds when it is
+  implemented by an argument the template's own widgets already accept — a
+  `name`, a `fallback`, a `custom_defaults`, an `advanced` flag, a `help` string,
+  a `widget_type` — or by section naming, section order, or a named preset in
+  `presets.json` (see `add-presets`). Reaching for a layout primitive the page
+  does not already use is out of bounds. *"Drop the tabs, put MS data and the database side by side"* is a good idea
+  about the wrong thing.
+- **One suggestion at a time**, asked, not listed. Three is a ceiling, not a
+  quota — a ceiling on the *round*, and never on one screen. A user handed three
+  at once reads a pile rather than a choice. Ask the highest-value one,
+  take the answer, then ask the next. Each must point at something visible; offer
+  two and name the third clean rather than padding.
+- A free field and an exit, always. Check the request against what exists,
+  then answer in one of the five shapes — *yes* / *yes and here is what you lose*
+  / *not as stated* / *yes but it reopens an earlier stage* / *no, and here is the
+  nearest thing*. **Never silently substitute** the nearest possible thing.
+- Apply, restart the server, re-render. Streamlit does not re-import an edited
+  `src/` module; without the restart you show the user their unchanged page.
+
+| axis | Upload page | Configure page |
+|---|---|---|
+| **data** | which file types, which are optional, what the labels say | which parameters are visible, in what order, what the help says |
+| **layout** | the section names and the order they appear in | section order, and what sits behind *advanced* |
+| **behaviour** | what shows with nothing uploaded yet | presets, and what the defaults are |
+
+Two suggestions nearly always right and almost never generated by default:
+**order config parameters by measured effect size** — `interview-parameters`
+already knows it, and screen order otherwise implies an importance that is not
+real — and **save the resolved notebook values as a preset**, a labelled way back
+to "what the notebook did". `add-presets` owns the `presets.json` schema; a
+preset is also the cheapest in-bounds suggestion a Configure round can make.
+
+Two `DEFAULTS` fields whose defaults are wrong for most parameters, and both fail
+silently:
+
+- **`widget_type`** — the legal values are exactly `text`, `textarea`, `number`,
+  `selectbox`, `slider`, `checkbox`, `multiselect`, `password`, `auto`
+  (`StreamlitUI.py:593`). **Anything else renders nothing at all.** The chain
+  that dispatches on it is a run of `elif`s with no final `else`
+  (`StreamlitUI.py:678-812`), so an unrecognised value matches no branch, raises
+  nothing, warns nothing, and the parameter simply is not on the page. Measured
+  on a real build: four widgets declared `number_input` — the Streamlit function
+  name, not the value this template takes — and the Configure page came up
+  missing four controls with a clean log. Give it explicitly to anything a
+  preset should drive.
+  `input_widget` prefixes the key (`StreamlitUI.py:676`), then the `auto` branch
+  recurses passing that already-prefixed key, prefixing it twice; the preset's
+  delete-list computes one prefix (`ParameterManager.py:647`), misses the stale
+  session key, and the old value overwrites the preset on the next rerun.
+- **`step_size`** — `input_python` defaults it to **1** (`StreamlitUI.py:1367`).
+  On a float parameter spanning 0.0–1.0 that is a two-position control, and on a
+  tolerance spanning 0.0–5.0 it is six. Declare it for every non-integer
+  parameter; the default is only ever right for counts.
+
diff --git a/.claude/skills/verify-webapp-usability/SKILL.md b/.claude/skills/verify-webapp-usability/SKILL.md
new file mode 100644
index 00000000..ac58e1c5
--- /dev/null
+++ b/.claude/skills/verify-webapp-usability/SKILL.md
@@ -0,0 +1,158 @@
+---
+name: verify-webapp-usability
+description: Use when checking that a Streamlit results page actually renders and is usable, when OpenMS-Insight panels need verifying in a real browser, or when a page passes its tests but nobody has looked at it.
+---
+
+# Verify webapp usability
+
+Gate a results page in a real browser: hard assertions for correctness, a
+screenshot for judgement.
+
+**This whole stage is internal.** The gate, the screenshot, the component count,
+`--ignore-console` — none of it appears in a user-facing turn. What a failure
+becomes is a fix, made before the page is shown; what a design note becomes is a
+suggestion in the user's own words, in the round that follows. A user told *"the
+gate passed 11/11 and I've opened the screenshot"* has been given the framework's
+homework instead of their app.
+
+## The rule
+
+**A results page built from OpenMS-Insight components cannot be verified with
+`AppTest`.**
+
+`streamlit.testing.v1.AppTest` executes no JavaScript. Insight components are
+custom bidirectional Vue components in iframes, so a page whose every panel
+fails to render still passes every AppTest assertion. Keep AppTest for what it
+can see — page boot, Streamlit-native widgets, parameter round-tripping — and
+gate the dashboard here.
+
+**And keep the Results page out of `test_launch` entirely.** It does not merely
+fail to *see* the panels — measured on three generated apps, constructing an
+Insight component under AppTest raises `RuntimeError: Preprocessing failed with
+exit code 1`, so the page cannot be launched at all there. The other pages of a
+generated app launch clean and belong in that list; this one is covered here, and
+listing it buys a failing test rather than coverage.
+
+## Running it
+
+```bash
+python gate.py --url http://localhost:8501/ --nav "Results" \
+    --expect-components 2 --screenshot results.png
+```
+
+Use `--nav` rather than a direct page URL. Opening a sub-page URL directly makes
+Streamlit resolve `/_stcore/health` and `/_stcore/host-config` relative to that
+path, producing two 404s that are an artefact of the test, not a defect. Clicking
+the sidebar link is also what a user does.
+
+## What it asserts
+
+- page boots with no Python traceback and no `stException` block
+- no uncaught JS page errors; browser console clean
+- every declared panel renders **with real width and height** — a zero-height
+  iframe is the failure mode to catch, because the component mounts and reports
+  no error. `--expect-components` is the **total** panel count: Insight iframes
+  plus fallback panels drawn with pyopenms-viz through `show_fig()`, which are
+  native Streamlit charts, not iframes. Counting iframes alone marks a dashboard
+  down for following the fallback rule in `build-insight-dashboard`
+- **no panel is stuck loading.** A panel filtering on a link identifier that
+  nothing sets and no `filter_defaults` value covers shows "Loading…" forever
+  while passing every other check: the iframe has real size, the console is
+  clean, nothing throws. The gate reads inside each iframe after settling and
+  fails on a panel whose entire content is a placeholder
+- the page is not blank; no horizontal scrollbar
+- clicking a row in the master panel changes a linked panel
+- first paint within budget
+
+Then it saves a screenshot. **Look at it.** The assertions cannot see that a
+column header is truncated, or that one half of a mirror plot is flattened onto
+the baseline by a shared axis. Both of those passed every check on a real build
+and were caught only by looking.
+
+## The second job: design input
+
+The gate runs twice for different reasons. During `build-insight-dashboard` it
+runs *before* the final whole-page design round, and its output feeds that round's
+suggestions — so it also prints **design notes**: panels below the fold, a missing
+summary strip, a column header with no slack left. These are observations, not failures, and
+they are written to be read by the user rather than by a log.
+
+When you relay them, keep them in the user's language. "Nothing is selected when
+the page opens, so the 3D panel is empty on arrival" — not `warn: no default
+selection`. A finding the user cannot picture is a finding they will skip.
+
+## Waiting correctly
+
+Never sample after a fixed sleep. Streamlit streams output while the script is
+still running, and Insight preprocesses large tables in a subprocess before its
+component mounts — so a fixed wait screenshots a half-rendered page and reports
+missing panels that are merely late. The gate polls Streamlit's own
+`stStatusWidget` until it clears, then waits either for the expected panels to
+appear or for the iframe count to stop changing — whichever comes first.
+
+**A screenshot that times out is a page mid-rerun — re-navigate, don't retry.**
+Driving the app yourself, every click reruns the script, and a screenshot taken
+during that rerun comes back *"Script injection timed out … the page is busy or
+mid-navigation"*. Retrying the screenshot fails again for the same reason; one
+run lost three calls to that twice over. Navigating to the page's URL again
+returns it in a settled state, and the screenshot then works.
+
+**When re-navigating does not fix it, the tab is wedged — open a new one.**
+Re-navigation recovers a page mid-rerun. It does not recover a tab that has
+stopped answering, and the two are indistinguishable from the timeout message.
+Three builds on three notebooks hit this: one re-navigated the same tab three
+times over ~40 seconds with every screenshot still timing out while the server
+answered `curl` in 1.5ms; another wedged twice, both times just after the File
+Upload page re-copied a 37 MB fallback file. A fresh tab fixed it instantly in
+every case.
+
+**A wedged tab reads as a broken app, and that is the expensive part.** One run
+took three dead `Start Workflow` clicks as the button being broken and went
+through the log, the pid directory, the process table and the multiprocessing
+spawn path before the tab turned out to be the fault. If the server answers
+`curl` and the page does not answer you, suspect the tab before the app.
+
+**Opening a new tab moves the MCP tab group**, so a `tabId` recorded before the
+switch is stale — re-read it rather than reusing it, or a batch of calls lands
+on nothing.
+
+**Never wait on a count that mixes iframes with native panels.** `settle()` also
+exits once the app is idle and the iframe count has stopped changing, because
+`--expect-components` is the *total* — a page with two Insight iframes plus one
+`show_fig()` panel would otherwise wait for a third iframe that never arrives and
+burn the full timeout. That bug ran for twenty gate invocations reporting 96.5s
+first paint on the one app with a fallback panel, and was read as a slow page.
+
+`full_page=True` does not work here: Streamlit scrolls its main container, not
+the document, so a full-page shot captures only the first viewport. The gate
+grows the viewport instead (`--capture-height`).
+
+## Ignoring benign errors
+
+`--ignore-console` takes a substring, and applies to console errors, page errors
+and failed requests. Use it only for a known upstream error, and record why. For
+this template, Tabulator emits `Scroll Error - Row not visible` when it scrolls
+to a default row before layout completes; it is harmless and not fixable from
+the app.
+
+Every other error is the app's problem. An ignore entry with no justification is
+how a gate stops catching anything.
+
+## Common mistakes
+
+- Trusting a green gate as proof the page is good. Green means it works;
+  the screenshot is where quality is judged.
+- **Trusting a green gate as proof the app produced what it is showing.** The
+  gate opens a results page and reads what is on it. It cannot tell an output
+  `execution()` wrote from one dropped into the results directory by hand, and
+  both render identically. Measured: all three corpus apps passed this gate at
+  1.000 for **ninety ticks** while their workspaces held nothing but seeded
+  files — no `params.json`, no `logs/`, and a `seed.json` naming the tool
+  invocation that had produced them. `execution()` had never run once.
+  A workspace with `results/` and no `logs/` beside it was filled by hand; the
+  smoke run in `scaffold-workflow-app` is what stops this.
+- Not restarting the server after editing a `src/` module. The gate will
+  keep reporting an exception you have already fixed, because Streamlit did not
+  re-import the module.
+- Leaving a stale Insight cache after changing a component config, then
+  concluding the change did nothing.
diff --git a/.claude/skills/verify-webapp-usability/gate.py b/.claude/skills/verify-webapp-usability/gate.py
new file mode 100644
index 00000000..4b52641f
--- /dev/null
+++ b/.claude/skills/verify-webapp-usability/gate.py
@@ -0,0 +1,593 @@
+"""Usability gate for a Streamlit results page.
+
+AppTest executes no JavaScript, so it cannot see OpenMS-Insight components at
+all -- a page built entirely from them passes every AppTest assertion while
+rendering nothing. This drives a real browser instead.
+
+Hard assertions catch breakage; the screenshot it saves is for a human or model
+to critique against the dashboard style contract.
+
+Usage:
+  python gate.py --url http://localhost:8510/identification_results \
+      --expect-components 2 --screenshot shot.png
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import time
+
+from playwright.sync_api import sync_playwright
+
+VIEWPORT = {"width": 1280, "height": 800}
+
+
+# Console noise this template emits that no app change can stop. Named here
+# rather than in prose, because prose is not what a run is reading at the
+# moment the gate fails.
+#
+# Three builds hit the Tabulator one and each spent two or more
+# edit-restart-gate cycles on it: one dropped `initial_sort` and widened
+# columns, one bisected a minimal app three ways, and one turned server-side
+# pagination off on a 333-row table -- losing the page-size control and the
+# page buttons -- to silence a message the skill already documents as
+# harmless. All three eventually found the sentence saying so. The skill was
+# never wrong; it was in the wrong place. A build reads the FAIL line.
+KNOWN_BENIGN = {
+    "Scroll Error - Row not visible":
+        "the table scrolls to a default row before layout completes; "
+        "harmless, and not fixable from the app",
+}
+
+
+class Gate:
+    def __init__(self):
+        self.checks: list[tuple[str, bool, str]] = []
+
+    def check(self, name: str, ok: bool, detail: str = "") -> bool:
+        self.checks.append((name, bool(ok), detail))
+        mark = "ok  " if ok else "FAIL"
+        print(f"  [{mark}] {name}" + (f"  -- {detail}" if detail else ""))
+        return bool(ok)
+
+    def warn(self, name: str, detail: str = "") -> None:
+        self.checks.append((name, True, "WARN: " + detail))
+        print(f"  [warn] {name}" + (f"  -- {detail}" if detail else ""))
+
+    @property
+    def failed(self) -> int:
+        return sum(1 for _, ok, _ in self.checks if not ok)
+
+
+def settle(page, seconds: float = 2.0, expect_frames: int = 0,
+           timeout: float = 90.0) -> None:
+    """Wait for Streamlit to stop running, not for a fixed number of seconds.
+
+    A fixed sleep samples a half-rendered page: Streamlit streams output while
+    the script is still executing, and OpenMS-Insight preprocesses large tables
+    in a subprocess before its component ever mounts. Poll the app's own running
+    indicator, then wait for the components to actually appear.
+    """
+    time.sleep(seconds)
+    deadline = time.time() + timeout
+    last, stable_since = -1, None
+    while time.time() < deadline:
+        running = page.query_selector("[data-testid='stStatusWidget']")
+        frames = len(page.query_selector_all("iframe"))
+        if frames != last:
+            last, stable_since = frames, time.time()
+        if running is None and frames >= expect_frames:
+            break
+        # Waiting for a frame COUNT alone is wrong: --expect-components is the
+        # TOTAL panel count including native fallbacks, so a page with two
+        # iframes plus a show_fig() panel waits for a third iframe that never
+        # arrives, and burns the whole timeout. Measured on the one corpus app
+        # with a fallback panel: 96.5s first paint, every run, for twenty runs,
+        # read as a slow page rather than as this bug. So also stop once the app
+        # is idle and the iframe count has stopped changing.
+        if running is None and stable_since and time.time() - stable_since >= 3.0:
+            break
+        time.sleep(1.0)
+    try:
+        page.wait_for_load_state("networkidle", timeout=15000)
+    except Exception:
+        pass
+
+
+def component_frames(page):
+    """Iframes holding custom components, with their rendered size."""
+    frames = []
+    for el in page.query_selector_all("iframe"):
+        try:
+            box = el.bounding_box() or {}
+            frames.append((el, box.get("width", 0), box.get("height", 0)))
+        except Exception:
+            continue
+    return frames
+
+
+# A panel is not always an Insight component. When no Insight component fits a
+# role, build-insight-dashboard prescribes falling back to pyopenms-viz through
+# show_fig(), which renders a native Streamlit chart rather than an iframe.
+# Counting iframes alone marks that dashboard down for following the guidance.
+# stDataFrame is here for the TABLE role specifically. A plot falling back to
+# pyopenms-viz renders Plotly and was always counted; a table has no plot to fall
+# back to, so it becomes st.dataframe and was counted as nothing. A run hit that,
+# read a real 9/10 on a page missing its table, and reached PASS by lowering
+# --expect-components from 2 to 1 -- changing the measurement to fit the result.
+# Counting it removes that pressure. The size filter below is what keeps an
+# incidental show_table() in a collapsed expander from inflating the count.
+NATIVE_PANEL_SELECTORS = (
+    "[data-testid='stPlotlyChart']",
+    "[data-testid='stVegaLiteChart']",
+    "[data-testid='stArrowVegaLiteChart']",
+    "[data-testid='stPyplotChart']",
+    "[data-testid='stDataFrame']",
+)
+
+
+def native_panels(page):
+    """Non-iframe chart panels (fallback panels), with their rendered size."""
+    panels = []
+    for selector in NATIVE_PANEL_SELECTORS:
+        for el in page.query_selector_all(selector):
+            try:
+                box = el.bounding_box() or {}
+                panels.append((el, box.get("width", 0), box.get("height", 0)))
+            except Exception:
+                continue
+    return panels
+
+
+def stuck_panels(frames):
+    """Panels that mounted but never finished loading their data.
+
+    This is the failure mode the rest of the gate is blind to: the iframe has
+    real size, the console is clean and nothing throws, so every other check
+    passes while the user looks at the word "Loading" forever. It happens when a
+    panel filters on a link identifier that no panel has set and no
+    filter_defaults value covers.
+
+    Only called after settle(), so a loading indicator here has outlived the
+    app's own running indicator and is not merely late.
+    """
+    stuck = []
+    for el, _, _ in frames:
+        try:
+            frame = el.content_frame()
+            if frame is None:
+                continue
+            text = (frame.inner_text("body") or "").strip()
+        except Exception:
+            continue
+        if not text:
+            stuck.append("a panel renders no text at all")
+            continue
+        # A real panel carries axis labels, headers or rows. A stuck one has a
+        # placeholder and nothing else, so bound this on total length as well as
+        # on the word, or a table with a "Loading" column header trips it.
+        if len(text) < 200 and any(
+            marker in text.lower() for marker in ("loading", "no data", "waiting")
+        ):
+            stuck.append(f"a panel shows only: {text.splitlines()[0][:60]!r}")
+    return stuck
+
+
+def design_notes(page, frames, native, viewport_height):
+    """Observations for the final design round, phrased for a user.
+
+    The gate's second job. Its findings feed the last design round in
+    build-insight-dashboard, where a user reads them -- so these are sentences
+    about the page, not log lines about assertions.
+    """
+    notes = []
+
+    below = [f for f in frames + native
+             if (f[0].bounding_box() or {}).get("y", 0) + f[2] > viewport_height]
+    if below:
+        notes.append(
+            f"{len(below)} panel(s) sit below the fold at {viewport_height}px -- "
+            "a first-time visitor has to scroll to learn they exist"
+        )
+
+    if not page.query_selector("[data-testid='stMetric']"):
+        notes.append(
+            "no summary strip: the page opens with no headline numbers, so the "
+            "size of the result is only inferable from a table"
+        )
+
+    # Crowding, measured. This note used to fire on `len(cols) > 6`, the ceiling
+    # tick 002 disproved: a six-column table truncated 'Matched i...' while the
+    # count check stayed silent. `truncated_headers` fails on a header that has
+    # already overflowed; the useful *note* is the one that has not overflowed
+    # yet but has no room left, because that is the table a longer value or one
+    # more column will break.
+    for el, _, _ in frames:
+        try:
+            frame = el.content_frame()
+            if frame is None:
+                continue
+            tight = frame.evaluate(
+                """() => {
+                    const sel = '.tabulator-col-title, .tabulator-col .tabulator-title';
+                    let worst = null;
+                    for (const n of document.querySelectorAll(sel)) {
+                        const slack = n.clientWidth - n.scrollWidth;
+                        if (slack < 0) continue;          // already truncated
+                        if (worst === null || slack < worst.slack) {
+                            worst = {slack, text: (n.textContent || '').trim().slice(0, 40)};
+                        }
+                    }
+                    return worst;
+                }"""
+            )
+        except Exception:
+            continue
+        # 8px is roughly one character at Tabulator's default header font, so
+        # the note means "one more character and this truncates" rather than an
+        # aesthetic judgement. It is a threshold on the measured property, not a
+        # proxy for it -- which is the distinction the column-count rule failed.
+        if tight and tight["slack"] <= 8:
+            notes.append(
+                f"the header {tight['text']!r} has {tight['slack']}px of slack "
+                "left -- a longer value, or one more column, truncates it"
+            )
+
+    return notes
+
+
+def collapsed_columns(frames):
+    """Columns Tabulator folded into stacked label/value rows under each record.
+
+    A third failure, invisible to both header checks. The headers that remain
+    are neither truncated nor wrapped -- the columns that would have been are
+    simply gone from the header row and reappear beneath every record as
+    label/value pairs. Four builds on three notebooks hit it, and the most
+    recent states the problem exactly: `[ok] no table header is truncated` and
+    `[ok] no table header has wrapped onto a second line` both passed while the
+    screenshot showed three columns stacked under each row.
+
+    It is not predicted by the width budget either. `responsiveLayout:
+    "collapse"` is hardcoded in the component, so it fires on Tabulator's own
+    minimum-width measurement at mount time -- one build hit it with declared
+    widths summing to well under the panel width.
+
+    The collapse holder exists in every row whether or not anything collapsed,
+    so emptiness is the signal, not absence.
+    """
+    collapsed = []
+    for el, _, _ in frames:
+        try:
+            frame = el.content_frame()
+            if frame is None:
+                continue
+            found = frame.evaluate(
+                """() => {
+                    const out = [];
+                    for (const holder of document.querySelectorAll(
+                            '.tabulator-responsive-collapse')) {
+                        const txt = (holder.textContent || '').trim();
+                        if (txt && holder.offsetHeight > 0) {
+                            out.push(txt.slice(0, 40));
+                        }
+                    }
+                    return out;
+                }"""
+            )
+        except Exception:
+            continue
+        collapsed.extend(t for t in found if t)
+    return collapsed
+
+
+def wrapped_headers(frames):
+    """Table column headers that have folded onto a second line.
+
+    Not the same failure as truncation, and invisible to it: a wrapped header
+    shows all of its text, so `scrollWidth > clientWidth` never trips. The row
+    simply grows a phantom second line and the table looks broken.
+
+    Three builds on three notebooks hit this and every one of them reported the
+    same thing -- the gate returned a full pass while the screenshot showed
+    'Quality 3.0' folded onto a second line. Each then spent four or five
+    edit-restart-gate cycles finding a width by trial, because the instrument
+    that was supposed to catch it could not see it.
+
+    A header cell that fits on one line is about one line-height tall. One that
+    wrapped is about two, so comparing the cell's height against its own
+    line-height is exact rather than a guess at pixels.
+    """
+    wrapped = []
+    for el, _, _ in frames:
+        try:
+            frame = el.content_frame()
+            if frame is None:
+                continue
+            found = frame.evaluate(
+                """() => {
+                    const out = [];
+                    const sel = '.tabulator-col-title, .tabulator-col .tabulator-title';
+                    for (const n of document.querySelectorAll(sel)) {
+                        const cs = getComputedStyle(n);
+                        let lh = parseFloat(cs.lineHeight);
+                        if (!isFinite(lh)) lh = parseFloat(cs.fontSize) * 1.2;
+                        if (!isFinite(lh) || lh <= 0) continue;
+                        // 1.5 line-heights: comfortably above one line, below two.
+                        if (n.scrollHeight > lh * 1.5) {
+                            out.push((n.textContent || '').trim().slice(0, 40));
+                        }
+                    }
+                    return out;
+                }"""
+            )
+        except Exception:
+            continue
+        wrapped.extend(h for h in found if h)
+    return wrapped
+
+
+def truncated_headers(frames):
+    """Table column headers whose text does not fit the column it sits in.
+
+    Column count was a proxy for this and the proxy was wrong: a table with
+    exactly six columns rendered 'Matched i...' while a >6 check stayed silent
+    and the gate reported a full pass. Measure the property actually cared about
+    -- rendered text wider than the box holding it -- instead of guessing at a
+    ceiling that produces it.
+
+    Tabulator sets the title element's scrollWidth beyond its clientWidth when it
+    ellipsises, so this is exact rather than an estimate.
+    """
+    truncated = []
+    for el, _, _ in frames:
+        try:
+            frame = el.content_frame()
+            if frame is None:
+                continue
+            found = frame.evaluate(
+                """() => {
+                    const out = [];
+                    const sel = '.tabulator-col-title, .tabulator-col .tabulator-title';
+                    for (const n of document.querySelectorAll(sel)) {
+                        if (n.scrollWidth > n.clientWidth + 1) {
+                            out.push((n.textContent || '').trim().slice(0, 40));
+                        }
+                    }
+                    return out;
+                }"""
+            )
+        except Exception:
+            continue
+        truncated.extend(h for h in found if h)
+    return truncated
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--url", required=True)
+    ap.add_argument("--expect-components", type=int, default=1)
+    ap.add_argument("--screenshot", default="usability.png")
+    ap.add_argument("--first-paint-budget", type=float, default=5.0)
+    ap.add_argument("--no-interaction", action="store_true")
+    ap.add_argument(
+        "--nav",
+        default=None,
+        help="Sidebar link to click after loading --url. Navigating like a user "
+        "avoids Streamlit resolving /_stcore relative to a sub-page path, which "
+        "produces two spurious 404s when a page URL is opened directly.",
+    )
+    ap.add_argument(
+        "--ignore-console",
+        action="append",
+        default=[],
+        help="Substring of a known-benign console error to ignore. Every use "
+        "should be justified in the skill or the app's notes.",
+    )
+    ap.add_argument("--capture-height", type=int, default=2400)
+    args = ap.parse_args()
+
+    gate = Gate()
+    console_errors: list[str] = []
+    page_errors: list[str] = []
+    failed_requests: list[str] = []
+
+    with sync_playwright() as pw:
+        browser = pw.chromium.launch(headless=True)
+        page = browser.new_page(viewport=VIEWPORT)
+        page.on(
+            "console",
+            lambda m: console_errors.append(m.text) if m.type == "error" else None,
+        )
+        page.on("pageerror", lambda e: page_errors.append(str(e)))
+        # "Failed to load resource" in the console never says which resource;
+        # record the URL and status so a 404 is actionable.
+        page.on(
+            "response",
+            lambda r: failed_requests.append(f"{r.status} {r.url}")
+            if r.status >= 400
+            else None,
+        )
+
+        print(f"\nUSABILITY GATE  {args.url}  @{VIEWPORT['width']}x{VIEWPORT['height']}\n")
+
+        t0 = time.time()
+        page.goto(args.url, wait_until="domcontentloaded", timeout=60000)
+        if args.nav:
+            settle(page, 2.0)
+            link = page.get_by_role("link", name=args.nav).first
+            link.click(timeout=20000)
+        settle(page, 3.0, expect_frames=args.expect_components)
+        first_paint = time.time() - t0
+
+        # Ignored by default, but never silently: a check that quietly drops
+        # what it was asked to look at is the failure this file exists to
+        # prevent. It says what it dropped and why, and everything not on the
+        # list still fails.
+        benign = [e for e in console_errors + page_errors
+                  if any(k in e for k in KNOWN_BENIGN)]
+        for text in dict.fromkeys(benign):
+            why = next(v for k, v in KNOWN_BENIGN.items() if k in text)
+            print(f"  known-benign, ignored: {text[:70]} -- {why}")
+
+        console_errors[:] = [
+            e for e in console_errors
+            if not any(pat in e for pat in args.ignore_console)
+            and not any(k in e for k in KNOWN_BENIGN)
+        ]
+        page_errors[:] = [
+            e for e in page_errors
+            if not any(pat in e for pat in args.ignore_console)
+            and not any(k in e for k in KNOWN_BENIGN)
+        ]
+        failed_requests[:] = [
+            r for r in failed_requests
+            if not any(pat in r for pat in args.ignore_console)
+        ]
+
+        body = page.inner_text("body")
+
+        gate.check(
+            "page boots without a Python traceback",
+            "Traceback (most recent call last)" not in body,
+            body.split("Traceback")[-1][:160].strip() if "Traceback" in body else "",
+        )
+        gate.check(
+            "no Streamlit exception block",
+            page.query_selector("[data-testid='stException']") is None,
+        )
+        gate.check("no uncaught JS page errors", not page_errors, "; ".join(page_errors[:2]))
+        gate.check(
+            "browser console clean",
+            not console_errors,
+            f"{len(console_errors)} error(s): " + "; ".join(console_errors[:2]),
+        )
+
+        frames = component_frames(page)
+        rendered = [f for f in frames if f[1] > 50 and f[2] > 50]
+        native = [p for p in native_panels(page) if p[1] > 50 and p[2] > 50]
+        total = len(rendered) + len(native)
+        gate.check(
+            f"{args.expect_components} panel(s) rendered with real size",
+            total >= args.expect_components,
+            f"found {len(rendered)} Insight component(s) + {len(native)} "
+            f"fallback panel(s), of {len(frames)} iframes",
+        )
+        # Machine-readable, so a harness never has to scrape the prose above.
+        # Renaming a check's wording must not silently zero someone's metric.
+        print(f"PANELS insight={len(rendered)} fallback={len(native)} total={total}")
+
+        # A panel that mounted but never loaded passes every check above.
+        stuck = stuck_panels(rendered)
+        gate.check(
+            "no panel is stuck loading",
+            not stuck,
+            "; ".join(stuck[:2]),
+        )
+
+        # An unreadable column header is a defect a user sees immediately and no
+        # other assertion sees at all -- the same shape of blind spot as the
+        # stuck panel above.
+        clipped = truncated_headers(rendered)
+        gate.check(
+            "no table header is truncated",
+            not clipped,
+            "clipped: " + ", ".join(repr(h) for h in clipped[:3]) if clipped else "",
+        )
+
+        # A header that WRAPPED shows all its text, so the truncation check
+        # above never sees it -- and three builds shipped a table folded onto a
+        # phantom second row while this gate reported a full pass. Each then
+        # spent four or five edit-restart-gate cycles finding a width by trial,
+        # because the check that should have caught it was blind to it.
+        folded = wrapped_headers(rendered)
+        gate.check(
+            "no table header has wrapped onto a second line",
+            not folded,
+            "wrapped: " + ", ".join(repr(h) for h in folded[:3]) if folded else "",
+        )
+
+        stacked = collapsed_columns(rendered)
+        gate.check(
+            "no table column collapsed into stacked rows",
+            not stacked,
+            "collapsed: " + ", ".join(repr(t) for t in stacked[:3])
+            if stacked else "",
+        )
+
+        # Empty state, not a blank page.
+        gate.check("page is not blank", len(body.strip()) > 40, f"{len(body.strip())} chars")
+
+        # Horizontal overflow: the body must never scroll sideways.
+        overflow = page.evaluate(
+            "() => document.documentElement.scrollWidth - document.documentElement.clientWidth"
+        )
+        gate.check("no horizontal scrollbar", overflow <= 2, f"overflow {overflow}px")
+
+        if first_paint <= args.first_paint_budget:
+            gate.check(f"first paint within {args.first_paint_budget}s", True,
+                       f"{first_paint:.1f}s")
+        else:
+            gate.warn("first paint over budget", f"{first_paint:.1f}s")
+
+        # Cross-component linking: click a row, assert a linked panel changes.
+        if not args.no_interaction and rendered:
+            before = page.screenshot(full_page=False)
+            clicked = False
+            for el, _, _ in rendered:
+                frame = el.content_frame()
+                if not frame:
+                    continue
+                row = frame.query_selector(".tabulator-row")
+                if row:
+                    try:
+                        row.click(timeout=5000)
+                        clicked = True
+                        break
+                    except Exception:
+                        continue
+            if clicked:
+                settle(page, 2.5)
+                after = page.screenshot(full_page=False)
+                gate.check(
+                    "clicking a table row changes a linked panel",
+                    before != after,
+                    "page identical after click" if before == after else "",
+                )
+            else:
+                gate.warn("no clickable table row found", "linking not exercised")
+
+        # The gate's second output: not pass/fail, but material for the final
+        # design round. Printed before the screenshot so the two arrive together.
+        notes = design_notes(page, rendered, native, VIEWPORT["height"])
+        if notes:
+            print("\n  design notes -- material for the final round:")
+            for note in notes:
+                print(f"   -  {note}")
+
+        # full_page is useless here: Streamlit scrolls its main container, not
+        # the document, so a full-page shot captures only the first viewport.
+        # Grow the viewport instead so panels below the fold are in the critique.
+        page.set_viewport_size({"width": VIEWPORT["width"], "height": args.capture_height})
+        settle(page, 2.0)
+        page.screenshot(path=args.screenshot)
+        page.set_viewport_size(VIEWPORT)
+        print(f"\n  [img ] screenshot -> {args.screenshot}")
+
+        browser.close()
+
+    print(f"\n{'PASS' if gate.failed == 0 else 'FAIL'}: "
+          f"{len(gate.checks) - gate.failed}/{len(gate.checks)} checks\n")
+    if console_errors:
+        print("console errors:")
+        for e in console_errors[:8]:
+            print("   ", e[:200])
+    if failed_requests:
+        print("failed requests:")
+        for r in failed_requests[:8]:
+            print("   ", r[:200])
+    return 1 if gate.failed else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/.gitattributes b/.gitattributes
new file mode 100644
index 00000000..6e46e983
--- /dev/null
+++ b/.gitattributes
@@ -0,0 +1,5 @@
+# Shell scripts are executed by /bin/sh inside Linux containers and by POSIX
+# shells in tests/test_seed_demos.py. A CRLF checkout on Windows breaks both:
+# sh reports "not found" on every carriage return, and a shebang with a
+# trailing CR fails to exec. Pin them to LF regardless of core.autocrlf.
+*.sh text eol=lf
diff --git a/.gitignore b/.gitignore
index 5e1c74f3..40bae8b7 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,34 +1,46 @@
-# OpenMS Streamlit template
 workspaces-streamlit-template
 build
 myenv
 build.log
 run_app.spec
 clean-up-workspaces.log
-gdpr_consent/node_modules/
-
-# FLASHApp
-Pipfile
-workspaces-flashtaggerviewer
-
-# Editor directories and files
-.idea
-.vscode
-*.suo
-*.ntvs*
-*.njsproj
-*.sln
-*.sw*
-
-# Temp files
-**/__pycache__
-.DS_Store
 *-embed-amd64
 get-pip.py
 run_app.bat
-python*
+/python*
+**/__pycache__/
 gdpr_consent/node_modules/
 *~
 .streamlit/secrets.toml
 docs/superpowers/
-.venv/
\ No newline at end of file
+.venv/
+
+# Helm charts vendored by `kubectl kustomize --enable-helm k8s/storage/`.
+# Kustomize downloads the Ganesha chart into a `charts/` directory beside the
+# kustomization that inflates it, so every render - local or CI - leaves a tree
+# here. It must never be committed: the vendored chart carries its own
+# `nodeSelector` keys, which would make the no-node-pinning assertion in
+# .github/scripts/ci-assertions.sh red from a clean checkout, and a committed
+# copy silently outranks the version pin the chart is deliberately held at.
+k8s/storage/charts/
+
+# notebook-to-webapp capture scratch (holds staged mzML/FASTA, executed notebooks)
+.capture-baseline/
+
+# eval run artifacts (screenshots, server logs) are regenerable; scores.jsonl is not
+eval/tick-*/
+
+# blind-judging key files: opening one before recording a verdict defeats the
+# point, and committing them would make every past verdict re-derivable
+eval/tick-*/.judge-*-key.json
+
+# End-to-end build runs: disposable, one directory per tick
+eval/builds/
+eval/b/
+
+# the eval harness is not part of the template
+eval/
+
+# the hook log is per-installation, not part of the framework
+.claude/language-violations.jsonl
+.claude/language-check-ran
diff --git a/CONTEXT.md b/CONTEXT.md
new file mode 100644
index 00000000..04ec8cc1
--- /dev/null
+++ b/CONTEXT.md
@@ -0,0 +1,336 @@
+# OpenMS Streamlit Template
+
+The framework for building mass spectrometry web applications, and for deriving
+them from Jupyter notebooks. This file fixes the vocabulary; it is a glossary,
+not a design document.
+
+## Language
+
+### Already overloaded — use these senses only
+
+**Workflow**:
+A `WorkflowManager` subclass and its slug, owning an upload/configure/execute/results
+cycle inside a workspace. Never use this word for a notebook's analysis, for a CI
+pipeline, or for the sequence of skills that builds an app.
+_Avoid_: pipeline, process, job
+
+**Parameter**:
+Unqualified, this word is ambiguous — the template has three unrelated parameter
+systems. Always qualify it: *simple-page parameter* (`default-parameters.json`),
+*TOPP parameter* (`:1:`-prefixed, from an `.ini`), *python-tool parameter* (a
+`DEFAULTS` entry), or *config parameter* (see below).
+_Avoid_: setting, option, knob, argument
+
+**Feature**:
+In OpenMS file formats, a 2D isotopic peak cluster in a single run. In
+OpenMS-Insight, the row identity of a quantification matrix. Name the sense
+whenever both could be meant.
+_Avoid_: analyte, entity
+
+### Deriving an app from a notebook
+
+**Entry prompt**:
+The fixed natural-language text a user copies from the application and pastes into
+their agentic terminal. It clones the template and points the agent at the
+orchestrator skill *by file path*, because a repository cloned mid-session brings
+its skills onto disk but not into the running session's skill registry — and
+because terminals other than Claude Code have no skill registry at all.
+_Avoid_: bootstrap, installer, one-liner, magic prompt
+
+**Source notebook**:
+The Jupyter notebook an application is derived from. It is read, never modified.
+_Avoid_: input notebook, original, source file
+
+**Capture**:
+The act of deriving an application's analysis from a source notebook. Distinct
+from copying it: capture classifies, isolates and verifies.
+_Avoid_: conversion, port, migration, translation
+
+**Cell class**:
+What a source notebook cell is for — one of *setup*, *input*, *processing*,
+*visualization*, *exercise*, or *demo shortcut*. Every code cell gets exactly one.
+_Avoid_: cell type (that already means code/markdown/raw), category, kind
+
+**Demo shortcut**:
+Code present only to make a teaching notebook fast or short — a truncation applied
+after a filter, a hardcoded plot window, a limit justified by a "for this tutorial"
+comment. It is not analysis and must never reach an application unexamined.
+_Avoid_: hack, stub, simplification, placeholder
+
+**Golden value**:
+A reference measurement taken from executing the source notebook, against which
+the captured processing step is tested. Distinct from a fixture, which is input.
+_Avoid_: baseline, expected value, snapshot, reference output
+
+### The generated application
+
+**Processing step**:
+The analysis captured from a source notebook, as a single script that imports no
+Streamlit, receives its configuration as JSON, and communicates only through files.
+Realized as a python tool.
+_Avoid_: backend, kernel, engine, core, business logic
+
+**Output contract**:
+The processing step's static declaration of what it produces — each file, its role,
+and the identifier it can be linked on. Read without executing anything.
+_Avoid_: manifest, schema, result spec, interface
+
+**Config parameter**:
+A value the application's *end user* can change, surfaced on a configuration page.
+The outcome of a parameter interview; a notebook constant that stays fixed is not
+one.
+_Avoid_: exposed parameter, tunable, user parameter
+
+**Panel**:
+One visualization region on a results page, bound to one output and one component.
+The unit of dashboard construction and of dashboard review.
+_Avoid_: widget, chart, plot, tile, card, block
+
+**Role**:
+The word in the output contract that says what kind of thing a file holds —
+`table`, `mirror`, `peakmap`, `chromatogram`. A fixed vocabulary, because the
+dashboard stage *looks it up* to get a component rather than interpreting it. A
+step may coin a role outside the four, and then must say it has, because a coined
+role has no component waiting for it.
+_Avoid_: kind, type, category, output type
+
+**Fallback panel**:
+A panel drawn with pyopenms-viz instead of the Insight component. Legal for
+exactly two reasons, and it always carries which: the role is outside the
+vocabulary, or Insight could not be imported. It is never described to the user
+as a design choice — a run whose import had failed called its fallback *"the same
+backend your notebook used"*, which was true and read as deliberate. **Always
+qualified**: bare *"the fallback"* already means going without browser control
+(see **The decline**), and the two have nothing to do with each other.
+_Avoid_: static panel, simple panel, plain plot, degraded panel, bare "the fallback"
+
+**Link identifier**:
+The shared name through which panels communicate a selection — set by one panel,
+consumed as a filter by others.
+_Avoid_: selection key, link key, cross-filter, join key
+
+**Style contract**:
+The checkable appearance rules a results page must satisfy — colour semantics,
+axis labelling, empty states, layout limits. Enforced, not advisory.
+_Avoid_: style guide, design system, conventions
+
+### The framework itself
+
+**Browser control**:
+Driving a page — screenshotting it, clicking it, reading its DOM. Distinct from
+**opening** a page, which needs nothing at all. Control needs two pieces: the
+Claude browser extension, installed by the user in their own browser under their
+own claude.ai account, and a native messaging host that Claude Code registers
+itself. Only the first is ever the user's to do.
+_Avoid_: browser access, Chrome integration, headless browser
+
+**The attached browser**:
+The browser the extension answers for. Attached is not theirs: it may be a
+window nobody is sitting at, and a run drove one for a whole preflight while
+the user was asking what it was looking at. Where it runs is a property of the
+deployment, never a fault to diagnose. One thing earns it their app — that it
+loads a page this host serves **on loopback**. Nothing available proves a human
+is in front of it, so the framework does not claim that and does not measure it.
+_Avoid_: their browser, the local browser, the Chrome instance
+
+**The marker**:
+A token of at least ten characters, served from this host on `127.0.0.1` and
+read back out of the page body in the browser under control. The single
+instrument that separates a browser which can load what you serve from one that
+merely answers. Its verdict is reach, never presence and never location: a
+token returned proves the pair works, not where either end is. One navigation
+carries both checks — the token out of the page body, and the screenshot that
+proves the other tool, taken on that same served page.
+_Avoid_: the test page, the handshake, the ping, the reachability check
+
+**The watch**:
+What a run does between the browser ask and its answer: it looks for the device
+in the connected-browser list — once when the rest of setup is done, then every
+fifteen seconds — rather than waiting to be told the click has happened. The
+user's words are a backstop, not the signal, and a device has been measured
+connecting before its user typed anything at all. There is no watch on the road
+where the tool schemas never loaded, because there is no list to read.
+_Avoid_: polling, the handshake wait, waiting for confirmation
+
+**The decline**:
+An explicit no to the browser ask. It is the only thing that licenses a run to
+judge its own pages in the gate's headless browser instead of the user's
+window. Silence is not a decline; neither is moving on to the next question.
+_Avoid_: no control, the fallback, going without
+
+**Control unreachable**:
+Control that answers and drives pages, attached to a browser that cannot load
+what this host serves on loopback. Its `localhost` is not this machine's, so it
+renders whatever sits on that port over there — convincingly, and as though it
+were the app under construction. Nothing in the tab context distinguishes it; a
+page you serve does. A property of the pair, never a verdict on the browser.
+_Avoid_: control foreign, wrong browser, broken control, not connected
+
+**Control lost**:
+Confirmed control that has silently stopped being true. The user closes their
+browser, the device leaves the account's list on its own, and the session is
+re-attached to another one without a word — after which `navigate` keeps
+returning success on a screen nobody is watching. It fails in the success
+direction, which is why no return value detects it and why the repair is the
+user reopening their browser rather than anything the run can do alone.
+_Avoid_: disconnected (that is a different failure), the browser crashed, stale control
+
+**Control absent** vs **control disconnected**:
+Two failures that look alike and are not. *Absent* is the browser tools having no
+schema in this session: there is no probe to run, launching a browser cannot
+create one, and a session started afterwards is what picks them up. *Disconnected*
+is the tools loading and reporting that nothing answers — the browser is shut, or
+the extension is missing from it — and that one is fixable where you stand.
+_Avoid_: not connected (for both), browser not working
+
+**Stage skill**:
+One of the skills performing a single stage of app derivation, invocable on its own
+against an existing application.
+_Avoid_: sub-skill, step, module, phase
+
+**Interview**:
+A single batch review pass in which the framework presents its findings with
+recommendations and the user decides each row. Not a series of questions. Used
+where the framework has *measured* something or has a defensible opinion, and the
+user is adjudicating it — findings, config parameters, which template pages to
+keep. It arrives **already decided**: every row carries the recommendation the
+framework would act on, so the user's work is unticking rather than choosing from
+nothing. Contrast with *design round*.
+
+An interview is **asked, never drawn**. A checklist rendered into the transcript
+is a decision the user cannot make: they would have to retype it to answer. Rows
+reach them as options they select. Where there are more rows than one screen of
+options holds, the interview asks whether the recommendation stands before it
+asks about any single row.
+_Avoid_: wizard, questionnaire, prompt, survey
+
+**Design round**:
+A single exchange of co-design: the framework renders something, **puts it in the
+user's own browser**, offers up to three suggestions and a free field, applies the
+user's choice, and re-renders. Used where there is nothing to measure and the
+decision is taste. Repeats until the user exits; the exit is always offered.
+Contrast with *interview*, which happens once and decides many rows at a time.
+
+Rounds on **Results** may propose anything the panels can express. Rounds on
+**Upload** and **Configure** are bounded by *template functionality*: those pages
+have a shape the template already chose. Suggestions arrive **one at a time** —
+three at once is not a choice, it is a pile.
+_Avoid_: iteration, refinement loop, review cycle, feedback round
+
+**Suggestion axis**:
+The aspect of a page a suggestion addresses — *data* (what is shown or accepted),
+*layout* (how it is arranged), or *behaviour* (what happens when the user acts, or
+has not acted yet). A design round offers **at most one** suggestion per axis — so
+where it offers several they are real alternatives rather than phrasings of one,
+and where an axis has nothing grounded to say it is named clean instead.
+_Avoid_: category, dimension, theme, bucket
+
+**Template functionality**:
+The surface a design round on Upload or Configure is allowed to touch: the
+arguments the template's own widgets already accept — `upload_widget`'s `name`,
+`file_types` and `fallback`; `input_TOPP` / `input_python`'s `custom_defaults`,
+`advanced`, `help`, `widget_type`, `display_subsections`, `display_tool_name`,
+`tool_instance_name` — plus section naming, section order, and named presets in
+`presets.json`. A suggestion that reaches for a layout primitive the page does
+not already use is out of bounds: the template decided that, not this app.
+_Avoid_: allowed changes, scope, the knobs
+
+**Feasibility pass**:
+The reasoning a suggestion goes through **before** it is shown — resolving it to
+the specific file and edit that would implement it. A suggestion whose edit
+cannot be named is dropped rather than offered, and one whose edit turns out
+smaller or larger than it sounded is reworded to match. Its purpose is that the
+framework never has to walk a suggestion back after the user has accepted it.
+_Avoid_: sanity check, validation, review
+
+**User-facing turn**:
+Everything the framework prints between one user input and the next. The unit the
+output budget applies to: **200 words**, because a reader who has to take in more
+than that at once stops reading and starts skimming. Thinking is not part of it —
+the budget constrains what is shown, never what is worked out.
+_Avoid_: message, response, output, turn (unqualified)
+
+**Progress line**:
+One short statement that a slow action is under way or has finished, naming the
+action and nothing about how it works — *"Running it once for reference
+numbers…"*. What replaces a report when there is no decision attached. A progress
+line is not a place to put evidence.
+_Avoid_: status update, log line, narration
+
+**Register**:
+The rule that the framework talks like a mass spectrometrist, never like its own
+implementation. Cell classes, harvesting, probes, sweeps, gates, screenshots,
+`DEFAULTS` and `OUTPUTS` are how the work is done and never appear in a
+user-facing turn. The user's own vocabulary — spectra, tolerances, peptides,
+pages — is what remains.
+_Avoid_: tone, voice, style (that is the *style contract*, which is about pixels)
+
+**Smoke run**:
+One complete pass through a generated app — upload, configure, execute, results —
+driven by the framework with the notebook's own data, before the user is asked to
+look at anything. It is what makes a design round possible: a page with no data
+in it cannot be designed against.
+_Avoid_: test run, dry run, sanity check
+
+**Usability gate**:
+The browser-driven check a results page must pass — hard assertions plus a
+screenshot critique. A gate, not a report: it can fail. **Internal**: its findings
+reach the user rephrased as design suggestions, and the gate itself is never
+mentioned.
+_Avoid_: smoke test, UI test, visual check
+
+**Persona**:
+A scripted user the self-improvement loop plays in order to measure the interviews
+rather than only the generated code. One of them, the **clicker**, types exactly
+two things in the whole session — the notebook's path and the app's name — and
+selects everything else. Any decision the clicker cannot reach is a decision that
+was drawn instead of asked.
+_Avoid_: mock user, actor, simulated user, role
+
+**The implementer** and **the responder**:
+The two agents in a driven build. The implementer is the Claude Code session
+that reads the skills and builds the app; the responder is the persona that
+answers its questions. Alike only in being agents. The implementer holds the
+whole build and is still alive at the end, so it can simply be asked. The
+responder is a fresh process per screen with no memory of any other, so there is
+nobody left to ask and its side is read back off the screens it saw.
+_Avoid_: the builder, the user agent, the driver (that is the harness itself)
+
+**Debrief**:
+Asking an agent in a finished build what went wrong, and classifying what it
+answers against evidence. Not an *interview*, which is the framework asking the
+user to adjudicate findings it has already made: a debrief runs after the work,
+is addressed to an agent, and never reaches a user's screen. An account is
+**confirmed** when the session's own record or the skill snapshot bears it out,
+**contradicted** when they do not, and **uncheckable** when it asserted nothing
+either can settle. A contradiction indicts the checker at least as often as the
+account, so it is surfaced rather than dropped.
+_Avoid_: interview, retro, post-mortem, self-review
+
+**Pitfall**:
+A debrief item, not contradicted, that has occurred in more than one build. A
+single occurrence is a finding; recurrence is what makes it a pitfall, and a
+pitfall binds the next tick to an edit. It stops being one by ceasing to appear
+in new builds — the only verdict a pitfall ever gets, since preference cannot
+settle whether something keeps happening.
+_Avoid_: issue, defect, complaint, friction
+
+**Judge**:
+The model that reads two persona transcripts of the same task, without being told
+which came from the edited skill, and says which one guided the user better and
+why. It never assigns an absolute score.
+_Avoid_: evaluator, grader, rater, critic
+
+**Pairwise verdict**:
+The judge's preference between the transcripts before and after a skill edit,
+counted across personas. It is the loop's keep-or-revert signal for guidance, and
+its stated reason is the lead for the next tick.
+_Avoid_: rubric score, guidance score, rating, win rate
+
+**Tick**:
+One iteration of the self-improvement loop: evaluate the corpus, make a skill
+edit, re-measure, keep or revert. A single edit, so the verdict attributes to
+it — except where pitfalls are promoted, which bind every one of themselves to
+the same tick and are judged as one batch. Not a *design round*, which is the
+user improving their own app.
+_Avoid_: round, cycle, epoch, run
diff --git a/docs/adr/0001-captured-notebooks-become-python-tools.md b/docs/adr/0001-captured-notebooks-become-python-tools.md
new file mode 100644
index 00000000..e740f4d4
--- /dev/null
+++ b/docs/adr/0001-captured-notebooks-become-python-tools.md
@@ -0,0 +1,24 @@
+# Captured notebooks become python tools, not simple pages
+
+A source notebook's analysis is captured into `src/python-tools/<name>.py` and
+driven by a `WorkflowManager` subclass, rather than into a simple page calling
+`page_setup()`/`save_params()`. The workflow framework's `run_python()` invokes a
+python tool as a subprocess with a JSON parameter file and no Streamlit import,
+which makes the isolation we need structural rather than conventional: the
+processing step is testable with plain pytest, unreachable from `st.session_state`,
+and its `DEFAULTS` list generates the configuration page for free.
+
+## Considered Options
+
+Simple pages are much lighter and would produce less code, but isolation would be
+a convention a generator could quietly break, parameters would land in one flat
+global namespace shared with every other page, and there would be no run button,
+log, cancellation or online queue. Choosing per notebook was rejected because a
+general-purpose framework with two shapes has two test strategies and two tutorials.
+
+## Consequences
+
+Every generated app inherits the workflow slug's three-way coupling (directory,
+`presets.json` key, session-state prefixes), so renaming a captured workflow
+orphans its parameters. Apps that use no TOPP tools still carry the framework, but
+they build with `Dockerfile_simple` and never generate an `.ini`.
diff --git a/docs/adr/0002-static-output-contract.md b/docs/adr/0002-static-output-contract.md
new file mode 100644
index 00000000..3069362b
--- /dev/null
+++ b/docs/adr/0002-static-output-contract.md
@@ -0,0 +1,23 @@
+# The processing step declares its outputs statically
+
+A python tool generated by capture declares `OUTPUTS = [...]` alongside `DEFAULTS`,
+naming each file it writes, that file's role, its columns and the identifier it can
+be linked on. The dashboard stage reads this declaration without executing anything,
+and the generated test asserts that a real run matches it.
+
+## Considered Options
+
+A `manifest.json` written at runtime is always truthful, because the run produces
+it — but it forces the ordering "run before you can design", which would make the
+dashboard stage unusable until a possibly slow analysis has completed, and would
+leave the tutorial unable to design a dashboard until then. Writing only native
+OpenMS formats and converting at render time is the most idiomatic option, but
+repeats conversion on every rerun and defeats OpenMS-Insight's server-side
+pagination, which needs files it can page through. Inferring roles by sniffing
+column names leaves nothing for a test to assert against.
+
+## Consequences
+
+The declaration can drift from what the script actually writes. That is deliberate:
+the drift is exactly what the generated test detects, and a failure there is a real
+defect rather than a stale comment.
diff --git a/docs/adr/0003-browser-verification-for-insight-pages.md b/docs/adr/0003-browser-verification-for-insight-pages.md
new file mode 100644
index 00000000..218754ed
--- /dev/null
+++ b/docs/adr/0003-browser-verification-for-insight-pages.md
@@ -0,0 +1,18 @@
+# Results pages are verified in a real browser, not with AppTest
+
+`streamlit.testing.v1.AppTest` executes no JavaScript, so it cannot see
+OpenMS-Insight components at all — they are custom bidirectional Vue components
+rendered in iframes. A results page built entirely from Insight components passes
+every AppTest assertion while rendering nothing. Results pages are therefore gated
+by headless Playwright, which asserts that panels render, that clicking a row
+changes a linked panel, and that the browser console is clean, plus a screenshot
+the model critiques against the style contract.
+
+## Consequences
+
+This is a second test mechanism beside the repo's existing AppTest suite, and it
+adds a Playwright dev dependency and a browser download to the development setup.
+AppTest is kept for everything it can still see — page boot, Streamlit-native
+widgets, parameter round-tripping. During interactive dashboard building a real
+Chrome session is driven instead, for the same reason in reverse: the model needs
+to look at the page it is designing.
diff --git a/docs/adr/0004-guidance-is-judged-pairwise.md b/docs/adr/0004-guidance-is-judged-pairwise.md
new file mode 100644
index 00000000..a4e9442e
--- /dev/null
+++ b/docs/adr/0004-guidance-is-judged-pairwise.md
@@ -0,0 +1,35 @@
+# Guidance is judged by blind pairwise comparison, not an absolute rubric
+
+The self-improvement loop scores how well a skill guides its user, not only what
+it produces. That score is obtained by having a judge model read two persona
+transcripts of the same task -- one from before a skill edit, one from after,
+neither labelled -- and say which guided the user better, and why. Verdicts are
+counted across personas; a majority preference for the edited skill is a keep.
+
+An absolute rubric was the obvious alternative and is richer: it says *how* good a
+transcript is, not merely which of two is better, and it produces a number that
+plots over time. It was rejected because it varies by roughly +/-0.4 on a 5-point
+scale between reruns of an unchanged skill, and the loop's ratchet keeps any tick
+whose score rose. A metric whose noise exceeds the size of a typical skill edit
+will ratchet in edits that changed nothing, and the loop cannot tell that this is
+happening from the inside.
+
+Preference between two concrete artifacts is far more stable than a score against
+an imagined ideal, and the judge's stated reason is directly actionable -- it
+names the next tick's edit, which a number never does.
+
+## Consequences
+
+Guidance has no absolute scale, so there is no guidance figure to plot across
+ticks and no way to compare a transcript against one from a distant tick without
+re-judging the pair. The history in `eval/scores.jsonl` records verdicts and
+reasons rather than a guidance score.
+
+Every tick must retain the previous transcript for each persona, which makes the
+persona transcripts a stored artifact rather than a byproduct, and doubles the
+transcript generation cost of a tick that re-runs a persona from scratch.
+
+The artifact dimensions stay scored numerically and keep their weights. They are
+saturated at 1.00 across the current corpus and no longer discriminate between
+skill edits, but they remain the regression guard: a tick that drops one has
+broken something that worked, and that has already happened once.
diff --git a/docs/adr/0005-design-rounds-judge-one-panel.md b/docs/adr/0005-design-rounds-judge-one-panel.md
new file mode 100644
index 00000000..e72e29d2
--- /dev/null
+++ b/docs/adr/0005-design-rounds-judge-one-panel.md
@@ -0,0 +1,49 @@
+# Design rounds judge one panel at a time, then the assembled page once
+
+> **Refined, not superseded.** The count below was retired at tick 007: a round
+> offers *up to* three suggestions, a ceiling rather than a quota. The per-panel
+> decision this ADR records is unchanged. See "Refinement" below.
+
+A design round shows the user one panel, offers three suggestions -- one on data,
+one on layout, one on behaviour -- plus a free field and an exit, applies the
+choice and re-renders. Panels are built and judged in sequence. Only when every
+panel has been approved does the framework run the usability gate and open a final
+round on the page as a whole, with the gate's findings and the screenshot feeding
+that round's suggestions.
+
+The objection to per-panel rounds is real: a layout cannot be judged from one
+panel, and a user asked to improve panel one has not yet seen panels two and
+three. Judging the whole assembled page every round avoids that entirely.
+
+Per-panel was chosen anyway, because the alternative asks the user to review a
+dashboard the framework designed alone and then argue with it. Building each panel
+with its author present is what makes the result theirs, and it matches how the
+dashboard skill already builds -- one panel, reload, look, adjust -- so the
+user-facing rhythm and the debugging rhythm are the same rhythm.
+
+The gate-fed final round is what repairs the objection. Layout, the summary strip,
+colour consistency across panels, and what the page shows before anything is
+selected are exactly the properties that only exist once everything is on screen,
+and they are also what the gate and the screenshot can speak to.
+
+## Refinement
+
+The round as described here offers three suggestions. Tick 007 of the
+self-improvement loop refined that to **up to three -- a ceiling, not a quota**:
+every suggestion must point at something visible, and a page the gate passes with
+no design notes honestly receives none. The per-panel structure this ADR decided
+is unchanged; only the count is.
+
+## Consequences
+
+A dashboard costs at least N+1 rounds for N panels, and more where a user iterates
+on one panel. This is the framework's longest interaction by some margin and is
+what the tutorial's time budget is mostly spent on.
+
+The first panel has nothing to link to, so its behaviour-axis suggestion is
+necessarily a promise about panels that do not exist yet. The suggestion must name
+the panel it is preparing for, or it reads as arbitrary.
+
+The usability gate acquires a second role. It was a pass/fail check run once at the
+end; it now also generates design input mid-conversation, so its warnings need to
+be phrased for a user rather than only for a log.
diff --git a/docs/notebook-to-webapp-design.md b/docs/notebook-to-webapp-design.md
new file mode 100644
index 00000000..5e739199
--- /dev/null
+++ b/docs/notebook-to-webapp-design.md
@@ -0,0 +1,542 @@
+# Notebook → WebApp: framework design
+
+How a Jupyter notebook becomes an OpenMS Streamlit application through natural
+language. This is the design spec behind `.claude/skills/`; the user-facing
+walkthrough is `docs/notebook_to_webapp.md`.
+
+Vocabulary is fixed in [`CONTEXT.md`](../CONTEXT.md). Decisions that were close
+calls are in [`docs/adr/`](./adr/).
+
+---
+
+## The arc
+
+```
+entry prompt (copied from the app's Quickstart page)
+      │
+      ▼
+┌─────────────────────┐
+│ opening             │  clone into a neutral folder, find a Python,
+│                     │  ask which notebook, classify it STATICALLY,
+│                     │  show the layered report, ask for a name
+└─────────┬───────────┘
+          │  app identity: folder, slug, class, pages
+          ▼
+source notebook
+      │
+      ▼
+┌─────────────────────┐
+│ capture             │  classify cells, isolate processing,
+│                     │  execute source once for golden values
+└─────────┬───────────┘
+          │  src/python-tools/<name>.py   (DEFAULTS + OUTPUTS)
+          │  tests/test_<name>.py         (golden values)
+          ▼
+┌─────────────────────┐
+│ review interview    │  ONE batch pass, two sections:
+│                     │  1. demo shortcuts + suspicious constants
+│                     │  2. config parameters (sensitivity-probed)
+└─────────┬───────────┘
+          │  DEFAULTS finalized: shown / advanced / hardcoded
+          ▼
+┌─────────────────────┐
+│ scaffold            │  WorkflowManager subclass, 4 content pages,
+│                     │  app.py registration, settings.json identity
+│                     │  DESIGN ROUNDS on Upload, then Configure
+└─────────┬───────────┘
+          │  app boots, config page renders, run works
+          ▼
+┌─────────────────────┐
+│ dashboard           │  link graph → wireframe approval →
+│                     │  DESIGN ROUND per panel, against the live app
+└─────────┬───────────┘
+          │  results page of linked Insight panels
+          ▼
+┌─────────────────────┐
+│ usability gate      │  Playwright assertions + screenshot critique
+└─────────┬───────────┘
+          │  gate findings, phrased for a user
+          ▼
+    final DESIGN ROUND on the whole page, until "ship it"
+```
+
+Six skills: `notebook-to-webapp` orchestrates, and five stage skills each work
+standalone against an existing application. *"Add an Insight dashboard to my
+results page"* invokes `build-insight-dashboard` alone.
+
+**The arc is a dependency graph, not a schedule.** It is drawn as a column because
+that is the common path, but position is fixed by what a stage *consumes*: capture
+must execute before extraction, and shortcuts must be resolved before parameters
+are probed. The dashboard's link graph and wireframe read `OUTPUTS` alone — the
+handoff `capture → dashboard` skips scaffold entirely — so they may be drawn while
+the interview is still open. Only the panels need a running app. A reader given
+the orchestrator skill found this parallelisation unprompted at tick 071 and was
+marked wrong for it, because the rule said only "in order".
+
+---
+
+## The interaction model
+
+The framework talks to a user in exactly two shapes, and they are not
+interchangeable. Choosing the wrong one is the most common way to make this
+framework unpleasant to use.
+
+| | **interview** | **design round** |
+|---|---|---|
+| used when | something was measured | there is nothing to measure |
+| shape | one batch, many rows | one thing, repeated |
+| the user | adjudicates evidence | picks a direction |
+| where | capture findings, config parameters | Upload, Configure, Results |
+
+A design round is: **render it → show it → up to three suggestions, one per axis
+→ a free field → an exit → apply → re-render**. The exit is always offered; the
+user decides how many rounds something gets.
+
+**Three is a ceiling, not a quota** (tick 007). Every suggestion must point at
+something visible — except the first panel's behaviour suggestion, which by
+definition names a panel that does not exist yet. Padding to reach three teaches
+the user the list is decorative.
+On a page the gate passes with no design notes the honest output is none, said
+plainly — but only after the gate has run and the screenshot has been opened.
+
+The three axes are **data** (what is shown or accepted), **layout** (how it is
+arranged) and **behaviour** (what happens when the user acts, or before they
+have). One suggestion per axis is what makes three suggestions three genuine
+alternatives rather than three phrasings of one idea — and it is checkable, which
+matters because guidance quality is otherwise only judgeable by taste.
+
+Three principles cut across both shapes:
+
+- **Show the thing before asking about it.** A question about something the user
+  cannot see is a question they must imagine an answer to.
+- **Every fork carries a recommendation.** The user came here to be guided.
+- **Never ask for what you can determine.** The interpreter, the column types,
+  the notebook's structure — find these. Ask only what is genuinely the user's:
+  the name, what belongs on the config page, what the page should look like.
+
+Why per-panel rather than whole-page rounds, and how the objection is repaired:
+[`adr/0005`](./adr/0005-design-rounds-judge-one-panel.md).
+
+---
+
+## Shared preconditions
+
+### Environment discovery
+
+No stage may assume a particular Python. Probe in order and report the choice:
+
+1. an already-active virtualenv (`VIRTUAL_ENV`)
+2. `python` / `python3` / `py` on `PATH`, if ≥3.10
+3. a conda environment (`CONDA_PREFIX`, or `conda env list`)
+4. `uv` — create a scratch environment
+5. Docker, using `Dockerfile_simple`
+
+Report which was selected and why before doing anything that needs it.
+
+#### Verified on the development machine (2026-08-31)
+
+`python`/`python3` on `PATH` are Microsoft Store stubs, not interpreters, and
+there is no conda — so discovery selects **step 4, `uv`**. Established working
+baseline:
+
+| | |
+|---|---|
+| interpreter | `uv` → CPython 3.12.13, venv at `streamlit-template/.venv` |
+| analysis | `pyopenms 3.5.0`, `pyopenms-viz 1.0.0` |
+| app | `streamlit 1.49.1`, `numpy 1.26.4` (pin held), `pandas 2.2.3`, `pyarrow 19.0.1` |
+| dashboard | `openms-insight 0.2.0`, `polars 1.44.1` |
+| gate | `playwright 1.62.0` + Chromium 151, launches headless at 1280×800 |
+| TOPP tools | **150 binaries native on `PATH`** from `OpenMS-3.5.0-pre-FVdeploy-2026-01-29` — no Docker needed locally |
+| fallback | Docker 29.4.3, Linux containers, 24 CPU / 33 GB |
+
+**Test baseline: `pytest test_gui.py tests/` → 241 passed, 0 failed.**
+
+An earlier version of this section excused two failures as pre-existing and
+platform-specific. That excuse was withdrawn at tick 002: `test_seed_demos` passes
+all 17 of its cases, and no test named `test_storage_health` exists in the
+repository. The earlier failures were environmental, not properties of the suite.
+**No failure is one a tick is entitled to ignore** — a standing allowance to
+disregard named tests licenses dismissing a real regression that happens to land
+on one of them.
+
+### Non-interactive mode
+
+Every stage supports `mode=auto`: take the recommended answer for every interview
+row, never block. The self-improvement loop depends on this, and it is the only
+sanctioned way to skip an interview.
+
+---
+
+## Stage 1 — `capture-notebook-workflow`
+
+**In:** a source notebook. **Out:** a python tool, a golden-value test, a capture
+report.
+
+### Cell classification
+
+Every code cell gets exactly one class:
+
+| class | goes to | example from Task 2 |
+|---|---|---|
+| `setup` | dropped | `import pyopenms as oms`, version prints |
+| `input` | upload page | `wget` of `.fasta` / `.mzML`, `MzMLFile().load` |
+| `processing` | the python tool | digest, candidate search, TSG, alignment, scoring |
+| `visualization` | dashboard stage | mirror plot cell |
+| `exercise` | code dropped, **output harvested** | tolerance sweep loops, "predict first" prose |
+| `demo shortcut` | **review interview** | `candidate_df.head(5)` |
+
+Classification runs twice. The first pass is static -- AST, markdown headings,
+comment text -- and is shown for confirmation before the notebook is executed,
+because execution costs minutes and everything after is built on the split. The
+second pass refines it against the golden run's execution trace, which sees which
+branch ran and which output was empty; only what changed is reported, and a change
+is confirmed again.
+
+Both classification passes are shown for confirmation — the static one before the
+notebook is executed, and the refined one only if the trace changed anything.
+Capture is otherwise uninterrupted: every finding that needs a human is collected
+for the single review pass in stage 2, never asked about mid-run.
+
+### Isolation
+
+The emitted script imports no Streamlit, takes a JSON parameter file as `argv`,
+reads its inputs from paths, writes its outputs as files, and returns nonzero on
+failure. Notebook-local helper functions come across as functions; module-level
+statements become a `main()`.
+
+### Golden values
+
+The source notebook is executed once. Recorded per processing stage: row counts,
+column schemas, and value checksums over sorted numeric columns. These become
+fixtures. The extracted script must reproduce them exactly, or capture reports a
+transcription defect and stops.
+
+Golden values are recorded **before** demo shortcuts are resolved, so they
+describe the notebook as written. Resolving a shortcut in stage 2 re-derives them.
+
+### The output contract
+
+```python
+OUTPUTS = [
+    {"key": "psms", "file": "psms.parquet", "role": "table",
+     "id": "psm_id",
+     "columns": ["psm_id", "spectrum_idx", "peptide", "score",
+                 "n_candidates", "charge"]},
+    {"key": "matched_peaks", "file": "matched_peaks.parquet",
+     "role": "mirror", "links": {"psm": "psm_id"},
+     "columns": ["psm_id", "side", "mz", "intensity", "ion_annotation"]},
+    {"key": "fragments", "file": "fragments.parquet",
+     "role": "sequence", "links": {"psm": "psm_id"},
+     "columns": ["psm_id", "position", "residue", "b_matched", "y_matched"]},
+]
+```
+
+`role` names what the data *is*, not which component draws it — the dashboard
+stage owns that mapping. See [ADR 0002](./adr/0002-static-output-contract.md).
+
+---
+
+## Stage 2 — `interview-parameters`
+
+One batch review, two sections, presented after capture completes.
+
+### Section 1 — shortcuts and suspicious constants
+
+Every demo shortcut and every constant that looks wrong, each with a proposed
+resolution: **drop**, **promote to a config parameter**, or **keep as written**.
+
+Detection rules:
+
+- **truncations** — slices or `.head(n)` applied after a filter
+- **intent comments** — "for this tutorial / demonstration / example"
+- **discarded results** — an expression statement whose value is a call to a
+  known non-mutating method, so the line does nothing. Task 2 has a bare
+  `candidate_df.sort_values(...)` immediately before `head(5)`, which silently
+  changes *which* five spectra are analysed
+- **domain sanity** — a relative mass tolerance of 0.1 is 10%, where mass
+  spectrometry works in ppm
+
+Each shortcut is reported **with the runtime it costs**, measured from the golden
+run and extrapolated to full scale. Whether to drop a truncation depends on what
+the corrected parameters cost, so the number has to be on the screen when the
+decision is made.
+
+This section comes first because dropping a truncation changes the scale
+everything else is measured at.
+
+### Section 2 — config parameters
+
+Candidates ranked by provenance:
+
+1. named constants and default arguments (`missed_cleavages=2`)
+2. `setValue` arguments (`tolerance`, `add_y_ions`)
+3. inline literals
+4. parameters of the underlying algorithm the notebook never touched
+
+Tiers 1–2 are shortlisted and **probed**: re-run the processing step on a
+downsampled input with each numeric parameter perturbed, and report the measured
+effect on the outputs.
+
+**A parameter that probes as inert is never recommended `hardcode` on that
+evidence alone.** It must first be re-probed with each other numeric parameter
+driven to its neutral value. If its effect appears under some setting of another,
+the finding is *masking*: report the interaction and keep both.
+
+This rule exists because the naive version fails on the hero example. Task 2's
+`absolute_tolerance` moves candidate counts by 0.7% as shipped — because
+`relative_tolerance=0.1` opens a ±169 Da window that swamps it — yet it is the
+most important parameter in the notebook. Inert-in-isolation and genuinely-inert
+are different findings and must not share a recommendation. Evidence:
+[`eval/baseline-task2.md`](../eval/baseline-task2.md).
+
+Each row resolves to one of: **shown**, **advanced** (`"advanced": True`),
+**hardcoded** (absent from `DEFAULTS`), or **dashboard control** (a display-time
+choice, handed to stage 4).
+
+A widget type is proposed with each kept parameter. Anything intended to be
+driven by a preset gets an **explicit** `widget_type` — auto-typed numeric,
+selectbox and multiselect widgets double-prefix their session key, and presets
+silently fail to apply to them.
+
+---
+
+## Stage 3 — `scaffold-workflow-app`
+
+Generates the `WorkflowManager` subclass, four content pages, `app.py`
+registration, and application identity in `settings.json`.
+
+Non-negotiables, each a known way to produce a silently broken app:
+
+- `execution()` is annotated `-> bool` and returns `True` only when every step
+  succeeded; every `run_python()` call is gated on its return value.
+- `page_setup()` runs before the workflow object is constructed.
+- `configure()` and `results()` are decorated `@st.fragment`.
+- Anything reachable from `execution()` is free of `st.session_state` — in online
+  mode it runs inside an RQ worker that has none.
+- `get_files()` raises on an empty list; the user's selection is guarded first.
+- The workflow slug is chosen once and never changed.
+
+Sits beside `create-workflow` and `create-page`, which remain loadable
+skills for their own routes; this stage is the path for a *captured* python tool.
+
+---
+
+## Stage 4 — `build-insight-dashboard`
+
+### Step 1 — link graph
+
+Derived from the output contract. Each output's `role` maps to a component; each
+`links` entry becomes a link identifier. Components with no matching output are
+skipped explicitly rather than silently.
+
+```
+psms.parquet          → Table         sets    'psm'
+matched_peaks.parquet → MirrorPlot    filters 'psm'
+fragments.parquet     → SequenceView  filters 'psm'
+```
+
+When no Insight component fits a role, fall back to pyopenms-viz through
+`show_fig()` and say so in the wireframe — a fallback is a design decision the
+user should see, not a silent substitution.
+
+### Step 2 — wireframe
+
+Approved **before any code is written**. Shows placement, sizes, what each panel
+sets and what it filters on.
+
+### Step 3 — panels, one design round each
+
+One panel at a time against the running app. Chrome is driven directly here so
+the model sees the page as it is designed, and each panel gets a design round —
+screenshot, up to three suggestions on data / layout / behaviour, a free field, an exit
+— before the next panel is built.
+
+The first panel has nothing to link to, so its behaviour suggestion is necessarily
+a promise about a panel that does not exist yet. It must name that panel, or it
+reads as arbitrary.
+
+Streamlit does not re-import an already-imported `src/` module, so applying a
+suggestion requires a server restart. Skipping it shows the user the panel they
+just changed, unchanged, and they conclude the framework ignored them.
+
+### Step 4 — the final round, on the whole page
+
+Per-panel rounds cannot see what only exists once everything is on screen: the
+summary strip, column ratios between panels, one colour meaning one thing
+throughout, and what the page looks like before anything is selected — the state
+every user sees first and the one built last.
+
+So the gate runs *before* the last round, and its findings become that round's
+suggestions. Repeats until the user ships it. See
+[`adr/0005`](./adr/0005-design-rounds-judge-one-panel.md).
+
+### Style contract
+
+Applied here, enforced in stage 5:
+
+**Layout** — a summary strip of 3–5 headline numbers first; no panel taller than
+the viewport; column ratios follow panel role, never a default even split.
+
+**Semantics** — one colour per concept, identical in every panel (b-ions blue,
+y-ions red, unmatched grey); axis labels carry units and never expose a raw
+column name (`mz` → `m/z`, `rt` → `Retention time (s)`).
+
+**States** — nothing-selected shows an instruction, not a blank; no-results-yet
+points at the Run page; a traceback never reaches the UI.
+
+**Theme** — primary, secondary and font set in `.streamlit/config.toml`.
+
+---
+
+## Stage 5 — `verify-webapp-usability`
+
+Headless Playwright at 1280×800. Hard assertions:
+
+- page boots with no Python traceback
+- browser console has zero errors
+- every declared panel renders with real width and height (*vertical* placement
+  is not asserted: below-the-fold is a design note, not a failure)
+- each component iframe is non-empty and reports the expected row count
+- **no panel is stuck loading** — a panel filtering on a link identifier nothing
+  sets and no `filter_defaults` covers shows "Loading…" forever while passing
+  every other assertion: real iframe size, clean console, nothing thrown. The
+  gate reads inside each iframe after settling and fails on a panel whose entire
+  content is a placeholder
+- clicking a row in the master panel changes the linked panels' payloads
+- no horizontal scrollbar
+- first paint within budget
+
+Then a screenshot the model critiques against the style contract. Assertions
+catch breakage; the critique catches ugliness. Both are recorded.
+
+**The gate has a second job.** Run before the dashboard's final design round, it
+also emits *design notes* — panels below the fold, a missing summary strip, a
+column header with no slack left. These are observations rather than failures, and they are
+written to be read by a user, not by a log.
+
+Kept as a permanent gate in `tests/`. AppTest is retained for what it can still
+see — see [ADR 0003](./adr/0003-browser-verification-for-insight-pages.md).
+
+---
+
+## The tutorial
+
+`docs/notebook_to_webapp.md`, single-sourced into the in-app documentation page.
+Registering it means editing the `pages` list in `content/documentation.py` **and**
+the `test_documentation` parametrize list in `test_gui.py`, or CI breaks.
+
+Hands-on, full scope, built on `EUBIC_Task2_ID.ipynb`. Roughly two screens of
+prose: a prerequisites check, then the stages, each with a "you should now see
+this" checkpoint and a tag to jump to if the reader's machine fails them.
+
+It starts at the **Quickstart page**, not at a slash command — the entry prompt is
+the real front door, and a tutorial that starts anywhere else documents a path
+nobody takes.
+
+**One round per kind, not one per page.** Rounds are the framework's longest
+interaction by a wide margin, and the tutorial's budget is thirty minutes. It
+walks three in full — a page round on Configure, a panel round on the first
+panel, and the whole-page round the gate feeds — because each differs from the
+others in a way a reader has to see. It then states that Upload and the remaining
+panels work identically rather than showing them. The cap belongs on the
+tutorial, not on the framework.
+
+### Why Task 2 is the hero example
+
+It maps onto OpenMS-Insight almost exactly — the notebook's payoff is a mirror
+plot of observed against theoretical spectra with b/y ion annotations, and
+Insight ships `MirrorPlot` and `SequenceView` for precisely that. The parameter
+surface is rich (`missed_cleavages`, peptide length bounds, enzyme, precursor
+tolerance, ion-type toggles, alignment tolerance). Cell 22 is *already* a
+sensitivity sweep over the precursor tolerance, so the probe has ground truth
+handed to it. And it carries two real traps — a `head(5)` demo truncation and a
+`relative_tolerance=0.1` that means 10% — which make the review interview
+demonstrably worth doing.
+
+Output lands in a sibling directory (`../eubic-id-app`), cloned from the template,
+so the template checkout stays clean and the result is a real standalone app.
+
+---
+
+## The self-improvement loop
+
+Driven by `/loop` with no interval — ticks cost real compute and pace themselves.
+
+### Each tick
+
+1. Run the corpus headless and score artifacts. A drop stops the tick.
+2. Run the framework end to end under a persona (below), saving the transcript.
+3. Pick the single worst moment in that transcript.
+4. Make **one** skill edit.
+5. Re-run the same persona, saving the new transcript.
+6. Judge the two transcripts blind. One persona is judged per tick by default, so
+   its verdict is the tick's verdict; a tie counts against the edit. Where a tick
+   judges several personas — worth doing for a change that touches every
+   stage — a majority is required, and a split is a revert.
+7. All corpus notebooks above threshold → add a notebook by a different author.
+
+Stop after three consecutive ticks with no commit, and report the plateau rather
+than churning.
+
+### Two measurements, measured differently
+
+**Artifacts** — capture split accepted, golden values reproduced, tests pass, app
+boots, panels built vs. planned, usability gate result, minus human fixes. Scored
+numerically by `eval/run_eval.py`. These are **saturated at 1.00** across the
+current corpus and no longer discriminate between skill edits; they are retained
+as the regression guard, which has already caught one broken harness.
+
+**Guidance** — how well the skill guided its user. Has no absolute scale. Judged
+by `eval/judge.py`, which shuffles the before-edit and after-edit transcripts into
+X and Y, hides the mapping, and asks a judge which guided better and why. The
+reason is as valuable as the verdict: it names the next tick's edit, which a
+number never does.
+
+An absolute rubric was rejected because it varies by roughly ±0.4 on a 5-point
+scale between reruns of an *unchanged* skill — larger than a typical skill edit's
+effect, so a ratchet built on it keeps edits that changed nothing, invisibly. See
+[`adr/0004`](./adr/0004-guidance-is-judged-pairwise.md).
+
+The judge must not be the context that made the edit. Blindness is enforced
+mechanically as far as it can be — separate key file, revealed only on `record` —
+but nothing stops a judge opening it, so this is finally a discipline.
+
+### Personas
+
+Auto-accept alone would only ever measure code generation — the interviews and
+design rounds, which are the product, would go unmeasured. So ticks rotate a
+persona:
+
+| persona | behaviour | measures |
+|---|---|---|
+| `auto` | takes every recommendation and first suggestion | baseline generation quality |
+| `sceptic` | rejects the first split, demands a redo | does it re-derive or repeat itself? |
+| `novice` | asks what a term means | does it explain, or restate the question? |
+| `expert` | wants the full algorithm surface exposed | does it degrade gracefully? |
+| `minimal` | wants two parameters, everything else hidden | does it respect a hard constraint? |
+| `designer` | rejects all three suggestions, always uses the free field | are the axes real, or only its own ideas handled? |
+
+`designer` exists because the design round is the newest mechanism in the
+framework and the free field is the part most likely to be handled badly.
+
+### Corpus
+
+Starts at EuBIC Task 1, Task 2, Task 3. Grows when all members clear threshold —
+the guard against tuning the skills into three notebooks by one author.
+
+### Artifacts
+
+`eval/scores.jsonl` holds one row per tick; `eval/tick-NNN/` holds that tick's
+screenshots, transcripts and diff.
+
+---
+
+## Assumptions
+
+- One source notebook produces one captured workflow. Running the orchestrator
+  again adds a second workflow to the same app.
+- OpenMS-Insight becomes a dependency of generated apps. It is not, and does not
+  become, a dependency of the template itself.
+- The eight existing flat `.claude/skills/*.md` playbooks are converted to real
+  loadable skills as part of this work — with no frontmatter and no directory,
+  nothing currently surfaces them.
diff --git a/docs/notebook_to_webapp.md b/docs/notebook_to_webapp.md
new file mode 100644
index 00000000..ed93c7d7
--- /dev/null
+++ b/docs/notebook_to_webapp.md
@@ -0,0 +1,317 @@
+# From notebook to web app
+
+Turn a Jupyter notebook into a working OpenMS web app by describing what you
+want. This walkthrough converts the EuBIC winter-school identification notebook
+(`EUBIC_Task2_ID.ipynb`) into an app with a configuration page you chose and a
+results dashboard you designed.
+
+**Time:** about 30 minutes. **You need:** a notebook, `git`, **Claude Code**, and a
+Python 3.10+ environment. If you have none, `uv` is enough — the framework finds
+whatever is there and tells you what it picked.
+
+---
+
+## What you are building
+
+```
+notebook cell                    becomes
+
+  digest, search, score    ->    src/python-tools/identify.py
+                                 a script with no Streamlit, tested on its own
+
+  the constants in it      ->    a configuration page you designed
+
+  the mirror plot          ->    a results dashboard where clicking a
+                                 peptide shows its annotated spectrum
+```
+
+---
+
+## 0. Start
+
+Go to the **Quickstart** page of this app, copy the prompt under *Turn a Jupyter
+notebook into an app*, and paste it into your terminal. It works from anywhere —
+it will ask you where the notebook is. Nothing else is needed — the prompt clones the template and
+points the agent at the framework.
+
+**Checkpoint:** it names the Python interpreter it found, and a temporary folder
+it cloned into — the app is not named yet, so the folder gets its real name in the
+next step.
+
+---
+
+## 1. Choose, analyse, name
+
+Three quick exchanges before any real work starts.
+
+It asks for the path to your notebook — it does not go looking through your
+folders. Then it reads that notebook, **without running it**, and tells you how it
+read your analysis:
+
+```
+EUBIC_Task2_ID.ipynb — here is how I read it:
+
+  loads an mzML and a FASTA                  ->  Upload page
+  digests the proteins                       ->  the analysis
+  generates theoretical spectra              ->  the analysis
+  matches them to the measured spectra       ->  the analysis
+  plots one mirror spectrum                  ->  Results page
+  a tolerance exercise at the end            ->  dropped, but I'll reuse
+                                                 the numbers it printed
+
+Look right? Then I'll run it once and come back with what needs deciding.
+```
+
+Rows are steps of your analysis, not cells — you should not have to count cells to
+follow your own notebook. No row counts and no runtimes appear here, because
+nothing has been executed yet. Ask if you want it cell by cell.
+
+Then it asks what to call the app. Everything else is derived from your answer —
+the folder (the temporary clone is renamed now, before the app is ever launched),
+the workflow class, the slug, the page titles — so this is the one name you pick
+and it is picked once.
+
+**Checkpoint:** the app folder is named after your app, and you have seen what it
+thinks the notebook does.
+
+---
+
+## 2. Capture
+
+The notebook is executed once, unmodified, and the reading is checked against what
+actually ran. You see progress, not bookkeeping:
+
+```
+Running it once for reference numbers... (3.9s)
+Extracting the analysis... testing it against your notebook... 7/7 OK
+```
+
+Executing first is the point: the numbers the notebook printed become the test
+the extracted script must reproduce. Here that is 473 peptides, 1887 MS2 spectra,
+and five specific peptide-spectrum matches.
+
+**Checkpoint:** `src/python-tools/identify.py` exists and its test passes. The
+script imports no Streamlit — you can run it from a terminal.
+
+---
+
+## 3. Review
+
+Two batches, each arriving **already decided** — every row carries the
+recommendation the framework would act on, so your job is unticking, not choosing
+from a blank page.
+
+**Shortcuts and suspicious constants** — code written for teaching, not analysis.
+Each one quotes your line, says where it is, and says what it would do:
+
+```
+Your notebook analyses only the first 5 of 1887 spectra — `candidate_df.head(5)`,
+cell 20. Remove that for the app?        (recommended: yes — the full run takes 4 s)
+
+The sort just above it, `candidate_df.sort_values(...)`, throws its result away,
+so head(5) takes the first five spectra and not the top five. Remove it?   (yes)
+
+`relative_tolerance=0.1`, cell 19: np.isclose reads that as 10%, roughly ±169 Da
+on a typical peptide, where MS works in ppm. Deliberate, or a typo?   (10 ppm)
+```
+
+**Config parameters** — the whole list, ranked by where each value came from in
+your code, with the ones a mass spectrometrist would expose already ticked:
+
+```
+These are the settings I'd give the app's users.
+Untick anything you'd rather fix at the notebook's value.
+
+  [x] precursor mass tolerance   10 ppm     main specificity control
+  [x] fragment mass tolerance    0.05 Da    same, at the MS2 level
+  [x] missed cleavages           2
+  [x] peptide length             6-30
+  [ ] enzyme                     Trypsin    rarely changed per run
+  [ ] fixed modifications        none
+
+  The two tolerances interact — if you keep one, keep both.
+
+  Want me to measure how much each one actually moves the result
+  before you decide? (~90 s)
+```
+
+That last offer is optional on purpose. Measuring every parameter properly is
+quadratic — a dozen of them is minutes, forty is hours — and it is only ever
+needed to justify *hiding* something. **An unmeasured setting can be shown, never
+hidden**: showing one that turns out not to matter costs a row on a page, hiding
+one that does costs you something you cannot see was taken.
+
+The two tolerances are why that rule exists. Swept on its own the absolute
+tolerance moves the result by 0.7% and looks useless — because the relative
+tolerance opens a window 1700 times wider and swamps it. A tool that measured one
+parameter at a time would tell you to hardcode the most important setting in your
+notebook. Ranking by where the value came from puts it first without measuring
+anything at all.
+
+Fixing that tolerance is also what makes the app practical: at 10 ppm the search
+runs over all 1887 spectra in under a second and identifies 94 of them — instead
+of five spectra carrying 57 spurious candidates each. That 94 is the number the
+results page reports.
+
+**Checkpoint:** `DEFAULTS` reflects your decisions and the tests still pass
+against re-derived values.
+
+---
+
+## 4. Design the pages
+
+Now the shape changes. From here the framework stops presenting tables and starts
+**building things with you, one at a time**. Every round works the same way:
+
+> it puts something on screen **in your own browser**, offers up to three
+> suggestions — one about the **data**, one about the **layout**, one about the
+> **behaviour** — plus a field for your own idea, and an exit.
+
+One suggestion per axis, deliberately: three variations on the same idea would
+not be a choice. And **three is a ceiling, not a quota** — every suggestion has to
+point at something you can see on screen, so if only two axes have anything real
+to say you get two, and if the page is already good you get told so and offered
+the exit. The one exception is the very first panel: it has nothing to link to
+yet, so its behaviour suggestion is a promise about a panel still to come, and it
+says which one.
+
+Before the first round it runs your app once end to end with your notebook's own
+data — upload, configure, run, results — so nothing you are asked to look at is
+empty or broken. Then it opens your browser on it.
+
+```
+Starting the app and doing a test run with your notebook's own data...
+  upload -> configure -> run -> results    OK (11s)
+
+Your app is running at http://localhost:8501 - opening it now.
+```
+
+The Upload and Configure pages come first. Here is one round on Configure:
+
+```
+[your browser, on the Configure page]
+
+  A  data       Order the parameters the way they matter — precursor
+                tolerance outranks missed cleavages, but sits below
+                it on screen
+  B  layout     Seven inputs in one column reads as a form. Two
+                columns fits without scrolling
+  C  behaviour  Save these values as a preset called "Notebook
+                defaults", so there is a way back
+
+  D  something else — tell me
+
+  or: looks good, next
+```
+
+Pick one, and it re-renders and asks again. Take the exit whenever you are happy.
+**The Upload page works identically** — the same three axes, asking about file
+types, grouping, and what the page shows before anything is uploaded.
+
+**Checkpoint:** `streamlit run app.py` starts, and Configure looks the way you
+chose.
+
+---
+
+## 5. Design the dashboard
+
+Same rounds, now per panel. First the link graph and a wireframe, before any code
+exists:
+
+```
+ psms.parquet          -> Table        click sets 'psm'
+ mirror_peaks.parquet  -> MirrorPlot   filters on 'psm'
+
+ +--------------------------------------------------+
+ | Peptide-spectrum matches            (Table)      |
+ +--------------------------------------------------+
+ | Spectrum match                 (MirrorPlot)      |
+ |   observed above / theoretical below             |
+ +--------------------------------------------------+
+```
+
+Then one panel is built, and you get a round on it:
+
+```
+[your browser, showing the match table]
+
+Panel 1 of 2 — the match table.
+
+  A  data       Show the charge column — you have it, and it explains
+                why two matches score differently
+  B  layout     The "Matched intensity" header is cut to "Matched i…"
+                at the width this column has — shorten it, or take
+                40px from the score column
+  C  behaviour  Make a row click select the match, so the mirror plot
+                below follows your selection
+
+  D  something else — tell me
+
+  or: looks good, next
+```
+
+Notice that C names the panel it is preparing for. The first panel has nothing to
+link to yet, so a behaviour suggestion there is always a promise about something
+you have not seen.
+
+**Checkpoint:** clicking a row in the table changes the spectrum below it.
+
+---
+
+## 6. The last round
+
+When every panel is approved, the page is exercised in a real browser before the
+final round — it boots, the console is clean, every panel rendered, nothing sits
+stuck loading, and clicking a row moves the panel linked to it. You never see that
+check run. You see what it found, as the last round:
+
+```
+  A  data       Summary strip on top: 94 identified · best score 30 ·
+                median 13
+  B  layout     The mirror plot is taller than the fold; 520px puts
+                both panels on one screen
+  C  behaviour  Nothing is selected on arrival, so the mirror plot is
+                empty — default to the top-scoring match
+
+  D  something else       or: ship it
+```
+
+This step is not optional theatre. Streamlit's own test tools execute no
+JavaScript, so a dashboard whose every panel fails to render passes them
+completely. And the page is *looked at*, not only asserted on, because no
+assertion catches a truncated column header or half a mirror plot flattened onto
+the baseline — both real defects from building this app, both invisible to every
+check above.
+
+**Checkpoint:** the page works, and you have signed off on how it looks.
+
+---
+
+## What you end up with
+
+```
+eubic-id-app/
+  src/python-tools/identify.py     tested, Streamlit-free processing
+  src/IdentificationWorkflow.py    upload / configure / run / results
+  src/dashboards/identification.py the linked panels
+  content/identification_*.py      four pages
+  tests/test_identify.py           your notebook's own numbers
+```
+
+The processing step runs from a terminal, in the app, or on a queue, and it is
+the same code in all three.
+
+## If a stage fails
+
+Each stage leaves its artifact behind, so you can rerun one without redoing the
+others. `interview-parameters`, `build-insight-dashboard` and
+`verify-webapp-usability` all work standalone against an existing app — you can
+point the dashboard builder at a results page you wrote by hand.
+
+## Going further
+
+- Add a second notebook: paste the prompt again inside the app; it adds another
+  workflow rather than merging into the first.
+- Change your mind about a panel: ask for another round on it.
+- Change your mind about a parameter: rerun `interview-parameters`.
+- Deploy: see the Deployment and Kubernetes guides.
diff --git a/src/Workflow.py b/src/Workflow.py
index f172f267..d703efe7 100644
--- a/src/Workflow.py
+++ b/src/Workflow.py
@@ -18,6 +18,13 @@
     'example-data/tnt/example_native_antibody.mzML',
 ]
 
+# Valueless TOPP switches (registerFlag_ in the tool source), emitted as a bare
+# "-name" when on and omitted when off. Every other parameter is passed with its
+# value, so true/false string parameters such as iq:isotope_correction keep an
+# explicit "false".
+FLASHDECONV_FLAGS = ['keep_empty_out', 'write_detail']
+FLASHTNT_FLAGS = ['only_single_hit', 'discard_underdetermined', 'keep_decoy']
+
 class TagWorkflow(WorkflowManager):
     share_cache = True
 
@@ -64,7 +71,8 @@ def configure(self) -> None:
                     'reporter_mz_tol', 'only_fully_quantified'
                 ],
                 display_subsections=True,
-                display_tool_name=False
+                display_tool_name=False,
+                flag_parameters=FLASHDECONV_FLAGS,
             )
         with t[1]:
             # FLASHTnT Configuration
@@ -73,6 +81,7 @@ def configure(self) -> None:
                 display_subsections=True,
                 display_tool_name=False,
                 custom_defaults={'tag:min_length': 4, 'tag:max_length': 4},
+                flag_parameters=FLASHTNT_FLAGS,
             )
 
 
@@ -281,6 +290,7 @@ def configure(self) -> None:
         # FLASHDeconv Configuration
         self.ui.input_TOPP(
             'FLASHDeconv', exclude_parameters = ['ida_log'], display_subsections=True,
+            flag_parameters=FLASHDECONV_FLAGS,
         )
 
 
diff --git a/src/common/common.py b/src/common/common.py
index 411b4d82..e8788ee9 100644
--- a/src/common/common.py
+++ b/src/common/common.py
@@ -5,6 +5,7 @@
 import time
 import psutil
 import shutil
+import logging
 
 import pandas as pd
 import streamlit as st
@@ -28,6 +29,8 @@
     save_workspace_as_demo,
 )
 
+logger = logging.getLogger(__name__)
+
 # Detect system platform
 OS_PLATFORM = sys.platform
 
@@ -216,6 +219,17 @@ def copy_demo_workspace(demo_name: str, target_path: Path) -> bool:
 
 @st.fragment(run_every=5)
 def monitor_hardware():
+    """
+    Display CPU and RAM of the machine running this Streamlit process.
+
+    Gated by the caller on where the workflows actually run, not on
+    `online_deployment`: in Kubernetes psutil here reports a Streamlit pod that
+    does no work, and an idle 2Gi container shown while a 64Gi worker saturates
+    is worse than showing nothing. In the single-container images - the full
+    one under docker-compose, and `Dockerfile_simple`, which has no queue at
+    all - this process and the workflows share a machine and these are the only
+    numbers that expander has. See `health.queue_workers_are_remote()`.
+    """
     cpu_progress = psutil.cpu_percent(interval=None) / 100
     ram_progress = 1 - psutil.virtual_memory().available / psutil.virtual_memory().total
 
@@ -272,6 +286,106 @@ def monitor_queue():
         pass  # Silently fail if queue not available
 
 
+@st.fragment(run_every=5)
+def monitor_storage():
+    """
+    Display shared storage status in sidebar.
+
+    Reads Redis and nothing else. The workspace volume is a shared NFS mount
+    online, and its failure mode is a hang rather than an error: a `stat` on a
+    `hard` mount that has wedged blocks in uninterruptible sleep and cannot be
+    killed, so a fragment re-running every 5 seconds would accumulate unkillable
+    threads - this indicator would become the very hang it exists to report.
+    The mount is touched by the rq-worker readiness probe instead, which
+    publishes a per node heartbeat whose Redis TTL is the liveness mechanism.
+
+    Renders nothing where no node publishes a heartbeat at all - local mode,
+    docker-compose, apptainer - because a red tick for a mechanism that is not
+    deployed is a false alarm pointing at the wrong layer.
+    """
+    try:
+        from src.workflow.health import get_storage_status
+
+        status = get_storage_status()
+        if not status:
+            return
+
+        state = status.get("state", "unknown")
+        nodes = status.get("nodes") or []
+        stale = status.get("stale_nodes") or []
+
+        st.markdown("---")
+        st.markdown("**Storage Status**")
+
+        if state == "connected":
+            st.markdown(":green[Connected]")
+            st.caption(
+                f"{len(nodes)} node{'' if len(nodes) == 1 else 's'} reporting a "
+                "healthy shared volume."
+            )
+        elif state == "degraded":
+            # The case per node heartbeats exist for. Collapsing them would
+            # show green here, because a healthy node is still reporting.
+            st.markdown(":orange[Degraded]")
+            st.caption(
+                f"{', '.join(stale)} stopped confirming the shared volume. "
+                "Workflows running there may be stalled; other nodes are fine."
+            )
+        elif state == "unreachable":
+            st.markdown(":red[Unreachable]")
+            st.caption(
+                "No node has confirmed the shared volume recently. Running "
+                "workflows may be stalled and new results may not appear."
+            )
+        else:
+            # Redis is down, which says nothing about the mount. Showing this as
+            # unreachable storage would send an operator to the wrong layer.
+            st.markdown(":gray[Unknown]")
+            st.caption("Cannot reach the queue, so storage status is unknown.")
+
+        st.caption(f"Last fetched at: {time.strftime('%H:%M:%S')}")
+
+    except Exception:
+        # Never break the sidebar over an indicator, but never swallow it in
+        # silence either: a broken indicator that renders nothing is
+        # indistinguishable from a deployment that has no shared storage.
+        logger.exception("Could not render the shared storage indicator")
+
+
+def render_resource_utilization():
+    """
+    Render the sidebar's "Resource Utilization" expander.
+
+    Extracted from `render_sidebar()` so the choice of panels is reachable
+    without standing up a whole session (tests/test_sidebar_monitors.py).
+
+    Which panels apply is a question about the deployment, and the three
+    answers do not line up with `online_deployment`:
+
+    - Kubernetes: the queue and the shared volume are what a user's job waits
+      on, and psutil here would describe a Streamlit pod that runs nothing.
+    - Full image under docker/docker-compose: one container runs Redis, the RQ
+      workers and Streamlit, so all three panels describe the same machine.
+    - `Dockerfile_simple`: `online_deployment` is baked true but there is no
+      Redis and no queue, so the psutil panel is the only content there is.
+      Gating it on `online_deployment` left the expander empty.
+    """
+    from src.workflow.health import get_queue_metrics, queue_workers_are_remote
+
+    with st.expander("📊 **Resource Utilization**"):
+        # `{}` means "no queue in this deployment" - the same distinction
+        # get_queue_metrics() already draws for the metrics themselves.
+        metrics = get_queue_metrics()
+        if metrics:
+            monitor_queue()
+            monitor_storage()
+        # Short-circuited on `available`: an unreachable queue is not evidence
+        # that the workers are elsewhere, and this saves the second round trip
+        # in exactly the case where Redis is slow to answer.
+        if not (metrics.get("available") and queue_workers_are_remote()):
+            monitor_hardware()
+
+
 def load_params(default: bool = False) -> dict[str, Any]:
     """
     Load parameters from a JSON file and return a dictionary containing them.
@@ -795,11 +909,7 @@ def change_workspace():
             else:
                 st.session_state["spectrum_num_bins"] = 50
 
-        with st.expander("📊 **Resource Utilization**"):
-            monitor_hardware()
-            # Show queue metrics in online mode
-            if st.session_state.settings.get("online_deployment", False):
-                monitor_queue()
+        render_resource_utilization()
 
         # Display OpenMS WebApp Template Version from settings.json
         with st.container():
diff --git a/src/render/compression.py b/src/render/compression.py
index f42576b4..805b75b4 100644
--- a/src/render/compression.py
+++ b/src/render/compression.py
@@ -60,7 +60,7 @@ def downsample_heatmap(data, max_datapoints=20000, rt_bins=400, mz_bins=50, logg
         return data
     
     # Count peaks
-    total_count = sorted_data.select(pl.count()).item()
+    total_count = sorted_data.select(pl.len()).item()
     
     # Extract arrays for scipy
     mass_array = sorted_data['mass'].to_numpy()
diff --git a/src/workflow/CommandExecutor.py b/src/workflow/CommandExecutor.py
index 9b4f898e..38412c82 100644
--- a/src/workflow/CommandExecutor.py
+++ b/src/workflow/CommandExecutor.py
@@ -6,6 +6,7 @@
 from pathlib import Path
 from .Logger import Logger
 from .ParameterManager import ParameterManager, bool_param_paths_from_param_xml_ini
+from .settings_io import load_settings, detect_cpu_quota
 import sys
 import importlib.util
 import json
@@ -25,28 +26,73 @@ def __init__(self, workflow_dir: Path, logger: Logger, parameter_manager: Parame
         self.pid_dir = Path(workflow_dir, "pids")
         self.logger = logger
         self.parameter_manager = parameter_manager
+        # Memoised thread budget, resolved lazily by _get_max_threads().
+        self._max_threads = None
 
     def _get_max_threads(self) -> int:
         """
         Get max threads for current deployment mode.
 
-        In local mode, reads from parameter manager (persisted params.json).
-        In online mode, uses the configured value directly from settings.
+        Settings are read from settings.json on disk, not from
+        st.session_state: inside the RQ work horse there is no
+        ScriptRunContext, so st.session_state is an empty mock, the online
+        branch was unreachable and the hardcoded local default silently won
+        instead of max_threads.online.
+
+        In local mode the workspace params.json may override the configured
+        value - that is what the "Threads" widget writes, and it is only
+        rendered in local mode. Online the worker is shared and sized by its
+        pod spec, so user supplied params.json is ignored.
+
+        Online the container's own cgroup CPU quota wins over
+        max_threads.online where one exists. The rq-worker runs at
+        requests.cpu == limits.cpu, so its pod spec IS its allocation, and the
+        memory-tier components size that per deployment - a 4 cpu worker and a
+        20 cpu worker cannot both be described by one number in settings.json,
+        and the number that was there described neither. max_threads.online
+        remains the fallback for every deployment where no quota is readable:
+        bare metal, docker-compose without a cpu limit, a dev box.
+
+        The trade-off, deliberately taken: an operator can no longer
+        under-subscribe a container that declares more CPU than it wants used.
+        For a Guaranteed pod that is the right call, because the declaration
+        and the allocation are the same thing.
+
+        The result is memoised for the lifetime of this executor: run_topp()
+        consults it twice, once for its own thread split and once more inside
+        run_multiple_commands(), and the two must agree.
 
         Returns:
             int: Maximum number of threads to use for parallel processing (minimum 1).
         """
-        settings = st.session_state.get("settings", {})
+        if self._max_threads is not None:
+            return self._max_threads
+
+        settings = load_settings()
         max_threads_config = settings.get("max_threads", {"local": 4, "online": 2})
 
         if settings.get("online_deployment", False):
-            value = max_threads_config.get("online", 2)
+            quota = detect_cpu_quota()
+            if quota is not None:
+                value = quota
+            else:
+                value = max_threads_config.get("online", 2)
         else:
             default = max_threads_config.get("local", 4)
             params = self.parameter_manager.get_parameters_from_json()
             value = params.get("max_threads", default)
 
-        return max(1, int(value))
+        try:
+            value = int(value)
+        except (TypeError, ValueError):
+            # params.json is user supplied - the parameter import uploader
+            # writes it verbatim - so a non numeric thread budget degrades to
+            # serial execution instead of taking the whole run down.
+            self.logger.log(f"Invalid max_threads value {value!r}, falling back to 1.", 1)
+            value = 1
+
+        self._max_threads = max(1, value)
+        return self._max_threads
 
     def run_multiple_commands(
         self, commands: list[str]
@@ -234,10 +280,9 @@ def run_topp(self, tool: str, input_output: dict, custom_params: dict = {}, tool
             tool (str): The executable name or path of the tool.
             input_output (dict): A dictionary specifying the input/output parameter names (as key) and their corresponding file paths (as value).
             custom_params (dict): A dictionary of custom parameters to pass to the tool.
-            tool_instance_name (str, optional): Key for ``params.json`` when it differs
-                from ``tool`` (e.g. multiple instances). Defaults to ``tool``.
-            Custom parameters whose keys appear in the tool's ParamXML ``type="bool"``
-            entries are passed as valueless CLI flags (``-name`` only when enabled).
+            tool_instance_name (str, optional): A unique instance name for this tool
+                invocation, used for parameter lookup when multiple instances of the
+                same tool exist. If not provided, defaults to the tool name.
 
         Returns:
             bool: True if all commands succeeded, False if any failed.
@@ -246,6 +291,8 @@ def run_topp(self, tool: str, input_output: dict, custom_params: dict = {}, tool
             ValueError: If the lengths of input/output file lists are inconsistent,
                         except for single string inputs.
         """
+        # Use tool_instance_name for parameter lookup, fall back to tool name
+        params_key = tool_instance_name if tool_instance_name else tool
         # check input: any input lists must be same length, other items can be a single string
         # e.g. input_mzML : [list of n mzML files], output_featureXML : [list of n featureXML files], input_database : database.tsv
         io_lengths = [len(v) for v in input_output.values() if len(v) > 1]
@@ -265,15 +312,17 @@ def run_topp(self, tool: str, input_output: dict, custom_params: dict = {}, tool
 
         commands = []
 
-        params = self.parameter_manager.get_parameters_from_json()
+        # Load merged parameters (_defaults + user overrides) for this tool instance
+        merged_params = self.parameter_manager.get_merged_params(params_key)
+
+        # Load flag parameter names: params.json takes priority (survives session restart),
+        # session_state is the live fallback during the current session.
+        flag_map = self.parameter_manager.get_parameters_from_json().get("_flag_params", {})
+        flag_list = flag_map.get(params_key)
+        if flag_list is None:
+            flag_list = st.session_state.get("_topp_flag_params", {}).get(params_key, [])
+        flag_params: set = set(flag_list)
 
-        topp_tool_ini_path = Path(self.parameter_manager.ini_dir, f"{tool}.ini")
-        # Keys of type="bool" in the .ini: TOPP treats these as on/off flags (omit value when off)
-        topp_bool_flag_param_keys = (
-            bool_param_paths_from_param_xml_ini(topp_tool_ini_path, tool)
-            if topp_tool_ini_path.exists()
-            else set()
-        )
         # Construct commands for each process
         for i in range(n_processes):
             command = [tool]
@@ -292,59 +341,48 @@ def run_topp(self, tool: str, input_output: dict, custom_params: dict = {}, tool
                 # standard case, files was a list of strings, take the file name at index
                 else:
                     command += [value[i]]
-            # Add non-default TOPP tool parameters
-            if tool in params.keys():
-                for k, v in params[tool].items():
-                    # Boolean flag handling. A parameter is emitted as a
-                    # valueless TOPP on/off flag when EITHER the tool's ParamXML
-                    # .ini marks the key type="bool" (upstream key-based
-                    # detection via topp_bool_flag_param_keys) OR the stored
-                    # value is itself boolean. The value-based branch is the
-                    # fallback FLASHApp relies on: checkbox widgets persist a
-                    # Python bool (True/False) to params.json, and pyOpenMS /
-                    # presets may surface the 'true'/'false' string form. This
-                    # keeps flags correct even when the .ini bool set is empty
-                    # (e.g. the .ini was not written).
-                    is_bool_value = isinstance(v, bool) or (
-                        isinstance(v, str) and v.lower() in ("true", "false")
-                    )
-                    if (k in topp_bool_flag_param_keys and v != "") or is_bool_value:
-                        # CLI flag: include "-k" only when enabled, never a value.
-                        if isinstance(v, str):
-                            is_enabled = v.lower() == "true"
-                        else:
-                            is_enabled = bool(v)
-                        if is_enabled:
-                            command += [f"-{k}"]
-                        continue
-                    command += [f"-{k}"]
-                    # Skip only empty strings (pass flag with no value)
-                    # Note: 0 and 0.0 are valid values, so use explicit check
-                    if v != "" and v is not None:
-                        if isinstance(v, str) and "\n" in v:
-                            command += v.split("\n")
-                        else:
-                            command += [str(v)]
+            # Add merged TOPP tool parameters (_defaults + user overrides)
+            for k, v in merged_params.items():
+                if k in flag_params:
+                    # CLI flag: include "-k" only when truthy, omit when false
+                    if isinstance(v, str):
+                        is_enabled = v.lower() == "true"
+                    else:
+                        is_enabled = bool(v)
+                    if is_enabled:
+                        command += [f"-{k}"]
+                    continue
+                # Regular parameter: skip empty/None/empty-list, append value otherwise
+                if v == "" or v is None or (isinstance(v, list) and not v):
+                    continue
+                command += [f"-{k}"]
+                if isinstance(v, str) and "\n" in v:
+                    command += v.split("\n")
+                elif isinstance(v, list):
+                    command += [str(x) for x in v]
+                else:
+                    command += [str(v)]
             # Add custom parameters
             for k, v in custom_params.items():
-                command += [f"-{k}"]
-                
-                # Skip only empty strings (pass flag with no value)
-                # Note: 0 and 0.0 are valid values, so use explicit check
-                if v != "" and v is not None:
-                    if isinstance(v, list):
-                        command += [str(x) for x in v]
+                if k in flag_params:
+                    if isinstance(v, str):
+                        is_enabled = v.lower() == "true"
                     else:
-                        command += [str(v)]
+                        is_enabled = bool(v)
+                    if is_enabled:
+                        command += [f"-{k}"]
+                    continue
+                if v == "" or v is None or (isinstance(v, list) and not v):
+                    continue
+                command += [f"-{k}"]
+                if isinstance(v, list):
+                    command += [str(x) for x in v]
+                else:
+                    command += [str(v)]
             # Add threads parameter for TOPP tools
             command += ["-threads", str(threads_per_command)]
             commands.append(command)
 
-            # check if a ini file has been written, if yes use it (contains custom defaults)
-            ini_path = Path(self.parameter_manager.ini_dir, tool + ".ini")
-            if ini_path.exists():
-                command += ["-ini", str(ini_path)]
-
         # Run command(s)
         if len(commands) == 1:
             return self.run_command(commands[0])
@@ -369,7 +407,7 @@ def stop(self) -> None:
         shutil.rmtree(self.pid_dir, ignore_errors=True)
         self.logger.log("Workflow stopped.")
 
-    def run_python(self, script_file: str, input_output: dict = {}) -> None:
+    def run_python(self, script_file: str, input_output: dict = {}) -> bool:
         """
         Executes a specified Python script with dynamic input and output parameters,
         optionally logging the execution process. The method identifies and loads
@@ -386,6 +424,13 @@ def run_python(self, script_file: str, input_output: dict = {}) -> None:
                                 If the path is omitted, the method looks for the script in 'src/python-tools/'.
                                 The '.py' extension is appended if not present.
             input_output (dict, optional): A dictionary specifying the input/output parameter names (as key) and their corresponding file paths (as value). Defaults to {}.
+
+        Returns:
+            bool: True if the script ran and exited 0, False otherwise. Same
+                contract as run_topp(), so execution() can gate on it. This used
+                to discard run_command()'s result and return None, which made
+                every `if not self.executor.run_python(...)` guard dead code and
+                left a failed Python tool indistinguishable from a successful one.
         """
         # Check if script file exists (can be specified without path and extension)
         # default location: src/python-tools/script_file
@@ -395,8 +440,12 @@ def run_python(self, script_file: str, input_output: dict = {}) -> None:
         if not path.exists():
             path = Path("src", "python-tools", script_file)
             if not path.exists():
-                self.logger.log(f"Script file not found: {script_file}")
-                
+                # Bail out here: falling through to spec_from_file_location on a
+                # path that does not exist raises out of the workflow instead of
+                # reporting a failed step.
+                self.logger.log(f"ERROR: Script file not found: {script_file}", 0)
+                return False
+
         # load DEFAULTS
         if path.parent not in sys.path:
             sys.path.append(str(path.parent))
@@ -407,7 +456,7 @@ def run_python(self, script_file: str, input_output: dict = {}) -> None:
         if defaults is None:
             self.logger.log(f"WARNING: No DEFAULTS found in {path.name}")
             # run command without params
-            self.run_command(["python", str(path)])
+            return self.run_command([sys.executable, str(path)])
         elif isinstance(defaults, list):
             defaults = {entry["key"]: entry["value"] for entry in defaults}
             # load paramters from JSON file
@@ -422,6 +471,19 @@ def run_python(self, script_file: str, input_output: dict = {}) -> None:
             with open(tmp_params_file, "w", encoding="utf-8") as f:
                 json.dump(defaults, f, indent=4)
             # run command
-            self.run_command(["python", str(path), str(tmp_params_file)])
+            success = self.run_command(
+                [sys.executable, str(path), str(tmp_params_file)]
+            )
             # remove tmp params file
-            tmp_params_file.unlink()
\ No newline at end of file
+            tmp_params_file.unlink()
+            return success
+
+        # DEFAULTS exists but is not the documented list of parameter dicts, so
+        # nothing ran. Reporting that as success would put the workflow's
+        # WORKFLOW FINISHED marker on a step which never executed.
+        self.logger.log(
+            f"ERROR: DEFAULTS in {path.name} is a {type(defaults).__name__}, "
+            "expected a list of parameter dicts. Script not run.",
+            0,
+        )
+        return False
\ No newline at end of file
diff --git a/src/workflow/ParameterManager.py b/src/workflow/ParameterManager.py
index 14ec5267..d3ffc310 100644
--- a/src/workflow/ParameterManager.py
+++ b/src/workflow/ParameterManager.py
@@ -1,11 +1,18 @@
 import pyopenms as poms
+import errno
 import json
+import logging
+import os
 import shutil
 import subprocess
 import streamlit as st
+import time
+import uuid
 import xml.etree.ElementTree as ET
 from pathlib import Path
 
+logger = logging.getLogger(__name__)
+
 
 def bool_param_paths_from_param_xml_ini(ini_path: Path, tool_stem: str) -> set[str]:
     """
@@ -49,6 +56,191 @@ def walk(el: ET.Element, parts: tuple[str, ...]) -> None:
     return out
 
 
+class InvalidParameterFileError(ValueError):
+    """
+    Raised when a params.json exists but cannot be read as a parameter dict.
+
+    Deliberately distinct from an absent file, which simply means a first run
+    with no stored parameters. Conflating the two is the erasure bug: a failed
+    read reported as an empty dict gets merged into a read-modify-write and
+    written back as the current session's subset, permanently deleting
+    ``_defaults``, ``_flag_params`` and every other tool's values.
+    """
+
+
+class TransientParameterFileError(InvalidParameterFileError):
+    """
+    Raised when the read failed for a reason expected to clear by itself.
+
+    A shared NFS export is restarted by upgrades, evictions and node drains,
+    and clients see ESTALE/EIO until it is back. The stored bytes are almost
+    certainly intact, so callers must still refuse to write - the current
+    content is unknown - but must not offer to delete the file. Resetting
+    during a self-healing blip is what would turn a momentary outage into the
+    permanent data loss this split exists to prevent.
+
+    A subclass, so every ``except InvalidParameterFileError`` guard keeps
+    catching it; only code that treats the two differently has to know.
+    """
+
+
+# errno values meaning "the storage is not answering right now", as opposed to
+# "this file is broken". Looked up defensively: not all exist on every platform.
+_TRANSIENT_READ_ERRNOS = frozenset(
+    value
+    for value in (
+        getattr(errno, name, None)
+        for name in (
+            "ESTALE",
+            "EIO",
+            "ENOTCONN",
+            "ETIMEDOUT",
+            "EAGAIN",
+            "EINTR",
+            "ENOLINK",
+            "EREMOTEIO",
+        )
+    )
+    if value is not None
+)
+
+# Two retries, at 0.2s and 0.4s. Long enough to ride out a re-established NFS
+# connection, short enough that a Streamlit rerun does not visibly stall. Only
+# transient errnos retry, so a corrupt file still fails on the first attempt.
+_READ_ATTEMPTS = 3
+_READ_RETRY_DELAY_SECONDS = 0.2
+
+
+def _read_parameter_file(params_file: Path) -> dict:
+    """
+    Read a parameter JSON file. Pure I/O, no Streamlit and no session state.
+
+    Args:
+        params_file: Path of the JSON file to read.
+
+    Returns:
+        dict: The stored parameters, or an empty dict if the file does not
+            exist at all - a first run has no parameters and that is not a
+            failure.
+
+    Raises:
+        TransientParameterFileError: The storage did not answer (ESTALE, EIO,
+            ...), and still did not after retrying. The file is probably fine.
+        InvalidParameterFileError: The file exists but could not be read as a
+            JSON object: malformed or torn content, a bad encoding, a directory
+            in its place, permissions. Callers which merge the result and write
+            it back must abort on this rather than treat it as "no parameters".
+    """
+    last_error = None
+    for attempt in range(_READ_ATTEMPTS):
+        try:
+            with open(params_file, "r", encoding="utf-8") as f:
+                params = json.load(f)
+            break
+        except FileNotFoundError:
+            # Ordered before OSError on purpose: an absent file is a first run,
+            # not a failure, and conflating the two is the erasure bug.
+            return {}
+        except OSError as e:
+            if e.errno not in _TRANSIENT_READ_ERRNOS:
+                raise InvalidParameterFileError(
+                    f"Could not read parameter file {params_file}: {e}"
+                ) from e
+            last_error = e
+            if attempt + 1 < _READ_ATTEMPTS:
+                time.sleep(_READ_RETRY_DELAY_SECONDS * (attempt + 1))
+        except ValueError as e:
+            # json.JSONDecodeError *and* UnicodeDecodeError - the latter is a
+            # ValueError, not an OSError, so catching OSError alone let a
+            # params.json written in the platform codepage escape both readers
+            # uncaught and take the workflow page down with a raw traceback.
+            raise InvalidParameterFileError(
+                f"Could not read parameter file {params_file}: {e}"
+            ) from e
+    else:
+        raise TransientParameterFileError(
+            f"Could not read parameter file {params_file} after "
+            f"{_READ_ATTEMPTS} attempts: {last_error}"
+        ) from last_error
+
+    if not isinstance(params, dict):
+        raise InvalidParameterFileError(
+            f"Parameter file {params_file} does not hold a JSON object "
+            f"(found {type(params).__name__})."
+        )
+    return params
+
+
+def _write_parameter_file(params_file: Path, params: dict) -> None:
+    """
+    Write a parameter JSON file atomically: temp file, then ``os.replace()``.
+
+    A truncate-then-rewrite that dies half way - an OOM kill, ENOSPC - leaves a
+    file which is neither the old parameters nor the new ones. Every later
+    strict read rejects it, so ``save_parameters()`` becomes a permanent silent
+    no-op and the parameter page stops on every render, with no way out but the
+    reset button. ``os.replace()`` is atomic on POSIX and on Windows, so a
+    reader sees either the whole old file or the whole new one.
+
+    This does not make concurrent writers safe - the last writer still wins the
+    whole file, docs/storage-defect-register.md A2 - it only removes the torn file.
+
+    The scratch name carries a uuid as well as the pid. The pid alone is not
+    unique per writer: Streamlit serves every session from threads of ONE
+    process, and in a container that process is pid 1 in every replica - so two
+    sessions sharing a `?workspace=` link, or two pods now that the volume is
+    genuinely ReadWriteMany, resolved to the same scratch path and interleaved
+    their writes into it. Whichever one reached os.replace() second published a
+    file the other was still writing, which is precisely the torn file this
+    function exists to prevent.
+
+    flush + fsync before the rename because os.replace() orders the directory
+    entry, not the data behind it: on NFS a crash between the two can otherwise
+    publish a name pointing at unwritten blocks.
+
+    Deliberately not tempfile.mkstemp(): it creates at mode 0600, so params.json
+    would quietly change permissions the first time it was rewritten.
+
+    Args:
+        params_file: Destination path.
+        params: Parameters to store.
+    """
+    tmp_file = params_file.with_name(
+        f".{params_file.name}.{os.getpid()}.{uuid.uuid4().hex}.tmp"
+    )
+    try:
+        with open(tmp_file, "w", encoding="utf-8") as f:
+            json.dump(params, f, indent=4)
+            f.flush()
+            os.fsync(f.fileno())
+        os.replace(tmp_file, params_file)
+    except BaseException:
+        # Never leave the scratch file behind next to params.json.
+        try:
+            tmp_file.unlink()
+        except OSError:
+            pass
+        raise
+
+
+def _streamlit_session_active() -> bool:
+    """
+    True only while running inside a real Streamlit script run.
+
+    tasks.py builds a ParameterManager inside the RQ work horse, where there is
+    no ScriptRunContext and st.error() is a silent no-op - so the user facing
+    half of a message is skipped there and the log carries it instead.
+    """
+    try:
+        from streamlit.runtime.scriptrunner import get_script_run_ctx
+
+        # suppress_warning, or every probe from the worker logs a "missing
+        # ScriptRunContext!" warning next to the message it is deciding about.
+        return get_script_run_ctx(suppress_warning=True) is not None
+    except Exception:  # streamlit absent, mocked out, or internals moved
+        return False
+
+
 class ParameterManager:
     """
     Manages the parameters for a workflow, including saving parameters to a JSON file,
@@ -132,10 +324,20 @@ def save_parameters(self) -> None:
         }
 
         # Merge with parameters from json
-        # Advanced parameters are only in session state if the view is active
-        json_params = self.get_parameters_from_json() | json_params
+        # Advanced parameters are only in session state if the view is active.
+        # The read has to be strict: merging a tolerant empty dict from a failed
+        # read and writing that back is what erases every stored value, so a
+        # failed read aborts the write and leaves the file on disk untouched.
+        try:
+            stored_params = self.read_parameters_strict()
+        except InvalidParameterFileError as e:
+            self._report_unreadable_parameter_file(
+                e, "Parameters were not saved, the existing file is left unchanged."
+            )
+            return
+        json_params = stored_params | json_params
 
-        # get a list of TOPP tools which are in session state
+        # get a list of TOPP tools (or tool instance names) which are in session state
         current_topp_tools = list(
             set(
                 [
@@ -145,12 +347,16 @@ def save_parameters(self) -> None:
                 ]
             )
         )
-        # for each TOPP tool, open the ini file
+        # Retrieve the instance-name → real-tool-name mapping (set by input_TOPP)
+        tool_instance_map = st.session_state.get("_topp_tool_instance_map", {})
+        # for each TOPP tool (or instance name), open the ini file
         for tool in current_topp_tools:
-            if not self.create_ini(tool):
+            # Resolve instance name to real tool name for create_ini / ini loading
+            real_tool = tool_instance_map.get(tool, tool)
+            if not self.create_ini(real_tool):
                 # Could not create ini file - skip this tool
                 continue
-            ini_path = Path(self.ini_dir, f"{tool}.ini")
+            ini_path = Path(self.ini_dir, f"{real_tool}.ini")
             if tool not in json_params:
                 json_params[tool] = {}
             # load the param object
@@ -162,57 +368,141 @@ def save_parameters(self) -> None:
                     # Skip display keys used by multiselect widgets
                     if key.endswith("_display"):
                         continue
-                    # get ini_key
-                    ini_key = key.replace(self.topp_param_prefix, "").encode()
+                    # get ini_key – map instance name back to real tool name
+                    ini_key = key.replace(self.topp_param_prefix, "")
+                    if tool != real_tool:
+                        ini_key = ini_key.replace(f"{tool}:1:", f"{real_tool}:1:", 1)
+                    ini_key = ini_key.encode()
                     # get ini (default) value by ini_key
                     ini_value = param.getValue(ini_key)
                     is_list_param = isinstance(ini_value, list)
-                    # check if value is different from default OR is an empty list parameter
+                    # Effective default: _defaults value if present, else ini value
+                    short_key = key.split(":1:")[1]
+                    defaults = json_params.get("_defaults", {}).get(tool, {})
+                    default_value = defaults.get(short_key, ini_value)
+                    # check if value is different from effective default OR is an empty list parameter
                     if (
-                        (ini_value != value)
-                        or (key.split(":1:")[1] in json_params[tool])
+                        (default_value != value)
+                        or (short_key in json_params[tool])
                         or (is_list_param and not value)  # Always save empty list params
                     ):
                         if isinstance(value, str):
                             value = value.strip()
                         # store non-default value
-                        json_params[tool][key.split(":1:")[1]] = value
+                        json_params[tool][short_key] = value
         # Save to json file
-        with open(self.params_file, "w", encoding="utf-8") as f:
-            json.dump(json_params, f, indent=4)
+        _write_parameter_file(self.params_file, json_params)
 
     def get_parameters_from_json(self) -> dict:
         """
         Loads parameters from the JSON file if it exists and returns them as a dictionary.
-        If the file does not exist, it returns an empty dictionary.
+        If the file does not exist or cannot be read, it returns an empty dictionary.
+
+        Tolerant on purpose, for the constructors and the read-only callers which
+        have no way to handle a raise. Never use it as the read half of a
+        read-modify-write: an empty dict from a failed read, merged over the
+        stored parameters and written back, erases them. Use
+        read_parameters_strict() there.
 
         Returns:
             dict: A dictionary containing the loaded parameters. Keys are parameter names,
                 and values are parameter values.
         """
-        # Check if parameter file exists
-        if not Path(self.params_file).exists():
+        try:
+            return _read_parameter_file(self.params_file)
+        except InvalidParameterFileError as e:
+            self._report_unreadable_parameter_file(
+                e, "Falling back to default parameters."
+            )
             return {}
-        else:
-            # Load parameters from json file
-            try:
-                with open(self.params_file, "r", encoding="utf-8") as f:
-                    return json.load(f)
-            except:
-                st.error("**ERROR**: Attempting to load an invalid JSON parameter file. Reset to defaults.")
-                return {}
-
-    def get_topp_parameters(self, tool: str) -> dict:
+
+    def read_parameters_strict(self) -> dict:
+        """
+        Loads parameters from the JSON file, raising instead of hiding a failed read.
+
+        This is the reader for every read-modify-write-back site.
+        get_parameters_from_json() cannot be used there: its empty dict for an
+        unreadable file gets merged with the current session's parameters and
+        written back, permanently erasing everything the session does not hold -
+        while the user is told it was a deliberate reset to defaults.
+
+        Returns:
+            dict: The stored parameters. Empty only if params.json does not exist.
+
+        Raises:
+            InvalidParameterFileError: params.json exists but is unreadable.
+        """
+        return _read_parameter_file(self.params_file)
+
+    def write_parameters(self, params: dict) -> None:
+        """
+        Write params.json, atomically, for the write-back sites outside this class.
+
+        StreamlitUI._input_TOPP_impl() seeds ``_flag_params`` and ``_defaults``
+        by reading with read_parameters_strict(), merging, and writing straight
+        back, so it needs the same atomic write save_parameters() uses - a torn
+        file written there wedges the parameter page on every later render.
+
+        Args:
+            params: The complete parameter dict to store.
+        """
+        _write_parameter_file(self.params_file, params)
+
+    def _report_unreadable_parameter_file(self, error: Exception, consequence: str) -> None:
+        """
+        Report an unreadable params.json, to the log always and to the user if there is one.
+
+        logging is the sink which always works: tasks.py builds a
+        ParameterManager inside the RQ work horse, where st.error() reaches
+        nobody.
+
+        Args:
+            error: The read failure being reported.
+            consequence: What the caller did about it, in the user's terms.
+        """
+        message = f"{error} {consequence}"
+        logger.error(message)
+        if _streamlit_session_active():
+            st.error(f"**ERROR**: {message}")
+
+    def get_merged_params(self, tool_instance_name: str, ini_params: dict = None) -> dict:
+        """
+        Three-layer parameter merge: ini defaults < _defaults < user overrides.
+
+        Args:
+            tool_instance_name: Instance name (or tool name) to look up in params.json.
+            ini_params: Base parameters from the .ini file. Optional — callers that
+                don't need the ini layer (e.g., run_topp, which passes -ini separately)
+                can omit this.
+
+        Returns:
+            Merged dict with the effective value for each parameter.
+        """
+        params = self.get_parameters_from_json()
+        defaults = params.get("_defaults", {}).get(tool_instance_name, {})
+        user = params.get(tool_instance_name, {})
+
+        merged = {}
+        if ini_params:
+            merged.update(ini_params)
+        merged.update(defaults)
+        merged.update(user)
+        return merged
+
+    def get_topp_parameters(self, tool: str, tool_instance_name: str = None) -> dict:
         """
         Get all parameters for a TOPP tool, merging defaults with user values.
 
         Args:
-            tool: Name of the TOPP tool (e.g., "CometAdapter")
+            tool: Name of the TOPP tool executable (e.g., "CometAdapter")
+            tool_instance_name: Optional instance name used for parameter storage
+                (e.g., "IDFilter_step1"). If not provided, defaults to tool name.
 
         Returns:
             Dict with parameter names as keys (without tool prefix) and their values.
             Returns empty dict if ini file doesn't exist.
         """
+        instance_name = tool_instance_name or tool
         ini_path = Path(self.ini_dir, f"{tool}.ini")
         if not ini_path.exists():
             return {}
@@ -223,26 +513,51 @@ def get_topp_parameters(self, tool: str) -> dict:
 
         # Build dict from ini (extract short key names)
         prefix = f"{tool}:1:"
-        full_params = {}
+        ini_params = {}
         for key in param.keys():
             key_str = key.decode() if isinstance(key, bytes) else str(key)
             if prefix in key_str:
                 short_key = key_str.split(prefix, 1)[1]
-                full_params[short_key] = param.getValue(key)
+                ini_params[short_key] = param.getValue(key)
 
-        # Override with user-modified values from JSON
-        user_params = self.get_parameters_from_json().get(tool, {})
-        full_params.update(user_params)
+        return self.get_merged_params(instance_name, ini_params=ini_params)
 
-        return full_params
-
-    def reset_to_default_parameters(self) -> None:
+    def reset_to_default_parameters(self) -> Path | None:
         """
-        Resets the parameters to their default values by deleting the custom parameters
-        JSON file.
+        Reset to defaults by moving the stored parameter file out of the way.
+
+        Moved, not deleted. This is also the recovery offered when params.json
+        cannot be read, and an unreadable file is very often a healthy file
+        behind a storage blip, so deleting it there would turn a self-healing
+        outage into permanent loss. The bytes are kept under a timestamped name
+        beside the original and the caller is told where they went. A rename
+        also copes with a directory in place of params.json, which
+        ``unlink()`` cannot - that used to make the reset button itself raise,
+        leaving the parameter page stopped on every render with no way out.
+
+        Returns:
+            Path: Where the previous parameters were moved, or None when there
+                was nothing to reset.
+
+        Raises:
+            OSError: The file exists but could not be moved. Callers rendering
+                a reset affordance must surface this rather than let it escape.
         """
-        # Delete custom params json file
-        self.params_file.unlink(missing_ok=True)
+        if not self.params_file.exists():
+            return None
+
+        stamp = time.strftime("%Y%m%d-%H%M%S")
+        backup = self.params_file.with_name(f"{self.params_file.name}.{stamp}.bak")
+        collision = 1
+        while backup.exists():
+            backup = self.params_file.with_name(
+                f"{self.params_file.name}.{stamp}-{collision}.bak"
+            )
+            collision += 1
+
+        self.params_file.rename(backup)
+        logger.info("Reset parameters, previous file kept at %s", backup)
+        return backup
 
     def load_presets(self) -> dict:
         """
@@ -309,8 +624,16 @@ def apply_preset(self, preset_name: str) -> bool:
         if not preset:
             return False
 
-        # Load existing parameters
-        current_params = self.get_parameters_from_json()
+        # Load existing parameters. Strict, because this is a read-modify-write
+        # back too: a tolerant empty dict here would delete every parameter the
+        # preset does not mention and still report success.
+        try:
+            current_params = self.read_parameters_strict()
+        except InvalidParameterFileError as e:
+            self._report_unreadable_parameter_file(
+                e, "The preset was not applied, the existing file is left unchanged."
+            )
+            return False
 
         # Collect keys to delete from session_state
         keys_to_delete = []
@@ -342,8 +665,7 @@ def apply_preset(self, preset_name: str) -> bool:
                 del st.session_state[session_key]
 
         # Save updated parameters to file
-        with open(self.params_file, "w", encoding="utf-8") as f:
-            json.dump(current_params, f, indent=4)
+        _write_parameter_file(self.params_file, current_params)
 
         return True
 
diff --git a/src/workflow/QueueManager.py b/src/workflow/QueueManager.py
index 21db9a8b..1dd35147 100644
--- a/src/workflow/QueueManager.py
+++ b/src/workflow/QueueManager.py
@@ -7,12 +7,13 @@
 """
 
 import os
-import json
 from typing import Optional, Callable, Any
 from dataclasses import dataclass
 from enum import Enum
 from pathlib import Path
 
+from .settings_io import load_settings
+
 
 class JobStatus(Enum):
     """Job status enumeration matching RQ states"""
@@ -63,6 +64,13 @@ def __init__(self):
         queue_settings = settings.get("queue_settings", {})
         self._default_timeout = queue_settings.get("default_timeout", 7200)
         self._default_result_ttl = queue_settings.get("result_ttl", 86400)
+        # RQ's own default failure_ttl is one year. Failed jobs only started
+        # existing once execute_workflow began re-raising, and each one keeps
+        # its full traceback in Redis - which runs with a 256Mi limit, no
+        # persistence and no maxmemory-policy, so it is OOMKilled rather than
+        # evicting. "No mzML files selected" is a routine user error; it must
+        # not leave a year-lived key behind.
+        self._default_failure_ttl = queue_settings.get("failure_ttl", 86400)
 
         if self._is_online:
             self._init_redis()
@@ -70,11 +78,7 @@ def __init__(self):
     @staticmethod
     def _load_settings() -> dict:
         """Load settings.json once; return empty dict on failure."""
-        try:
-            with open("settings.json", "r") as f:
-                return json.load(f)
-        except Exception:
-            return {}
+        return load_settings()
 
     def _check_online_mode(self, settings: dict) -> bool:
         """Check if running in online mode"""
@@ -119,6 +123,7 @@ def submit_job(
         job_id: Optional[str] = None,
         timeout: Optional[int] = None,
         result_ttl: Optional[int] = None,
+        failure_ttl: Optional[int] = None,
         description: str = ""
     ) -> Optional[str]:
         """
@@ -131,6 +136,9 @@ def submit_job(
             job_id: Optional custom job ID (defaults to UUID)
             timeout: Job timeout in seconds (defaults to settings.json queue_settings.default_timeout)
             result_ttl: How long to keep results (defaults to settings.json queue_settings.result_ttl)
+            failure_ttl: How long to keep failed jobs, with their traceback
+                (defaults to settings.json queue_settings.failure_ttl). Without
+                it RQ keeps them for a year.
             description: Human-readable job description
 
         Returns:
@@ -144,6 +152,8 @@ def submit_job(
             timeout = self._default_timeout
         if result_ttl is None:
             result_ttl = self._default_result_ttl
+        if failure_ttl is None:
+            failure_ttl = self._default_failure_ttl
 
         try:
             job = self._queue.enqueue(
@@ -153,6 +163,7 @@ def submit_job(
                 job_id=job_id,
                 job_timeout=timeout,
                 result_ttl=result_ttl,
+                failure_ttl=failure_ttl,
                 description=description,
                 meta={"description": description, "progress": 0.0, "current_step": ""}
             )
diff --git a/src/workflow/StreamlitUI.py b/src/workflow/StreamlitUI.py
index 07b78c72..50007d54 100644
--- a/src/workflow/StreamlitUI.py
+++ b/src/workflow/StreamlitUI.py
@@ -21,6 +21,10 @@
     tk_file_dialog,
 )
 from src.workflow._log_status import classify_log_outcome
+from src.workflow.ParameterManager import (
+    InvalidParameterFileError,
+    TransientParameterFileError,
+)
 
 
 def _mounted_data_root() -> Union[Path, None]:
@@ -558,7 +562,9 @@ def _select_input_file_impl(self, key, name, multiple, display_file_path, reacti
         if not path.exists():
             st.warning(f"No **{name}** files!")
             return
-        options = [str(f) for f in path.iterdir() if "external_files.txt" not in str(f)]
+        options = sorted(
+            str(f) for f in path.iterdir() if "external_files.txt" not in str(f)
+        )
 
         # Check if local files are available
         external_files = Path(
@@ -674,11 +680,21 @@ def format_files(input: Any) -> List[str]:
 
         key = f"{self.parameter_manager.param_prefix}{key}"
 
+        # Streamlit ignores a widget's initial-value argument (value=/default=/index=)
+        # once that key already exists in session state -- but on Streamlit < 1.50 the
+        # argument is still hashed into the widget's element id. Since this method feeds
+        # the persisted parameter straight back in as that argument, the id changed on
+        # every interaction, the following interaction arrived under the now-stale id and
+        # was silently dropped: selecting six mzML files kept only three. Seed the widget
+        # on first render only; from then on session state owns the value.
+        def seed(**kwargs: Any) -> dict:
+            return {} if key in st.session_state else kwargs
+
         if widget_type == "text":
-            st.text_input(name, value=value, key=key, help=help, on_change=on_change)
+            st.text_input(name, key=key, help=help, on_change=on_change, **seed(value=value))
 
         elif widget_type == "textarea":
-            st.text_area(name, value=value, key=key, help=help, on_change=on_change)
+            st.text_area(name, key=key, help=help, on_change=on_change, **seed(value=value))
 
         elif widget_type == "number":
             number_type = float if isinstance(value, float) else int
@@ -692,27 +708,27 @@ def format_files(input: Any) -> List[str]:
                 name,
                 min_value=min_value,
                 max_value=max_value,
-                value=value,
                 step=step_size,
                 format=None,
                 key=key,
                 help=help,
                 on_change=on_change,
+                **seed(value=value),
             )
 
         elif widget_type == "checkbox":
-            st.checkbox(name, value=value, key=key, help=help, on_change=on_change)
+            st.checkbox(name, key=key, help=help, on_change=on_change, **seed(value=value))
 
         elif widget_type == "selectbox":
             if options is not None:
                 st.selectbox(
                     name,
                     options=options,
-                    index=options.index(value) if value in options else 0,
                     key=key,
                     format_func=format_files,
                     help=help,
                     on_change=on_change,
+                    **seed(index=options.index(value) if value in options else 0),
                 )
             else:
                 st.warning(f"Select widget '{name}' requires options parameter")
@@ -722,11 +738,11 @@ def format_files(input: Any) -> List[str]:
                 st.multiselect(
                     name,
                     options=options,
-                    default=value,
                     key=key,
                     format_func=format_files,
                     help=help,
                     on_change=on_change,
+                    **seed(default=value),
                 )
             else:
                 st.warning(f"Select widget '{name}' requires options parameter")
@@ -743,12 +759,12 @@ def format_files(input: Any) -> List[str]:
                     name,
                     min_value=min_value,
                     max_value=max_value,
-                    value=value,
                     step=step_size,
                     key=key,
                     format=None,
                     help=help,
                     on_change=on_change,
+                    **seed(value=value),
                 )
             else:
                 st.warning(
@@ -756,12 +772,12 @@ def format_files(input: Any) -> List[str]:
                 )
 
         elif widget_type == "password":
-            st.text_input(name, value=value, type="password", key=key, help=help, on_change=on_change)
+            st.text_input(name, type="password", key=key, help=help, on_change=on_change, **seed(value=value))
 
         elif widget_type == "auto":
             # Auto-determine widget type based on value
             if isinstance(value, bool):
-                st.checkbox(name, value=value, key=key, help=help, on_change=on_change)
+                st.checkbox(name, key=key, help=help, on_change=on_change, **seed(value=value))
             elif isinstance(value, (int, float)):
                 self._input_widget_impl(
                     key,
@@ -822,17 +838,19 @@ def format_files(input: Any) -> List[str]:
 
         self.parameter_manager.save_parameters()
 
-    @st.fragment
     def input_TOPP(
         self,
         topp_tool_name: str,
         num_cols: int = 4,
         exclude_parameters: List[str] = [],
         include_parameters: List[str] = [],
+        flag_parameters: List[str] = [],
         display_tool_name: bool = True,
         display_subsections: bool = True,
         display_subsection_tabs: bool = False,
         custom_defaults: dict = {},
+        tool_instance_name: str = None,
+        reactive: bool = False,
     ) -> None:
         """
         Generates input widgets for TOPP tool parameters dynamically based on the tool's
@@ -844,33 +862,187 @@ def input_TOPP(
             num_cols (int, optional): Number of columns to use for the layout. Defaults to 3.
             exclude_parameters (List[str], optional): List of parameter names to exclude from the widget. Defaults to an empty list.
             include_parameters (List[str], optional): List of parameter names to include in the widget. Defaults to an empty list.
+            flag_parameters (List[str], optional): List of parameter names that should
+                be treated as no-value CLI flags during command construction.
             display_tool_name (bool, optional): Whether to display the TOPP tool name. Defaults to True.
             display_subsections (bool, optional): Whether to split parameters into subsections based on the prefix. Defaults to True.
             display_subsection_tabs (bool, optional): Whether to display main subsections in separate tabs (if more than one main section). Defaults to False.
             custom_defaults (dict, optional): Dictionary of custom defaults to use. Defaults to an empty dict.
+            tool_instance_name (str, optional): A unique instance name for this tool
+                invocation. Allows multiple instances of the same TOPP tool with
+                independent parameters (e.g., two IDFilter calls). If not provided,
+                defaults to topp_tool_name. The instance name is used for session
+                state keys and parameter storage, while topp_tool_name is used for
+                the actual tool executable and ini file creation.
+            reactive (bool, optional): If True, widget changes trigger the parent
+                section to re-render, enabling conditional UI based on this widget's
+                value. Use when downstream UI depends on a parameter value (e.g.,
+                TMT type driving channel count). Default is False.
+        """
+        if reactive:
+            self._input_TOPP_impl(
+                topp_tool_name, num_cols, exclude_parameters, include_parameters,
+                flag_parameters, display_tool_name, display_subsections,
+                display_subsection_tabs, custom_defaults, tool_instance_name,
+            )
+        else:
+            self._input_TOPP_fragmented(
+                topp_tool_name, num_cols, exclude_parameters, include_parameters,
+                flag_parameters, display_tool_name, display_subsections,
+                display_subsection_tabs, custom_defaults, tool_instance_name,
+            )
+
+    @st.fragment
+    def _input_TOPP_fragmented(
+        self,
+        topp_tool_name: str,
+        num_cols: int = 4,
+        exclude_parameters: List[str] = [],
+        include_parameters: List[str] = [],
+        flag_parameters: List[str] = [],
+        display_tool_name: bool = True,
+        display_subsections: bool = True,
+        display_subsection_tabs: bool = False,
+        custom_defaults: dict = {},
+        tool_instance_name: str = None,
+    ) -> None:
+        self._input_TOPP_impl(
+            topp_tool_name, num_cols, exclude_parameters, include_parameters,
+            flag_parameters, display_tool_name, display_subsections,
+            display_subsection_tabs, custom_defaults, tool_instance_name,
+        )
+
+    def _read_params_for_update(self, tool_instance_name: str) -> dict:
+        """
+        Strict read of params.json for the read-modify-write-back sites below.
+
+        Both callers merge into what they read and write the result straight
+        back, so a tolerant empty dict from an unreadable file would be written
+        over everything stored - erasing `_defaults`, `_flag_params` and every
+        other tool's values while looking like a successful save.
+        read_parameters_strict() raises instead, and here that raise becomes a
+        halt: the write is skipped entirely, so the file on disk is preserved
+        for inspection and can still be repaired by hand, or reset from the
+        button rendered below.
+
+        Args:
+            tool_instance_name (str): Instance currently being rendered, used to
+                keep the reset button key unique across tool fragments.
+
+        Returns:
+            dict: Stored parameters, or an empty dict for an absent file.
+
+        Does not return if the file exists but cannot be read.
         """
+        try:
+            return self.parameter_manager.read_parameters_strict()
+        except TransientParameterFileError as e:
+            # Ordered before InvalidParameterFileError, of which this is a
+            # subclass. The storage is not answering; the file itself is most
+            # likely intact, so deliberately no reset affordance here - a reset
+            # during a Ganesha restart is what would actually destroy it.
+            st.error(
+                f"**ERROR**: {e} Nothing was written, so no stored parameters "
+                "were lost. This usually clears by itself, reload the page in "
+                "a moment."
+            )
+            st.stop()
+            # st.stop() raises, so this is only reached when Streamlit is
+            # stubbed out; re-raise rather than fall through to the write.
+            raise
+        except InvalidParameterFileError as e:
+            st.error(
+                f"**ERROR**: {e} Nothing was written, so no stored parameters "
+                "were lost. Repair the file, or reset to defaults to continue."
+            )
+            if st.button(
+                "⚠️ Reset parameters to defaults",
+                help="Move the unreadable parameter file aside and start over from the default parameters.",
+                key=f"reset_unreadable_params_{tool_instance_name}",
+            ):
+                try:
+                    backup = self.parameter_manager.reset_to_default_parameters()
+                except OSError as reset_error:
+                    # Without this the button itself raises and the page stops
+                    # again on the next render, with no remaining way out.
+                    st.error(
+                        f"**ERROR**: Could not move "
+                        f"{self.parameter_manager.params_file} aside: "
+                        f"{reset_error}"
+                    )
+                else:
+                    self.parameter_manager.clear_parameter_session_state()
+                    st.toast(
+                        f"Parameters reset to defaults, previous file kept as {backup.name}"
+                        if backup is not None
+                        else "Parameters reset to defaults"
+                    )
+                    # Every tool section is affected, not just this fragment.
+                    st.rerun(scope="app")
+            st.stop()
+            # st.stop() raises, so this is only reached when Streamlit is
+            # stubbed out; re-raise rather than fall through to the write.
+            raise
+
+    def _input_TOPP_impl(
+        self,
+        topp_tool_name: str,
+        num_cols: int = 4,
+        exclude_parameters: List[str] = [],
+        include_parameters: List[str] = [],
+        flag_parameters: List[str] = [],
+        display_tool_name: bool = True,
+        display_subsections: bool = True,
+        display_subsection_tabs: bool = False,
+        custom_defaults: dict = {},
+        tool_instance_name: str = None,
+    ) -> None:
+        """Internal implementation of input_TOPP - contains all the widget logic."""
+        # Default instance name to the tool name when not provided
+        if tool_instance_name is None:
+            tool_instance_name = topp_tool_name
+
+        # Register instance-name → real-tool-name mapping in session state
+        if "_topp_tool_instance_map" not in st.session_state:
+            st.session_state["_topp_tool_instance_map"] = {}
+        st.session_state["_topp_tool_instance_map"][tool_instance_name] = topp_tool_name
+
+        # Persist flag_parameters to session_state and params.json so run_topp
+        # can skip appending a value for these boolean CLI flags.
+        if "_topp_flag_params" not in st.session_state:
+            st.session_state["_topp_flag_params"] = {}
+        st.session_state["_topp_flag_params"][tool_instance_name] = list(flag_parameters)
+        _fp = self._read_params_for_update(tool_instance_name)
+        if "_flag_params" not in _fp:
+            _fp["_flag_params"] = {}
+        _fp["_flag_params"][tool_instance_name] = list(flag_parameters)
+        # Atomic: a truncate-then-rewrite interrupted here leaves a torn
+        # params.json which every later strict read rejects, wedging this very
+        # method on each render.
+        self.parameter_manager.write_parameters(_fp)
 
         if not display_subsections:
             display_subsection_tabs = False
         if display_subsection_tabs:
             display_subsections = True
 
-        # write defaults ini files
+        # Create pristine ini file (never mutated with custom defaults)
         ini_file_path = Path(self.parameter_manager.ini_dir, f"{topp_tool_name}.ini")
-        ini_existed = ini_file_path.exists()
         if not self.parameter_manager.create_ini(topp_tool_name):
             st.error(f"TOPP tool **'{topp_tool_name}'** not found.")
             return
-        if not ini_existed:
-            # update custom defaults if necessary
-            if custom_defaults:
-                param = poms.Param()
-                poms.ParamXMLFile().load(str(ini_file_path), param)
-                for key, value in custom_defaults.items():
-                    encoded_key = f"{topp_tool_name}:1:{key}".encode()
-                    if encoded_key in param.keys():
-                        param.setValue(encoded_key, value)
-                poms.ParamXMLFile().store(str(ini_file_path), param)
+
+        # Seed custom defaults into params.json under _defaults key
+        if custom_defaults:
+            params = self._read_params_for_update(tool_instance_name)
+            if "_defaults" not in params:
+                params["_defaults"] = {}
+            params["_defaults"][tool_instance_name] = custom_defaults
+            self.parameter_manager.write_parameters(params)
+            # Refresh self.params so widget resolution sees _defaults - reuse
+            # what was just written instead of reading the file back, which
+            # could be torn by a concurrent writer.
+            self.params = params
 
         # read into Param object
         param = poms.Param()
@@ -947,18 +1119,18 @@ def _matches_parameter(pattern: str, key: bytes) -> bool:
                 )
             params.append(p)
 
-        # for each parameter in params_decoded
-        # if a parameter with custom default value exists, use that value
-        # else check if the parameter is already in self.params, if yes take the value from self.params
+        # Build ini_params dict for three-layer merge
+        ini_params = {}
         for p in params:
             name = p["key"].decode().split(":1:")[1]
-            if topp_tool_name in self.params:
-                if name in self.params[topp_tool_name]:
-                    p["value"] = self.params[topp_tool_name][name]
-                elif name in custom_defaults:
-                    p["value"] = custom_defaults[name]
-            elif name in custom_defaults:
-                p["value"] = custom_defaults[name]
+            ini_params[name] = p["value"]
+
+        # Resolve effective values: ini < _defaults < user overrides
+        merged = self.parameter_manager.get_merged_params(tool_instance_name, ini_params=ini_params)
+        for p in params:
+            name = p["key"].decode().split(":1:")[1]
+            if name in merged:
+                p["value"] = merged[name]
             # Ensure list parameters stay as lists after loading from JSON
             # (JSON may store single-item lists as strings)
             if p["original_is_list"] and isinstance(p["value"], str):
@@ -992,7 +1164,7 @@ def _matches_parameter(pattern: str, key: bytes) -> bool:
 
         # Display tool name if required
         if display_tool_name:
-            st.markdown(f"**{topp_tool_name}**")
+            st.markdown(f"**{tool_instance_name}**")
 
         tab_names = [k for k in param_sections.keys() if ":" not in k]
         tabs = None
@@ -1020,8 +1192,11 @@ def display_TOPP_params(params: dict, num_cols):
             cols = st.columns(num_cols)
             i = 0
             for p in params:
-                # get key and name
-                key = f"{self.parameter_manager.topp_param_prefix}{p['key'].decode()}"
+                # get key and name – use tool_instance_name in session state key
+                key_str = p['key'].decode()
+                if tool_instance_name != topp_tool_name:
+                    key_str = key_str.replace(f"{topp_tool_name}:1:", f"{tool_instance_name}:1:", 1)
+                key = f"{self.parameter_manager.topp_param_prefix}{key_str}"
                 name = p["name"]
                 try:
                     # sometimes strings with newline, handle as list
@@ -1385,7 +1560,10 @@ def parameter_section(self, custom_parameter_function) -> None:
                 key="param_import_uploader"
             )
             if up is not None:
-                with open(self.parameter_manager.params_file, "w") as f:
+                # encoding="utf-8" explicitly: the payload is decoded as utf-8
+                # just above, and writing it back in the platform codepage
+                # produced a params.json that no later utf-8 read could decode.
+                with open(self.parameter_manager.params_file, "w", encoding="utf-8") as f:
                     f.write(up.read().decode("utf-8"))
                 self.parameter_manager.clear_parameter_session_state()
                 st.toast("Parameters imported")
@@ -1616,7 +1794,8 @@ def remove_full_paths(d: dict) -> dict:
         general = {}
 
         for k, v in params.items():
-            # skip if v is a file path
+            if k == "_defaults":
+                continue
             if isinstance(v, dict):
                 topp[k] = v
             elif ".py" in k:
@@ -1627,6 +1806,13 @@ def remove_full_paths(d: dict) -> dict:
             else:
                 general[k] = v
 
+        # Merge _defaults into topp so summary shows custom defaults + user overrides
+        defaults = params.get("_defaults", {})
+        for tool_name, default_vals in defaults.items():
+            if tool_name not in topp:
+                topp[tool_name] = {}
+            topp[tool_name] = {**default_vals, **topp.get(tool_name, {})}
+
         markdown = []
 
         def dict_to_markdown(d: dict):
diff --git a/src/workflow/health.py b/src/workflow/health.py
index 6473f9e7..9e5ba99a 100644
--- a/src/workflow/health.py
+++ b/src/workflow/health.py
@@ -1,11 +1,100 @@
 """
-Health check utilities for Redis queue monitoring.
+Health check utilities for Redis queue and shared storage monitoring.
 
-Provides functions to check Redis and worker health status
-for display in the sidebar metrics.
+Provides functions to check Redis and worker health status for display in the
+sidebar metrics, plus the shared storage heartbeat: `probe_storage()` runs on
+the node that holds the mount (from the rq-worker readiness probe),
+`get_storage_status()` is what the sidebar fragment renders.
+
+Three constraints hold for everything in this module:
+
+* **No Streamlit.** The heartbeat writer runs next to the RQ worker, which has
+  no ScriptRunContext - the same constraint `tasks.py` carries.
+* **The readers never touch the filesystem.** A `stat` on a `hard` NFS mount
+  that has wedged blocks in uninterruptible sleep and cannot be killed, so a
+  sidebar fragment re-running every 5 seconds would accumulate unkillable
+  threads: the indicator would become the very hang it exists to report. The
+  mount is touched only by `probe_storage()`, which runs from the readiness
+  probe under a shell `timeout`, in a process nobody waits on.
+* **Every Redis call is bounded.** All of them go through `_redis_client()`,
+  which sets a connect and a socket timeout. An unbounded call is reachable
+  from the sidebar - `get_queue_metrics()` drives a fragment on the session's
+  ScriptRunner thread - so a Redis that is black-holing packets would otherwise
+  freeze the session rather than show it as unavailable.
 """
 
+import logging
 import os
+import socket
+import sys
+import time
+
+logger = logging.getLogger(__name__)
+
+# Shared storage heartbeat: an inverted health check.
+#
+#   rq-worker readiness probe                            sidebar
+#     SET storage:node:<node>  (a worker lives here)  --> reads Redis only
+#     touch .nfs-probe --ok--> SET storage:ok:<node>  -->
+#          \-- blocks on a wedged mount --> storage:ok expires --> goes red
+#
+# Redis' TTL *is* the liveness mechanism, so there is no timeout logic here to
+# get wrong, and nothing in the Streamlit process ever calls into the mount.
+#
+# Two keys, not one, and the order between them is the whole design:
+#
+#   storage:node:<node>  published *before* the mount is touched, so it keeps
+#                        being refreshed by a node whose mount has wedged. This
+#                        is the expected-node baseline. Without it "no key" and
+#                        "no such node" are indistinguishable, and a healthy
+#                        node silently covers for a wedged one.
+#   storage:ok:<node>    published *after* the mount answered. Its absence
+#                        against a present storage:node:<node> is exactly the
+#                        signal the indicator exists to show.
+#
+# STORAGE_SENTINEL_NAME is named here and nowhere else. The readiness probe in
+# k8s/base/rq-worker-deployment.yaml runs `--probe` rather than spelling the
+# path out in YAML, precisely so there is no second copy to drift from this
+# one - drift would show up as a permanently red indicator, not as a lint
+# error. tests/test_storage_health.py runs the probe's command to keep that
+# delegation honest.
+STORAGE_SENTINEL_NAME = ".nfs-probe"
+STORAGE_HEARTBEAT_PREFIX = "storage:ok:"
+STORAGE_NODE_PREFIX = "storage:node:"
+# Four times the readiness probe's periodSeconds (30s): three refreshes may be
+# missed before the indicator goes red, which keeps a slow probe - a cold
+# interpreter on a CPU-saturated worker, a DNS hiccup on the way to Redis -
+# from turning it red while the mount is healthy. It still goes red before the
+# probe's failureThreshold marks the worker NotReady (4 x 30s plus a 20s
+# timeout, ~140s): degradation should be visible before it is fatal. Keep the
+# two in step - a TTL below periodSeconds makes the indicator flicker red
+# between healthy probes.
+STORAGE_HEARTBEAT_TTL = 120
+# Ten probe periods. A node stops being *expected* five minutes after its
+# worker stopped probing at all - a drain, a scale-down, a deleted node - so a
+# node that legitimately went away does not leave the indicator permanently
+# degraded. A wedged mount does not clear it: the registration is written
+# before the mount is touched, so a wedged node keeps re-registering and stays
+# visible for as long as its worker is alive.
+STORAGE_NODE_TTL = 300
+
+DEFAULT_REDIS_URL = "redis://localhost:6379/0"
+DEFAULT_WORKSPACES_DIR = "/workspaces-streamlit-template"
+# Every Redis call made from the Streamlit process is bounded: the sidebar
+# fragment re-runs every 5 seconds and must not sit in a connect() to a Redis
+# that is black-holing packets.
+REDIS_SOCKET_TIMEOUT = 2
+
+
+def _redis_client(redis_url: str):
+    """Connect to Redis with every socket operation bounded."""
+    from redis import Redis
+
+    return Redis.from_url(
+        redis_url,
+        socket_connect_timeout=REDIS_SOCKET_TIMEOUT,
+        socket_timeout=REDIS_SOCKET_TIMEOUT,
+    )
 
 
 def check_redis_health() -> dict:
@@ -15,12 +104,10 @@ def check_redis_health() -> dict:
     Returns:
         Dictionary with health status and metrics
     """
-    redis_url = os.environ.get("REDIS_URL", "redis://localhost:6379/0")
+    redis_url = os.environ.get("REDIS_URL", DEFAULT_REDIS_URL)
 
     try:
-        from redis import Redis
-
-        redis = Redis.from_url(redis_url)
+        redis = _redis_client(redis_url)
         redis.ping()
         info = redis.info()
 
@@ -49,13 +136,12 @@ def check_worker_health() -> dict:
     Returns:
         Dictionary with worker status and metrics
     """
-    redis_url = os.environ.get("REDIS_URL", "redis://localhost:6379/0")
+    redis_url = os.environ.get("REDIS_URL", DEFAULT_REDIS_URL)
 
     try:
-        from redis import Redis
         from rq import Worker, Queue
 
-        redis = Redis.from_url(redis_url)
+        redis = _redis_client(redis_url)
         queue = Queue("openms-workflows", connection=redis)
         workers = Worker.all(connection=redis)
 
@@ -101,11 +187,10 @@ def get_queue_metrics() -> dict:
         return {}
 
     try:
-        from redis import Redis
         from rq import Worker, Queue
 
-        redis_url = os.environ.get("REDIS_URL", "redis://localhost:6379/0")
-        redis = Redis.from_url(redis_url)
+        redis_url = os.environ.get("REDIS_URL", DEFAULT_REDIS_URL)
+        redis = _redis_client(redis_url)
 
         # Test connection
         redis.ping()
@@ -127,3 +212,409 @@ def get_queue_metrics() -> dict:
         }
     except Exception:
         return {"available": False}
+
+
+def _as_text(value) -> str:
+    """Redis hands back bytes or str depending on the client's decoding."""
+    if isinstance(value, bytes):
+        return value.decode(errors="replace")
+    return "" if value is None else str(value)
+
+
+def queue_workers_are_remote() -> bool:
+    """
+    Whether the workflows run on a machine other than this one.
+
+    The sidebar's psutil panel measures *this* process. Whether that is the
+    right machine depends on the deployment, not on `online_deployment`:
+
+    - Kubernetes: Streamlit and rq-worker are separate pods, usually on
+      separate nodes. psutil here would show an idle 2Gi pod while a 64Gi
+      worker saturates, so the panel is hidden.
+    - The full Docker image (and docker-compose): `docker/entrypoint.sh` starts
+      Redis, the RQ workers *and* Streamlit in one container, so psutil is
+      measuring exactly the machine that runs the workflows. The panel stays.
+    - `Dockerfile_simple`: no Redis at all, workflows run in-process. The panel
+      stays - it is the only thing that expander has to show.
+
+    RQ records each worker's hostname at birth, so the question answers itself
+    from data the queue already holds. Uncertainty resolves to False: a
+    possibly-wrong number beats an empty panel, and every failure here (no
+    Redis, no RQ, an unreachable queue, no workers registered) means nothing
+    has *proved* the workers are elsewhere.
+
+    Returns:
+        bool: True only when the queue is reachable, workers are registered,
+            and none of them runs on this host.
+    """
+    redis_url = os.environ.get("REDIS_URL")
+    if not redis_url:
+        return False
+
+    try:
+        from rq import Worker
+
+        client = _redis_client(redis_url)
+        client.ping()
+        hostnames = {
+            _as_text(getattr(worker, "hostname", "")) for worker in Worker.all(connection=client)
+        }
+        hostnames.discard("")
+    except Exception:
+        return False
+
+    return bool(hostnames) and socket.gethostname() not in hostnames
+
+
+def storage_heartbeat_key(node: str) -> str:
+    """
+    Redis key carrying one node's storage heartbeat: its mount answered.
+
+    Keyed per node, never a single shared key: with one key a healthy node
+    would keep refreshing it while another node's mount is wedged, and the
+    indicator would stay green straight through a real outage. The per node
+    keys only deliver that if something also says which nodes are *expected* -
+    see `storage_node_key()`.
+
+    Args:
+        node: Node name, as the Downward API reports `spec.nodeName`.
+
+    Returns:
+        str: The Redis key for that node.
+    """
+    return f"{STORAGE_HEARTBEAT_PREFIX}{node}"
+
+
+def storage_node_key(node: str) -> str:
+    """
+    Redis key registering that a worker lives on this node.
+
+    The expected-node baseline. It is written before the mount is touched, so
+    it survives a wedged mount and makes that node's missing heartbeat visible
+    instead of merely absent. It expires (`STORAGE_NODE_TTL`) so a node that
+    was drained stops being expected.
+
+    Args:
+        node: Node name, as the Downward API reports `spec.nodeName`.
+
+    Returns:
+        str: The Redis key for that node.
+    """
+    return f"{STORAGE_NODE_PREFIX}{node}"
+
+
+def current_node_name() -> str:
+    """
+    Name of the node this process runs on.
+
+    `NODE_NAME` is injected from the Downward API (`spec.nodeName`) in
+    k8s/base/rq-worker-deployment.yaml. Outside Kubernetes - docker-compose, a
+    local run - the container hostname is the closest analogue and keeps the
+    key per writer rather than shared.
+
+    Returns:
+        str: The node name.
+    """
+    return os.environ.get("NODE_NAME") or socket.gethostname()
+
+
+def register_storage_node(node: str = "", ttl: int = STORAGE_NODE_TTL) -> bool:
+    """
+    Register that a worker is running on this node.
+
+    Deliberately says nothing about the mount, and is therefore called *before*
+    the mount is touched: a node whose mount has wedged must keep answering
+    "I exist" so that its missing heartbeat reads as a fault rather than as an
+    absent node.
+
+    Never raises: a Redis that is down says nothing about the mount, and the
+    caller's exit code is a statement about storage.
+
+    Args:
+        node: Node name to register. Defaults to `current_node_name()`.
+        ttl: Seconds the registration stays valid.
+
+    Returns:
+        bool: True if the registration was published.
+    """
+    node = node or current_node_name()
+    redis_url = os.environ.get("REDIS_URL", DEFAULT_REDIS_URL)
+
+    try:
+        client = _redis_client(redis_url)
+        client.set(storage_node_key(node), str(int(time.time())), ex=int(ttl))
+        return True
+    except Exception as e:
+        logger.warning("Could not register the storage node %s: %s", node, e)
+        return False
+
+
+def touch_storage_sentinel(workspaces_dir: str = "") -> bool:
+    """
+    Write to the shared volume, the way the readiness probe means it.
+
+    A write, not a `stat`: with the default `actimeo` a stat can be answered
+    from the client's attribute cache while the server is gone, which is a
+    false green. `utime` is a metadata write, so it always reaches the server,
+    and creating the file first means a fresh volume passes instead of failing
+    forever on a file nothing else makes. The sentinel is dot-named and is not
+    a directory, so clean-up-workspaces.py skips it twice over.
+
+    This is the one function in this module that touches the filesystem, and it
+    is only ever called from `probe_storage()` in the worker's readiness probe:
+    on a `hard` mount this call can block in uninterruptible sleep, which is
+    survivable only in a process nobody waits on and a shell `timeout` is
+    holding the stopwatch for.
+
+    Args:
+        workspaces_dir: Directory holding the sentinel. Defaults to
+            `$WORKSPACES_DIR`, then `DEFAULT_WORKSPACES_DIR`.
+
+    Returns:
+        bool: True if the volume accepted the write.
+    """
+    directory = (
+        workspaces_dir
+        or os.environ.get("WORKSPACES_DIR")
+        or DEFAULT_WORKSPACES_DIR
+    )
+    sentinel = os.path.join(directory, STORAGE_SENTINEL_NAME)
+
+    try:
+        # Append mode: create if missing, never truncate. The open alone can be
+        # served from the client's cache, which is why utime follows.
+        with open(sentinel, "ab"):
+            pass
+        os.utime(sentinel, None)
+        return True
+    except Exception as e:
+        logger.warning("The shared volume did not accept a write at %s: %s", sentinel, e)
+        return False
+
+
+def write_storage_heartbeat(node: str = "", ttl: int = STORAGE_HEARTBEAT_TTL) -> bool:
+    """
+    Publish this node's storage heartbeat: its mount answered just now.
+
+    **Verifies nothing.** Call `probe_storage()` unless the mount has already
+    been confirmed in this same process - this function on its own publishes a
+    green light for a volume it never touched. It is separate so that the
+    blocking half lives in `touch_storage_sentinel()`, in a process that may
+    block forever and be abandoned, which the Redis write must not be.
+
+    Expiry is the whole mechanism - a heartbeat is a claim with a deadline, not
+    a flag somebody has to remember to clear. The node registration is
+    refreshed alongside it, in one round trip, so a heartbeat always implies an
+    expected node.
+
+    Never raises: a Redis that is down says nothing about the mount, and the
+    caller's exit code is a statement about storage.
+
+    Args:
+        node: Node name to key the heartbeat under. Defaults to
+            `current_node_name()`.
+        ttl: Seconds the heartbeat stays valid.
+
+    Returns:
+        bool: True if the heartbeat was published.
+    """
+    node = node or current_node_name()
+    redis_url = os.environ.get("REDIS_URL", DEFAULT_REDIS_URL)
+
+    try:
+        client = _redis_client(redis_url)
+        # SET ... EX rather than SETEX: same single atomic write-with-deadline,
+        # without the command Redis deprecated in 2.6.12. Pipelined so the two
+        # keys cost one round trip, not two.
+        stamp = str(int(time.time()))
+        pipeline = client.pipeline()
+        pipeline.set(storage_heartbeat_key(node), stamp, ex=int(ttl))
+        pipeline.set(storage_node_key(node), stamp, ex=int(STORAGE_NODE_TTL))
+        pipeline.execute()
+        return True
+    except Exception as e:
+        # Not an error worth failing a probe over, but an operator chasing a red
+        # indicator against a healthy mount needs to find this line.
+        logger.warning("Could not publish the storage heartbeat for %s: %s", node, e)
+        return False
+
+
+def probe_storage(workspaces_dir: str = "", node: str = "") -> bool:
+    """
+    The rq-worker readiness probe, in one process.
+
+    Ordering is the contract, and it is load-bearing in both directions:
+
+    1. `register_storage_node()` - unconditional, before anything can block, so
+       a node with a wedged mount still counts as expected.
+    2. `touch_storage_sentinel()` - the only call that can block. If it fails
+       or never returns, the probe fails and no heartbeat is published.
+    3. `write_storage_heartbeat()` - reached only from a mount that answered.
+
+    Publishing is best effort in both directions: a Redis that is down says
+    nothing about the mount, so it must not fail the probe, and a mount that
+    did not answer must not publish regardless of how healthy Redis is.
+
+    Args:
+        workspaces_dir: Directory holding the sentinel. Defaults to
+            `$WORKSPACES_DIR`.
+        node: Node name. Defaults to `current_node_name()`.
+
+    Returns:
+        bool: True if the shared volume accepted a write.
+    """
+    node = node or current_node_name()
+
+    register_storage_node(node)
+    if not touch_storage_sentinel(workspaces_dir):
+        return False
+    write_storage_heartbeat(node)
+    return True
+
+
+def get_storage_status() -> dict:
+    """
+    Read the shared storage heartbeats for the sidebar indicator.
+
+    Reads Redis and nothing else. Never stat the mount from here: on a `hard`
+    mount that call blocks in uninterruptible sleep and the indicator becomes
+    the hang it is supposed to report.
+
+    Follows `get_queue_metrics()`'s distinction between "not applicable" and
+    "cannot tell":
+
+    - `{}` - no `REDIS_URL`, or a Redis nothing has ever published a heartbeat
+      to. Both mean there is no shared storage being reported here and the
+      sidebar renders nothing. The second case is what keeps every non
+      Kubernetes deployment of the image quiet: `Dockerfile` bakes in both
+      `online_deployment` and a `REDIS_URL`, but the readiness probe that
+      writes the heartbeat exists only in `k8s/`, and a permanent red tick on
+      docker-compose would be exactly the wrong-layer alarm this indicator was
+      built to avoid.
+    - `{"available": False, "state": "unknown", ...}` - Redis is down, which
+      says nothing about the mount. Reporting that as unreachable storage sends
+      an operator to debug the wrong layer.
+    - `{"available": True, "state": "connected"}` - every expected node's mount
+      answered within its TTL.
+    - `{"available": True, "state": "degraded"}` - some did and some did not.
+      This is the case per node keys exist for: with one shared key, or by
+      collapsing the keys with `any()`, a healthy node would cover for a node
+      whose mount is wedged and the indicator would stay green through a real
+      outage.
+    - `{"available": True, "state": "unreachable"}` - no expected node's mount
+      answered.
+
+    Returns:
+        dict: Empty when not applicable, otherwise `available`, `state`,
+            `nodes` (reporting a healthy mount), `stale_nodes` (expected but
+            silent) and, when Redis is down, `error`.
+    """
+    redis_url = os.environ.get("REDIS_URL")
+    if not redis_url:
+        return {}
+
+    try:
+        client = _redis_client(redis_url)
+
+        # Test connection
+        client.ping()
+
+        # SCAN, not KEYS: KEYS blocks the whole server for the length of the
+        # keyspace, and this runs from a sidebar fragment every 5 seconds.
+        healthy = _scan_suffixes(client, STORAGE_HEARTBEAT_PREFIX)
+        expected = _scan_suffixes(client, STORAGE_NODE_PREFIX)
+    except Exception as e:
+        return {
+            "available": False,
+            "state": "unknown",
+            "nodes": [],
+            "stale_nodes": [],
+            "error": str(e),
+        }
+
+    # A heartbeat implies an expected node even if the registration expired
+    # first (a much longer TTL, so only reachable if Redis lost the key).
+    expected |= healthy
+    if not expected:
+        return {}
+
+    stale = expected - healthy
+    if not healthy:
+        state = "unreachable"
+    elif stale:
+        state = "degraded"
+    else:
+        state = "connected"
+
+    return {
+        "available": True,
+        "state": state,
+        "nodes": sorted(healthy),
+        "stale_nodes": sorted(stale),
+    }
+
+
+def _scan_suffixes(client, prefix: str) -> set:
+    """Every key under `prefix`, with the prefix stripped off."""
+    found = set()
+    for key in client.scan_iter(match=f"{prefix}*", count=100):
+        found.add(_as_text(key)[len(prefix):])
+    found.discard("")
+    return found
+
+
+def _cli(argv=None) -> int:
+    """
+    Command line entry point, used by the rq-worker readiness probe.
+
+    `--probe` is the probe itself: register the node, write to the shared
+    volume, and publish the heartbeat only if that write succeeded. `--status`
+    is for a human with a shell (`kubectl exec ... -- python -m
+    src.workflow.health --status`).
+
+    There is deliberately no flag that publishes a heartbeat without checking
+    the mount. It would look like the obvious remedy for a red indicator and
+    would turn it green while the volume stayed wedged.
+    """
+    import argparse
+    import json
+
+    parser = argparse.ArgumentParser(
+        prog="python -m src.workflow.health",
+        description="Shared storage heartbeat for the OpenMS web app.",
+    )
+    parser.add_argument(
+        "--probe",
+        action="store_true",
+        help=(
+            "confirm the shared volume accepts a write and publish this node's "
+            "storage heartbeat; exit 1 if the volume did not answer"
+        ),
+    )
+    parser.add_argument(
+        "--status",
+        action="store_true",
+        help="print the storage status the sidebar renders, as JSON",
+    )
+    args = parser.parse_args(argv)
+
+    if args.status:
+        print(json.dumps(get_storage_status(), indent=2))
+        return 0
+    if args.probe:
+        if probe_storage():
+            return 0
+        directory = os.environ.get("WORKSPACES_DIR") or DEFAULT_WORKSPACES_DIR
+        print(
+            f"storage probe failed: {os.path.join(directory, STORAGE_SENTINEL_NAME)} "
+            "did not accept a write",
+            file=sys.stderr,
+        )
+        return 1
+
+    parser.print_help()
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(_cli())
diff --git a/src/workflow/settings_io.py b/src/workflow/settings_io.py
new file mode 100644
index 00000000..f688b07b
--- /dev/null
+++ b/src/workflow/settings_io.py
@@ -0,0 +1,151 @@
+"""
+Streamlit free access to settings.json.
+
+Inside the RQ work horse there is no ScriptRunContext, so `st.session_state` is
+an empty global mock and every setting read through session state silently
+falls back to its hardcoded default there (docs/storage-defect-register.md G1). Code which has to
+behave the same in the worker and in a Streamlit session reads the settings
+from disk through this module instead.
+
+Kept dependency free on purpose: `src/workflow/tasks.py` runs inside the worker
+and must stay importable without Streamlit.
+"""
+
+import json
+import logging
+import math
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+SETTINGS_FILE_NAME = "settings.json"
+
+CGROUP_V2_CPU_MAX = Path("/sys/fs/cgroup/cpu.max")
+CGROUP_V1_CPU_QUOTA = Path("/sys/fs/cgroup/cpu/cpu.cfs_quota_us")
+CGROUP_V1_CPU_PERIOD = Path("/sys/fs/cgroup/cpu/cpu.cfs_period_us")
+
+
+def load_settings(path: Path | str = SETTINGS_FILE_NAME) -> dict:
+    """
+    Read the app settings from disk.
+
+    The path is resolved against the process working directory by default,
+    which is how every other reader in this repository resolves it (app.py:8,
+    src/common/common.py:362, test_gui.py:14). Deliberately not memoised: the
+    caller decides how long a value stays valid.
+
+    Settings are only ever read here, never written back, so tolerating an
+    unreadable file cannot destroy it - unlike a workflow's params.json, see
+    ParameterManager.read_parameters_strict().
+
+    Total by construction: it never raises, whatever is on disk. The two other
+    readers in this repository (app.py, src/common/common.py) open settings.json
+    with the platform default encoding, so a file hand-edited on a cp1252 box
+    loads there; decoding with errors="replace" here keeps this loader from
+    being the one place that hard-fails on it - inside the RQ work horse, where
+    nothing catches it and the job dies.
+
+    Args:
+        path: Location of the settings file.
+
+    Returns:
+        dict: The parsed settings, or an empty dict if the file is absent,
+            unreadable or does not hold a JSON object. Callers are expected to
+            supply their own defaults per key.
+    """
+    settings_file = Path(path)
+    try:
+        with open(settings_file, "r", encoding="utf-8", errors="replace") as f:
+            settings = json.load(f)
+    except FileNotFoundError:
+        logger.warning(
+            "No %s in %s, falling back to default settings.", settings_file, Path.cwd()
+        )
+        return {}
+    except (ValueError, OSError) as e:
+        # ValueError covers json.JSONDecodeError and UnicodeDecodeError, which
+        # is a ValueError rather than an OSError - the gap that let an
+        # undecodable settings.json escape a handler documented as total.
+        logger.warning(
+            "Could not read %s (%s), falling back to default settings.", settings_file, e
+        )
+        return {}
+
+    if not isinstance(settings, dict):
+        logger.warning(
+            "%s does not hold a JSON object (found %s), falling back to default settings.",
+            settings_file,
+            type(settings).__name__,
+        )
+        return {}
+    return settings
+
+
+def _read_int(path: Path) -> int | None:
+    """Read a single integer out of a cgroup pseudo-file, or None."""
+    try:
+        return int(path.read_text(encoding="utf-8").strip())
+    except (OSError, ValueError):
+        return None
+
+
+def detect_cpu_quota() -> int | None:
+    """
+    Number of CPUs this container is actually allowed to use, from its cgroup.
+
+    Returns None whenever no CPU ceiling can be established - not on Linux, not
+    in a container, or in a container with no quota set - and the caller then
+    falls back to its configured value. None is "do not know", never "one".
+
+    Why this exists: the rq-worker runs at ``requests.cpu == limits.cpu``
+    (Guaranteed QoS), so its pod spec IS its CPU allocation, and the two are
+    sized per deployment by the memory-tier components. A single
+    ``max_threads.online`` in settings.json cannot be right for both a 4 cpu
+    worker and a 20 cpu one, and the one that was there described neither.
+
+    Both cgroup generations are handled:
+
+    * v2 (``/sys/fs/cgroup/cpu.max``) holds ``"<quota> <period>"``, or
+      ``"max <period>"`` when unconstrained.
+    * v1 (``cpu.cfs_quota_us`` / ``cpu.cfs_period_us``) uses a quota of ``-1``
+      to mean unconstrained.
+
+    Rounded UP: Kubernetes turns ``cpu: 1500m`` into a quota of 1.5 cores, and
+    two runnable threads throttled to 1.5 cores finish sooner than one thread
+    using 1.0 and leaving 0.5 idle.
+
+    Returns:
+        int | None: CPU count, at least 1, or None if no quota applies.
+    """
+    quota_us: float | None = None
+    period_us: int | None = None
+
+    try:
+        raw = CGROUP_V2_CPU_MAX.read_text(encoding="utf-8").strip()
+    except OSError:
+        raw = ""
+    if raw:
+        parts = raw.split()
+        # "max <period>" is the unconstrained case and must read as None, not
+        # as a fallthrough to v1 - a host with both hierarchies mounted would
+        # otherwise answer from the wrong one.
+        if parts[0] == "max":
+            return None
+        try:
+            quota_us = float(parts[0])
+            period_us = int(parts[1]) if len(parts) > 1 else 100000
+        except (IndexError, ValueError):
+            logger.warning("Unparsable %s: %r", CGROUP_V2_CPU_MAX, raw)
+            return None
+    else:
+        v1_quota = _read_int(CGROUP_V1_CPU_QUOTA)
+        if v1_quota is None or v1_quota <= 0:
+            # -1 is the documented "no limit"; 0 is not a legal quota and is
+            # treated the same rather than propagated as a zero CPU budget.
+            return None
+        quota_us = float(v1_quota)
+        period_us = _read_int(CGROUP_V1_CPU_PERIOD) or 100000
+
+    if not quota_us or not period_us or period_us <= 0:
+        return None
+    return max(1, math.ceil(quota_us / period_us))
diff --git a/src/workflow/tasks.py b/src/workflow/tasks.py
index 6ae9e151..51bd8e27 100644
--- a/src/workflow/tasks.py
+++ b/src/workflow/tasks.py
@@ -12,6 +12,17 @@
 from pathlib import Path
 
 
+class WorkflowExecutionError(RuntimeError):
+    """
+    Raised when a workflow's execution() reports failure by returning False.
+
+    RQ records a job as failed only if the job function raises, so an
+    application level failure has to be turned into an exception here.
+    Returning a result dict instead leaves the FailedJobRegistry empty and
+    health.py's failed_jobs metric structurally zero.
+    """
+
+
 def execute_workflow(
     workflow_dir: str,
     workflow_class: str,
@@ -30,6 +41,14 @@ def execute_workflow(
 
     Returns:
         Dictionary with execution results
+
+    Raises:
+        Exception: Anything raised while setting up or running the workflow is
+            re-raised after the failure has been written to the workflow logs,
+            and a WorkflowExecutionError if execution() returned False. RQ
+            needs the job function to raise to record the job as failed. A
+            legacy execution() returning None is accepted as success with a
+            deprecation warning in the workflow log.
     """
     try:
         from rq import get_current_job
@@ -62,7 +81,10 @@ def execute_workflow(
         # Load parameters from saved params.json
         params_file = workflow_path / "params.json"
         if params_file.exists():
-            with open(params_file, "r") as f:
+            # encoding="utf-8" explicitly, matching every other reader and
+            # writer of params.json: the platform codepage here would decode a
+            # file written elsewhere differently, or fail outright.
+            with open(params_file, "r", encoding="utf-8") as f:
                 params = json.load(f)
         else:
             params = {}
@@ -108,10 +130,35 @@ def execute_workflow(
 
         _update_progress(job, 0.15, "Executing workflow steps...")
 
-        # Execute the workflow
-        workflow.execution()
-
-        # Log workflow completion
+        # Execute the workflow. It reports success with a bool
+        # (WorkflowManager.execution is declared -> bool), same as the local
+        # mode in WorkflowManager.workflow_process.
+        success = workflow.execution()
+
+        if success is None:
+            # Migration shim for workflows written against the older example,
+            # which was annotated -> None and returned nothing. Those
+            # subclasses live in downstream repositories (quantms-web,
+            # umetaflow, FLASHApp) and cannot be fixed in the same commit as
+            # this file, so treating their None as a failure would report every
+            # successful queued run as failed the moment they rebase. Accepted
+            # as success, loudly, so they have a runway; explicit False is
+            # still a failure.
+            logger.log(
+                "WARNING: execution() returned None and was treated as success. "
+                "Annotate it '-> bool' and return True on success / False on "
+                "failure - see .claude/skills/create-workflow.md. A future "
+                "release will treat None as a failure.",
+                0,
+            )
+        elif not success:
+            raise WorkflowExecutionError(
+                f"Workflow execution reported failure (returned {success!r})"
+            )
+
+        # Log workflow completion. Only write the marker for a run which
+        # actually succeeded, it is what classify_log_outcome reads to tell a
+        # finished run from a failed one.
         logger.log("WORKFLOW FINISHED")
 
         _update_progress(job, 1.0, "Workflow completed")
@@ -126,8 +173,6 @@ def execute_workflow(
         }
 
     except Exception as e:
-        error_msg = f"Workflow failed: {str(e)}\n{traceback.format_exc()}"
-
         # Log error to workflow logs
         try:
             log_dir = workflow_path / "logs"
@@ -137,7 +182,10 @@ def execute_workflow(
                 log_file = log_dir / log_name
                 with open(log_file, "a") as f:
                     f.write(f"\n\nERROR: {str(e)}\n")
-                    f.write(traceback.format_exc())
+                    # A workflow reporting failure by returning False is not a
+                    # crash, the reason is in the tool output above.
+                    if not isinstance(e, WorkflowExecutionError):
+                        f.write(traceback.format_exc())
         except Exception:
             pass
 
@@ -148,11 +196,10 @@ def execute_workflow(
         except Exception:
             pass
 
-        return {
-            "success": False,
-            "workflow_dir": str(workflow_path),
-            "error": error_msg
-        }
+        # Re-raise so RQ moves the job into the FailedJobRegistry. Returning a
+        # {"success": False} dict here looked like a normal return to RQ, which
+        # recorded every crashed workflow as finished successfully.
+        raise
 
 
 def _update_progress(job, progress: float, step: str) -> None:
diff --git a/tests/test_command_executor_run_python.py b/tests/test_command_executor_run_python.py
new file mode 100644
index 00000000..89e2358d
--- /dev/null
+++ b/tests/test_command_executor_run_python.py
@@ -0,0 +1,184 @@
+"""
+The ``run_python()`` result contract.
+
+``CommandExecutor.run_topp()`` returns a bool and ``execution()`` gates on it.
+``run_python()`` looked like it did the same — the shipped workflow guards both
+of its Python steps with ``if not self.executor.run_python(...)`` — but it was
+annotated ``-> None`` and simply discarded the bool ``run_command()`` handed
+back, at every one of its branches. So those guards were dead code: a Python
+tool that exited non-zero still produced ``execution() == True``,
+``tasks.execute_workflow`` still wrote the ``WORKFLOW FINISHED`` marker, and
+``classify_log_outcome`` still reported "finished" next to the
+``ERROR: Command failed with exit code`` line already in the log.
+
+That is invisible from ``tests/test_tasks.py``, which drives a ``MagicMock``
+executor: ``run_python.return_value = False`` is a value the real method could
+not produce, so the parametrized "python-export-fails" case certified a code
+path that could never run. These tests pin the real thing.
+"""
+import json
+import os
+import sys
+from pathlib import Path
+from unittest.mock import MagicMock
+
+import pytest
+
+# Add project root to path for imports
+PROJECT_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+sys.path.append(PROJECT_ROOT)
+
+# ---------------------------------------------------------------------------
+# Import with `streamlit` and `pyopenms` mocked at the sys.modules level,
+# mirroring tests/test_topp_flag_parameters.py. run_python() needs neither: it
+# reads params.json through ParameterManager and shells out through
+# run_command(), which is stubbed below.
+# ---------------------------------------------------------------------------
+mock_streamlit = MagicMock()
+mock_streamlit.session_state = {}
+
+_original_streamlit = sys.modules.get("streamlit")
+_original_pyopenms = sys.modules.get("pyopenms")
+sys.modules["streamlit"] = mock_streamlit
+if _original_pyopenms is None:
+    sys.modules["pyopenms"] = MagicMock()
+
+from src.workflow.ParameterManager import ParameterManager
+from src.workflow.CommandExecutor import CommandExecutor
+
+# Restore the original modules so other test files import the real ones. The
+# classes imported above keep their module-level `st`/`poms` bound to the mocks.
+if _original_streamlit is not None:
+    sys.modules["streamlit"] = _original_streamlit
+else:
+    sys.modules.pop("streamlit", None)
+if _original_pyopenms is None:
+    sys.modules.pop("pyopenms", None)
+
+for _key in list(sys.modules.keys()):
+    if _key.startswith("src.workflow"):
+        sys.modules.pop(_key, None)
+
+
+SCRIPT_WITH_DEFAULTS = '''DEFAULTS = [
+    {"key": "in", "value": [], "hide": True},
+    {"key": "my-param", "value": 5, "name": "My Parameter"},
+]
+'''
+
+SCRIPT_WITHOUT_DEFAULTS = "PLACEHOLDER = 1\n"
+
+
+def _executor(tmp_path, run_command_result):
+    """A CommandExecutor whose run_command() reports the given exit status."""
+    executor = CommandExecutor(tmp_path, MagicMock(), ParameterManager(tmp_path))
+    executor.run_command = MagicMock(return_value=run_command_result)
+    return executor
+
+
+def _write_tool(tmp_path, source=SCRIPT_WITH_DEFAULTS, name="example_tool.py"):
+    script = tmp_path / name
+    script.write_text(source, encoding="utf-8")
+    return script
+
+
+@pytest.mark.parametrize("exit_status", [True, False], ids=["exit-0", "exit-non-zero"])
+def test_run_python_reports_the_scripts_exit_status(tmp_path, exit_status):
+    """
+    The bool from run_command() has to reach the caller.
+
+    Without it every `if not self.executor.run_python(...)` in execution() is
+    dead code and a failed Python tool is reported as a completed workflow.
+    """
+    executor = _executor(tmp_path, exit_status)
+    script = _write_tool(tmp_path)
+
+    result = executor.run_python(str(script), {"in": ["a.mzML"]})
+
+    assert result is exit_status, (
+        f"run_python() returned {result!r} for a script that exited "
+        f"{'0' if exit_status else 'non-zero'}; it must return the same bool "
+        "run_topp() does, or execution() cannot tell the two apart"
+    )
+    assert executor.run_command.call_count == 1
+
+
+def test_run_python_without_defaults_reports_the_exit_status(tmp_path):
+    """The no-DEFAULTS branch runs the script too, so it reports on it too."""
+    executor = _executor(tmp_path, False)
+    script = _write_tool(tmp_path, SCRIPT_WITHOUT_DEFAULTS, "bare_tool.py")
+
+    assert executor.run_python(str(script)) is False
+    assert executor.run_command.call_args.args[0] == [sys.executable, str(script)]
+
+
+def test_run_python_passes_the_parameters_file_and_cleans_it_up(tmp_path):
+    """
+    The DEFAULTS branch writes a temporary params file, passes it as argv and
+    removes it. Pinned alongside the return value so returning early on failure
+    cannot leak it into the workflow directory.
+    """
+    executor = _executor(tmp_path, False)
+    script = _write_tool(tmp_path)
+
+    executor.run_python(str(script), {"in": ["a.mzML"]})
+
+    command = executor.run_command.call_args.args[0]
+    assert command[:2] == [sys.executable, str(script)]
+    assert not Path(command[2]).exists(), (
+        "the temporary parameter file was left behind in the workflow directory"
+    )
+
+
+def test_run_python_passes_input_output_and_stored_parameters(tmp_path):
+    """
+    Guards the argv the exit status is reported *about*: DEFAULTS, overridden by
+    the stored params.json entries for this script, overridden by input_output.
+    """
+    pm = ParameterManager(tmp_path)
+    script = _write_tool(tmp_path)
+    pm.params_file.write_text(
+        json.dumps({f"{script.name}:my-param": 42, "unrelated": 1}), encoding="utf-8"
+    )
+
+    executor = CommandExecutor(tmp_path, MagicMock(), pm)
+    captured = {}
+
+    def capture(command):
+        captured["params"] = json.loads(
+            Path(command[2]).read_text(encoding="utf-8")
+        )
+        return True
+
+    executor.run_command = MagicMock(side_effect=capture)
+
+    assert executor.run_python(str(script), {"in": ["a.mzML"]}) is True
+    assert captured["params"]["my-param"] == 42
+    assert captured["params"]["in"] == ["a.mzML"]
+    assert "unrelated" not in captured["params"]
+
+
+def test_missing_script_returns_false_instead_of_raising(tmp_path):
+    """
+    A script that is nowhere to be found used to log and fall through into
+    importlib, raising out of execution() rather than reporting a failed step -
+    and in queue mode that traceback is all the user gets.
+    """
+    executor = _executor(tmp_path, True)
+
+    assert executor.run_python("definitely-not-a-real-tool") is False
+    executor.run_command.assert_not_called()
+
+
+def test_defaults_of_the_wrong_shape_is_not_reported_as_success(tmp_path):
+    """
+    DEFAULTS must be the documented list of parameter dicts. Anything else runs
+    nothing at all, which is a failed step, not a successful one - reporting it
+    as success would put the WORKFLOW FINISHED marker on a run that skipped a
+    step silently.
+    """
+    executor = _executor(tmp_path, True)
+    script = _write_tool(tmp_path, 'DEFAULTS = {"my-param": 5}\n', "dict_tool.py")
+
+    assert executor.run_python(str(script)) is False
+    executor.run_command.assert_not_called()
diff --git a/tests/test_parameter_defaults.py b/tests/test_parameter_defaults.py
new file mode 100644
index 00000000..9ccd679e
--- /dev/null
+++ b/tests/test_parameter_defaults.py
@@ -0,0 +1,363 @@
+"""
+Tests for get_merged_params() and the refactored get_topp_parameters().
+
+This module verifies the three-layer parameter merge:
+  ini defaults < _defaults < user overrides
+"""
+import os
+import sys
+import json
+import pytest
+import tempfile
+from pathlib import Path
+from unittest.mock import MagicMock
+
+# Add project root to path for imports
+PROJECT_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+sys.path.append(PROJECT_ROOT)
+
+# Mock streamlit before importing ParameterManager so that the imported module
+# uses a controllable `st.session_state` (a plain dict) instead of the real one,
+# which requires a running Streamlit app context.
+mock_streamlit = MagicMock()
+mock_streamlit.session_state = {}
+
+# Temporarily replace streamlit in sys.modules so that ParameterManager's
+# `import streamlit as st` picks up the mock. Restore immediately after import
+# so other test files (e.g., test_gui.py AppTest) get the real streamlit.
+_original_streamlit = sys.modules.get('streamlit')
+sys.modules['streamlit'] = mock_streamlit
+
+from src.workflow.ParameterManager import ParameterManager
+
+if _original_streamlit is not None:
+    sys.modules['streamlit'] = _original_streamlit
+else:
+    sys.modules.pop('streamlit', None)
+
+# Remove cached src.workflow modules that were imported with mocked streamlit so
+# that AppTest (in test_gui.py) re-imports them fresh with the real package.
+for _key in list(sys.modules.keys()):
+    if _key.startswith('src.workflow'):
+        sys.modules.pop(_key, None)
+
+
+@pytest.fixture(autouse=True)
+def reset_streamlit_state():
+    """Reset mock streamlit session state before each test."""
+    mock_streamlit.session_state.clear()
+    yield
+
+
+@pytest.fixture
+def temp_workflow_dir():
+    """Create a temporary workflow directory for testing."""
+    with tempfile.TemporaryDirectory() as tmpdir:
+        workflow_dir = Path(tmpdir) / "test-workflow"
+        workflow_dir.mkdir()
+        ini_dir = workflow_dir / "ini"
+        ini_dir.mkdir()
+        yield workflow_dir
+
+
+class TestGetMergedParams:
+    """Tests for ParameterManager.get_merged_params()."""
+
+    def test_returns_ini_params_when_no_json(self, temp_workflow_dir):
+        """ini params returned when params.json doesn't exist."""
+        pm = ParameterManager(temp_workflow_dir)
+        ini_params = {"algorithm:param": 1.0, "algorithm:other": "hello"}
+
+        result = pm.get_merged_params("SomeTool", ini_params=ini_params)
+
+        assert result == {"algorithm:param": 1.0, "algorithm:other": "hello"}
+
+    def test_defaults_override_ini(self, temp_workflow_dir):
+        """_defaults layer overrides ini values."""
+        pm = ParameterManager(temp_workflow_dir)
+        params_json = {
+            "_defaults": {"SomeTool": {"algorithm:param": 42.0}}
+        }
+        with open(pm.params_file, "w") as f:
+            json.dump(params_json, f)
+
+        result = pm.get_merged_params("SomeTool", ini_params={"algorithm:param": 1.0})
+
+        assert result["algorithm:param"] == 42.0
+
+    def test_user_overrides_defaults(self, temp_workflow_dir):
+        """User overrides take priority over _defaults."""
+        pm = ParameterManager(temp_workflow_dir)
+        params_json = {
+            "_defaults": {"SomeTool": {"algorithm:param": 42.0}},
+            "SomeTool": {"algorithm:param": 99.0}
+        }
+        with open(pm.params_file, "w") as f:
+            json.dump(params_json, f)
+
+        result = pm.get_merged_params("SomeTool", ini_params={"algorithm:param": 1.0})
+
+        assert result["algorithm:param"] == 99.0
+
+    def test_full_three_layer_merge(self, temp_workflow_dir):
+        """All three layers merge correctly: ini < _defaults < user."""
+        pm = ParameterManager(temp_workflow_dir)
+        params_json = {
+            "_defaults": {
+                "SomeTool": {
+                    "algorithm:param_a": 10.0,  # overrides ini
+                    "algorithm:param_b": 20.0,  # overrides ini, NOT overridden by user
+                }
+            },
+            "SomeTool": {
+                "algorithm:param_a": 99.0,  # overrides _defaults
+                "algorithm:param_c": 55.0,  # only in user
+            }
+        }
+        with open(pm.params_file, "w") as f:
+            json.dump(params_json, f)
+
+        ini_params = {
+            "algorithm:param_a": 1.0,
+            "algorithm:param_b": 2.0,
+            "algorithm:param_d": 3.0,  # only in ini
+        }
+
+        result = pm.get_merged_params("SomeTool", ini_params=ini_params)
+
+        assert result["algorithm:param_a"] == 99.0   # user wins
+        assert result["algorithm:param_b"] == 20.0   # _defaults wins over ini
+        assert result["algorithm:param_c"] == 55.0   # user-only key present
+        assert result["algorithm:param_d"] == 3.0    # ini-only key present
+
+    def test_no_ini_params(self, temp_workflow_dir):
+        """Works when ini_params is None."""
+        pm = ParameterManager(temp_workflow_dir)
+        params_json = {
+            "_defaults": {"SomeTool": {"algorithm:param": 42.0}},
+            "SomeTool": {"algorithm:other": 7.0}
+        }
+        with open(pm.params_file, "w") as f:
+            json.dump(params_json, f)
+
+        result = pm.get_merged_params("SomeTool")
+
+        assert result["algorithm:param"] == 42.0
+        assert result["algorithm:other"] == 7.0
+
+    def test_different_instances_same_tool(self, temp_workflow_dir):
+        """Different instance names get independent _defaults and user overrides."""
+        pm = ParameterManager(temp_workflow_dir)
+        params_json = {
+            "_defaults": {
+                "IDFilter_step1": {"score:min": 0.05},
+                "IDFilter_step2": {"score:min": 0.01},
+            },
+            "IDFilter_step1": {"score:min": 0.001},
+        }
+        with open(pm.params_file, "w") as f:
+            json.dump(params_json, f)
+
+        result1 = pm.get_merged_params("IDFilter_step1", ini_params={"score:min": 0.5})
+        result2 = pm.get_merged_params("IDFilter_step2", ini_params={"score:min": 0.5})
+
+        assert result1["score:min"] == 0.001   # user override for step1
+        assert result2["score:min"] == 0.01    # _defaults for step2 (no user override)
+
+    def test_empty_params_json(self, temp_workflow_dir):
+        """Returns empty dict when params.json is empty and no ini_params."""
+        pm = ParameterManager(temp_workflow_dir)
+        with open(pm.params_file, "w") as f:
+            json.dump({}, f)
+
+        result = pm.get_merged_params("SomeTool")
+
+        assert result == {}
+
+
+class TestGetToppParametersWithDefaults:
+
+    def test_get_topp_parameters_includes_defaults(self, temp_workflow_dir):
+        """get_topp_parameters merges _defaults between ini and user values."""
+        pm = ParameterManager(temp_workflow_dir)
+        params_json = {
+            "_defaults": {"SomeTool": {"algorithm:param": 42.0}},
+            "SomeTool": {"algorithm:other": 99.0}
+        }
+        with open(pm.params_file, "w") as f:
+            json.dump(params_json, f)
+
+        result = pm.get_merged_params("SomeTool", ini_params={"algorithm:param": 1.0})
+        assert result["algorithm:param"] == 42.0
+        assert result["algorithm:other"] == 99.0
+
+
+class TestDefaultsSeeding:
+
+    def test_seed_writes_defaults_to_params_json(self, temp_workflow_dir):
+        """Seeding creates _defaults entry in params.json."""
+        pm = ParameterManager(temp_workflow_dir)
+        custom_defaults = {"param_a": 10.0, "param_b": "fast"}
+
+        # Simulate what input_TOPP seeding does
+        params = pm.get_parameters_from_json()
+        if "_defaults" not in params:
+            params["_defaults"] = {}
+        params["_defaults"]["MyTool"] = custom_defaults
+        with open(pm.params_file, "w") as f:
+            json.dump(params, f)
+
+        # Verify
+        loaded = pm.get_parameters_from_json()
+        assert loaded["_defaults"]["MyTool"] == {"param_a": 10.0, "param_b": "fast"}
+
+    def test_seed_is_idempotent(self, temp_workflow_dir):
+        """Seeding the same tool twice overwrites cleanly."""
+        pm = ParameterManager(temp_workflow_dir)
+
+        # First seed
+        params = {"_defaults": {"Tool": {"p1": 1.0}}, "other_key": "keep"}
+        with open(pm.params_file, "w") as f:
+            json.dump(params, f)
+
+        # Second seed with updated defaults
+        params = pm.get_parameters_from_json()
+        params["_defaults"]["Tool"] = {"p1": 2.0}
+        with open(pm.params_file, "w") as f:
+            json.dump(params, f)
+
+        loaded = pm.get_parameters_from_json()
+        assert loaded["_defaults"]["Tool"]["p1"] == 2.0
+        assert loaded["other_key"] == "keep"
+
+    def test_seed_multiple_instances(self, temp_workflow_dir):
+        """Different instances of the same tool get independent _defaults."""
+        pm = ParameterManager(temp_workflow_dir)
+        params = {
+            "_defaults": {
+                "IDFilter_strict": {"score:pep": 0.01},
+                "IDFilter_lenient": {"score:pep": 0.05},
+            }
+        }
+        with open(pm.params_file, "w") as f:
+            json.dump(params, f)
+
+        loaded = pm.get_parameters_from_json()
+        assert loaded["_defaults"]["IDFilter_strict"]["score:pep"] == 0.01
+        assert loaded["_defaults"]["IDFilter_lenient"]["score:pep"] == 0.05
+
+
+try:
+    import pyopenms as poms
+    HAS_PYOPENMS = True
+except ImportError:
+    HAS_PYOPENMS = False
+
+
+@pytest.mark.skipif(not HAS_PYOPENMS, reason="pyopenms not available")
+class TestSaveParametersWithDefaults:
+
+    def _create_fake_ini(self, pm, tool_name, params_dict):
+        """Create a fake .ini file with given parameters."""
+        param = poms.Param()
+        for key, value in params_dict.items():
+            param.setValue(f"{tool_name}:1:{key}".encode(), value)
+        poms.ParamXMLFile().store(str(Path(pm.ini_dir, f"{tool_name}.ini")), param)
+
+    def test_value_matching_custom_default_not_saved(self, temp_workflow_dir):
+        """A value equal to the _defaults entry should not be saved as a user override."""
+        pm = ParameterManager(temp_workflow_dir)
+
+        # Create a fake ini with a default value
+        self._create_fake_ini(pm, "Tool", {"param_a": 10.0})
+
+        # Pre-seed _defaults with a different value than ini
+        params = {"_defaults": {"Tool": {"param_a": 42.0}}}
+        with open(pm.params_file, "w") as f:
+            json.dump(params, f)
+
+        # Session state has value matching the custom default (42.0), not the ini default (10.0)
+        mock_streamlit.session_state[f"{pm.topp_param_prefix}Tool:1:param_a"] = 42.0
+        mock_streamlit.session_state["_topp_tool_instance_map"] = {"Tool": "Tool"}
+
+        pm.save_parameters()
+
+        with open(pm.params_file, "r") as f:
+            saved = json.load(f)
+
+        # param_a should NOT appear under Tool (it matches the _defaults value)
+        assert "param_a" not in saved.get("Tool", {})
+        # _defaults should still be present
+        assert saved["_defaults"]["Tool"]["param_a"] == 42.0
+
+    def test_value_different_from_custom_default_saved(self, temp_workflow_dir):
+        """A value different from _defaults entry should be saved as user override."""
+        pm = ParameterManager(temp_workflow_dir)
+
+        # Create a fake ini with a default value
+        self._create_fake_ini(pm, "Tool", {"param_a": 10.0})
+
+        params = {"_defaults": {"Tool": {"param_a": 42.0}}}
+        with open(pm.params_file, "w") as f:
+            json.dump(params, f)
+
+        mock_streamlit.session_state[f"{pm.topp_param_prefix}Tool:1:param_a"] = 99.0
+        mock_streamlit.session_state["_topp_tool_instance_map"] = {"Tool": "Tool"}
+
+        pm.save_parameters()
+
+        with open(pm.params_file, "r") as f:
+            saved = json.load(f)
+
+        assert saved["Tool"]["param_a"] == 99.0
+
+
+class TestNonDefaultParamsSummaryDefaults:
+
+    def test_defaults_key_excluded_from_classification(self):
+        """_defaults dict should not appear as a TOPP tool in the summary."""
+        params = {
+            "_defaults": {"Tool": {"p1": 10}},
+            "Tool": {"p1": 20},
+            "general_param": "value"
+        }
+        # Simulate the classification logic
+        topp = {}
+        general = {}
+        for k, v in params.items():
+            if k == "_defaults":
+                continue
+            if isinstance(v, dict):
+                topp[k] = v
+            else:
+                general[k] = v
+
+        assert "_defaults" not in topp
+        assert "Tool" in topp
+        assert "general_param" in general
+
+    def test_defaults_merged_into_summary(self):
+        """_defaults values should appear in summary merged with user overrides."""
+        params = {
+            "_defaults": {
+                "ToolA": {"p1": 10, "p2": 20},
+                "ToolB": {"p3": 30}
+            },
+            "ToolA": {"p1": 99}
+        }
+        # Simulate the merge logic for summary
+        topp = {}
+        for k, v in params.items():
+            if k == "_defaults":
+                continue
+            if isinstance(v, dict):
+                topp[k] = v
+
+        defaults = params.get("_defaults", {})
+        for tool_name, default_vals in defaults.items():
+            if tool_name not in topp:
+                topp[tool_name] = {}
+            topp[tool_name] = {**default_vals, **topp.get(tool_name, {})}
+
+        assert topp["ToolA"] == {"p1": 99, "p2": 20}  # user override wins for p1
+        assert topp["ToolB"] == {"p3": 30}              # defaults-only tool appears
diff --git a/tests/test_parameter_integrity.py b/tests/test_parameter_integrity.py
new file mode 100644
index 00000000..b1a04111
--- /dev/null
+++ b/tests/test_parameter_integrity.py
@@ -0,0 +1,986 @@
+"""
+Parameter-file integrity tests.
+
+These pin the contract that a *failed read* of ``params.json`` must never turn
+into a *write* that erases it — the live data-loss bug recorded as A2 in
+``docs/storage-defect-register.md`` and the first item of Step 1 in the
+multi-node distribution plan.
+
+The bug, end to end:
+
+* ``ParameterManager.save_parameters()`` is a read-modify-write:
+  ``ParameterManager.py:136`` does ``self.get_parameters_from_json() | json_params``.
+* ``get_parameters_from_json()`` (``:193-212``) wraps the read in a bare
+  ``except:`` that returns ``{}`` for *any* failure — a torn read from a
+  concurrent truncate-then-rewrite, an unreadable file, anything.
+* So one transient bad read makes the merge ``{} | this_session_params``, and
+  that subset is written back, permanently deleting ``_defaults``,
+  ``_flag_params`` and every other tool's stored values — while telling the user
+  it was a deliberate "Reset to defaults".
+
+``apply_preset()`` (``:345``) has the identical shape and is covered here too.
+The plan's fix is to split the read: a tolerant ``get_parameters_from_json()``
+that keeps returning ``{}`` for its read-only callers, and a strict
+``read_parameters_strict()`` that **raises** on a malformed file and returns
+``{}`` only for a genuinely absent one, used by the read-modify-write-back
+sites. Conflating "absent" with "unreadable" *is* the bug, so both branches get
+their own test.
+
+The next group pins the shapes an unreadable file actually takes on a shared,
+restartable filesystem — a bad encoding, JSON that is not an object, a directory
+in its place, and a storage blip that clears by itself — plus the two halves of
+the recovery: the write must be atomic, and the reset offered on failure must
+not be the thing that destroys the data.
+
+The last two groups cover G1: ``CommandExecutor._get_max_threads()`` reads
+settings out of ``st.session_state``, which is empty inside the RQ work horse,
+so the configured ``max_threads`` has been silently replaced by a hardcoded
+``4``; and ``src/workflow/settings_io.load_settings()``, the Streamlit-free
+loader it now reads them through.
+
+Every test here is expected to fail before Step 1 lands.
+"""
+import builtins
+import contextlib
+import errno
+import json
+import os
+import sys
+import time
+from pathlib import Path
+from unittest.mock import MagicMock
+
+import pytest
+
+# Add project root to path for imports
+PROJECT_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+sys.path.append(PROJECT_ROOT)
+
+# ---------------------------------------------------------------------------
+# Import the modules under test with `streamlit` (and `pyopenms`) mocked at the
+# sys.modules level, mirroring tests/test_topp_flag_parameters.py. Both modules
+# do `import streamlit as st` at the top (ParameterManager also
+# `import pyopenms as poms`); nothing exercised here needs more than a dict-like
+# `st.session_state`, so the mocks keep the suite runnable without the heavy
+# deps while still driving the real read/merge/write logic.
+# ---------------------------------------------------------------------------
+mock_streamlit = MagicMock()
+mock_streamlit.session_state = {}
+
+_original_streamlit = sys.modules.get("streamlit")
+_original_pyopenms = sys.modules.get("pyopenms")
+sys.modules["streamlit"] = mock_streamlit
+if _original_pyopenms is None:
+    sys.modules["pyopenms"] = MagicMock()
+
+from src.workflow.ParameterManager import ParameterManager
+from src.workflow.CommandExecutor import CommandExecutor
+from src.workflow.settings_io import load_settings
+
+# Restore the original modules so other test files import the real ones. The
+# classes imported above keep their module-level `st`/`poms` bound to the mocks.
+if _original_streamlit is not None:
+    sys.modules["streamlit"] = _original_streamlit
+else:
+    sys.modules.pop("streamlit", None)
+if _original_pyopenms is None:
+    sys.modules.pop("pyopenms", None)
+
+for _key in list(sys.modules.keys()):
+    if _key.startswith("src.workflow"):
+        sys.modules.pop(_key, None)
+
+
+# Name of the strict, raising reader introduced by Step 1 of the plan.
+STRICT_READER_NAME = "read_parameters_strict"
+
+# Reached through the class rather than imported, because the sys.modules
+# entries for src.workflow.* are popped after the import block above - and
+# because the name does not exist before Step 1, so importing it at module
+# scope would turn this file into a collection error instead of a failure.
+_MODULE_GLOBALS = ParameterManager.__init__.__globals__
+
+
+def _error_class(name: str) -> type:
+    """The named exception class from ParameterManager, or fail loudly."""
+    cls = _MODULE_GLOBALS.get(name)
+    if cls is None:
+        pytest.fail(
+            f"ParameterManager.{name} does not exist. Step 1 of the plan "
+            "requires a read failure to be reported as its own exception type, "
+            "so that every read-modify-write-back site can abort on it."
+        )
+    return cls
+
+
+def invalid_parameter_file_error() -> type:
+    """The exception a failed strict read raises."""
+    return _error_class("InvalidParameterFileError")
+
+
+def transient_parameter_file_error() -> type:
+    """
+    The subclass used for a read failure expected to clear by itself.
+
+    A restarted NFS export makes clients ESTALE for a moment. Reporting that
+    the same way as a corrupt file sends the user to a reset affordance which
+    would delete a perfectly intact params.json.
+    """
+    return _error_class("TransientParameterFileError")
+
+
+# The one general parameter whose widget is on screen in the tests below, i.e.
+# the only key the saving session legitimately owns.
+CHANGED_KEY = "example-general-param"
+
+# A realistic, fully populated params.json: the reserved keys, two TOPP tools'
+# stored values, and two general parameters. A session that is not currently
+# rendering the TOPP widgets (a different page, a collapsed fragment, advanced
+# view off) holds *none* of this in session state — which is exactly why
+# save_parameters() merges the file back in, and exactly what a laundered `{}`
+# destroys.
+FULL_PARAMS = {
+    "_defaults": {
+        "FeatureFinderMetabo": {"algorithm:common:noise_threshold_int": 1000.0},
+        "MetaboliteAdductDecharger": {
+            "algorithm:MetaboliteFeatureDeconvolution:charge_max": 3
+        },
+    },
+    "_flag_params": {"FeatureFinderMetabo": ["force"]},
+    "max_threads": 3,
+    "FeatureFinderMetabo": {
+        "algorithm:common:noise_threshold_int": 500.0,
+        "algorithm:mtd:mass_error_ppm": 10.0,
+    },
+    "MetaboliteAdductDecharger": {
+        "algorithm:MetaboliteFeatureDeconvolution:charge_max": 2
+    },
+    CHANGED_KEY: "keep-me",
+    "run-adduct-detection": True,
+}
+
+
+@pytest.fixture(autouse=True)
+def reset_session_state():
+    """Give each test a fresh, empty mocked session_state."""
+    mock_streamlit.session_state = {}
+    yield
+    mock_streamlit.session_state = {}
+
+
+def _assert_unparseable(text: str) -> None:
+    """Guard the fixtures themselves: the corruption must really break json."""
+    with pytest.raises(json.JSONDecodeError):
+        json.loads(text)
+
+
+def _write_torn_params_file(pm: ParameterManager) -> str:
+    """
+    Leave params.json holding FULL_PARAMS plus a fragment of a second write.
+
+    This is what a reader sees when a concurrent writer's truncate-then-rewrite
+    interleaves with it: unparseable, but with every original byte still on
+    disk and recoverable by hand — until something rewrites the file.
+
+    Returns the full text that was written.
+    """
+    text = json.dumps(FULL_PARAMS, indent=4) + '\n{\n    "_defaults": {\n'
+    _assert_unparseable(text)
+    pm.params_file.write_text(text, encoding="utf-8")
+    return text
+
+
+def _require_strict_reader(pm: ParameterManager):
+    """
+    Return the strict reader from Step 1 of the plan, or fail loudly.
+
+    Accepts either a ``ParameterManager`` method or a module-level function
+    taking the params file path, since only the name and the behaviour are
+    pinned by the plan. Uses ``pytest.fail`` (a BaseException) rather than
+    letting an AttributeError escape, so that a ``pytest.raises(Exception)``
+    around the call cannot mistake "not implemented yet" for "raised properly".
+    """
+    reader = getattr(pm, STRICT_READER_NAME, None)
+    if reader is not None:
+        return reader
+
+    # sys.modules entries for src.workflow.* are popped after import above, so
+    # reach the module namespace through the class instead.
+    module_globals = ParameterManager.__init__.__globals__
+    fn = module_globals.get(STRICT_READER_NAME)
+    if fn is not None:
+        return lambda: fn(pm.params_file)
+
+    pytest.fail(
+        f"ParameterManager.{STRICT_READER_NAME}() does not exist. Step 1 of the "
+        "plan requires a strict reader that raises on a malformed params.json "
+        "and returns {} only for an absent one, used by every "
+        "read-modify-write-back site."
+    )
+
+
+# ---------------------------------------------------------------------------
+# The erasure bug (docs/storage-defect-register.md A2)
+# ---------------------------------------------------------------------------
+
+
+def test_corrupt_read_does_not_erase(tmp_path):
+    """
+    A session holding a subset of the keys must not be able to delete the rest.
+
+    Sequence: params.json holds two tools' values plus `_defaults` and
+    `_flag_params`; a second process's write leaves the file momentarily
+    unparseable; this session — which only ever rendered one general widget —
+    saves. Whether save_parameters() refuses loudly or quietly is not pinned
+    here; what is pinned is that nothing on disk is lost.
+    """
+    pm = ParameterManager(tmp_path)
+    torn_text = _write_torn_params_file(pm)
+
+    # Only one key is in session state: the widget this page actually rendered.
+    mock_streamlit.session_state = {f"{pm.param_prefix}{CHANGED_KEY}": "changed"}
+
+    # Narrow on purpose: aborting the write is the point, but it must abort on
+    # the read failure and nothing else. A blanket suppress would let any crash
+    # satisfy the assertions below.
+    with contextlib.suppress(invalid_parameter_file_error()):
+        pm.save_parameters()
+
+    surviving_text = pm.params_file.read_text(encoding="utf-8")
+
+    try:
+        surviving = json.loads(surviving_text)
+    except json.JSONDecodeError:
+        # The file was left alone: still corrupt, but every byte is there and
+        # it can be repaired. Nothing was laundered away.
+        assert surviving_text == torn_text, (
+            "params.json was partially rewritten after a failed read; it must "
+            "be left intact so the stored parameters remain recoverable"
+        )
+        return
+
+    # The file was rewritten, so it has to be at least as complete as before.
+    for key, value in FULL_PARAMS.items():
+        assert key in surviving, (
+            f"'{key}' was erased from params.json by a save that could not read "
+            "it first (docs/storage-defect-register.md A2): the failed read became an empty dict and "
+            f"the merge wrote back only this session's subset {sorted(surviving)}"
+        )
+        if key != CHANGED_KEY:
+            assert surviving[key] == value, (
+                f"'{key}' lost its stored value after a failed read: "
+                f"{surviving[key]!r} != {value!r}"
+            )
+
+
+def test_truncated_read_does_not_rewrite_params_file(tmp_path):
+    """
+    Same bug, second corruption shape: a half-written file.
+
+    Here the tail of the original content is genuinely gone from disk, so the
+    only safe behaviour is to touch nothing — a rewrite would replace a
+    repairable file with a valid-JSON file that has silently lost everything.
+    """
+    pm = ParameterManager(tmp_path)
+    full_text = json.dumps(FULL_PARAMS, indent=4)
+    half_written = full_text[: len(full_text) // 2]
+    _assert_unparseable(half_written)
+    pm.params_file.write_text(half_written, encoding="utf-8")
+    before = pm.params_file.read_bytes()
+
+    mock_streamlit.session_state = {f"{pm.param_prefix}{CHANGED_KEY}": "changed"}
+
+    with contextlib.suppress(invalid_parameter_file_error()):
+        pm.save_parameters()
+
+    assert pm.params_file.read_bytes() == before, (
+        "params.json was rewritten from a session subset after a torn read; "
+        "the unreadable file must be preserved, not replaced"
+    )
+
+
+def test_apply_preset_does_not_erase_on_corrupt_read(tmp_path, monkeypatch):
+    """
+    apply_preset() is the second read-modify-write-back site (:345).
+
+    It has the same shape as save_parameters() — read, merge, write — so an
+    unreadable file makes applying a preset delete every parameter the preset
+    does not mention, and report success while doing it.
+    """
+    workflow_dir = tmp_path / "topp-workflow"
+    workflow_dir.mkdir()
+    pm = ParameterManager(workflow_dir, workflow_name="TOPP Workflow")
+    torn_text = _write_torn_params_file(pm)
+
+    # presets.json is read relative to the process CWD (ParameterManager.py:287).
+    cwd = tmp_path / "app-root"
+    cwd.mkdir()
+    (cwd / "presets.json").write_text(
+        json.dumps(
+            {
+                "topp-workflow": {
+                    "High Sensitivity": {
+                        "_description": "Tooltip text",
+                        "FeatureFinderMetabo": {
+                            "algorithm:common:noise_threshold_int": 50.0
+                        },
+                    }
+                }
+            }
+        ),
+        encoding="utf-8",
+    )
+    monkeypatch.chdir(cwd)
+
+    result = None
+    with contextlib.suppress(invalid_parameter_file_error()):
+        result = pm.apply_preset("High Sensitivity")
+
+    assert result is not True, (
+        "apply_preset() reported success against a params.json it could not read"
+    )
+
+    surviving_text = pm.params_file.read_text(encoding="utf-8")
+    try:
+        surviving = json.loads(surviving_text)
+    except json.JSONDecodeError:
+        assert surviving_text == torn_text, (
+            "params.json was partially rewritten while applying a preset over "
+            "an unreadable file"
+        )
+        return
+
+    for key in FULL_PARAMS:
+        assert key in surviving, (
+            f"'{key}' was erased by apply_preset() after a failed read; the "
+            f"file now holds only {sorted(surviving)}"
+        )
+
+
+# ---------------------------------------------------------------------------
+# Absent vs unreadable — the distinction whose absence causes the erasure
+# ---------------------------------------------------------------------------
+
+
+def test_absent_parameter_file_reads_as_empty(tmp_path):
+    """An absent params.json is a first run, not a failure: {} is correct."""
+    pm = ParameterManager(tmp_path)
+    assert not pm.params_file.exists()
+
+    assert pm.get_parameters_from_json() == {}
+    assert _require_strict_reader(pm)() == {}, (
+        "the strict reader must still return {} for a genuinely absent file — "
+        "a first run has no parameters and that is not an error"
+    )
+
+
+def test_malformed_parameter_file_does_not_read_as_empty(tmp_path):
+    """
+    A malformed params.json must be distinguishable from an absent one.
+
+    Returning {} for both is what lets save_parameters() merge an empty dict
+    over real data. The tolerant reader keeps its {} contract for its read-only
+    callers; the strict reader used by the write-back sites must raise.
+    """
+    pm = ParameterManager(tmp_path)
+    _write_torn_params_file(pm)
+
+    reader = _require_strict_reader(pm)
+    with pytest.raises(invalid_parameter_file_error()):
+        result = reader()
+        pytest.fail(
+            f"the strict reader returned {result!r} for an unreadable "
+            "params.json instead of raising; an unreadable file must never be "
+            "reported as 'no parameters'"
+        )
+
+    # Deliberate asymmetry: the tolerant reader keeps its signature and its {}
+    # for the constructors and read-only callers that cannot handle a raise.
+    assert pm.get_parameters_from_json() == {}
+
+
+# ---------------------------------------------------------------------------
+# max_threads outside a Streamlit session (docs/storage-defect-register.md G1)
+# ---------------------------------------------------------------------------
+
+
+def _executor_in_worker(
+    tmp_path, monkeypatch, settings, params_json=None, cpu_quota=None
+):
+    """
+    Build a CommandExecutor under the RQ work horse's real conditions.
+
+    `cpu_quota` pins what detect_cpu_quota() reports. It defaults to None — "no
+    readable CPU ceiling" — so the settings-driven tests below assert the
+    setting rather than whatever cgroup the test host happens to have. Left
+    unpinned they would pass on an unconstrained runner and fail the moment CI
+    ran inside a container with a quota, which is a fixture reading the
+    environment rather than a test.
+
+    No ScriptRunContext means `st.session_state` is an empty global mock, so
+    `st.session_state.get("settings", {})` yields {} and every configured value
+    has to come from settings.json, which this repo resolves against the process
+    CWD everywhere it is read (app.py:8, common.py:362, QueueManager.py:74,
+    test_gui.py:14). The chdir happens before the executor is built so that
+    memoising the lookup — which the plan requires, since run_topp() calls it
+    twice and the two calls must agree — cannot serve a value read from some
+    other directory.
+    """
+    cwd = tmp_path / "app-root"
+    cwd.mkdir()
+    (cwd / "settings.json").write_text(json.dumps(settings), encoding="utf-8")
+
+    workflow_dir = tmp_path / "workflow"
+    workflow_dir.mkdir()
+
+    monkeypatch.chdir(cwd)
+    monkeypatch.delenv("REDIS_URL", raising=False)
+    # Reached through the function's own globals, not by dotted name: the
+    # import block above pops src.workflow.* from sys.modules, so a string
+    # target would re-import a *different* CommandExecutor module - one bound
+    # to the real streamlit - and patch a copy this executor never calls.
+    monkeypatch.setitem(
+        CommandExecutor._get_max_threads.__globals__,
+        "detect_cpu_quota",
+        lambda: cpu_quota,
+    )
+
+    pm = ParameterManager(workflow_dir)
+    if params_json is not None:
+        pm.params_file.write_text(json.dumps(params_json), encoding="utf-8")
+
+    mock_streamlit.session_state = {}
+    return CommandExecutor(workflow_dir, MagicMock(), pm)
+
+
+def test_max_threads_without_session_state(tmp_path, monkeypatch):
+    """
+    The worker must honour max_threads.online, not the hardcoded literal 4.
+
+    `st.session_state.get("settings", {})` is {} inside the work horse, so the
+    online branch of _get_max_threads() (CommandExecutor.py:41) is unreachable
+    there and the local branch's hardcoded 4 wins — dead config since #333
+    (docs/storage-defect-register.md G1), and a correctness bug once a worker has a hard memory
+    limit sized for a known thread count.
+    """
+    executor = _executor_in_worker(
+        tmp_path,
+        monkeypatch,
+        {"online_deployment": True, "max_threads": {"local": 9, "online": 6}},
+    )
+
+    assert executor._get_max_threads() == 6, (
+        "max_threads.online was ignored outside a Streamlit session; a value of "
+        "4 means the hardcoded literal was used instead of settings.json"
+    )
+
+
+def test_max_threads_local_without_session_state_uses_configured_local(
+    tmp_path, monkeypatch
+):
+    """Same failure in local mode: the configured local value, not the literal 4."""
+    executor = _executor_in_worker(
+        tmp_path,
+        monkeypatch,
+        {"online_deployment": False, "max_threads": {"local": 9, "online": 6}},
+    )
+
+    assert executor._get_max_threads() == 9, (
+        "max_threads.local from settings.json was ignored; 4 is the hardcoded "
+        "fallback that only applies when the setting is missing entirely"
+    )
+
+
+def test_max_threads_online_ignores_workspace_params_json(tmp_path, monkeypatch):
+    """
+    In online mode the workspace's params.json must not set the thread budget.
+
+    Workers are shared and params.json is user-supplied — the import uploader
+    writes it verbatim, with no reserved-key filter (docs/storage-defect-register.md G2) — so the
+    per-workspace value may only apply to the local, single-user deployment.
+    """
+    executor = _executor_in_worker(
+        tmp_path,
+        monkeypatch,
+        {"online_deployment": True, "max_threads": {"local": 9, "online": 6}},
+        params_json={"max_threads": 3, "example-general-param": "x"},
+    )
+
+    assert executor._get_max_threads() == 6, (
+        "a workspace params.json overrode max_threads.online on a shared worker"
+    )
+
+
+# ---------------------------------------------------------------------------
+# The shapes an unreadable params.json actually takes
+# ---------------------------------------------------------------------------
+
+
+def test_undecodable_parameter_file_does_not_read_as_empty(tmp_path):
+    """
+    A params.json that is not valid UTF-8 is unreadable, not empty.
+
+    UnicodeDecodeError subclasses ValueError, not OSError, so a handler
+    catching (JSONDecodeError, OSError) misses it entirely: it escapes the
+    tolerant reader - which both constructors call, taking the whole page down
+    - and escapes the strict reader as a type no `except
+    InvalidParameterFileError` guard catches, so save_parameters() loses its
+    "left unchanged" protection.
+
+    Reachable in this repo: the parameter import uploader decodes the upload as
+    utf-8 and writes it back out, and a torn write can also cut a multi-byte
+    sequence in half.
+    """
+    pm = ParameterManager(tmp_path)
+    # cp1252 bytes for {"note": "\u00b5m tolerance"} - 0xb5 is not valid UTF-8.
+    pm.params_file.write_bytes(b'{"note": "\xb5m tolerance"}')
+    before = pm.params_file.read_bytes()
+
+    with pytest.raises(invalid_parameter_file_error()):
+        _require_strict_reader(pm)()
+
+    assert pm.get_parameters_from_json() == {}, (
+        "the tolerant reader must keep degrading to {} - its two callers are "
+        "constructors with no way to handle a raise"
+    )
+
+    mock_streamlit.session_state = {f"{pm.param_prefix}{CHANGED_KEY}": "changed"}
+    with contextlib.suppress(invalid_parameter_file_error()):
+        pm.save_parameters()
+
+    assert pm.params_file.read_bytes() == before, (
+        "params.json was rewritten from a session subset after an undecodable "
+        "read"
+    )
+
+
+@pytest.mark.parametrize(
+    "content", ["[1, 2, 3]", '"just a string"', "42", "null"], ids=["array", "string", "number", "null"]
+)
+def test_parameter_file_that_is_not_an_object_is_rejected(tmp_path, content):
+    """
+    Valid JSON that is not an object is still not a parameter dict.
+
+    ``{} | ["a"]`` raises and ``{} | "x"`` raises, but a JSON ``null`` merges as
+    nothing at all - so without this guard the strict reader would hand a
+    non-dict to the merge and either crash the run or quietly erase the file.
+    """
+    pm = ParameterManager(tmp_path)
+    pm.params_file.write_text(content, encoding="utf-8")
+
+    with pytest.raises(invalid_parameter_file_error()):
+        _require_strict_reader(pm)()
+
+    assert pm.get_parameters_from_json() == {}
+
+
+def test_directory_in_place_of_parameter_file_is_rejected(tmp_path):
+    """
+    A directory where params.json should be is unreadable, not absent.
+
+    Raises IsADirectoryError on Linux and PermissionError on Windows; both are
+    OSError, and neither may be reported as "no parameters stored".
+    """
+    pm = ParameterManager(tmp_path)
+    pm.params_file.mkdir()
+
+    with pytest.raises(invalid_parameter_file_error()):
+        _require_strict_reader(pm)()
+
+    assert pm.get_parameters_from_json() == {}
+    assert pm.params_file.is_dir(), "the directory must be left in place"
+
+
+def _flaky_open(monkeypatch, target: Path, failures: int, errno_value: int) -> None:
+    """Make the first ``failures`` opens of ``target`` fail with ``errno_value``."""
+    real_open = builtins.open
+    remaining = {"n": failures}
+
+    def fake_open(file, *args, **kwargs):
+        if (
+            isinstance(file, (str, os.PathLike))
+            and Path(file) == target
+            and remaining["n"] > 0
+        ):
+            remaining["n"] -= 1
+            raise OSError(errno_value, os.strerror(errno_value))
+        return real_open(file, *args, **kwargs)
+
+    monkeypatch.setattr(builtins, "open", fake_open)
+    # The retry delay is real time; nothing here depends on its duration.
+    monkeypatch.setattr(time, "sleep", lambda _seconds: None)
+
+
+def test_transient_read_failure_is_retried(tmp_path, monkeypatch):
+    """
+    ESTALE from a restarted NFS export must not be reported as corruption.
+
+    Invariant 2 of the plan expects the Ganesha pod to be restarted by
+    upgrades, evictions and node drains. Every client ESTALEs while it comes
+    back. With no retry, a routine restart puts the user in front of a "reset
+    to defaults" button whose only effect would be to delete an intact file.
+    """
+    pm = ParameterManager(tmp_path)
+    pm.params_file.write_text(json.dumps(FULL_PARAMS, indent=4), encoding="utf-8")
+    _flaky_open(monkeypatch, pm.params_file, failures=1, errno_value=errno.ESTALE)
+
+    assert _require_strict_reader(pm)() == FULL_PARAMS, (
+        "a single ESTALE must be retried, not turned into a permanent failure"
+    )
+
+
+def test_persistent_transient_failure_is_reported_as_transient(tmp_path, monkeypatch):
+    """
+    A storage outage that outlasts the retries is still not corruption.
+
+    It stays an InvalidParameterFileError - every write-back site must still
+    abort, the content is unknown - but as a distinguishable subclass, so the
+    UI can withhold the destructive reset affordance.
+    """
+    pm = ParameterManager(tmp_path)
+    pm.params_file.write_text(json.dumps(FULL_PARAMS, indent=4), encoding="utf-8")
+    _flaky_open(monkeypatch, pm.params_file, failures=99, errno_value=errno.ESTALE)
+
+    with pytest.raises(transient_parameter_file_error()):
+        _require_strict_reader(pm)()
+
+    assert issubclass(
+        transient_parameter_file_error(), invalid_parameter_file_error()
+    ), (
+        "it must stay a subclass, or every existing `except "
+        "InvalidParameterFileError` write-back guard stops catching it"
+    )
+
+
+def test_permanent_read_failure_is_not_reported_as_transient(tmp_path):
+    """The control: a corrupt file must not be misreported as a passing blip."""
+    pm = ParameterManager(tmp_path)
+    _write_torn_params_file(pm)
+
+    with pytest.raises(invalid_parameter_file_error()) as excinfo:
+        _require_strict_reader(pm)()
+
+    assert not isinstance(excinfo.value, transient_parameter_file_error()), (
+        "unparseable content will never clear by itself; offering 'try again' "
+        "for it leaves the user with no way forward"
+    )
+
+
+def test_interrupted_write_leaves_the_previous_parameters_intact(tmp_path, monkeypatch):
+    """
+    A write that dies half way must not leave a file that is neither version.
+
+    Truncate-then-rewrite plus an OOM kill or ENOSPC - the failure modes this
+    deployment is being sized against - leaves a torn params.json which every
+    later strict read rejects. save_parameters() then becomes a permanent
+    silent no-op and the parameter page stops on every render, with only the
+    destructive reset left as an escape.
+    """
+    pm = ParameterManager(tmp_path)
+    pm.params_file.write_text(json.dumps(FULL_PARAMS, indent=4), encoding="utf-8")
+    before = pm.params_file.read_bytes()
+
+    def half_written_dump(obj, fp, **kwargs):
+        fp.write('{\n    "_defaults": {')
+        raise OSError(errno.ENOSPC, os.strerror(errno.ENOSPC))
+
+    monkeypatch.setattr(json, "dump", half_written_dump)
+    mock_streamlit.session_state = {f"{pm.param_prefix}{CHANGED_KEY}": "changed"}
+
+    with pytest.raises(OSError):
+        pm.save_parameters()
+
+    monkeypatch.undo()
+
+    assert pm.params_file.read_bytes() == before, (
+        "params.json holds a half-written document; the write must go to a "
+        "temporary file and be moved into place with os.replace()"
+    )
+    assert json.loads(pm.params_file.read_text(encoding="utf-8")) == FULL_PARAMS
+    leftovers = [q.name for q in tmp_path.iterdir() if q.name.endswith(".tmp")]
+    assert leftovers == [], f"scratch files left behind: {leftovers}"
+
+
+def test_reset_keeps_the_previous_parameters(tmp_path):
+    """
+    The recovery offered for an unreadable file must not be the data loss.
+
+    reset_to_default_parameters() backs the reading UI's "reset to defaults"
+    button, which is offered exactly when the file could not be read - and an
+    unreadable file is very often a healthy file behind a storage blip.
+    Deleting it there converts a self-healing outage into permanent loss.
+    """
+    pm = ParameterManager(tmp_path)
+    torn_text = _write_torn_params_file(pm)
+
+    backup = pm.reset_to_default_parameters()
+
+    assert not pm.params_file.exists(), "the workflow must start from defaults"
+    assert backup is not None and backup.exists(), (
+        "the previous parameter file must be kept, not unlinked"
+    )
+    assert backup.read_text(encoding="utf-8") == torn_text
+    assert pm.get_parameters_from_json() == {}
+
+
+def test_reset_handles_a_directory_in_place_of_the_parameter_file(tmp_path):
+    """
+    unlink() raises on a directory, so the reset button used to raise too -
+    leaving the parameter page stopped on every render with no way out.
+    """
+    pm = ParameterManager(tmp_path)
+    pm.params_file.mkdir()
+    (pm.params_file / "unexpected.txt").write_text("x", encoding="utf-8")
+
+    backup = pm.reset_to_default_parameters()
+
+    assert not pm.params_file.exists()
+    assert backup is not None and backup.is_dir()
+
+
+def test_reset_with_no_stored_parameters_is_a_no_op(tmp_path):
+    """Nothing stored, nothing to preserve - and no crash."""
+    pm = ParameterManager(tmp_path)
+    assert pm.reset_to_default_parameters() is None
+    assert not pm.params_file.exists()
+
+
+# ---------------------------------------------------------------------------
+# settings_io.load_settings - the Streamlit-free loader _get_max_threads uses
+# ---------------------------------------------------------------------------
+
+
+def test_load_settings_reads_the_file_in_the_working_directory(tmp_path, monkeypatch):
+    """The default path resolves against the CWD, as every other reader does."""
+    monkeypatch.chdir(tmp_path)
+    (tmp_path / "settings.json").write_text(
+        json.dumps({"online_deployment": True}), encoding="utf-8"
+    )
+
+    assert load_settings() == {"online_deployment": True}
+
+
+def test_load_settings_accepts_an_explicit_path(tmp_path):
+    elsewhere = tmp_path / "config" / "settings.json"
+    elsewhere.parent.mkdir()
+    elsewhere.write_text(json.dumps({"max_threads": {"online": 6}}), encoding="utf-8")
+
+    assert load_settings(elsewhere) == {"max_threads": {"online": 6}}
+
+
+def test_load_settings_absent_file_is_empty(tmp_path):
+    assert load_settings(tmp_path / "nothing-here.json") == {}
+
+
+@pytest.mark.parametrize(
+    "content",
+    ["{not json", "[1, 2, 3]", '"a string"', ""],
+    ids=["malformed", "array", "string", "empty"],
+)
+def test_load_settings_unusable_content_is_empty(tmp_path, content):
+    """
+    Total by construction, as its docstring promises and QueueManager relies on.
+
+    QueueManager._load_settings() delegates here and is documented to return an
+    empty dict on failure; it is called from QueueManager.__init__, which
+    WorkflowManager.__init__ calls behind an `except ImportError` that would not
+    catch anything else. CommandExecutor._get_max_threads() calls it inside the
+    RQ work horse, where a raise kills the job.
+    """
+    settings_file = tmp_path / "settings.json"
+    settings_file.write_text(content, encoding="utf-8")
+
+    assert load_settings(settings_file) == {}
+
+
+def test_load_settings_survives_a_non_utf8_file(tmp_path):
+    """
+    A settings.json in the platform codepage must not be fatal here alone.
+
+    app.py and src/common/common.py open it with the platform default encoding,
+    so a file hand-edited on a Windows box loads in the UI. If this loader is
+    the only strict reader, the same file starts the app and then kills the RQ
+    worker - the exact split it was written to remove.
+    """
+    settings_file = tmp_path / "settings.json"
+    # cp1252 for {"app-name": "M\u00fcller Lab", "online_deployment": true}
+    settings_file.write_bytes(
+        b'{"app-name": "M\xfcller Lab", "online_deployment": true}'
+    )
+
+    settings = load_settings(settings_file)
+
+    assert settings.get("online_deployment") is True, (
+        "an undecodable byte in one value must not lose the whole file"
+    )
+
+
+def test_load_settings_unreadable_file_is_empty(tmp_path):
+    """A directory in place of settings.json is an OSError, not a crash."""
+    settings_file = tmp_path / "settings.json"
+    settings_file.mkdir()
+
+    assert load_settings(settings_file) == {}
+
+
+def test_max_threads_is_memoised(tmp_path, monkeypatch):
+    """
+    run_topp() consults _get_max_threads() twice - once for its own thread
+    split, once inside run_multiple_commands() - and the two must agree, or the
+    per-command budget and the parallelism are computed from different numbers.
+    """
+    executor = _executor_in_worker(
+        tmp_path,
+        monkeypatch,
+        {"online_deployment": True, "max_threads": {"local": 9, "online": 6}},
+    )
+
+    first = executor._get_max_threads()
+    Path("settings.json").write_text(
+        json.dumps({"online_deployment": True, "max_threads": {"online": 1}}),
+        encoding="utf-8",
+    )
+
+    assert executor._get_max_threads() == first, (
+        "the thread budget was re-read mid-run; the two call sites in run_topp() "
+        "would then disagree"
+    )
+
+
+# ---------------------------------------------------------------------------
+# max_threads from the container's cgroup CPU quota
+#
+# The rq-worker runs at requests.cpu == limits.cpu (Guaranteed QoS), and the
+# memory-tier components size that per deployment - 4 cpu on the low tier, 20
+# on the high one. A single max_threads.online in settings.json cannot describe
+# both, so where a real quota is readable it wins, and the setting stays as the
+# fallback for deployments that have none.
+# ---------------------------------------------------------------------------
+
+
+def _settings_io_ns():
+    """
+    The real detect_cpu_quota and the module globals it reads its paths from.
+
+    Same reason as the monkeypatch in _executor_in_worker: src.workflow.* is
+    popped from sys.modules by the import block at the top of this file, so
+    `from src.workflow import settings_io` would build a SECOND module object
+    and patching its constants would leave the function under test reading the
+    real /sys/fs/cgroup. Going through __globals__ reaches the namespace the
+    live function actually closes over.
+    """
+    detect = CommandExecutor._get_max_threads.__globals__["detect_cpu_quota"]
+    return detect, detect.__globals__
+
+
+def test_cpu_quota_beats_configured_online_value(tmp_path, monkeypatch):
+    """A readable quota is the allocation; max_threads.online is only a guess."""
+    executor = _executor_in_worker(
+        tmp_path,
+        monkeypatch,
+        {"online_deployment": True, "max_threads": {"local": 9, "online": 2}},
+        cpu_quota=20,
+    )
+
+    assert executor._get_max_threads() == 20, (
+        "the container's own CPU quota was ignored in favour of a static "
+        "max_threads.online, which is wrong on every tier it was not written for"
+    )
+
+
+def test_cpu_quota_ignored_in_local_mode(tmp_path, monkeypatch):
+    """
+    Local mode keeps its params.json override.
+
+    The Threads widget is rendered only locally and writing it must keep
+    working, so quota detection has to stay confined to the online branch.
+    """
+    executor = _executor_in_worker(
+        tmp_path,
+        monkeypatch,
+        {"online_deployment": False, "max_threads": {"local": 9, "online": 2}},
+        params_json={"max_threads": 3},
+        cpu_quota=20,
+    )
+
+    assert executor._get_max_threads() == 3, (
+        "cgroup detection leaked into local mode and overrode the user's "
+        "Threads setting"
+    )
+
+
+def test_configured_online_value_used_when_no_quota(tmp_path, monkeypatch):
+    """No quota - bare metal, an unlimited container - falls back to settings."""
+    executor = _executor_in_worker(
+        tmp_path,
+        monkeypatch,
+        {"online_deployment": True, "max_threads": {"local": 9, "online": 6}},
+        cpu_quota=None,
+    )
+
+    assert executor._get_max_threads() == 6
+
+
+@pytest.mark.parametrize(
+    "cpu_max, expected",
+    [
+        ("400000 100000", 4),      # cpu: 4
+        ("2000000 100000", 20),    # cpu: 20, the high tier
+        ("150000 100000", 2),      # cpu: 1500m rounds UP, not down
+        ("50000 100000", 1),       # cpu: 500m floors at 1, never 0
+        ("max 100000", None),      # unconstrained
+        ("garbage", None),
+        ("", None),
+    ],
+)
+def test_detect_cpu_quota_cgroup_v2(tmp_path, monkeypatch, cpu_max, expected):
+    """cgroup v2 writes '<quota> <period>', or 'max <period>' when unlimited."""
+    detect, g = _settings_io_ns()
+
+    cpu_file = tmp_path / "cpu.max"
+    cpu_file.write_text(cpu_max, encoding="utf-8")
+    monkeypatch.setitem(g, "CGROUP_V2_CPU_MAX", cpu_file)
+    # Point v1 at somewhere absent, so a fallthrough cannot be mistaken for a
+    # v2 read succeeding.
+    monkeypatch.setitem(g, "CGROUP_V1_CPU_QUOTA", tmp_path / "nope" / "cfs_quota_us")
+
+    assert detect() == expected
+
+
+@pytest.mark.parametrize(
+    "quota, period, expected",
+    [
+        ("400000", "100000", 4),
+        ("-1", "100000", None),     # v1's documented "no limit"
+        ("0", "100000", None),      # not a legal quota; never a 0 thread budget
+    ],
+)
+def test_detect_cpu_quota_cgroup_v1(tmp_path, monkeypatch, quota, period, expected):
+    """cgroup v1 splits the same information across two files, -1 meaning none."""
+    detect, g = _settings_io_ns()
+
+    quota_file = tmp_path / "cpu.cfs_quota_us"
+    period_file = tmp_path / "cpu.cfs_period_us"
+    quota_file.write_text(quota, encoding="utf-8")
+    period_file.write_text(period, encoding="utf-8")
+    monkeypatch.setitem(g, "CGROUP_V2_CPU_MAX", tmp_path / "absent-cpu.max")
+    monkeypatch.setitem(g, "CGROUP_V1_CPU_QUOTA", quota_file)
+    monkeypatch.setitem(g, "CGROUP_V1_CPU_PERIOD", period_file)
+
+    assert detect() == expected
+
+
+def test_detect_cpu_quota_absent_everywhere(tmp_path, monkeypatch):
+    """
+    Off Linux, or outside a container, the answer is None - never 1.
+
+    A 1 here would silently serialise every workflow on a developer's laptop
+    and look like a performance problem rather than a configuration one.
+    """
+    detect, g = _settings_io_ns()
+
+    monkeypatch.setitem(g, "CGROUP_V2_CPU_MAX", tmp_path / "no-cpu.max")
+    monkeypatch.setitem(g, "CGROUP_V1_CPU_QUOTA", tmp_path / "no-quota")
+    monkeypatch.setitem(g, "CGROUP_V1_CPU_PERIOD", tmp_path / "no-period")
+
+    assert detect() is None
diff --git a/tests/test_queue_manager_cancel.py b/tests/test_queue_manager_cancel.py
index 0f877082..c8ef44aa 100644
--- a/tests/test_queue_manager_cancel.py
+++ b/tests/test_queue_manager_cancel.py
@@ -153,9 +153,7 @@ def test_stopped_status_is_mapped_in_get_job_info(monkeypatch):
 
     info = qm.get_job_info("stopped-job")
     assert info is not None
-    assert info.status == __import__(
-        "src.workflow.QueueManager", fromlist=["JobStatus"]
-    ).JobStatus.CANCELED, (
+    assert info.status.name == "CANCELED", (
         "RQ 'stopped' status should be reported as CANCELED to the UI; "
         "otherwise stopped jobs appear stuck in 'queued'."
     )
diff --git a/tests/test_sidebar_monitors.py b/tests/test_sidebar_monitors.py
new file mode 100644
index 00000000..737ac1e3
--- /dev/null
+++ b/tests/test_sidebar_monitors.py
@@ -0,0 +1,322 @@
+"""
+Tests for the sidebar's "Resource Utilization" expander (Step 2 of the
+multi-node plan).
+
+Two decisions live there, and both are about *which machine* the numbers
+describe:
+
+* ``monitor_hardware()`` reads psutil in the Streamlit process. Once the
+  workers are spread across nodes that process runs no workflow at all, so the
+  panel would show an idle 2Gi pod while a 64Gi worker saturates.
+* ``monitor_storage()`` reads the shared volume's heartbeat out of Redis, and
+  must distinguish "no shared storage here" from "the shared storage is gone"
+  from "I cannot tell, because Redis is down". Each of the three sends an
+  operator somewhere different.
+
+The obvious gate for the first one - ``online_deployment`` - is wrong, and
+wrong in a way that is invisible from Kubernetes: ``Dockerfile_simple`` bakes
+``online_deployment: true`` and ships no Redis, so the workflows run in this
+very process, and gating psutil on that flag empties the expander completely.
+``Dockerfile`` bakes it too, and ``docker/entrypoint.sh`` starts Redis, the RQ
+workers *and* Streamlit in one container, where psutil is once again measuring
+exactly the right machine. So the question is answered from the queue - are any
+workers registered, and are they all on some other host - not from a flag.
+
+``src/common/common.py`` imports Streamlit at module scope, so it is imported
+here with the heavy dependencies mocked at the ``sys.modules`` level and the
+originals restored immediately afterwards, mirroring
+``tests/test_legal_links.py`` (and, for ``src.workflow``,
+``tests/test_topp_flag_parameters.py``). Every other test module - and
+``test_gui.py``'s AppTest smoke tests in particular - still gets the real
+packages.
+"""
+import importlib
+import os
+import sys
+import types
+from unittest.mock import MagicMock
+
+import pytest
+
+# Add project root to path for imports
+PROJECT_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+sys.path.append(PROJECT_ROOT)
+
+
+def _identity_decorator(*args, **kwargs):
+    """Stand in for `st.fragment(run_every=5)`, which wraps the monitors."""
+
+    def _wrap(function):
+        return function
+
+    return _wrap
+
+
+mock_streamlit = MagicMock()
+mock_streamlit.session_state = {}
+# A real function, not a MagicMock attribute: `@st.fragment(...)` applied to a
+# MagicMock replaces the decorated function with another MagicMock, and the
+# module's monitors would then be uncallable stand-ins rather than the code
+# under test.
+mock_streamlit.fragment = _identity_decorator
+
+_MOCKED_MODULES = {
+    "streamlit": mock_streamlit,
+    "streamlit.components": MagicMock(),
+    "streamlit.components.v1": MagicMock(),
+    "streamlit.source_util": MagicMock(),
+    "pandas": MagicMock(),
+    "psutil": MagicMock(),
+    # Local submodules with their own heavy deps (e.g. the captcha image library).
+    "src.common.captcha_": MagicMock(),
+    "src.common.admin": MagicMock(),
+}
+_saved_modules = {name: sys.modules.get(name) for name in _MOCKED_MODULES}
+sys.modules.update(_MOCKED_MODULES)
+
+# Force a FRESH import under the mocks, even if an earlier test module (e.g.
+# test_gui.py, or tests/test_legal_links.py, which mocks Streamlit differently)
+# already imported a version bound to something else.
+#
+# `import_module`, not `from src.common import common`: the second form is
+# satisfied by the *attribute* the import system left on the `src.common`
+# package object, which survives popping `sys.modules["src.common.common"]`.
+# It would hand back the module another test file imported under its own mock,
+# where `st.fragment` is a plain MagicMock - so every monitor here would be a
+# MagicMock stand-in, calling them would do nothing, and these tests would pass
+# or fail depending on which files ran first.
+_package = sys.modules.get("src.common")
+_saved_attribute = getattr(_package, "common", None) if _package is not None else None
+_saved_common = sys.modules.pop("src.common.common", None)
+
+common = importlib.import_module("src.common.common")  # noqa: E402
+
+for _name, _original in _saved_modules.items():
+    if _original is None:
+        sys.modules.pop(_name, None)
+    else:
+        sys.modules[_name] = _original
+if _saved_common is None:
+    sys.modules.pop("src.common.common", None)
+else:
+    sys.modules["src.common.common"] = _saved_common
+if _package is not None:
+    if _saved_attribute is None:
+        delattr(_package, "common")
+    else:
+        setattr(_package, "common", _saved_attribute)
+
+
+# ---------------------------------------------------------------------------
+# Stubbing health
+#
+# The monitors import `src.workflow.health` inside their own bodies, so the
+# stub is installed in `sys.modules` rather than patched onto a module object.
+# Several test files purge `src.workflow.*` from `sys.modules` after importing
+# under mocks, and pytest imports every test module before running any test -
+# so by the time these run, the `health` this file imported at collection time
+# may no longer be the one the function-level import resolves to. Patching
+# `sys.modules` is immune to that.
+# ---------------------------------------------------------------------------
+def _stub_health(monkeypatch, **functions):
+    stub = types.ModuleType("src.workflow.health")
+    for name, value in functions.items():
+        setattr(stub, name, value)
+    monkeypatch.setitem(sys.modules, "src.workflow.health", stub)
+    return stub
+
+
+@pytest.fixture
+def rendered(monkeypatch):
+    """Record which panels the expander rendered, without running them."""
+    mock_streamlit.reset_mock()
+    mock_streamlit.fragment = _identity_decorator
+    panels = []
+    for name in ("monitor_queue", "monitor_storage", "monitor_hardware"):
+        monkeypatch.setattr(
+            common, name, (lambda captured: lambda: panels.append(captured))(name)
+        )
+    return panels
+
+
+def _deployment(monkeypatch, *, queue: dict, workers_remote: bool):
+    _stub_health(
+        monkeypatch,
+        get_queue_metrics=lambda: queue,
+        queue_workers_are_remote=lambda: workers_remote,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Which panels apply
+# ---------------------------------------------------------------------------
+def test_monitor_hardware_hidden_online(monkeypatch, rendered):
+    """
+    Kubernetes: separate Streamlit and rq-worker pods. psutil here describes a
+    process that runs no workflow, so the panel is hidden and the queue and the
+    shared volume - what the user's job actually waits on - take its place.
+    """
+    _deployment(
+        monkeypatch,
+        queue={"available": True, "total_workers": 2},
+        workers_remote=True,
+    )
+
+    common.render_resource_utilization()
+
+    assert "monitor_hardware" not in rendered, (
+        "the psutil panel describes the Streamlit pod, which does no work; an "
+        "idle 2Gi container shown while a 64Gi worker saturates is worse than "
+        "showing nothing"
+    )
+    assert rendered == ["monitor_queue", "monitor_storage"], rendered
+
+
+def test_monitor_hardware_shown_when_the_workers_share_this_container(
+    monkeypatch, rendered
+):
+    """
+    The full image under docker/docker-compose: `docker/entrypoint.sh` runs
+    Redis, the RQ workers and Streamlit in one container, so psutil is
+    measuring exactly the machine the workflows run on.
+    """
+    _deployment(
+        monkeypatch,
+        queue={"available": True, "total_workers": 2},
+        workers_remote=False,
+    )
+
+    common.render_resource_utilization()
+
+    assert rendered == ["monitor_queue", "monitor_storage", "monitor_hardware"], rendered
+
+
+def test_the_expander_is_never_empty_without_a_queue(monkeypatch, rendered):
+    """
+    `Dockerfile_simple` bakes `online_deployment: true`, installs no
+    redis-server, and runs the workflows in this process. Gating the psutil
+    panel on that flag left the expander rendering an empty body - the queue
+    and storage panels draw nothing without a queue, and the one panel that had
+    real numbers was the one being suppressed.
+    """
+    _deployment(monkeypatch, queue={}, workers_remote=False)
+
+    common.render_resource_utilization()
+
+    assert rendered == ["monitor_hardware"], rendered
+
+
+# ---------------------------------------------------------------------------
+# What the storage indicator says
+# ---------------------------------------------------------------------------
+def _render_storage(monkeypatch, status):
+    mock_streamlit.reset_mock()
+    mock_streamlit.fragment = _identity_decorator
+    _stub_health(
+        monkeypatch,
+        get_storage_status=status if callable(status) else (lambda: status),
+    )
+    common.monitor_storage()
+
+
+def _markdown() -> str:
+    return " ".join(
+        str(call.args[0]) for call in mock_streamlit.markdown.call_args_list if call.args
+    )
+
+
+def _captions() -> str:
+    return " ".join(
+        str(call.args[0]) for call in mock_streamlit.caption.call_args_list if call.args
+    )
+
+
+def test_storage_indicator_renders_each_state(monkeypatch):
+    """
+    Colour is the whole payload here, so it is what gets asserted:
+
+    - green while every node's mount answers,
+    - amber naming the node whose mount stopped answering, because a healthy
+      node must not cover for a wedged one,
+    - red when no node answers at all,
+    - grey, never red, when Redis is down: that says nothing about the mount,
+      and reporting it as a storage fault sends the operator to the wrong layer.
+    """
+    _render_storage(
+        monkeypatch, {"available": True, "state": "connected", "nodes": ["node-a"]}
+    )
+    assert ":green[" in _markdown(), _markdown()
+
+    _render_storage(
+        monkeypatch,
+        {
+            "available": True,
+            "state": "degraded",
+            "nodes": ["node-a"],
+            "stale_nodes": ["node-b"],
+        },
+    )
+    degraded = _markdown()
+    assert ":green[" not in degraded, (
+        "one node's mount is wedged; a green tick is the outage the per node "
+        f"heartbeats exist to make visible: {degraded}"
+    )
+    assert ":orange[" in degraded, degraded
+    assert "node-b" in _captions(), (
+        "an operator needs to know which node to look at, not just that one "
+        f"broke: {_captions()}"
+    )
+
+    _render_storage(
+        monkeypatch,
+        {
+            "available": True,
+            "state": "unreachable",
+            "nodes": [],
+            "stale_nodes": ["node-a"],
+        },
+    )
+    assert ":red[" in _markdown(), _markdown()
+
+    _render_storage(monkeypatch, {"available": False, "state": "unknown", "nodes": []})
+    unknown = _markdown()
+    assert ":red[" not in unknown, (
+        f"a dead Redis must not be reported as failed storage: {unknown}"
+    )
+    assert ":gray[" in unknown, unknown
+
+
+def test_storage_indicator_renders_nothing_where_nothing_publishes(monkeypatch):
+    """
+    `{}` is "no shared storage is being reported here", which is every local
+    run, every docker-compose run and every apptainer run of the image. A red
+    tick there would be a permanent false alarm about a mechanism that is not
+    deployed.
+    """
+    _render_storage(monkeypatch, {})
+
+    assert _markdown() == ""
+    assert _captions() == ""
+
+
+def test_a_broken_storage_indicator_is_not_silent(monkeypatch, caplog):
+    """
+    The indicator must never break the sidebar, but swallowing the failure
+    leaves a broken indicator indistinguishable from a deployment that has no
+    shared storage - undetectable in production and in CI alike.
+    """
+
+    def _explode():
+        raise RuntimeError("redis client blew up")
+
+    with caplog.at_level("ERROR"):
+        _render_storage(monkeypatch, _explode)  # must not raise
+
+    assert caplog.records, (
+        "the indicator swallowed an exception without logging it, so a broken "
+        "indicator is silent in production and invisible in CI"
+    )
+    assert any(
+        "redis client blew up" in str(record.exc_info) or "redis client blew up" in record.getMessage()
+        for record in caplog.records
+    ), [record.getMessage() for record in caplog.records]
diff --git a/tests/test_streamlit_ui_param_read.py b/tests/test_streamlit_ui_param_read.py
new file mode 100644
index 00000000..3b5ed483
--- /dev/null
+++ b/tests/test_streamlit_ui_param_read.py
@@ -0,0 +1,240 @@
+"""
+``StreamlitUI._read_params_for_update()`` — the read half of the two
+read-modify-write-back sites inside ``_input_TOPP_impl()``.
+
+Both of them merge into what they read and write the result straight back, and
+they run on *every* ``input_TOPP()`` of *every* ``configure()`` render. A
+tolerant empty dict there is the erasure bug at its highest frequency: it would
+be written over ``_defaults``, ``_flag_params`` and every other tool's values
+while looking like a successful save.
+
+Raising alone is not enough at this site, which is why it has its own method and
+its own tests. The contract is:
+
+* an unreadable file skips the write entirely, so the bytes on disk stay
+  recoverable, and surfaces an error with a way forward;
+* the way forward preserves the previous file rather than deleting it — the
+  most common cause of an unreadable params.json on a shared filesystem is a
+  healthy params.json behind a storage blip;
+* a failure that is expected to clear by itself does *not* offer that reset at
+  all, because taking it during a Ganesha restart is what would destroy an
+  intact file;
+* an absent file still reads as ``{}``: a first run has no parameters.
+"""
+import json
+import os
+import sys
+from unittest.mock import MagicMock
+
+import pytest
+
+# Add project root to path for imports
+PROJECT_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+sys.path.append(PROJECT_ROOT)
+
+# ---------------------------------------------------------------------------
+# Import with `streamlit`, `pyopenms` and `src.common.common` mocked at the
+# sys.modules level, mirroring tests/test_topp_flag_parameters.py. The method
+# under test only calls st.error / st.button / st.toast / st.stop, and with a
+# mocked st.stop() the documented fallback applies: it re-raises rather than
+# falling through to the write, which is exactly the property to assert.
+# ---------------------------------------------------------------------------
+mock_streamlit = MagicMock()
+mock_streamlit.session_state = {}
+
+_originals = {
+    name: sys.modules.get(name)
+    for name in ("streamlit", "pyopenms", "src.common.common")
+}
+sys.modules["streamlit"] = mock_streamlit
+if _originals["pyopenms"] is None:
+    sys.modules["pyopenms"] = MagicMock()
+if _originals["src.common.common"] is None:
+    # Pulls in captcha / psutil / pandas and a lot of Streamlit surface; none
+    # of it is reachable from the method under test.
+    sys.modules["src.common.common"] = MagicMock()
+
+from src.workflow.ParameterManager import (
+    InvalidParameterFileError,
+    ParameterManager,
+    TransientParameterFileError,
+)
+from src.workflow.StreamlitUI import StreamlitUI
+
+for name, module in _originals.items():
+    if module is not None:
+        sys.modules[name] = module
+    else:
+        sys.modules.pop(name, None)
+
+for _key in list(sys.modules.keys()):
+    if _key.startswith("src.workflow"):
+        sys.modules.pop(_key, None)
+
+
+TOOL_INSTANCE = "FeatureFinderMetabo"
+
+STORED_PARAMS = {
+    "_defaults": {TOOL_INSTANCE: {"algorithm:common:noise_threshold_int": 1000.0}},
+    "_flag_params": {TOOL_INSTANCE: ["force"]},
+    "MetaboliteAdductDecharger": {
+        "algorithm:MetaboliteFeatureDeconvolution:charge_max": 2
+    },
+}
+
+
+@pytest.fixture(autouse=True)
+def reset_streamlit_mock():
+    """Fresh session state and a *falsy* st.button between tests."""
+    mock_streamlit.reset_mock()
+    mock_streamlit.session_state = {}
+    # A bare MagicMock() return value is truthy, which would press every button
+    # on the page.
+    mock_streamlit.button.return_value = False
+    yield
+    mock_streamlit.reset_mock()
+    mock_streamlit.session_state = {}
+
+
+def _ui(tmp_path):
+    """
+    A StreamlitUI carrying only the member the method touches.
+
+    __init__ is bypassed: it calls get_parameters_from_json(), which would
+    already have absorbed the failure under test.
+    """
+    ui = object.__new__(StreamlitUI)
+    ui.parameter_manager = ParameterManager(tmp_path)
+    return ui
+
+
+def _write_torn_params_file(ui) -> bytes:
+    """Leave params.json unparseable but with every original byte on disk."""
+    text = json.dumps(STORED_PARAMS, indent=4) + '\n{\n    "_defaults": {\n'
+    ui.parameter_manager.params_file.write_text(text, encoding="utf-8")
+    return ui.parameter_manager.params_file.read_bytes()
+
+
+def test_readable_file_is_returned_unchanged(tmp_path):
+    ui = _ui(tmp_path)
+    ui.parameter_manager.params_file.write_text(
+        json.dumps(STORED_PARAMS), encoding="utf-8"
+    )
+
+    assert ui._read_params_for_update(TOOL_INSTANCE) == STORED_PARAMS
+    mock_streamlit.error.assert_not_called()
+    mock_streamlit.stop.assert_not_called()
+
+
+def test_absent_file_reads_as_empty(tmp_path):
+    """A first run has no stored parameters; that is not a failure."""
+    ui = _ui(tmp_path)
+    assert not ui.parameter_manager.params_file.exists()
+
+    assert ui._read_params_for_update(TOOL_INSTANCE) == {}
+    mock_streamlit.error.assert_not_called()
+    mock_streamlit.stop.assert_not_called()
+
+
+def test_unreadable_file_stops_instead_of_returning_an_empty_dict(tmp_path):
+    """
+    The one thing that must never happen here: returning {} to the caller,
+    which merges it and writes it straight back.
+    """
+    ui = _ui(tmp_path)
+    before = _write_torn_params_file(ui)
+
+    with pytest.raises(InvalidParameterFileError):
+        ui._read_params_for_update(TOOL_INSTANCE)
+
+    mock_streamlit.stop.assert_called_once()
+    assert mock_streamlit.error.called, "the user has to be told why nothing saved"
+    assert ui.parameter_manager.params_file.read_bytes() == before, (
+        "the unreadable file must be preserved so it can still be repaired"
+    )
+
+
+def test_unreadable_file_offers_a_reset_keyed_per_tool_instance(tmp_path):
+    """
+    Without an affordance the page stops on every render with no way forward.
+    The key has to carry the instance name: this runs once per tool fragment,
+    and duplicate widget keys raise.
+    """
+    ui = _ui(tmp_path)
+    _write_torn_params_file(ui)
+
+    with pytest.raises(InvalidParameterFileError):
+        ui._read_params_for_update(TOOL_INSTANCE)
+
+    assert mock_streamlit.button.called
+    assert TOOL_INSTANCE in mock_streamlit.button.call_args.kwargs["key"]
+
+
+def test_reset_preserves_the_unreadable_file(tmp_path):
+    """
+    Pressing reset must not be the data loss. An unreadable params.json is very
+    often an intact params.json behind a storage blip, so the previous file is
+    moved aside rather than unlinked.
+    """
+    ui = _ui(tmp_path)
+    before = _write_torn_params_file(ui)
+    mock_streamlit.button.return_value = True
+
+    with pytest.raises(InvalidParameterFileError):
+        ui._read_params_for_update(TOOL_INSTANCE)
+
+    assert not ui.parameter_manager.params_file.exists()
+    backups = [p for p in tmp_path.iterdir() if p.name.endswith(".bak")]
+    assert len(backups) == 1, f"expected the previous file to be kept, found {backups}"
+    assert backups[0].read_bytes() == before
+
+
+def test_transient_failure_does_not_offer_the_destructive_reset(tmp_path, monkeypatch):
+    """
+    ESTALE from a restarting NFS export is not corruption. Offering "reset to
+    defaults" there invites the user to delete a file that is about to become
+    readable again on its own.
+    """
+    ui = _ui(tmp_path)
+    ui.parameter_manager.params_file.write_text(
+        json.dumps(STORED_PARAMS), encoding="utf-8"
+    )
+
+    def unreachable():
+        raise TransientParameterFileError("storage did not answer")
+
+    monkeypatch.setattr(
+        ui.parameter_manager, "read_parameters_strict", unreachable
+    )
+
+    with pytest.raises(TransientParameterFileError):
+        ui._read_params_for_update(TOOL_INSTANCE)
+
+    mock_streamlit.stop.assert_called_once()
+    assert mock_streamlit.error.called
+    mock_streamlit.button.assert_not_called()
+    assert ui.parameter_manager.params_file.exists()
+
+
+def test_a_failed_reset_is_reported_rather_than_raised(tmp_path, monkeypatch):
+    """
+    If the reset itself cannot run, the button used to raise, the file stayed,
+    and the next render stopped again — an unrecoverable halt of the parameter
+    page. The failure has to be surfaced instead.
+    """
+    ui = _ui(tmp_path)
+    _write_torn_params_file(ui)
+    mock_streamlit.button.return_value = True
+
+    def refuse():
+        raise PermissionError("read-only filesystem")
+
+    monkeypatch.setattr(
+        ui.parameter_manager, "reset_to_default_parameters", refuse
+    )
+
+    with pytest.raises(InvalidParameterFileError):
+        ui._read_params_for_update(TOOL_INSTANCE)
+
+    messages = " ".join(str(call) for call in mock_streamlit.error.call_args_list)
+    assert "read-only filesystem" in messages
diff --git a/tests/test_tool_instance_name.py b/tests/test_tool_instance_name.py
new file mode 100644
index 00000000..d1eef17a
--- /dev/null
+++ b/tests/test_tool_instance_name.py
@@ -0,0 +1,284 @@
+"""
+Tests for the tool_instance_name functionality.
+
+This module verifies that save_parameters correctly resolves tool instance names
+to real tool names when calling create_ini, and that parameters are stored and
+retrieved using the instance name as the key.
+"""
+import os
+import sys
+import json
+import pytest
+import tempfile
+from pathlib import Path
+from unittest.mock import patch, MagicMock, call
+
+# Add project root to path for imports
+PROJECT_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+sys.path.append(PROJECT_ROOT)
+
+# Mock streamlit before importing ParameterManager
+mock_streamlit = MagicMock()
+mock_streamlit.session_state = {}
+
+_original_streamlit = sys.modules.get('streamlit')
+sys.modules['streamlit'] = mock_streamlit
+
+
+def _drop_cached_workflow_modules() -> None:
+    """Forget any cached src.workflow modules.
+
+    A module binds `st` once, at import time. If an earlier test file has already
+    imported src.workflow.ParameterManager against the real streamlit, the import
+    below is just a cache hit and the mock never takes effect - which is why these
+    tests passed when run alone but failed in a full-suite run.
+    """
+    for _key in list(sys.modules.keys()):
+        if _key.startswith('src.workflow'):
+            sys.modules.pop(_key, None)
+
+
+# Drop first, so the import below really binds the mock.
+_drop_cached_workflow_modules()
+
+from src.workflow.ParameterManager import ParameterManager
+
+if _original_streamlit is not None:
+    sys.modules['streamlit'] = _original_streamlit
+else:
+    sys.modules.pop('streamlit', None)
+
+# Drop again, so later test files re-import against the real streamlit instead of
+# the mock-bound modules this file just created.
+_drop_cached_workflow_modules()
+
+
+@pytest.fixture
+def temp_workflow_dir():
+    """Create a temporary workflow directory for testing."""
+    with tempfile.TemporaryDirectory() as tmpdir:
+        workflow_dir = Path(tmpdir) / "test-workflow"
+        workflow_dir.mkdir()
+        ini_dir = workflow_dir / "ini"
+        ini_dir.mkdir()
+        yield workflow_dir
+
+
+@pytest.fixture(autouse=True)
+def reset_streamlit_state():
+    """Reset mock streamlit session state before each test."""
+    mock_streamlit.session_state.clear()
+    yield
+
+
+class TestSaveParametersWithInstanceName:
+    """Tests for save_parameters correctly resolving tool instance names."""
+
+    def test_save_parameters_uses_real_tool_name_for_create_ini(self, temp_workflow_dir):
+        """Test that save_parameters resolves instance name to real tool name
+        before calling create_ini."""
+        pm = ParameterManager(temp_workflow_dir)
+
+        # Simulate session state with an instance name (IDFilter_step1)
+        # that differs from the real tool name (IDFilter)
+        mock_streamlit.session_state[f"{pm.topp_param_prefix}IDFilter_step1:1:score:pep"] = 0.05
+        # Register instance mapping (as input_TOPP would)
+        mock_streamlit.session_state["_topp_tool_instance_map"] = {
+            "IDFilter_step1": "IDFilter"
+        }
+
+        # Mock create_ini to track calls - return False (tool not found)
+        # to prevent further processing that requires actual ini files
+        with patch.object(pm, 'create_ini', return_value=False) as mock_create_ini:
+            pm.save_parameters()
+
+        # Verify create_ini was called with the REAL tool name, not the instance name
+        mock_create_ini.assert_called_once_with("IDFilter")
+
+    def test_save_parameters_without_instance_map_uses_tool_name_directly(self, temp_workflow_dir):
+        """Test that save_parameters works normally when no instance map exists
+        (backward compatibility)."""
+        pm = ParameterManager(temp_workflow_dir)
+
+        # Simulate session state with a normal tool name (no instance mapping)
+        mock_streamlit.session_state[f"{pm.topp_param_prefix}IDFilter:1:score:pep"] = 0.05
+
+        with patch.object(pm, 'create_ini', return_value=False) as mock_create_ini:
+            pm.save_parameters()
+
+        # Should use the tool name directly
+        mock_create_ini.assert_called_once_with("IDFilter")
+
+    def test_save_parameters_stores_under_instance_name(self, temp_workflow_dir):
+        """Test that parameters are stored in JSON under the instance name, not
+        the real tool name."""
+        pm = ParameterManager(temp_workflow_dir)
+
+        # Create a mock ini file for IDFilter
+        ini_path = temp_workflow_dir / "ini" / "IDFilter.ini"
+        ini_path.touch()
+
+        # Set up instance mapping
+        mock_streamlit.session_state["_topp_tool_instance_map"] = {
+            "IDFilter_step1": "IDFilter"
+        }
+        mock_streamlit.session_state[f"{pm.topp_param_prefix}IDFilter_step1:1:score:pep"] = 0.05
+
+        # Mock pyopenms Param and ParamXMLFile to avoid needing real ini files
+        mock_param = MagicMock()
+        mock_param.getValue.return_value = 0.01  # Different from session state value
+
+        with patch.object(pm, 'create_ini', return_value=True), \
+             patch('pyopenms.Param', return_value=mock_param), \
+             patch('pyopenms.ParamXMLFile') as mock_xml:
+            pm.save_parameters()
+
+        # Load saved parameters
+        with open(pm.params_file, "r") as f:
+            saved = json.load(f)
+
+        # Parameters should be stored under the instance name
+        assert "IDFilter_step1" in saved
+        assert saved["IDFilter_step1"]["score:pep"] == 0.05
+
+    def test_save_parameters_multiple_instances_same_tool(self, temp_workflow_dir):
+        """Test that two instances of the same tool get separate parameter entries."""
+        pm = ParameterManager(temp_workflow_dir)
+
+        ini_path = temp_workflow_dir / "ini" / "IDFilter.ini"
+        ini_path.touch()
+
+        # Set up two instances with different parameter values
+        mock_streamlit.session_state["_topp_tool_instance_map"] = {
+            "IDFilter_step1": "IDFilter",
+            "IDFilter_step2": "IDFilter",
+        }
+        mock_streamlit.session_state[f"{pm.topp_param_prefix}IDFilter_step1:1:score:pep"] = 0.01
+        mock_streamlit.session_state[f"{pm.topp_param_prefix}IDFilter_step2:1:score:pep"] = 0.05
+
+        mock_param = MagicMock()
+        mock_param.getValue.return_value = 0.0  # Default differs from both
+
+        with patch.object(pm, 'create_ini', return_value=True), \
+             patch('pyopenms.Param', return_value=mock_param), \
+             patch('pyopenms.ParamXMLFile'):
+            pm.save_parameters()
+
+        with open(pm.params_file, "r") as f:
+            saved = json.load(f)
+
+        # Both instances should have separate entries
+        assert "IDFilter_step1" in saved
+        assert "IDFilter_step2" in saved
+        assert saved["IDFilter_step1"]["score:pep"] == 0.01
+        assert saved["IDFilter_step2"]["score:pep"] == 0.05
+
+    def test_save_parameters_ini_key_maps_instance_to_real_tool(self, temp_workflow_dir):
+        """Test that ini_key correctly maps instance name back to real tool name
+        for param.getValue lookup."""
+        pm = ParameterManager(temp_workflow_dir)
+
+        ini_path = temp_workflow_dir / "ini" / "IDFilter.ini"
+        ini_path.touch()
+
+        mock_streamlit.session_state["_topp_tool_instance_map"] = {
+            "IDFilter_step1": "IDFilter"
+        }
+        mock_streamlit.session_state[f"{pm.topp_param_prefix}IDFilter_step1:1:score:pep"] = 0.05
+
+        mock_param = MagicMock()
+        mock_param.getValue.return_value = 0.01
+
+        with patch.object(pm, 'create_ini', return_value=True), \
+             patch('pyopenms.Param', return_value=mock_param), \
+             patch('pyopenms.ParamXMLFile'):
+            pm.save_parameters()
+
+        # Verify that param.getValue was called with the REAL tool name key
+        # (IDFilter:1:score:pep), not the instance name key (IDFilter_step1:1:score:pep)
+        mock_param.getValue.assert_called_with(b"IDFilter:1:score:pep")
+
+    def test_save_parameters_display_keys_skipped_with_instance_name(self, temp_workflow_dir):
+        """Test that _display keys are still skipped when using instance names."""
+        pm = ParameterManager(temp_workflow_dir)
+
+        ini_path = temp_workflow_dir / "ini" / "IDFilter.ini"
+        ini_path.touch()
+
+        mock_streamlit.session_state["_topp_tool_instance_map"] = {
+            "IDFilter_step1": "IDFilter"
+        }
+        mock_streamlit.session_state[f"{pm.topp_param_prefix}IDFilter_step1:1:score:pep"] = 0.05
+        mock_streamlit.session_state[f"{pm.topp_param_prefix}IDFilter_step1:1:score:pep_display"] = ["0.05"]
+
+        mock_param = MagicMock()
+        mock_param.getValue.return_value = 0.01
+
+        with patch.object(pm, 'create_ini', return_value=True), \
+             patch('pyopenms.Param', return_value=mock_param), \
+             patch('pyopenms.ParamXMLFile'):
+            pm.save_parameters()
+
+        with open(pm.params_file, "r") as f:
+            saved = json.load(f)
+
+        # _display key should not be stored
+        assert "score:pep_display" not in saved.get("IDFilter_step1", {})
+        assert "score:pep" in saved.get("IDFilter_step1", {})
+
+
+class TestGetToppParametersWithInstanceName:
+    """Tests for get_topp_parameters with tool_instance_name."""
+
+    def test_get_topp_parameters_with_instance_name(self, temp_workflow_dir):
+        """Test that get_topp_parameters uses instance name for JSON lookup."""
+        pm = ParameterManager(temp_workflow_dir)
+
+        # Create params.json with instance-keyed parameters
+        params = {
+            "IDFilter_step1": {
+                "score:pep": 0.05
+            }
+        }
+        with open(pm.params_file, "w") as f:
+            json.dump(params, f)
+
+        # Create a mock ini file
+        ini_path = temp_workflow_dir / "ini" / "IDFilter.ini"
+        ini_path.touch()
+
+        mock_param = MagicMock()
+        mock_param.keys.return_value = [b"IDFilter:1:score:pep"]
+        mock_param.getValue.return_value = 0.01  # default
+
+        with patch('pyopenms.Param', return_value=mock_param), \
+             patch('pyopenms.ParamXMLFile'):
+            result = pm.get_topp_parameters("IDFilter", tool_instance_name="IDFilter_step1")
+
+        # Should return the instance-specific value
+        assert result["score:pep"] == 0.05
+
+    def test_get_topp_parameters_without_instance_name_backward_compat(self, temp_workflow_dir):
+        """Test that get_topp_parameters works without instance name (backward compat)."""
+        pm = ParameterManager(temp_workflow_dir)
+
+        params = {
+            "IDFilter": {
+                "score:pep": 0.05
+            }
+        }
+        with open(pm.params_file, "w") as f:
+            json.dump(params, f)
+
+        ini_path = temp_workflow_dir / "ini" / "IDFilter.ini"
+        ini_path.touch()
+
+        mock_param = MagicMock()
+        mock_param.keys.return_value = [b"IDFilter:1:score:pep"]
+        mock_param.getValue.return_value = 0.01
+
+        with patch('pyopenms.Param', return_value=mock_param), \
+             patch('pyopenms.ParamXMLFile'):
+            result = pm.get_topp_parameters("IDFilter")
+
+        assert result["score:pep"] == 0.05
diff --git a/tests/test_topp_flag_parameters.py b/tests/test_topp_flag_parameters.py
new file mode 100644
index 00000000..3dcd10ef
--- /dev/null
+++ b/tests/test_topp_flag_parameters.py
@@ -0,0 +1,365 @@
+"""
+Unit tests for PR #397 — flag parameter support for TOPP tools.
+
+PR #397 lets a caller mark certain TOPP parameters as CLI *flags*: parameters
+passed by presence only (e.g. ``-force``), without a trailing value. The flag
+names are persisted per tool instance by ``input_TOPP()`` into both
+``st.session_state["_topp_flag_params"]`` and ``params.json["_flag_params"]``,
+and consumed by ``run_topp()`` in ``src/workflow/CommandExecutor.py`` when it
+builds the command line.
+
+These tests exercise ``run_topp()`` — the consumer that turns the persisted flag
+definitions and merged parameters into an actual command. Driving ``run_topp()``
+also validates the persistence *contract* (the exact ``_flag_params`` /
+``_topp_flag_params`` shapes that ``input_TOPP()`` writes), which is where the two
+halves of the feature meet.
+
+The suite covers the working behaviour of the feature and also guards the two
+issues CodeRabbit flagged during review, which are now fixed in ``run_topp()``:
+    - Finding 1 (per-tool flag fallback):
+      https://github.com/OpenMS/streamlit-template/pull/397#discussion_r3585023551
+    - Finding 2 (list expansion / empty-list skipping):
+      https://github.com/OpenMS/streamlit-template/pull/397#discussion_r3585023558
+The tests that pin those findings carry a "CodeRabbit finding N" note in their
+docstrings and live alongside the related behaviour they protect.
+"""
+import os
+import sys
+import json
+import tempfile
+from pathlib import Path
+from unittest.mock import MagicMock
+
+import pytest
+
+# Add project root to path for imports
+PROJECT_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+sys.path.append(PROJECT_ROOT)
+
+# ---------------------------------------------------------------------------
+# Import the modules under test with `streamlit` (and `pyopenms`) mocked at the
+# sys.modules level. Both CommandExecutor and ParameterManager do
+# `import streamlit as st` at module top (ParameterManager also
+# `import pyopenms as poms`). run_topp() only needs `st.session_state` to behave
+# like a plain dict and never touches pyopenms, so lightweight mocks keep the
+# test runnable without those heavy deps installed while still exercising the
+# real command-construction logic. Mirrors tests/test_tool_instance_name.py.
+# ---------------------------------------------------------------------------
+mock_streamlit = MagicMock()
+mock_streamlit.session_state = {}
+
+_original_streamlit = sys.modules.get("streamlit")
+_original_pyopenms = sys.modules.get("pyopenms")
+sys.modules["streamlit"] = mock_streamlit
+if _original_pyopenms is None:
+    sys.modules["pyopenms"] = MagicMock()
+
+from src.workflow.ParameterManager import ParameterManager
+from src.workflow.CommandExecutor import CommandExecutor
+
+# Restore the original modules so other test files import the real ones. The
+# classes imported above keep their module-level `st`/`poms` bound to the mocks.
+if _original_streamlit is not None:
+    sys.modules["streamlit"] = _original_streamlit
+else:
+    sys.modules.pop("streamlit", None)
+if _original_pyopenms is None:
+    sys.modules.pop("pyopenms", None)
+
+for _key in list(sys.modules.keys()):
+    if _key.startswith("src.workflow"):
+        sys.modules.pop(_key, None)
+
+
+TOOL = "FeatureFinderMetabo"
+
+
+@pytest.fixture(autouse=True)
+def reset_session_state():
+    """Give each test a fresh, empty mocked session_state."""
+    mock_streamlit.session_state = {}
+    yield
+    mock_streamlit.session_state = {}
+
+
+def build_command(
+    params_json=None,
+    session_state=None,
+    *,
+    tool=TOOL,
+    input_output=None,
+    custom_params=None,
+    tool_instance_name=None,
+):
+    """
+    Invoke ``run_topp()`` with the supplied ``params.json`` content and
+    ``session_state``, and return the single command list it builds.
+
+    ``run_command`` / ``run_multiple_commands`` are stubbed so nothing is
+    executed; the built command is captured from the ``run_command`` mock.
+
+    ``max_threads`` is pinned to 1 so the trailing ``-threads`` argument is
+    deterministic, and pinning it takes *both* halves: ``_get_max_threads()``
+    resolves ``online_deployment`` from a ``settings.json`` read relative to the
+    process working directory, and only consults the workspace ``params.json``
+    on the local branch. So the temporary directory gets its own local-mode
+    ``settings.json`` and becomes the CWD for the call — otherwise these argv
+    assertions would silently depend on the repository-root config and on where
+    pytest happens to be run from, and a fork shipping
+    ``online_deployment: true`` would see ``-threads 2`` here.
+    """
+    if input_output is None:
+        input_output = {"in": ["input.mzML"], "out": ["output.featureXML"]}
+
+    params_json = dict(params_json or {})
+    params_json.setdefault("max_threads", 1)
+
+    with tempfile.TemporaryDirectory() as tmpdir:
+        workflow_dir = Path(tmpdir)
+        with open(Path(tmpdir, "settings.json"), "w", encoding="utf-8") as f:
+            json.dump(
+                {"online_deployment": False, "max_threads": {"local": 1, "online": 1}},
+                f,
+            )
+
+        pm = ParameterManager(workflow_dir)
+        with open(pm.params_file, "w", encoding="utf-8") as f:
+            json.dump(params_json, f)
+
+        mock_streamlit.session_state = dict(session_state or {})
+
+        executor = CommandExecutor(workflow_dir, MagicMock(), pm)
+        executor.run_command = MagicMock(return_value=True)
+        executor.run_multiple_commands = MagicMock(return_value=True)
+
+        previous_cwd = os.getcwd()
+        os.chdir(tmpdir)
+        try:
+            executor.run_topp(
+                tool,
+                input_output,
+                custom_params=custom_params or {},
+                tool_instance_name=tool_instance_name or tool,
+            )
+        finally:
+            os.chdir(previous_cwd)
+
+        assert executor.run_command.call_count == 1, (
+            "expected exactly one single-process command, got "
+            f"{executor.run_command.call_count}"
+        )
+        return executor.run_command.call_args.args[0]
+
+
+# --------------------------- assertion helpers -----------------------------
+
+def has_flag(cmd, name):
+    """True if ``-name`` appears anywhere in the command."""
+    return f"-{name}" in cmd
+
+
+def token_after(cmd, name):
+    """The single token immediately following ``-name`` (or None if it is last)."""
+    idx = cmd.index(f"-{name}")
+    return cmd[idx + 1] if idx + 1 < len(cmd) else None
+
+
+def values_after(cmd, name):
+    """All value tokens following ``-name`` up to the next ``-flag`` token."""
+    idx = cmd.index(f"-{name}")
+    vals = []
+    for tok in cmd[idx + 1:]:
+        if tok.startswith("-"):
+            break
+        vals.append(tok)
+    return vals
+
+
+def is_bare_flag(cmd, name):
+    """True if ``-name`` is present with no value (next token is another flag)."""
+    if not has_flag(cmd, name):
+        return False
+    nxt = token_after(cmd, name)
+    return nxt is None or nxt.startswith("-")
+
+
+# ============================ working behaviour ============================
+
+
+class TestCommandSkeleton:
+    def test_input_output_files_prefixed(self):
+        cmd = build_command()
+        assert cmd[0] == TOOL
+        assert cmd[1:5] == ["-in", "input.mzML", "-out", "output.featureXML"]
+        # threads pinned to 1 and always appended last
+        assert cmd[-2:] == ["-threads", "1"]
+
+    def test_collected_files_passed_as_single_list(self):
+        # A [["a", "b"]] entry is expanded in place after its -key.
+        cmd = build_command(input_output={"in": [["a.mzML", "b.mzML"]], "out": ["c.featureXML"]})
+        assert cmd[1:4] == ["-in", "a.mzML", "b.mzML"]
+
+
+class TestFlagParameters:
+    """Flags emit a bare ``-key`` when enabled and nothing when disabled."""
+
+    def test_flag_true_bool_emits_bare_flag(self):
+        cmd = build_command(
+            {"_flag_params": {TOOL: ["force"]}, TOOL: {"force": True}}
+        )
+        assert is_bare_flag(cmd, "force")
+        assert "True" not in cmd
+
+    def test_flag_string_true_emits_bare_flag(self):
+        cmd = build_command(
+            {"_flag_params": {TOOL: ["force"]}, TOOL: {"force": "true"}}
+        )
+        assert is_bare_flag(cmd, "force")
+        assert "true" not in cmd
+
+    def test_flag_string_true_is_case_insensitive(self):
+        cmd = build_command(
+            {"_flag_params": {TOOL: ["force"]}, TOOL: {"force": "True"}}
+        )
+        assert is_bare_flag(cmd, "force")
+
+    def test_flag_false_bool_omitted(self):
+        cmd = build_command(
+            {"_flag_params": {TOOL: ["force"]}, TOOL: {"force": False}}
+        )
+        assert not has_flag(cmd, "force")
+
+    def test_flag_string_false_omitted(self):
+        cmd = build_command(
+            {"_flag_params": {TOOL: ["force"]}, TOOL: {"force": "false"}}
+        )
+        assert not has_flag(cmd, "force")
+
+
+class TestRegularParameters:
+    """Non-flag merged parameters keep the existing value-appending behaviour."""
+
+    def test_empty_string_skipped(self):
+        cmd = build_command({TOOL: {"opt": ""}})
+        assert not has_flag(cmd, "opt")
+
+    def test_none_skipped(self):
+        cmd = build_command({TOOL: {"opt": None}})
+        assert not has_flag(cmd, "opt")
+
+    def test_zero_is_preserved(self):
+        # 0 and 0.0 are valid values, not "empty" — they must be passed through.
+        cmd = build_command({TOOL: {"min_int": 0, "min_float": 0.0}})
+        assert values_after(cmd, "min_int") == ["0"]
+        assert values_after(cmd, "min_float") == ["0.0"]
+
+    def test_scalar_value_appended(self):
+        cmd = build_command({TOOL: {"mz_tolerance": 10.5}})
+        assert values_after(cmd, "mz_tolerance") == ["10.5"]
+
+    def test_multiline_string_split_into_args(self):
+        cmd = build_command({TOOL: {"seq": "ALPHA\nBETA\nGAMMA"}})
+        assert values_after(cmd, "seq") == ["ALPHA", "BETA", "GAMMA"]
+
+    def test_merged_list_param_expanded(self):
+        """
+        CodeRabbit finding 2 (fixed): a list-valued merged parameter expands into
+        separate CLI args, not its Python ``str()`` (e.g. ``"['a', 'b']"``).
+        https://github.com/OpenMS/streamlit-template/pull/397#discussion_r3585023558
+        """
+        cmd = build_command({TOOL: {"ids": ["a", "b"]}})
+        assert values_after(cmd, "ids") == ["a", "b"]
+
+    def test_merged_empty_list_param_skipped(self):
+        """
+        CodeRabbit finding 2 (fixed): an empty-list merged parameter is omitted
+        entirely rather than emitting a ``-key`` with no usable value.
+        https://github.com/OpenMS/streamlit-template/pull/397#discussion_r3585023558
+        """
+        cmd = build_command({TOOL: {"ids": []}})
+        assert not has_flag(cmd, "ids")
+
+
+class TestCustomParameters:
+    """custom_params share the flag set and expand non-empty lists."""
+
+    def test_custom_flag_truthy_bare(self):
+        cmd = build_command(
+            {"_flag_params": {TOOL: ["force"]}},
+            custom_params={"force": True},
+        )
+        assert is_bare_flag(cmd, "force")
+
+    def test_custom_flag_false_omitted(self):
+        cmd = build_command(
+            {"_flag_params": {TOOL: ["force"]}},
+            custom_params={"force": False},
+        )
+        assert not has_flag(cmd, "force")
+
+    def test_custom_scalar_value(self):
+        cmd = build_command(custom_params={"extra": 5})
+        assert values_after(cmd, "extra") == ["5"]
+
+    def test_custom_nonempty_list_expanded(self):
+        cmd = build_command(custom_params={"ids": ["a", "b", "c"]})
+        assert values_after(cmd, "ids") == ["a", "b", "c"]
+
+    def test_custom_empty_string_skipped(self):
+        cmd = build_command(custom_params={"opt": ""})
+        assert not has_flag(cmd, "opt")
+
+    def test_custom_empty_list_param_skipped(self):
+        """
+        CodeRabbit finding 2 (fixed): an empty-list custom parameter is omitted
+        rather than emitting a bare ``-key`` with no value.
+        https://github.com/OpenMS/streamlit-template/pull/397#discussion_r3585023558
+        """
+        cmd = build_command(custom_params={"ids": []})
+        assert not has_flag(cmd, "ids")
+
+
+class TestFlagSourceContract:
+    """Where run_topp() reads the flag definitions from."""
+
+    def test_flag_params_loaded_from_params_json(self):
+        # Survives a session restart: only params.json carries the flag list.
+        cmd = build_command(
+            {"_flag_params": {TOOL: ["force"]}, TOOL: {"force": True}},
+            session_state={},
+        )
+        assert is_bare_flag(cmd, "force")
+
+    def test_fallback_to_session_state_when_json_has_no_flags(self):
+        # params.json has no _flag_params at all -> live session_state is used.
+        cmd = build_command(
+            {TOOL: {"force": True}},
+            session_state={"_topp_flag_params": {TOOL: ["force"]}},
+        )
+        assert is_bare_flag(cmd, "force")
+
+    def test_params_json_takes_priority_over_session_state(self):
+        # params.json says "force" is a flag; session_state disagrees (empty).
+        # params.json wins, so force is treated as a flag (bare, no value).
+        cmd = build_command(
+            {"_flag_params": {TOOL: ["force"]}, TOOL: {"force": True}},
+            session_state={"_topp_flag_params": {TOOL: []}},
+        )
+        assert is_bare_flag(cmd, "force")
+        assert "True" not in cmd
+
+    def test_flag_fallback_uses_current_tool_when_other_tool_has_flags(self):
+        """
+        CodeRabbit finding 1 (fixed): when params.json._flag_params holds an entry
+        for a DIFFERENT tool, the current tool's flags must still be read from the
+        session_state fallback. Previously the global ``if not flag_map`` check
+        skipped the fallback whenever any tool had flags, so the current tool's
+        flag was treated as a regular parameter and emitted as ``-force True``.
+        https://github.com/OpenMS/streamlit-template/pull/397#discussion_r3585023551
+        """
+        cmd = build_command(
+            {"_flag_params": {"OtherTool": ["some_flag"]}, TOOL: {"force": True}},
+            session_state={"_topp_flag_params": {TOOL: ["force"]}},
+        )
+        assert is_bare_flag(cmd, "force")
+        assert "True" not in cmd