diff --git a/.dockerignore b/.dockerignore
index f0165244..5c94b0ec 100644
--- a/.dockerignore
+++ b/.dockerignore
@@ -3,3 +3,4 @@ __pycache__
 .DS_Store
 node_modules
 .venv
+pytorch_connectomics
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 00000000..32169baf
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,78 @@
+name: CI
+
+permissions:
+  contents: read
+
+"on":
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  backend:
+    name: Backend tests
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        with:
+          python-version: "3.11"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        with:
+          version: "0.7.3"
+          enable-cache: true
+
+      - name: Fetch pinned PyTorch Connectomics runtime
+        run: bash scripts/setup_pytorch_connectomics.sh
+
+      - name: Install Python dependencies
+        run: uv sync --frozen --python 3.11 --group dev
+
+      - name: Run backend tests
+        run: uv run pytest -q
+
+  frontend:
+    name: Frontend tests and build
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    defaults:
+      run:
+        working-directory: client
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+
+      - name: Set up Node.js
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: "22"
+          cache: npm
+          cache-dependency-path: client/package-lock.json
+
+      - name: Install frontend dependencies
+        run: npm ci --fetch-retries=5 --fetch-retry-maxtimeout=120000
+
+      - name: Run frontend tests
+        run: npm test -- --runInBand
+        env:
+          CI: "true"
+
+      - name: Build frontend
+        run: npm run build
diff --git a/.github/workflows/superlinter.yml b/.github/workflows/superlinter.yml
index 05823f6e..e91ddcf5 100644
--- a/.github/workflows/superlinter.yml
+++ b/.github/workflows/superlinter.yml
@@ -1,6 +1,10 @@
 ---
 name: Super-Linter
 
+permissions:
+  contents: read
+  statuses: write
+
 "on":
   push:
     branches:
@@ -15,14 +19,18 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code
-        uses: actions/checkout@v2
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          fetch-depth: 0
+          persist-credentials: false
 
       - name: Run Super-Linter
-        uses: github/super-linter@v4
+        uses: super-linter/super-linter@4ce20838b8ab83717e78138c5b3a1407148e0918 # v8.7.0
         env:
           DEFAULT_BRANCH: main
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           VALIDATE_ALL_CODEBASE: false
+          ENABLE_GITHUB_PULL_REQUEST_SUMMARY_COMMENT: false
           VALIDATE_CSS_PRETTIER: true
           VALIDATE_HTML_PRETTIER: true
           VALIDATE_JAVASCRIPT_PRETTIER: true
diff --git a/.gitignore b/.gitignore
index 20267ae2..0d858bfe 100644
--- a/.gitignore
+++ b/.gitignore
@@ -14,4 +14,10 @@ sql_app.db
 uploads
 pytorch_connectomics
 server_api/chatbot/faiss_index/
-.logs/
\ No newline at end of file
+.logs/
+
+# Local deployment evidence (may contain transient viewer URLs)
+demo-proofread-3d.png
+docs/case-studies/yixiao-postdeploy-smoke-report-*.json
+docs/case-studies/yixiao-postdeploy-smoke-report-*.md
+docs/case-studies/yixiao-synthetic-walkthrough-report-*.md
diff --git a/Dockerfile b/Dockerfile
index 08ebe97b..94713534 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -15,12 +15,10 @@ RUN curl -LsSf https://astral.sh/uv/install.sh | sh -s -- --install-dir /usr/loc
 WORKDIR /app
 
 COPY pyproject.toml uv.lock ./
-RUN uv sync --frozen --no-dev --python 3.11
-
 COPY scripts/setup_pytorch_connectomics.sh ./scripts/setup_pytorch_connectomics.sh
 RUN chmod +x scripts/setup_pytorch_connectomics.sh && \
-    ./scripts/setup_pytorch_connectomics.sh --force && \
-    uv pip install --directory /app --editable /app/pytorch_connectomics && \
+    ./scripts/setup_pytorch_connectomics.sh && \
+    uv sync --frozen --no-dev --python 3.11 && \
     rm -rf /app/pytorch_connectomics/.git
 
 COPY server_api ./server_api
diff --git a/README.md b/README.md
index c4e6747f..1fdc2da7 100644
--- a/README.md
+++ b/README.md
@@ -22,6 +22,11 @@ scripts\bootstrap.ps1     # Windows
 
 Re-run the relevant bootstrap script when you need to update dependencies.
 
+The bootstrap scripts fetch the legacy-compatible PyTorch Connectomics runtime
+from `pytc-client-legacy-runtime` and verify commit
+`04c2a35e78a1a7ca1138f83a98fc3ef27097abd4` before installation. The generated
+`pytorch_connectomics/` checkout is intentionally not tracked by this repository.
+
 ## Run the app
 
 ```
@@ -35,6 +40,10 @@ Optional runtime environment variables:
 PYTC_AUTH_SECRET=replace-me
 PYTC_ALLOWED_ORIGINS=http://localhost:3000,http://127.0.0.1:3000,null
 PYTC_NEUROGLANCER_PUBLIC_BASE=http://localhost:4244
+OLLAMA_MODEL=qwen3.6:27b
+PYTC_WORKFLOW_INTENT_MODEL=qwen3.6:27b
+OLLAMA_EMBED_MODEL=qwen3-embedding:8b
+PYTC_UNLOAD_OLLAMA_BEFORE_TRAINING=0  # set to 1 only on memory-constrained GPUs
 ```
 
 ## Chatbot Docs Index
@@ -54,6 +63,11 @@ You can override the embeddings endpoint if needed:
 OLLAMA_BASE_URL=http://cscigpu08.bc.edu:4443 uv run python server_api/chatbot/update_faiss.py
 ```
 
+The local assistant and workflow intent classifier default to `qwen3.6:27b` with
+`qwen3-embedding:8b`, matching the bundled FAISS index settings. For
+experimental local model upgrades, see
+`docs/research/on-device-llm-options-2026-04-26.md`.
+
 If restarting after a crash or interrupted session, kill any lingering processes first:
 
 ```
diff --git a/app_event_logger.py b/app_event_logger.py
new file mode 100644
index 00000000..3cdc5dfd
--- /dev/null
+++ b/app_event_logger.py
@@ -0,0 +1,200 @@
+from __future__ import annotations
+
+import json
+import logging
+import os
+import sys
+import threading
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+_ROOT_DIR = Path(__file__).resolve().parent
+_DEFAULT_LOG_PATH = _ROOT_DIR / ".logs" / "app" / "app-events.jsonl"
+_ORIGINAL_STDOUT = sys.stdout
+_ORIGINAL_STDERR = sys.stderr
+_WRITE_LOCK = threading.Lock()
+_CONFIG_LOCK = threading.Lock()
+_CONFIGURED_COMPONENTS: set[str] = set()
+_STDIO_REDIRECTED = False
+
+
+def get_app_event_log_path() -> Path:
+    raw_path = os.getenv("PYTC_APP_EVENT_LOG_PATH", "").strip()
+    if raw_path:
+        return Path(raw_path).expanduser().resolve(strict=False)
+    return _DEFAULT_LOG_PATH
+
+
+def _detect_stream_level(default_level: str, message: str) -> str:
+    text = (message or "").strip()
+    upper = text.upper()
+    if upper.startswith("INFO:") or " INFO:" in upper:
+        return "INFO"
+    if (
+        upper.startswith("WARNING:")
+        or upper.startswith("WARN:")
+        or " WARNING:" in upper
+    ):
+        return "WARNING"
+    if upper.startswith("DEBUG:") or " DEBUG:" in upper:
+        return "DEBUG"
+    if upper.startswith("ERROR:") or " ERROR:" in upper:
+        return "ERROR"
+    if "TRACEBACK" in upper or "EXCEPTION" in upper or "FAILED" in upper:
+        return "ERROR"
+    return default_level.upper()
+
+
+def _normalize_value(value: Any) -> Any:
+    if value is None or isinstance(value, (bool, int, float, str)):
+        return value
+    if isinstance(value, Path):
+        return str(value)
+    if isinstance(value, dict):
+        return {str(key): _normalize_value(val) for key, val in value.items()}
+    if isinstance(value, (list, tuple, set)):
+        return [_normalize_value(item) for item in value]
+    return str(value)
+
+
+def append_app_event(
+    *,
+    component: str,
+    event: str,
+    level: str = "INFO",
+    message: str | None = None,
+    **fields: Any,
+) -> dict[str, Any]:
+    log_path = get_app_event_log_path()
+    log_path.parent.mkdir(parents=True, exist_ok=True)
+
+    record = {
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+        "pid": os.getpid(),
+        "component": component,
+        "event": event,
+        "level": level.upper(),
+        "message": message or "",
+    }
+    record.update(
+        {
+            key: _normalize_value(value)
+            for key, value in fields.items()
+            if value is not None
+        }
+    )
+
+    with _WRITE_LOCK:
+        with log_path.open("a", encoding="utf-8") as handle:
+            handle.write(json.dumps(record, ensure_ascii=True) + "\n")
+
+    return record
+
+
+class _AppEventStream:
+    def __init__(
+        self,
+        *,
+        component: str,
+        stream_name: str,
+        level: str,
+        original_stream,
+    ) -> None:
+        self.component = component
+        self.stream_name = stream_name
+        self.level = level
+        self.original_stream = original_stream
+        self._buffer = ""
+
+    def write(self, data) -> int:
+        text = str(data)
+        if not text:
+            return 0
+
+        self.original_stream.write(text)
+        self._buffer += text
+
+        while "\n" in self._buffer:
+            line, self._buffer = self._buffer.split("\n", 1)
+            if line.strip():
+                append_app_event(
+                    component=self.component,
+                    event=f"{self.stream_name}_line",
+                    level=_detect_stream_level(self.level, line),
+                    message=line,
+                    stream=self.stream_name,
+                )
+
+        return len(text)
+
+    def flush(self) -> None:
+        self.original_stream.flush()
+        if self._buffer.strip():
+            append_app_event(
+                component=self.component,
+                event=f"{self.stream_name}_line",
+                level=_detect_stream_level(self.level, self._buffer),
+                message=self._buffer,
+                stream=self.stream_name,
+            )
+        self._buffer = ""
+
+    def isatty(self) -> bool:
+        return bool(getattr(self.original_stream, "isatty", lambda: False)())
+
+    def fileno(self) -> int:
+        return self.original_stream.fileno()
+
+
+def configure_process_logging(component: str) -> Path:
+    global _STDIO_REDIRECTED
+
+    with _CONFIG_LOCK:
+        if component in _CONFIGURED_COMPONENTS:
+            return get_app_event_log_path()
+
+        if not _STDIO_REDIRECTED:
+            sys.stdout = _AppEventStream(
+                component=component,
+                stream_name="stdout",
+                level="INFO",
+                original_stream=_ORIGINAL_STDOUT,
+            )
+            sys.stderr = _AppEventStream(
+                component=component,
+                stream_name="stderr",
+                level="ERROR",
+                original_stream=_ORIGINAL_STDERR,
+            )
+            _STDIO_REDIRECTED = True
+
+        root_logger = logging.getLogger()
+        root_logger.setLevel(logging.INFO)
+        if not root_logger.handlers:
+            logging.basicConfig(
+                level=logging.INFO,
+                stream=sys.stdout,
+                format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+            )
+        else:
+            for handler in root_logger.handlers:
+                if not isinstance(handler, logging.StreamHandler):
+                    continue
+                stream = getattr(handler, "stream", None)
+                if stream is _ORIGINAL_STDOUT:
+                    handler.setStream(sys.stdout)
+                elif stream is _ORIGINAL_STDERR:
+                    handler.setStream(sys.stderr)
+
+        append_app_event(
+            component=component,
+            event="process_logging_configured",
+            level="INFO",
+            message=f"{component} logging configured",
+            log_path=str(get_app_event_log_path()),
+            configured_at_ms=round(time.time() * 1000),
+        )
+        _CONFIGURED_COMPONENTS.add(component)
+        return get_app_event_log_path()
diff --git a/client/main.js b/client/main.js
index d80fb2ea..1881f411 100644
--- a/client/main.js
+++ b/client/main.js
@@ -1,23 +1,56 @@
 const path = require("path");
 const url = require("url");
+const fs = require("fs");
 const {
   app,
   BrowserWindow,
   ipcMain,
   dialog,
   Menu,
+  nativeImage,
   screen,
   shell,
 } = require("electron");
 
 let mainWindow;
+const APP_NAME = "PyTC Client";
+
+app.setName(APP_NAME);
+app.setAppUserModelId("bio.seg.pytc-client");
+process.title = APP_NAME;
+
+function getAppIconPath() {
+  const candidates = [
+    path.join(__dirname, "public", "pytc-app-icon.png"),
+    path.join(__dirname, "build", "pytc-app-icon.png"),
+    path.join(__dirname, "public", "favicon.ico"),
+    path.join(__dirname, "build", "favicon.ico"),
+  ];
+  return candidates.find((candidate) => fs.existsSync(candidate));
+}
+
+function loadAppIcon() {
+  const iconPath = getAppIconPath();
+  if (!iconPath) return undefined;
+
+  const icon = nativeImage.createFromPath(iconPath);
+  if (icon.isEmpty()) return undefined;
+
+  if (process.platform === "darwin" && app.dock) {
+    app.dock.setIcon(icon);
+  }
+
+  return icon;
+}
 
 function createWindow() {
   const { width, height } = screen.getPrimaryDisplay().workAreaSize;
+  const appIcon = loadAppIcon();
   mainWindow = new BrowserWindow({
+    title: APP_NAME,
     width,
     height,
-    icon: path.join(__dirname, "public", "favicon.ico"),
+    icon: appIcon,
     webPreferences: {
       preload: path.join(__dirname, "preload.js"),
       nodeIntegration: false,
@@ -42,6 +75,7 @@ function createWindow() {
     });
   }
   mainWindow.loadURL(startUrl);
+  mainWindow.setTitle(APP_NAME);
 
   mainWindow.on("closed", () => {
     mainWindow = null;
@@ -51,9 +85,11 @@ function createWindow() {
 }
 
 function createMenu() {
+  app.setName(APP_NAME);
+  app.setAboutPanelOptions({ applicationName: APP_NAME });
   const template = [
     {
-      label: "Electron",
+      label: APP_NAME,
       submenu: [{ role: "toggleDevTools" }, { role: "quit" }],
     },
     { role: "editMenu" },
diff --git a/client/package-lock.json b/client/package-lock.json
index bda968ff..868d7b99 100644
--- a/client/package-lock.json
+++ b/client/package-lock.json
@@ -1,11 +1,11 @@
 {
-  "name": "PyTC Client",
+  "name": "pytc-client",
   "version": "0.1.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
-      "name": "PyTC Client",
+      "name": "pytc-client",
       "version": "0.1.0",
       "dependencies": {
         "@testing-library/jest-dom": "^6.4.6",
@@ -26,6 +26,7 @@
         "react-router-dom": "^6.23.1",
         "react-scripts": "^5.0.1",
         "remark-gfm": "^4.0.1",
+        "three": "^0.164.1",
         "utif": "^3.1.0",
         "web-vitals": "^4.1.1"
       },
@@ -34,7 +35,7 @@
         "babel-loader": "8.2.2",
         "cross-env": "^7.0.3",
         "electron-reload": "^2.0.0-alpha.1",
-        "prettier": "^3.3.2"
+        "prettier": "3.8.4"
       }
     },
     "node_modules/@adobe/css-tools": {
@@ -15401,11 +15402,10 @@
       }
     },
     "node_modules/prettier": {
-      "version": "3.8.1",
-      "resolved": "https://registry.npmjs.org/prettier/-/prettier-3.8.1.tgz",
-      "integrity": "sha512-UOnG6LftzbdaHZcKoPFtOcCKztrQ57WkHDeRD9t/PTQtmT0NHSeWWepj6pS0z/N7+08BHFDQVUrfmfMRcZwbMg==",
+      "version": "3.8.4",
+      "resolved": "https://registry.npmjs.org/prettier/-/prettier-3.8.4.tgz",
+      "integrity": "sha512-N2MylSdi48+5N/6S5j+maeHbUSIzzZ5uOcX5Hm4QpV8Dkb1HFjfAKTKX6yNPJQD9AhcT3ifHNB66tWTTJDi11Q==",
       "dev": true,
-      "license": "MIT",
       "bin": {
         "prettier": "bin/prettier.cjs"
       },
@@ -18763,10 +18763,9 @@
       }
     },
     "node_modules/tailwindcss/node_modules/yaml": {
-      "version": "2.8.2",
-      "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.8.2.tgz",
-      "integrity": "sha512-mplynKqc1C2hTVYxd0PU2xQAc22TI1vShAYGksCCfxbn/dFwnHTNi1bvYsBTkhdUNtGIf5xNOg938rrSSYvS9A==",
-      "license": "ISC",
+      "version": "2.9.0",
+      "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.9.0.tgz",
+      "integrity": "sha512-2AvhNX3mb8zd6Zy7INTtSpl1F15HW6Wnqj0srWlkKLcpYl/gMIMJiyuGq2KeI2YFxUPjdlB+3Lc10seMLtL4cA==",
       "optional": true,
       "peer": true,
       "bin": {
@@ -18946,6 +18945,12 @@
         "node": ">=0.8"
       }
     },
+    "node_modules/three": {
+      "version": "0.164.1",
+      "resolved": "https://registry.npmjs.org/three/-/three-0.164.1.tgz",
+      "integrity": "sha512-iC/hUBbl1vzFny7f5GtqzVXYjMJKaTPxiCxXfrvVdBi1Sf+jhd1CAkitiFwC7mIBFCo3MrDLJG97yisoaWig0w==",
+      "license": "MIT"
+    },
     "node_modules/throat": {
       "version": "6.0.2",
       "resolved": "https://registry.npmjs.org/throat/-/throat-6.0.2.tgz",
diff --git a/client/package.json b/client/package.json
index 0107480c..3af2d657 100644
--- a/client/package.json
+++ b/client/package.json
@@ -1,5 +1,6 @@
 {
-  "name": "PyTC Client",
+  "name": "pytc-client",
+  "productName": "PyTC Client",
   "version": "0.1.0",
   "private": true,
   "main": "main.js",
@@ -23,6 +24,7 @@
     "react-router-dom": "^6.23.1",
     "react-scripts": "^5.0.1",
     "remark-gfm": "^4.0.1",
+    "three": "^0.164.1",
     "utif": "^3.1.0",
     "web-vitals": "^4.1.1"
   },
@@ -55,7 +57,7 @@
     "babel-loader": "8.2.2",
     "cross-env": "^7.0.3",
     "electron-reload": "^2.0.0-alpha.1",
-    "prettier": "^3.3.2"
+    "prettier": "3.8.4"
   },
   "overrides": {
     "nth-check": "$nth-check",
diff --git a/client/public/favicon.ico b/client/public/favicon.ico
index ab831f31..b509cdba 100644
Binary files a/client/public/favicon.ico and b/client/public/favicon.ico differ
diff --git a/client/public/pytc-app-icon.icns b/client/public/pytc-app-icon.icns
new file mode 100644
index 00000000..57e15acc
Binary files /dev/null and b/client/public/pytc-app-icon.icns differ
diff --git a/client/public/pytc-app-icon.png b/client/public/pytc-app-icon.png
new file mode 100644
index 00000000..8d2c4358
Binary files /dev/null and b/client/public/pytc-app-icon.png differ
diff --git a/client/src/App.css b/client/src/App.css
index 49191aa5..336d8ef9 100644
--- a/client/src/App.css
+++ b/client/src/App.css
@@ -2,6 +2,196 @@
   text-align: center;
 }
 
+:root {
+  --seg-bg-canvas: #f7f4ed;
+  --seg-bg-panel: #fffdfa;
+  --seg-bg-raised: #ffffff;
+  --seg-border-subtle: #e4ded2;
+  --seg-border-strong: #c9bda9;
+  --seg-text-primary: #1f2933;
+  --seg-text-muted: #667085;
+  --seg-accent-primary: #3f37c9;
+  --seg-accent-primary-soft: #f0efff;
+  --seg-accent-primary-border: #c7c2ff;
+  --seg-focus-ring: rgba(63, 55, 201, 0.22);
+  --seg-selection-fill: rgba(63, 55, 201, 0.12);
+  --seg-accent-teal: var(--seg-accent-primary);
+  --seg-accent-blue: #2b5b9f;
+  --seg-accent-amber: #b8660f;
+  --seg-accent-green: #2f7d32;
+  --seg-accent-red: #b13a2f;
+  --seg-radius-panel: 12px;
+  --seg-shadow-panel: 0 12px 32px rgba(51, 43, 31, 0.08);
+}
+
+.workflow-stage-header {
+  display: flex;
+  gap: 8px;
+  align-items: center;
+  justify-content: space-between;
+  padding: 2px 0 8px;
+  border: 0;
+  border-bottom: 1px solid var(--seg-border-subtle);
+  background: transparent;
+}
+
+.workflow-stage-title,
+.workflow-stage-copy {
+  min-width: 0;
+}
+
+.workflow-stage-copy {
+  display: flex;
+  align-items: center;
+  min-width: 0;
+}
+
+.workflow-stage-title {
+  display: inline-block;
+  padding-right: 8px;
+}
+
+.workflow-stage-eyebrow,
+.workflow-stage-description {
+  font-size: 12px;
+}
+
+.workflow-insight-card,
+.workflow-proposal-card {
+  border: 1px solid var(--seg-border-subtle);
+  border-radius: 10px;
+  background: var(--seg-bg-raised);
+}
+
+.workflow-insight-card {
+  margin-top: 8px;
+  padding: 8px 10px;
+}
+
+.workflow-proposal-card {
+  margin-top: 6px;
+  padding: 10px;
+}
+
+.workflow-proposal-card__header {
+  align-items: flex-start;
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+  min-width: 0;
+}
+
+.workflow-proposal-card__title {
+  flex: 1 1 100%;
+  overflow-wrap: anywhere;
+  min-width: 0;
+}
+
+.workflow-proposal-card__rationale,
+.workflow-proposal-card__field-value {
+  overflow-wrap: anywhere;
+}
+
+.workflow-proposal-card__type-tag,
+.workflow-proposal-card__status-tag {
+  max-width: 100%;
+  overflow-wrap: anywhere;
+  white-space: normal;
+}
+
+.workflow-proposal-card__agent-badge {
+  flex: 0 0 auto;
+  max-width: 100%;
+  min-width: 0;
+}
+
+.workflow-proposal-card__field-value--editable {
+  cursor: pointer;
+}
+
+.workflow-proposal-card__fields {
+  display: grid;
+  grid-template-columns: minmax(92px, auto) 1fr;
+  column-gap: 10px;
+  row-gap: 4px;
+  overflow-wrap: anywhere;
+  word-break: break-word;
+}
+
+.workflow-proposal-card__fields .workflow-proposal-card__field-label {
+  overflow-wrap: anywhere;
+}
+
+.workflow-proposal-card__trace {
+  border-top: 1px solid var(--seg-border-subtle);
+  margin-top: 4px;
+  padding-top: 4px;
+}
+
+.workflow-proposal-card__trace-body {
+  margin-top: 4px;
+}
+
+.workflow-proposal-card__trace-block {
+  margin-bottom: 4px;
+}
+
+.workflow-proposal-card__trace-block-title {
+  display: block;
+  font-size: 11px;
+}
+
+.workflow-proposal-card__trace-block-body {
+  margin-top: 2px;
+}
+
+.workflow-proposal-card__trace-line {
+  display: block;
+  font-size: 11px;
+  line-height: 1.35;
+}
+
+.assistant-trace__panel {
+  border-top: 1px solid var(--seg-border-subtle);
+  display: grid;
+  gap: 8px;
+  margin-top: 4px;
+  padding-top: 6px;
+}
+
+.assistant-trace__section {
+  display: grid;
+  gap: 4px;
+}
+
+.assistant-trace__items {
+  display: grid;
+  gap: 4px;
+}
+
+.assistant-trace__item {
+  border: 1px solid var(--seg-border-subtle);
+  border-radius: 8px;
+  display: grid;
+  gap: 4px;
+  padding: 6px 8px;
+  background: var(--seg-bg-raised);
+}
+
+.workflow-proposal-card__field-label {
+  font-size: 11px;
+  text-transform: capitalize;
+}
+
+.pytc-top-menu .ant-menu-item {
+  margin-inline: 4px !important;
+  padding-inline: 16px 24px !important;
+}
+
+.pytc-top-menu .ant-menu-title-content {
+  padding-right: 2px;
+}
+
 .app-logo {
   height: 40vmin;
   pointer-events: none;
@@ -18,6 +208,19 @@
   color: white;
 }
 
+.visualization-viewer-tabs > .ant-tabs-nav {
+  margin: 8px 0 0;
+}
+
+.visualization-viewer-tabs > .ant-tabs-content-holder,
+.visualization-viewer-tabs > .ant-tabs-content-holder > .ant-tabs-content,
+.visualization-viewer-tabs
+  > .ant-tabs-content-holder
+  > .ant-tabs-content
+  > .ant-tabs-tabpane {
+  height: 100%;
+}
+
 @media (prefers-reduced-motion: no-preference) {
   .app-logo {
     animation: app-logo-spin infinite 20s linear;
diff --git a/client/src/App.js b/client/src/App.js
index 9c26a2c7..00771fb5 100644
--- a/client/src/App.js
+++ b/client/src/App.js
@@ -1,36 +1,9 @@
-import { useContext, useEffect, useState } from "react";
 import "./App.css";
 import Views from "./views/Views";
-import { AppContext, ContextWrapper } from "./contexts/GlobalContext";
+import { ContextWrapper } from "./contexts/GlobalContext";
 import { YamlContextWrapper } from "./contexts/YamlContext";
 import { WorkflowProvider } from "./contexts/WorkflowContext";
 
-function CacheBootstrapper({ children }) {
-  const { resetFileState } = useContext(AppContext);
-  const [isCacheCleared, setIsCacheCleared] = useState(false);
-
-  useEffect(() => {
-    let isMounted = true;
-    const clearCache = async () => {
-      await resetFileState();
-      if (isMounted) {
-        setIsCacheCleared(true);
-      }
-    };
-
-    clearCache();
-    return () => {
-      isMounted = false;
-    };
-  }, [resetFileState]);
-
-  if (!isCacheCleared) {
-    return null;
-  }
-
-  return children;
-}
-
 function MainContent() {
   return <Views />;
 }
@@ -40,11 +13,9 @@ function App() {
     <ContextWrapper>
       <YamlContextWrapper>
         <WorkflowProvider>
-          <CacheBootstrapper>
-            <div className="App">
-              <MainContent />
-            </div>
-          </CacheBootstrapper>
+          <div className="App">
+            <MainContent />
+          </div>
         </WorkflowProvider>
       </YamlContextWrapper>
     </ContextWrapper>
diff --git a/client/src/__tests__/agentProposalCards.test.js b/client/src/__tests__/agentProposalCards.test.js
index afd415ea..ec287e3c 100644
--- a/client/src/__tests__/agentProposalCards.test.js
+++ b/client/src/__tests__/agentProposalCards.test.js
@@ -10,7 +10,7 @@ jest.mock("antd", () => ({
     </button>
   ),
   Space: ({ children }) => <div>{children}</div>,
-  Tag: ({ children }) => <span>{children}</span>,
+  Tag: ({ children, ...props }) => <span {...props}>{children}</span>,
   Typography: {
     Text: ({ children }) => <span>{children}</span>,
   },
@@ -43,7 +43,7 @@ describe("AgentProposalCard", () => {
     fireEvent.click(screen.getByRole("button", { name: "Approve" }));
     fireEvent.click(screen.getByRole("button", { name: "Reject" }));
 
-    expect(onApprove).toHaveBeenCalledWith(proposal);
+    expect(onApprove).toHaveBeenCalledWith(proposal, {});
     expect(onReject).toHaveBeenCalledWith(proposal);
   });
 
@@ -67,7 +67,11 @@ describe("AgentProposalCard", () => {
   it("renders fallback proposal content", () => {
     render(
       <AgentProposalCard
-        proposal={{ type: "custom_type", rationale: "Keep behavior stable", foo: "bar" }}
+        proposal={{
+          type: "custom_type",
+          rationale: "Keep behavior stable",
+          foo: "bar",
+        }}
       />,
     );
 
@@ -75,4 +79,24 @@ describe("AgentProposalCard", () => {
     expect(screen.getByText("Keep behavior stable")).toBeTruthy();
     expect(screen.getByText("bar")).toBeTruthy();
   });
+
+  it("shows specialist agent badges when supplied", () => {
+    render(
+      <AgentProposalCard
+        proposal={{
+          type: "agent_task",
+          rationale: "Specialist routing should be explicit.",
+          specialist_agent: {
+            agent_label: "Inference Specialist",
+            agent_short_label: "INFER",
+            agent_color: "#005f73",
+            agent_icon_key: "eye",
+          },
+        }}
+      />,
+    );
+
+    expect(screen.getByText("INFER")).toBeTruthy();
+    expect(screen.getByText("agent_task")).toBeTruthy();
+  });
 });
diff --git a/client/src/__tests__/assistantActionCard.test.js b/client/src/__tests__/assistantActionCard.test.js
new file mode 100644
index 00000000..c26d19e6
--- /dev/null
+++ b/client/src/__tests__/assistantActionCard.test.js
@@ -0,0 +1,42 @@
+import React from "react";
+import { fireEvent, render, screen } from "@testing-library/react";
+
+import AssistantActionCard from "../components/chat/AssistantActionCard";
+
+jest.mock("antd", () => ({
+  Button: ({ children, ...props }) => (
+    <button type="button" {...props}>
+      {children}
+    </button>
+  ),
+  Space: ({ children }) => <div>{children}</div>,
+  Tag: ({ children }) => <span>{children}</span>,
+  Typography: {
+    Text: ({ children }) => <span>{children}</span>,
+  },
+}));
+
+describe("AssistantActionCard", () => {
+  it("renders the action metadata and triggers execution", () => {
+    const onRun = jest.fn();
+    const action = {
+      id: "open-training",
+      label: "Open Training",
+      description: "Jump to training with staged labels.",
+      variant: "primary",
+      client_effects: {
+        navigate_to: "training",
+      },
+    };
+
+    render(<AssistantActionCard action={action} onRun={onRun} />);
+
+    expect(screen.getByText("Open Training")).toBeTruthy();
+    expect(
+      screen.getByText("Jump to training with staged labels."),
+    ).toBeTruthy();
+
+    fireEvent.click(screen.getByRole("button", { name: "Run in app" }));
+    expect(onRun).toHaveBeenCalledWith(action);
+  });
+});
diff --git a/client/src/__tests__/assistantCommandCard.test.js b/client/src/__tests__/assistantCommandCard.test.js
new file mode 100644
index 00000000..03f1593f
--- /dev/null
+++ b/client/src/__tests__/assistantCommandCard.test.js
@@ -0,0 +1,45 @@
+import React from "react";
+import { fireEvent, render, screen } from "@testing-library/react";
+
+import AssistantCommandCard from "../components/chat/AssistantCommandCard";
+
+jest.mock("antd", () => ({
+  Button: ({ children, ...props }) => (
+    <button type="button" {...props}>
+      {children}
+    </button>
+  ),
+  Space: ({ children }) => <div>{children}</div>,
+  Tag: ({ children }) => <span>{children}</span>,
+  Typography: {
+    Text: ({ children }) => <span>{children}</span>,
+  },
+}));
+
+describe("AssistantCommandCard", () => {
+  it("renders a terminal-style command block and runs it", () => {
+    const onRun = jest.fn();
+    const command = {
+      id: "prime-training",
+      title: "Prime the training screen",
+      description: "Move the UI into training setup mode.",
+      command:
+        'app open training\napp training labels set "/tmp/corrected.tif"',
+      run_label: "Execute",
+      client_effects: {
+        navigate_to: "training",
+        set_training_label_path: "/tmp/corrected.tif",
+      },
+    };
+
+    render(<AssistantCommandCard command={command} onRun={onRun} />);
+
+    expect(screen.getByText("Prime the training screen")).toBeTruthy();
+    expect(screen.queryByText(/app open training/)).toBeNull();
+    fireEvent.click(screen.getByRole("button", { name: "Route" }));
+    expect(screen.getByText(/app open training/)).toBeTruthy();
+
+    fireEvent.click(screen.getByRole("button", { name: "Execute" }));
+    expect(onRun).toHaveBeenCalledWith(command);
+  });
+});
diff --git a/client/src/api.js b/client/src/api.js
index 344e3319..f3010b37 100644
--- a/client/src/api.js
+++ b/client/src/api.js
@@ -1,13 +1,117 @@
 import axios from "axios";
-import { message } from "antd";
 import yaml from "js-yaml";
+import { logClientEvent } from "./logging/appEventLog";
+import {
+  detectConfigDiagnostics,
+  summarizeConfigText,
+} from "./logging/configLogSummary";
 import {
   setInferenceExecutionDefaults,
   setInferenceOutputPath,
   setTrainingOutputPath,
 } from "./configSchema";
 
-const BASE_URL = `${process.env.REACT_APP_SERVER_PROTOCOL || "http"}://${process.env.REACT_APP_SERVER_URL || "localhost:4242"}`;
+const API_LEGACY_PREFIXES = ["/api/workflows", "/api/files", "/api/app"];
+
+const removeTrailingSlash = (value) => value.replace(/\/+$/, "");
+
+const getDefaultBaseUrl = () => {
+  if (
+    typeof window !== "undefined" &&
+    window.location?.origin &&
+    !window.location.hostname.match(/^(localhost|127\.0\.0\.1)$/)
+  ) {
+    return `${window.location.origin}/api`;
+  }
+
+  return `${process.env.REACT_APP_SERVER_PROTOCOL || "http"}://${process.env.REACT_APP_SERVER_URL || "localhost:4242"}`;
+};
+
+const BASE_URL = removeTrailingSlash(
+  process.env.REACT_APP_API_BASE_URL || getDefaultBaseUrl(),
+);
+
+const getBasePath = (baseUrl) => {
+  if (!baseUrl) return "";
+  const protocolMatch = baseUrl.match(/^[a-z][a-z\d+\-.]*:\/\//i);
+  if (protocolMatch && protocolMatch.index === 0) {
+    try {
+      return new URL(baseUrl).pathname || "";
+    } catch {}
+  }
+
+  const originEnd = baseUrl.indexOf("/");
+  return originEnd === -1 ? "" : baseUrl.slice(originEnd);
+};
+
+const BASE_PATH = getBasePath(BASE_URL);
+const getLegacyApiBasePrefix = (basePath) => {
+  const candidates = [...API_LEGACY_PREFIXES, "/api"];
+  return (
+    candidates.find(
+      (prefix) =>
+        basePath === prefix ||
+        basePath.startsWith(`${prefix}/`) ||
+        basePath.startsWith(`${prefix}?`) ||
+        basePath.startsWith(`${prefix}#`),
+    ) || null
+  );
+};
+
+const BASE_LEGACY_API_PREFIX =
+  getLegacyApiBasePrefix(BASE_PATH) || getLegacyApiBasePrefix(BASE_URL);
+
+const shouldStripLegacyApiPrefix = (path) => {
+  const normalizedPath = path.startsWith("/") ? path : `/${String(path || "")}`;
+
+  if (!BASE_LEGACY_API_PREFIX) return false;
+  if (BASE_LEGACY_API_PREFIX === "/api") {
+    return (
+      normalizedPath === "/api" ||
+      normalizedPath.startsWith("/api/") ||
+      normalizedPath.startsWith("/api?") ||
+      normalizedPath.startsWith("/api#")
+    );
+  }
+
+  return (
+    normalizedPath === BASE_LEGACY_API_PREFIX ||
+    normalizedPath.startsWith(`${BASE_LEGACY_API_PREFIX}/`) ||
+    normalizedPath.startsWith(`${BASE_LEGACY_API_PREFIX}?`) ||
+    normalizedPath.startsWith(`${BASE_LEGACY_API_PREFIX}#`)
+  );
+};
+
+const canonicalizeApiPath = (path) => {
+  const normalized = String(path || "");
+  const match = normalized.match(/^([^?#]*)([?#].*)?$/);
+  const rawPath = match?.[1] || "";
+  const suffix = match?.[2] || "";
+  const normalizedPath = rawPath.startsWith("/") ? rawPath : `/${rawPath}`;
+
+  if (!shouldStripLegacyApiPrefix(normalizedPath)) {
+    return `${normalizedPath}${suffix}`;
+  }
+
+  const stripLength = BASE_LEGACY_API_PREFIX?.length || 0;
+  const deduped =
+    normalizedPath.length > stripLength
+      ? normalizedPath.slice(stripLength)
+      : "/";
+  return `${deduped}${suffix}`;
+};
+
+export const buildApiUrl = (path) => `${BASE_URL}${canonicalizeApiPath(path)}`;
+
+const DEBUG_API_LOGS =
+  process.env.REACT_APP_DEBUG_API_LOGS === "1" ||
+  process.env.REACT_APP_DEBUG_API_LOGS === "true";
+
+const apiDebugLog = (...args) => {
+  if (DEBUG_API_LOGS) {
+    console.log(...args);
+  }
+};
 
 // Create axios instance without auth headers—app runs as guest by default.
 export const apiClient = axios.create({
@@ -15,6 +119,106 @@ export const apiClient = axios.create({
   withCredentials: true,
 });
 
+const summarizePayload = (payload) => {
+  if (!payload) return { hasBody: false };
+  if (typeof payload === "string") {
+    return { hasBody: true, bodyLength: payload.length };
+  }
+  if (payload instanceof FormData) {
+    return { hasBody: true, bodyType: "FormData" };
+  }
+  if (typeof payload === "object") {
+    return {
+      hasBody: true,
+      bodyType: Array.isArray(payload) ? "array" : "object",
+      keys: Object.keys(payload).slice(0, 20),
+    };
+  }
+  return { hasBody: true, bodyType: typeof payload };
+};
+
+const attachApiLogging = (instance, source) => {
+  instance.interceptors.request.use(
+    (config) => {
+      config.metadata = {
+        startedAt:
+          typeof performance !== "undefined" ? performance.now() : Date.now(),
+      };
+      logClientEvent("api_request", {
+        level: "INFO",
+        message: `${String(config.method || "get").toUpperCase()} ${config.url}`,
+        source,
+        data: {
+          method: String(config.method || "get").toUpperCase(),
+          url: config.url,
+          baseURL: config.baseURL,
+          ...summarizePayload(config.data),
+        },
+      });
+      return config;
+    },
+    (error) => {
+      logClientEvent("api_request_setup_failed", {
+        level: "ERROR",
+        message: error.message || "Axios request setup failed",
+        source,
+        data: { error: error.message },
+      });
+      return Promise.reject(error);
+    },
+  );
+
+  instance.interceptors.response.use(
+    (response) => {
+      const startedAt = response.config?.metadata?.startedAt;
+      const endedAt =
+        typeof performance !== "undefined" ? performance.now() : Date.now();
+      logClientEvent("api_response", {
+        level: "INFO",
+        message: `${String(response.config?.method || "get").toUpperCase()} ${response.config?.url} -> ${response.status}`,
+        source,
+        data: {
+          method: String(response.config?.method || "get").toUpperCase(),
+          url: response.config?.url,
+          status: response.status,
+          latencyMs:
+            startedAt !== undefined
+              ? Number((endedAt - startedAt).toFixed(2))
+              : null,
+        },
+      });
+      return response;
+    },
+    (error) => {
+      const config = error.config || {};
+      const startedAt = config.metadata?.startedAt;
+      const endedAt =
+        typeof performance !== "undefined" ? performance.now() : Date.now();
+      logClientEvent("api_response_error", {
+        level: "ERROR",
+        message:
+          error.message ||
+          `${String(config.method || "get").toUpperCase()} ${config.url} failed`,
+        source,
+        data: {
+          method: String(config.method || "get").toUpperCase(),
+          url: config.url,
+          status: error.response?.status,
+          latencyMs:
+            startedAt !== undefined
+              ? Number((endedAt - startedAt).toFixed(2))
+              : null,
+          detail: error.response?.data?.detail || null,
+        },
+      });
+      return Promise.reject(error);
+    },
+  );
+};
+
+attachApiLogging(apiClient, "apiClient");
+attachApiLogging(axios, "axios");
+
 const buildFilePath = (file) => {
   if (!file) return "";
   if (typeof file === "string") return file;
@@ -35,6 +239,9 @@ const getErrorDetailMessage = (detail) => {
     return detail.map(getErrorDetailMessage).filter(Boolean).join("; ");
   }
   if (typeof detail === "object") {
+    if (detail.user_message) {
+      return getErrorDetailMessage(detail.user_message);
+    }
     const nestedUpstream =
       detail.upstream_body !== undefined
         ? getErrorDetailMessage(detail.upstream_body)
@@ -52,9 +259,14 @@ const getErrorDetailMessage = (detail) => {
   return String(detail);
 };
 
-export async function getNeuroglancerViewer(image, label, scales, workflowId = null) {
+export async function getNeuroglancerViewer(
+  image,
+  label,
+  scales,
+  workflowId = null,
+) {
   try {
-    const url = `${BASE_URL}/neuroglancer`;
+    const url = buildApiUrl("/neuroglancer");
     if (hasBrowserFile(image)) {
       const formData = new FormData();
       formData.append(
@@ -86,15 +298,86 @@ export async function getNeuroglancerViewer(image, label, scales, workflowId = n
     const res = await axios.post(url, data);
     return res.data;
   } catch (error) {
-    message.error(
-      'Invalid Data Path(s). Be sure to include all "/" and that data path is correct.',
+    handleError(error);
+  }
+}
+
+export async function getNeuroglancerProofreadingViewer({
+  image,
+  label,
+  scales,
+  workflowId = null,
+  sessionId = null,
+  activeInstanceId = null,
+  initialVoxel = null,
+} = {}) {
+  try {
+    const url = buildApiUrl("/neuroglancer/proofread");
+    const res = await axios.post(
+      url,
+      JSON.stringify({
+        image: buildFilePath(image),
+        label: buildFilePath(label),
+        scales,
+        workflow_id: workflowId,
+        session_id: sessionId,
+        active_instance_id: activeInstanceId,
+        initial_voxel: initialVoxel,
+      }),
     );
+    return res.data;
+  } catch (error) {
+    handleError(error);
+  }
+}
+
+export async function getInstanceVolumePreview(
+  sessionId,
+  instanceId,
+  maxPoints = 30000,
+) {
+  try {
+    const res = await apiClient.get(
+      canonicalizeApiPath("/eh/detection/instance-volume-preview"),
+      {
+        params: {
+          session_id: sessionId,
+          instance_id: instanceId,
+          max_points: maxPoints,
+        },
+      },
+    );
+    return res.data;
+  } catch (error) {
+    handleError(error);
+  }
+}
+
+export async function getInstanceMeshPreview(
+  sessionId,
+  instanceId,
+  maxFaces = 60000,
+) {
+  try {
+    const res = await apiClient.get(
+      canonicalizeApiPath("/eh/detection/instance-mesh-preview"),
+      {
+        params: {
+          session_id: sessionId,
+          instance_id: instanceId,
+          max_faces: maxFaces,
+        },
+      },
+    );
+    return res.data;
+  } catch (error) {
+    handleError(error);
   }
 }
 
 export async function checkFile(file) {
   try {
-    const url = `${BASE_URL}/check_files`;
+    const url = buildApiUrl("/check_files");
     const data = JSON.stringify({
       folderPath: file.folderPath || "",
       name: file.name,
@@ -120,7 +403,7 @@ function handleError(error) {
 
 export async function makeApiRequest(url, method, data = null) {
   try {
-    const fullUrl = `${BASE_URL}/${url}`;
+    const fullUrl = buildApiUrl(url);
     const config = {
       method,
       url: fullUrl,
@@ -146,11 +429,14 @@ export async function startModelTraining(
   outputPath,
   configOriginPath = "",
   workflowId = null,
+  autoParameters = false,
+  inputImagePath = "",
+  inputLabelPath = "",
 ) {
   try {
-    console.log("[API] ===== Starting Training Configuration =====");
-    console.log("[API] logPath:", logPath);
-    console.log("[API] outputPath:", outputPath);
+    apiDebugLog("[API] ===== Starting Training Configuration =====");
+    apiDebugLog("[API] logPath:", logPath);
+    apiDebugLog("[API] outputPath:", outputPath);
 
     // Parse the YAML config and inject the outputPath
     let configToSend = trainingConfig;
@@ -161,8 +447,8 @@ export async function startModelTraining(
         setTrainingOutputPath(configObj, outputPath);
 
         configToSend = yaml.dump(configObj);
-        console.log("[API] Injected training output path:", outputPath);
-        console.log(
+        apiDebugLog("[API] Injected training output path:", outputPath);
+        apiDebugLog(
           "[API] Modified config preview:",
           configToSend.substring(0, 500),
         );
@@ -171,6 +457,18 @@ export async function startModelTraining(
           "[API] Failed to parse/modify YAML, using original config:",
           e,
         );
+        logClientEvent("training_config_transform_failed", {
+          level: "WARNING",
+          message: "Failed to transform training config before request",
+          source: "api",
+          data: {
+            error: e.message || "unknown error",
+            configOriginPath,
+            outputPath,
+            logPath,
+            workflowId,
+          },
+        });
       }
     } else {
       console.warn(
@@ -184,11 +482,35 @@ export async function startModelTraining(
       trainingConfig: configToSend,
       configOriginPath,
       workflow_id: workflowId,
+      autoParameters: Boolean(autoParameters),
+      auto_parameters: Boolean(autoParameters),
+      inputImagePath,
+      inputLabelPath,
     });
 
-    console.log("[API] Request payload size:", data.length, "bytes");
-    console.log("[API] Note: TensorBoard will monitor outputPath, not logPath");
-    console.log("[API] =========================================");
+    apiDebugLog("[API] Request payload size:", data.length, "bytes");
+    apiDebugLog("[API] Note: TensorBoard will monitor outputPath, not logPath");
+    apiDebugLog("[API] =========================================");
+
+    const configSummary = summarizeConfigText(configToSend, "training");
+    const diagnostics = detectConfigDiagnostics(configSummary);
+    logClientEvent("training_api_payload_prepared", {
+      level: diagnostics.length ? "WARNING" : "INFO",
+      message: "Training API payload prepared",
+      source: "api",
+      data: {
+        workflowId,
+        configOriginPath,
+        outputPath,
+        logPath,
+        inputImagePath,
+        inputLabelPath,
+        autoParameters: Boolean(autoParameters),
+        requestBytes: data.length,
+        configSummary,
+        diagnostics,
+      },
+    });
 
     return makeApiRequest("start_model_training", "post", data);
   } catch (error) {
@@ -198,7 +520,7 @@ export async function startModelTraining(
 
 export async function stopModelTraining() {
   try {
-    await axios.post(`${BASE_URL}/stop_model_training`);
+    await axios.post(buildApiUrl("/stop_model_training"));
   } catch (error) {
     handleError(error);
   }
@@ -206,7 +528,7 @@ export async function stopModelTraining() {
 
 export async function getTrainingStatus() {
   try {
-    const res = await axios.get(`${BASE_URL}/training_status`);
+    const res = await axios.get(buildApiUrl("/training_status"));
     return res.data;
   } catch (error) {
     handleError(error);
@@ -215,7 +537,7 @@ export async function getTrainingStatus() {
 
 export async function getTrainingLogs() {
   try {
-    const res = await axios.get(`${BASE_URL}/training_logs`);
+    const res = await axios.get(buildApiUrl("/training_logs"));
     return res.data;
   } catch (error) {
     handleError(error);
@@ -226,6 +548,10 @@ export async function getTensorboardURL() {
   return makeApiRequest("get_tensorboard_url", "get");
 }
 
+export async function getTensorboardStatus() {
+  return makeApiRequest("get_tensorboard_status", "get");
+}
+
 export async function startTensorboard(logPath) {
   const query = logPath
     ? `?${new URLSearchParams({ logPath }).toString()}`
@@ -239,43 +565,44 @@ export async function startModelInference(
   checkpointPath,
   configOriginPath = "",
   workflowId = null,
+  inputImagePath = "",
 ) {
-  console.log("\n========== API.JS: START_MODEL_INFERENCE CALLED ==========");
-  console.log("[API] Function arguments:");
-  console.log("[API]   - inferenceConfig type:", typeof inferenceConfig);
-  console.log(
+  apiDebugLog("\n========== API.JS: START_MODEL_INFERENCE CALLED ==========");
+  apiDebugLog("[API] Function arguments:");
+  apiDebugLog("[API]   - inferenceConfig type:", typeof inferenceConfig);
+  apiDebugLog(
     "[API]   - inferenceConfig length:",
     inferenceConfig?.length || "N/A",
   );
-  console.log("[API]   - outputPath:", outputPath);
-  console.log("[API]   - outputPath type:", typeof outputPath);
-  console.log("[API]   - checkpointPath:", checkpointPath);
-  console.log("[API]   - checkpointPath type:", typeof checkpointPath);
+  apiDebugLog("[API]   - outputPath:", outputPath);
+  apiDebugLog("[API]   - outputPath type:", typeof outputPath);
+  apiDebugLog("[API]   - checkpointPath:", checkpointPath);
+  apiDebugLog("[API]   - checkpointPath type:", typeof checkpointPath);
 
   try {
-    console.log("[API] ===== Starting Inference Configuration =====");
+    apiDebugLog("[API] ===== Starting Inference Configuration =====");
 
     // Parse the YAML config and inject the outputPath
     let configToSend = inferenceConfig;
 
     if (inferenceConfig) {
       try {
-        console.log("[API] Parsing YAML config...");
+        apiDebugLog("[API] Parsing YAML config...");
         const configObj = yaml.load(inferenceConfig) || {};
-        console.log("[API] ✓ YAML parsed successfully");
+        apiDebugLog("[API] ✓ YAML parsed successfully");
 
         if (outputPath) {
           setInferenceOutputPath(configObj, outputPath);
-          console.log("[API] ✓ Injected inference output path:", outputPath);
+          apiDebugLog("[API] ✓ Injected inference output path:", outputPath);
         }
         setInferenceExecutionDefaults(configObj);
-        console.log("[API] ✓ Applied inference runtime defaults");
+        apiDebugLog("[API] ✓ Applied inference runtime defaults");
 
         // Convert back to YAML
-        console.log("[API] Converting back to YAML...");
+        apiDebugLog("[API] Converting back to YAML...");
         configToSend = yaml.dump(configObj);
-        console.log("[API] ✓ YAML conversion successful");
-        console.log(
+        apiDebugLog("[API] ✓ YAML conversion successful");
+        apiDebugLog(
           "[API] Modified config preview (first 500 chars):",
           configToSend.substring(0, 500),
         );
@@ -284,6 +611,18 @@ export async function startModelInference(
         console.error("[API] Error type:", e.constructor.name);
         console.error("[API] Error message:", e.message);
         console.warn("[API] Falling back to original config");
+        logClientEvent("inference_config_transform_failed", {
+          level: "WARNING",
+          message: "Failed to transform inference config before request",
+          source: "api",
+          data: {
+            error: e.message || "unknown error",
+            configOriginPath,
+            outputPath,
+            checkpointPath,
+            workflowId,
+          },
+        });
         configToSend = inferenceConfig;
       }
     } else {
@@ -292,43 +631,61 @@ export async function startModelInference(
       );
     }
 
-    console.log("[API] Building request payload...");
+    apiDebugLog("[API] Building request payload...");
     const payload = {
       arguments: {
         checkpoint: checkpointPath,
       },
       outputPath,
+      inputImagePath,
       inferenceConfig: configToSend,
       configOriginPath,
       workflow_id: workflowId,
     };
 
-    console.log("[API] Payload structure:");
-    console.log(
+    apiDebugLog("[API] Payload structure:");
+    apiDebugLog(
       "[API]   - arguments.checkpoint:",
       payload.arguments.checkpoint,
     );
-    console.log("[API]   - outputPath:", payload.outputPath);
-    console.log(
+    apiDebugLog("[API]   - outputPath:", payload.outputPath);
+    apiDebugLog(
       "[API]   - inferenceConfig length:",
       payload.inferenceConfig?.length,
     );
 
     const data = JSON.stringify(payload);
-    console.log("[API] Request payload size:", data.length, "bytes");
-    console.log(
+    apiDebugLog("[API] Request payload size:", data.length, "bytes");
+    apiDebugLog(
       "[API] JSON payload preview (first 300 chars):",
       data.substring(0, 300),
     );
 
-    console.log("[API] Calling makeApiRequest...");
-    console.log("[API] Target endpoint: start_model_inference");
-    console.log("[API] Method: POST");
-    console.log("[API] =========================================");
+    const configSummary = summarizeConfigText(configToSend, "inference");
+    const diagnostics = detectConfigDiagnostics(configSummary);
+    logClientEvent("inference_api_payload_prepared", {
+      level: diagnostics.length ? "WARNING" : "INFO",
+      message: "Inference API payload prepared",
+      source: "api",
+      data: {
+        workflowId,
+        configOriginPath,
+        outputPath,
+        checkpointPath,
+        requestBytes: data.length,
+        configSummary,
+        diagnostics,
+      },
+    });
+
+    apiDebugLog("[API] Calling makeApiRequest...");
+    apiDebugLog("[API] Target endpoint: start_model_inference");
+    apiDebugLog("[API] Method: POST");
+    apiDebugLog("[API] =========================================");
 
     const result = await makeApiRequest("start_model_inference", "post", data);
-    console.log("[API] ✓ makeApiRequest returned:", result);
-    console.log("========== API.JS: END START_MODEL_INFERENCE ==========\n");
+    apiDebugLog("[API] ✓ makeApiRequest returned:", result);
+    apiDebugLog("========== API.JS: END START_MODEL_INFERENCE ==========\n");
     return result;
   } catch (error) {
     console.error(
@@ -345,7 +702,7 @@ export async function startModelInference(
 
 export async function getInferenceStatus() {
   try {
-    const res = await axios.get(`${BASE_URL}/inference_status`);
+    const res = await axios.get(buildApiUrl("/inference_status"));
     return res.data;
   } catch (error) {
     handleError(error);
@@ -354,7 +711,21 @@ export async function getInferenceStatus() {
 
 export async function getInferenceLogs() {
   try {
-    const res = await axios.get(`${BASE_URL}/inference_logs`);
+    const res = await axios.get(buildApiUrl("/inference_logs"));
+    return res.data;
+  } catch (error) {
+    handleError(error);
+  }
+}
+
+export async function syncWorkflowInferenceRuntime(workflowId, body = {}) {
+  try {
+    const res = await apiClient.post(
+      canonicalizeApiPath(
+        `/api/workflows/${workflowId}/sync-inference-runtime`,
+      ),
+      body,
+    );
     return res.data;
   } catch (error) {
     handleError(error);
@@ -363,7 +734,7 @@ export async function getInferenceLogs() {
 
 export async function stopModelInference() {
   try {
-    await axios.post(`${BASE_URL}/stop_model_inference`);
+    await axios.post(buildApiUrl("/stop_model_inference"));
   } catch (error) {
     handleError(error);
   }
@@ -371,7 +742,7 @@ export async function stopModelInference() {
 
 export async function queryChatBot(query, conversationId) {
   try {
-    const res = await axios.post(`${BASE_URL}/chat/query`, {
+    const res = await axios.post(buildApiUrl("/chat/query"), {
       query,
       conversationId,
     });
@@ -383,7 +754,7 @@ export async function queryChatBot(query, conversationId) {
 
 export async function clearChat() {
   try {
-    await axios.post(`${BASE_URL}/chat/clear`);
+    await axios.post(buildApiUrl("/chat/clear"));
   } catch (error) {
     handleError(error);
   }
@@ -393,7 +764,7 @@ export async function clearChat() {
 
 export async function listConversations() {
   try {
-    const res = await axios.get(`${BASE_URL}/chat/conversations`);
+    const res = await axios.get(buildApiUrl("/chat/conversations"));
     return res.data;
   } catch (error) {
     handleError(error);
@@ -402,7 +773,7 @@ export async function listConversations() {
 
 export async function createConversation() {
   try {
-    const res = await axios.post(`${BASE_URL}/chat/conversations`);
+    const res = await axios.post(buildApiUrl("/chat/conversations"));
     return res.data;
   } catch (error) {
     handleError(error);
@@ -411,7 +782,7 @@ export async function createConversation() {
 
 export async function getConversation(convoId) {
   try {
-    const res = await axios.get(`${BASE_URL}/chat/conversations/${convoId}`);
+    const res = await axios.get(buildApiUrl(`/chat/conversations/${convoId}`));
     return res.data;
   } catch (error) {
     handleError(error);
@@ -420,7 +791,7 @@ export async function getConversation(convoId) {
 
 export async function deleteConversation(convoId) {
   try {
-    await axios.delete(`${BASE_URL}/chat/conversations/${convoId}`);
+    await axios.delete(buildApiUrl(`/chat/conversations/${convoId}`));
   } catch (error) {
     handleError(error);
   }
@@ -428,21 +799,28 @@ export async function deleteConversation(convoId) {
 
 export async function updateConversationTitle(convoId, title) {
   try {
-    const res = await axios.patch(`${BASE_URL}/chat/conversations/${convoId}`, {
-      title,
-    });
+    const res = await axios.patch(
+      buildApiUrl(`/chat/conversations/${convoId}`),
+      { title },
+    );
     return res.data;
   } catch (error) {
     handleError(error);
   }
 }
 
-export async function queryHelperChat(taskKey, query, fieldContext) {
+export async function queryHelperChat(
+  taskKey,
+  query,
+  fieldContext,
+  history = [],
+) {
   try {
-    const res = await axios.post(`${BASE_URL}/chat/helper/query`, {
+    const res = await axios.post(buildApiUrl("/chat/helper/query"), {
       taskKey,
       query,
       fieldContext,
+      history,
     });
     return res.data?.response;
   } catch (error) {
@@ -452,7 +830,7 @@ export async function queryHelperChat(taskKey, query, fieldContext) {
 
 export async function clearHelperChat(taskKey) {
   try {
-    await axios.post(`${BASE_URL}/chat/helper/clear`, { taskKey });
+    await axios.post(buildApiUrl("/chat/helper/clear"), { taskKey });
   } catch (error) {
     handleError(error);
   }
@@ -475,7 +853,7 @@ export async function getModelArchitectures() {
 
 export async function getPMData() {
   try {
-    const res = await apiClient.get("/api/pm/data");
+    const res = await apiClient.get(canonicalizeApiPath("/api/pm/data"));
     return res.data;
   } catch (error) {
     handleError(error);
@@ -484,7 +862,7 @@ export async function getPMData() {
 
 export async function getPMConfig() {
   try {
-    const res = await apiClient.get("/api/pm/config");
+    const res = await apiClient.get(canonicalizeApiPath("/api/pm/config"));
     return res.data;
   } catch (error) {
     handleError(error);
@@ -493,7 +871,7 @@ export async function getPMConfig() {
 
 export async function getPMSchema() {
   try {
-    const res = await apiClient.get("/api/pm/schema");
+    const res = await apiClient.get(canonicalizeApiPath("/api/pm/schema"));
     return res.data;
   } catch (error) {
     handleError(error);
@@ -502,7 +880,10 @@ export async function getPMSchema() {
 
 export async function updatePMConfig(patch) {
   try {
-    const res = await apiClient.post("/api/pm/config", patch);
+    const res = await apiClient.post(
+      canonicalizeApiPath("/api/pm/config"),
+      patch,
+    );
     return res.data;
   } catch (error) {
     handleError(error);
@@ -511,7 +892,10 @@ export async function updatePMConfig(patch) {
 
 export async function savePMData(state) {
   try {
-    const res = await apiClient.post("/api/pm/data", state);
+    const res = await apiClient.post(
+      canonicalizeApiPath("/api/pm/data"),
+      state,
+    );
     return res.data;
   } catch (error) {
     handleError(error);
@@ -520,7 +904,33 @@ export async function savePMData(state) {
 
 export async function resetPMData() {
   try {
-    const res = await apiClient.post("/api/pm/data/reset");
+    const res = await apiClient.post(canonicalizeApiPath("/api/pm/data/reset"));
+    return res.data;
+  } catch (error) {
+    handleError(error);
+  }
+}
+
+export async function mountProjectDirectory({
+  directoryPath,
+  mountName = "",
+  destinationPath = "root",
+}) {
+  try {
+    const res = await apiClient.post(canonicalizeApiPath("/files/mount"), {
+      directory_path: directoryPath,
+      mount_name: mountName,
+      destination_path: destinationPath,
+    });
+    return res.data;
+  } catch (error) {
+    handleError(error);
+  }
+}
+
+export async function resetFileWorkspace() {
+  try {
+    const res = await apiClient.delete(canonicalizeApiPath("/files/workspace"));
     return res.data;
   } catch (error) {
     handleError(error);
@@ -531,7 +941,9 @@ export async function resetPMData() {
 
 export async function getCurrentWorkflow() {
   try {
-    const res = await apiClient.get("/api/workflows/current");
+    const res = await apiClient.get(
+      canonicalizeApiPath("/api/workflows/current"),
+    );
     return res.data;
   } catch (error) {
     handleError(error);
@@ -540,7 +952,10 @@ export async function getCurrentWorkflow() {
 
 export async function updateWorkflow(workflowId, patch) {
   try {
-    const res = await apiClient.patch(`/api/workflows/${workflowId}`, patch);
+    const res = await apiClient.patch(
+      canonicalizeApiPath(`/api/workflows/${workflowId}`),
+      patch,
+    );
     return res.data;
   } catch (error) {
     handleError(error);
@@ -549,7 +964,9 @@ export async function updateWorkflow(workflowId, patch) {
 
 export async function listWorkflowEvents(workflowId) {
   try {
-    const res = await apiClient.get(`/api/workflows/${workflowId}/events`);
+    const res = await apiClient.get(
+      canonicalizeApiPath(`/api/workflows/${workflowId}/events`),
+    );
     return res.data;
   } catch (error) {
     handleError(error);
@@ -558,7 +975,9 @@ export async function listWorkflowEvents(workflowId) {
 
 export async function getWorkflowHotspots(workflowId) {
   try {
-    const res = await apiClient.get(`/api/workflows/${workflowId}/hotspots`);
+    const res = await apiClient.get(
+      canonicalizeApiPath(`/api/workflows/${workflowId}/hotspots`),
+    );
     return res.data;
   } catch (error) {
     handleError(error);
@@ -567,7 +986,9 @@ export async function getWorkflowHotspots(workflowId) {
 
 export async function getWorkflowImpactPreview(workflowId) {
   try {
-    const res = await apiClient.get(`/api/workflows/${workflowId}/impact-preview`);
+    const res = await apiClient.get(
+      canonicalizeApiPath(`/api/workflows/${workflowId}/impact-preview`),
+    );
     return res.data;
   } catch (error) {
     handleError(error);
@@ -576,7 +997,139 @@ export async function getWorkflowImpactPreview(workflowId) {
 
 export async function getWorkflowMetrics(workflowId) {
   try {
-    const res = await apiClient.get(`/api/workflows/${workflowId}/metrics`);
+    const res = await apiClient.get(
+      canonicalizeApiPath(`/api/workflows/${workflowId}/metrics`),
+    );
+    return res.data;
+  } catch (error) {
+    handleError(error);
+  }
+}
+
+export async function getWorkflowProjectProgress(workflowId) {
+  try {
+    const res = await apiClient.get(
+      canonicalizeApiPath(`/api/workflows/${workflowId}/project-progress`),
+    );
+    return res.data;
+  } catch (error) {
+    handleError(error);
+  }
+}
+
+export async function getWorkflowOverview(workflowId, { refresh = true } = {}) {
+  try {
+    const res = await apiClient.get(
+      canonicalizeApiPath(`/api/workflows/${workflowId}/overview`),
+      {
+        params: { refresh },
+      },
+    );
+    return res.data;
+  } catch (error) {
+    handleError(error);
+  }
+}
+
+export async function updateWorkflowProjectProgressVolume(workflowId, body) {
+  try {
+    const res = await apiClient.post(
+      canonicalizeApiPath(
+        `/api/workflows/${workflowId}/project-progress/volume-status`,
+      ),
+      body,
+    );
+    return res.data;
+  } catch (error) {
+    handleError(error);
+  }
+}
+
+export async function getWorkflowAgentRecommendation(workflowId) {
+  try {
+    const res = await apiClient.get(
+      canonicalizeApiPath(`/api/workflows/${workflowId}/agent/recommendation`),
+    );
+    return res.data;
+  } catch (error) {
+    handleError(error);
+  }
+}
+
+export async function getWorkflowPreflight(workflowId) {
+  try {
+    const res = await apiClient.get(
+      canonicalizeApiPath(`/api/workflows/${workflowId}/preflight`),
+    );
+    return res.data;
+  } catch (error) {
+    handleError(error);
+  }
+}
+
+export async function listWorkflowArtifacts(workflowId) {
+  try {
+    const res = await apiClient.get(
+      canonicalizeApiPath(`/api/workflows/${workflowId}/artifacts`),
+    );
+    return res.data;
+  } catch (error) {
+    handleError(error);
+  }
+}
+
+export async function listWorkflowModelRuns(workflowId) {
+  try {
+    const res = await apiClient.get(
+      canonicalizeApiPath(`/api/workflows/${workflowId}/model-runs`),
+    );
+    return res.data;
+  } catch (error) {
+    handleError(error);
+  }
+}
+
+export async function listWorkflowModelVersions(workflowId) {
+  try {
+    const res = await apiClient.get(
+      canonicalizeApiPath(`/api/workflows/${workflowId}/model-versions`),
+    );
+    return res.data;
+  } catch (error) {
+    handleError(error);
+  }
+}
+
+export async function listWorkflowCorrectionSets(workflowId) {
+  try {
+    const res = await apiClient.get(
+      canonicalizeApiPath(`/api/workflows/${workflowId}/correction-sets`),
+    );
+    return res.data;
+  } catch (error) {
+    handleError(error);
+  }
+}
+
+export async function listWorkflowEvaluationResults(workflowId) {
+  try {
+    const res = await apiClient.get(
+      canonicalizeApiPath(`/api/workflows/${workflowId}/evaluation-results`),
+    );
+    return res.data;
+  } catch (error) {
+    handleError(error);
+  }
+}
+
+export async function computeWorkflowEvaluationResult(workflowId, body) {
+  try {
+    const res = await apiClient.post(
+      canonicalizeApiPath(
+        `/api/workflows/${workflowId}/evaluation-results/compute`,
+      ),
+      body,
+    );
     return res.data;
   } catch (error) {
     handleError(error);
@@ -585,7 +1138,21 @@ export async function getWorkflowMetrics(workflowId) {
 
 export async function exportWorkflowBundle(workflowId) {
   try {
-    const res = await apiClient.post(`/api/workflows/${workflowId}/export-bundle`);
+    const res = await apiClient.post(
+      canonicalizeApiPath(`/api/workflows/${workflowId}/export-bundle`),
+    );
+    return res.data;
+  } catch (error) {
+    handleError(error);
+  }
+}
+
+export async function startNewWorkflow(body = {}) {
+  try {
+    const res = await apiClient.post(
+      canonicalizeApiPath("/api/workflows/current/reset"),
+      body,
+    );
     return res.data;
   } catch (error) {
     handleError(error);
@@ -594,7 +1161,10 @@ export async function exportWorkflowBundle(workflowId) {
 
 export async function appendWorkflowEvent(workflowId, event) {
   try {
-    const res = await apiClient.post(`/api/workflows/${workflowId}/events`, event);
+    const res = await apiClient.post(
+      canonicalizeApiPath(`/api/workflows/${workflowId}/events`),
+      event,
+    );
     return res.data;
   } catch (error) {
     handleError(error);
@@ -604,7 +1174,7 @@ export async function appendWorkflowEvent(workflowId, event) {
 export async function createAgentAction(workflowId, action) {
   try {
     const res = await apiClient.post(
-      `/api/workflows/${workflowId}/agent-actions`,
+      canonicalizeApiPath(`/api/workflows/${workflowId}/agent-actions`),
       action,
     );
     return res.data;
@@ -613,10 +1183,30 @@ export async function createAgentAction(workflowId, action) {
   }
 }
 
-export async function approveAgentAction(workflowId, eventId) {
+export async function approveAgentAction(workflowId, eventId, overrides = {}) {
+  try {
+    const hasOverrides =
+      overrides &&
+      typeof overrides === "object" &&
+      Object.keys(overrides).length > 0;
+    const res = await apiClient.post(
+      canonicalizeApiPath(
+        `/api/workflows/${workflowId}/agent-actions/${eventId}/approve`,
+      ),
+      hasOverrides ? { overrides } : undefined,
+    );
+    return res.data;
+  } catch (error) {
+    handleError(error);
+  }
+}
+
+export async function runWorkflowCommand(workflowId, commandId) {
   try {
     const res = await apiClient.post(
-      `/api/workflows/${workflowId}/agent-actions/${eventId}/approve`,
+      canonicalizeApiPath(
+        `/api/workflows/${workflowId}/commands/${commandId}/run`,
+      ),
     );
     return res.data;
   } catch (error) {
@@ -627,7 +1217,9 @@ export async function approveAgentAction(workflowId, eventId) {
 export async function rejectAgentAction(workflowId, eventId) {
   try {
     const res = await apiClient.post(
-      `/api/workflows/${workflowId}/agent-actions/${eventId}/reject`,
+      canonicalizeApiPath(
+        `/api/workflows/${workflowId}/agent-actions/${eventId}/reject`,
+      ),
     );
     return res.data;
   } catch (error) {
@@ -635,11 +1227,30 @@ export async function rejectAgentAction(workflowId, eventId) {
   }
 }
 
-export async function queryWorkflowAgent(workflowId, query) {
+export async function queryWorkflowAgent(
+  workflowId,
+  query,
+  conversationId = null,
+) {
   try {
-    const res = await apiClient.post(`/api/workflows/${workflowId}/agent/query`, {
-      query,
-    });
+    const res = await apiClient.post(
+      canonicalizeApiPath(`/api/workflows/${workflowId}/agent/query`),
+      {
+        query,
+        conversation_id: conversationId,
+      },
+    );
+    return res.data;
+  } catch (error) {
+    handleError(error);
+  }
+}
+
+export async function getWorkflowAgentConversation(workflowId) {
+  try {
+    const res = await apiClient.get(
+      canonicalizeApiPath(`/api/workflows/${workflowId}/agent/conversation`),
+    );
     return res.data;
   } catch (error) {
     handleError(error);
diff --git a/client/src/api.test.js b/client/src/api.test.js
new file mode 100644
index 00000000..25788c74
--- /dev/null
+++ b/client/src/api.test.js
@@ -0,0 +1,95 @@
+const BASE_WITH_API_PREFIX = "https://demo.example/api";
+const BASE_WITHOUT_API_PREFIX = "https://demo.example";
+
+const loadApiModule = (baseUrl) => {
+  process.env.REACT_APP_API_BASE_URL = baseUrl;
+  process.env.REACT_APP_SERVER_PROTOCOL = "https";
+  process.env.REACT_APP_SERVER_URL = "demo.example";
+
+  const apiClientMock = {
+    get: jest.fn(),
+    post: jest.fn(),
+    patch: jest.fn(),
+    delete: jest.fn(),
+    put: jest.fn(),
+    interceptors: {
+      request: { use: jest.fn() },
+      response: { use: jest.fn() },
+    },
+  };
+
+  const axiosMock = {
+    create: jest.fn(() => apiClientMock),
+    get: jest.fn(),
+    post: jest.fn(),
+    patch: jest.fn(),
+    delete: jest.fn(),
+    put: jest.fn(),
+    interceptors: {
+      request: { use: jest.fn() },
+      response: { use: jest.fn() },
+    },
+  };
+
+  jest.resetModules();
+  jest.doMock("axios", () => axiosMock);
+  jest.doMock("./logging/appEventLog", () => ({
+    logClientEvent: jest.fn(),
+  }));
+
+  const api = require("./api");
+  return { api, apiClientMock, axiosMock };
+};
+
+describe("api canonicalization", () => {
+  afterEach(() => {
+    delete process.env.REACT_APP_API_BASE_URL;
+    jest.clearAllMocks();
+  });
+
+  it("strips legacy workflow prefix when base URL already ends with /api", async () => {
+    const { api, apiClientMock } = loadApiModule(BASE_WITH_API_PREFIX);
+    apiClientMock.get.mockResolvedValue({ data: { id: 42 } });
+
+    await api.getCurrentWorkflow();
+
+    expect(apiClientMock.get).toHaveBeenCalledWith("/workflows/current");
+  });
+
+  it("keeps /api/workflows path when base URL does not end with /api", async () => {
+    const { api, apiClientMock } = loadApiModule(BASE_WITHOUT_API_PREFIX);
+    apiClientMock.get.mockResolvedValue({ data: { id: 42 } });
+
+    await api.getCurrentWorkflow();
+
+    expect(apiClientMock.get).toHaveBeenCalledWith("/api/workflows/current");
+  });
+
+  it("canonicalizes files-style prefixed paths with query strings", () => {
+    const { api } = loadApiModule(BASE_WITH_API_PREFIX);
+
+    const url = api.buildApiUrl("/api/files?parent=root");
+
+    expect(url).toBe("https://demo.example/api/files?parent=root");
+  });
+
+  it("canonicalizes training approval/action paths for base URLs with /api/workflows", () => {
+    const { api, apiClientMock } = loadApiModule(
+      "https://demo.example/api/workflows",
+    );
+    apiClientMock.post.mockResolvedValue({ data: {} });
+
+    api.approveAgentAction(99, 123);
+    expect(apiClientMock.post).toHaveBeenNthCalledWith(
+      1,
+      "/99/agent-actions/123/approve",
+      undefined,
+    );
+
+    api.runWorkflowCommand(99, 321);
+    expect(apiClientMock.post).toHaveBeenNthCalledWith(
+      2,
+      "/99/commands/321/run",
+    );
+  });
+});
diff --git a/client/src/components/Chatbot.js b/client/src/components/Chatbot.js
index 38de04e0..502672d1 100644
--- a/client/src/components/Chatbot.js
+++ b/client/src/components/Chatbot.js
@@ -6,78 +6,661 @@ import {
   Typography,
   Space,
   Spin,
-  Popconfirm,
-  Tooltip,
+  Tag,
+  message,
 } from "antd";
-import {
-  SendOutlined,
-  CloseOutlined,
-  DeleteOutlined,
-  PlusOutlined,
-  MessageOutlined,
-  MenuFoldOutlined,
-  MenuUnfoldOutlined,
-} from "@ant-design/icons";
-import {
-  queryChatBot,
-  clearChat,
-  listConversations,
-  getConversation,
-  deleteConversation,
-} from "../api";
+import { SendOutlined, CloseOutlined } from "@ant-design/icons";
+import { getWorkflowAgentConversation, queryChatBot } from "../api";
 import ReactMarkdown from "react-markdown";
 import remarkGfm from "remark-gfm";
-import WorkflowTimeline from "./WorkflowTimeline";
 import { useWorkflow } from "../contexts/WorkflowContext";
+import AgentProposalCard from "./chat/AgentProposalCard";
+import AssistantActionCard from "./chat/AssistantActionCard";
+import AssistantCommandCard from "./chat/AssistantCommandCard";
+import AssistantTrace from "./chat/AssistantTrace";
+import AgentBadge, { getAgentVisual } from "./chat/AgentVisuals";
+import { logClientEvent } from "../logging/appEventLog";
 
 const { TextArea } = Input;
 const { Text } = Typography;
+const MONO_FONT =
+  "'SFMono-Regular', Menlo, Monaco, Consolas, 'Liberation Mono', monospace";
 
 const GREETING = {
   role: "assistant",
   content:
-    "Hello! I'm your AI assistant, built to help you navigate PyTC Client. How can I help you today?",
+    "I’ll coordinate the workflow and pull in specialist agents for data, visualization, proofreading, training, inference, and evidence when needed. Tell me what you want to do in plain language.",
 };
 
-/* ─── helper: truncate a string to `n` chars ─────────────────────────────── */
-const truncate = (str, n = 50) =>
-  str.length > n ? str.slice(0, n).trimEnd() + "…" : str;
+const QUICK_NEXT_QUERY = "What should I do next?";
+const CONTINUOUS_CHAT_STORAGE_KEY = "pytc.workflowAssistant.continuousChat.v1";
+
+const WORKFLOW_SLASH_COMMANDS = {
+  "/status": "status",
+  "/next": "next step",
+  "/help": "what can the agent do",
+  "/infer": "run model",
+  "/inference": "run model",
+  "/segment": "run model to segment this volume",
+  "/proofread": "proofread this data",
+  "/train": "start training",
+  "/compare": "compare results and compute metrics",
+  "/metrics": "compare results and compute metrics",
+  "/export": "export evidence bundle",
+};
 
-const WORKFLOW_QUERY_TERMS = [
+const WORKFLOW_AGENT_KEYWORDS = [
   "workflow",
-  "next",
-  "stage",
-  "retrain",
-  "training",
-  "corrected",
-  "proofread",
+  "project",
+  "dataset",
+  "directory",
+  "folder",
+  "folders",
+  "file",
+  "files",
+  "volume",
+  "image",
+  "label",
   "mask",
+  "segmentation",
+  "segment",
+  "proofread",
+  "proofreading",
+  "train",
+  "training",
+  "retrain",
   "inference",
+  "infer",
+  "run model",
+  "checkpoint",
+  "config",
   "visualize",
+  "visualise",
+  "vis",
+  "viz",
+  "viewer",
+  "scales",
+  "voxel",
+  "resolution",
+  "status",
+  "next step",
+  "what next",
+  "what should i do",
+  "what do you need",
+  "what can you do",
+  "help me",
+  "run things",
+  "mount",
+  "reset workspace",
+  "clear workspace",
+  "monitor",
+  "logs",
+  "tensorboard",
   "evaluate",
+  "metrics",
+  "compare",
+  "export",
+  "evidence",
+];
+
+const WORKFLOW_AGENT_PATTERNS = [
+  /\b(view|show|open|inspect|see|vis|viz)\b.{0,48}\b(data|volume|volumes|image|images|label|labels|mask|masks|seg|segs|segmentation|segmentations)\b/,
+  /\blook at\b.{0,48}\b(data|volume|volumes|image|images|label|labels|mask|masks|seg|segs|segmentation|segmentations)\b/,
+  /\bwhat\b.{0,40}\b(looking at|loaded|open|mounted|project|dataset|volume|data)\b/,
+  /\bwhere\b.{0,40}\b(are we|am i|is this|in the workflow)\b/,
+  /\b(run|start|launch)\b.{0,48}\b(app|model|inference|training|proofread|proofreading|viewer|visualization)\b/,
+];
+
+const WORKFLOW_FOLLOW_UP_PATTERNS = [
+  /\b(take a look|look at|show|open|view|inspect|check)\b/,
+  /\b(it|this|that|those|them|there|here|first|next|again|same one)\b/,
+  /\b(go ahead|do it|do that|run it|start it|use that|sounds good)\b/,
+  /^(yes|yeah|yep|ok|okay|sure|please|what|why|how|wait|huh)[\s!.?,]*$/i,
+];
+
+const toList = (value) => (Array.isArray(value) ? value : []);
+
+const normalizeWorkflowAgentQuery = (query) => {
+  const trimmed = query.trim();
+  if (!trimmed.startsWith("/")) {
+    return { agentQuery: query, commandAlias: null };
+  }
+  const [command, ...rest] = trimmed.split(/\s+/);
+  const alias = WORKFLOW_SLASH_COMMANDS[command.toLowerCase()];
+  if (!alias) {
+    return { agentQuery: query, commandAlias: null };
+  }
+  const suffix = rest.join(" ").trim();
+  return {
+    agentQuery: suffix ? `${alias}: ${suffix}` : alias,
+    commandAlias: command.toLowerCase(),
+  };
+};
+
+const clientEffectsWithoutRuntime = (effects = {}) => {
+  if (!effects || typeof effects !== "object") return effects;
+  const { runtime_action: _runtimeAction, ...rest } = effects;
+  return rest;
+};
+
+const runnableAttachmentCount = (message = {}) =>
+  (Array.isArray(message.actions) ? message.actions.length : 0) +
+  (Array.isArray(message.commands) ? message.commands.length : 0) +
+  (Array.isArray(message.proposals) ? message.proposals.length : 0);
+
+const agentIdentityKey = (agent = {}) =>
+  agent.agent_type ||
+  agent.type ||
+  agent.label ||
+  agent.agent_label ||
+  "project_manager";
+
+const messageAgents = (message = {}) => {
+  const agents = [];
+  const addAgent = (agent) => {
+    if (!agent) return;
+    const visual = getAgentVisual(agent);
+    const key = agentIdentityKey(agent);
+    if (agents.some((item) => item.key === key)) return;
+    agents.push({ key, ...visual });
+  };
+
+  (message.trace || []).forEach((item) => addAgent(item));
+  (message.actions || []).forEach((action) => {
+    addAgent(action.specialist_agent || action);
+    addAgent(action.orchestrator_agent);
+  });
+  (message.proposals || []).forEach((proposal) => {
+    const payload = proposal.payload || proposal;
+    addAgent(payload.specialist_agent || payload.action_card?.specialist_agent);
+    addAgent(
+      payload.orchestrator_agent || payload.action_card?.orchestrator_agent,
+    );
+  });
+
+  return agents;
+};
+
+const STALE_WORKFLOW_CARD_NOTICE =
+  "That run card belonged to an earlier workflow, so I hid the stale button. Ask me to stage it again and I'll make a fresh one for this project.";
+
+const STALE_WORKFLOW_CARD_PATTERN =
+  /(review (?:the )?run card|review run|approve|run in app|launch(?:ing| it)?|run card)/i;
+
+const proposalRequestFromEvent = (proposal = {}) => {
+  const payload = proposal.payload || {};
+  const params = payload.params || proposal.params || {};
+  const action = payload.action || proposal.action || proposal.type;
+  if (!action || !params || typeof params !== "object") return null;
+  return {
+    action,
+    summary: proposal.summary || `Approve agent proposal: ${action}.`,
+    payload: params,
+  };
+};
+
+const isProposalNotFoundError = (error) => {
+  const messageText = String(error?.message || error || "").toLowerCase();
+  return (
+    messageText.includes("agent proposal not found") ||
+    messageText.includes("404")
+  );
+};
+
+const isGreetingQuery = (query) =>
+  /^(hi|hello|hey|yo|sup|hiya)[\s!.?,]*$/i.test(query.trim());
+
+const isGibberishQuery = (query) => {
+  const lower = query.trim().toLowerCase();
+  const compact = lower.replace(/[^a-z0-9]+/g, "");
+  if (!compact || lower.startsWith("/")) return false;
+  const vowelCount = (compact.match(/[aeiou]/g) || []).length;
+  return compact.length >= 8 && !/\s/.test(lower) && vowelCount <= 2;
+};
+
+const isWorkflowAgentQuery = (query) => {
+  const trimmed = query.trim();
+  if (!trimmed) return false;
+  const normalized = normalizeWorkflowAgentQuery(trimmed);
+  if (normalized.commandAlias) return true;
+  if (isGreetingQuery(trimmed)) return true;
+  const lower = trimmed.toLowerCase();
+  return (
+    WORKFLOW_AGENT_KEYWORDS.some((keyword) => lower.includes(keyword)) ||
+    WORKFLOW_AGENT_PATTERNS.some((pattern) => pattern.test(lower))
+  );
+};
+
+const getLastAssistantMessage = (messages = []) => {
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    if (messages[index]?.role === "assistant") {
+      return messages[index];
+    }
+  }
+  return null;
+};
+
+const isWorkflowFollowUpQuery = (query, messages = [], workflowId = null) => {
+  const lastAssistant = getLastAssistantMessage(messages);
+  if (lastAssistant?.source !== "workflow_orchestrator") {
+    return false;
+  }
+  if (
+    lastAssistant.workflow_id &&
+    workflowId &&
+    String(lastAssistant.workflow_id) !== String(workflowId)
+  ) {
+    return false;
+  }
+  const trimmed = query.trim();
+  if (!trimmed || trimmed.length > 140) {
+    return false;
+  }
+  const lower = trimmed.toLowerCase();
+  return WORKFLOW_FOLLOW_UP_PATTERNS.some((pattern) => pattern.test(lower));
+};
+
+const PROMPT_LEAK_MARKERS = [
+  "you are the supervisor agent",
+  "response style for biologists",
+  "routing — decide",
+  "routing - decide",
+  "critical rules:",
+  "sub-agents:",
+  "search_documentation",
+  "delegate_to_training_agent",
+  "delegate_to_inference_agent",
 ];
 
+const parseToolCallJson = (text) => {
+  try {
+    const parsed = JSON.parse(text);
+    if (
+      !parsed ||
+      typeof parsed !== "object" ||
+      typeof parsed.name !== "string"
+    ) {
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+};
+
+const parseRawToolCall = (content) => {
+  const text = String(content || "").trim();
+  if (text.startsWith("{") && text.endsWith("}")) {
+    const parsed = parseToolCallJson(text);
+    if (parsed) return parsed;
+  }
+  const embeddedJson = text.match(/\{[\s\S]*"name"\s*:\s*"[^"]+"[\s\S]*\}/);
+  return embeddedJson ? parseToolCallJson(embeddedJson[0]) : null;
+};
+
+const normalizeAssistantContent = (content) => {
+  const toolCall = parseRawToolCall(content);
+  if (!toolCall) return String(content || "");
+  if (toolCall.name === "visualize_volume_pair") {
+    return (
+      "I should not have shown that internal command.\n" +
+      "Do this: use the workflow action card to choose a volume pair, then open it in Visualize."
+    );
+  }
+  return (
+    "I should not have shown that internal command.\n" +
+    "Tell me what you want to do in plain language and I will offer a safe app action."
+  );
+};
+
+const sanitizeLoadedMessage = (message, currentWorkflowId = null) => {
+  if (message.role !== "assistant") return message;
+  const content = String(message.content || "");
+  const normalizedContent = normalizeAssistantContent(content);
+  const messageWorkflowId = Number(
+    message.workflow_id || message.workflowId || 0,
+  );
+  const activeWorkflowId = Number(currentWorkflowId || 0);
+  if (
+    messageWorkflowId &&
+    activeWorkflowId &&
+    messageWorkflowId !== activeWorkflowId
+  ) {
+    const shouldExplainStrippedCard =
+      runnableAttachmentCount(message) > 0 &&
+      STALE_WORKFLOW_CARD_PATTERN.test(normalizedContent) &&
+      !normalizedContent.includes(STALE_WORKFLOW_CARD_NOTICE);
+    return {
+      ...message,
+      content: shouldExplainStrippedCard
+        ? `${normalizedContent}\n\n${STALE_WORKFLOW_CARD_NOTICE}`
+        : normalizedContent,
+      actions: [],
+      commands: [],
+      proposals: [],
+      trace: [],
+    };
+  }
+  if (normalizedContent !== content) {
+    return { ...message, content: normalizedContent };
+  }
+  const lower = content.toLowerCase();
+  const leaked = PROMPT_LEAK_MARKERS.some((marker) => lower.includes(marker));
+  if (!leaked) return message;
+  return {
+    ...message,
+    content:
+      "Hi. I can help run this segmentation loop. Ask me to run the model, proofread masks, use saved edits for training, or compare results.",
+  };
+};
+
+const loadContinuousChatState = (currentWorkflowId = null) => {
+  if (typeof window === "undefined" || !window.sessionStorage) {
+    return { activeConvoId: null, messages: [GREETING] };
+  }
+  try {
+    const raw = window.sessionStorage.getItem(CONTINUOUS_CHAT_STORAGE_KEY);
+    if (!raw) return { activeConvoId: null, messages: [GREETING] };
+    const parsed = JSON.parse(raw);
+    const storedMessages = Array.isArray(parsed?.messages)
+      ? parsed.messages
+          .filter(
+            (message) =>
+              message &&
+              (message.role === "assistant" || message.role === "user") &&
+              typeof message.content === "string",
+          )
+          .map((message) => sanitizeLoadedMessage(message, currentWorkflowId))
+      : [];
+    return {
+      activeConvoId: parsed?.activeConvoId || parsed?.conversationId || null,
+      messages: storedMessages.length ? storedMessages : [GREETING],
+    };
+  } catch {
+    return { activeConvoId: null, messages: [GREETING] };
+  }
+};
+
+const saveContinuousChatState = ({ activeConvoId, messages }) => {
+  if (typeof window === "undefined" || !window.sessionStorage) return;
+  try {
+    window.sessionStorage.setItem(
+      CONTINUOUS_CHAT_STORAGE_KEY,
+      JSON.stringify({ activeConvoId, messages }),
+    );
+  } catch {
+    // Session persistence is a convenience; chat should still work without it.
+  }
+};
+
+const workflowConversationMessageToChatMessage = (
+  message,
+  currentWorkflowId = null,
+) =>
+  sanitizeLoadedMessage(
+    {
+      role: message.role,
+      content: message.content,
+      source: message.source || undefined,
+      workflow_id: message.workflow_id || currentWorkflowId || undefined,
+      actions: message.actions || [],
+      commands: message.commands || [],
+      proposals: message.proposals || [],
+      trace: message.trace || [],
+    },
+    currentWorkflowId,
+  );
+
+const byProposalId = (messages = []) => {
+  const index = {};
+  messages.forEach((message) => {
+    (message?.proposals || []).forEach((proposal) => {
+      if (proposal?.id == null) return;
+      index[String(proposal.id)] = {
+        ...(proposal?.payload ? { payload: proposal.payload } : {}),
+        ...proposal,
+      };
+    });
+  });
+  return index;
+};
+
+const reconcileProposal = (localProposal, hydratedProposal) => {
+  if (!localProposal?.id || !hydratedProposal) return localProposal;
+  const approval_status =
+    hydratedProposal.approval_status ||
+    localProposal.approval_status ||
+    "pending";
+  return {
+    ...localProposal,
+    ...hydratedProposal,
+    summary: hydratedProposal.summary || localProposal.summary,
+    payload: {
+      ...(localProposal?.payload || {}),
+      ...(hydratedProposal.payload || {}),
+    },
+    params: {
+      ...(localProposal?.params || {}),
+      ...(hydratedProposal.params || {}),
+    },
+    approval_status,
+  };
+};
+
+const reconcileProposalStatuses = (messages = [], hydratedMessages = []) => {
+  const hydrated = byProposalId(hydratedMessages);
+  return messages.map((message) => {
+    if (
+      !message ||
+      !Array.isArray(message.proposals) ||
+      !message.proposals.length
+    ) {
+      return message;
+    }
+    return {
+      ...message,
+      proposals: message.proposals.map((proposal) => {
+        const hydratedProposal = hydrated[String(proposal?.id)];
+        if (!hydratedProposal) return proposal;
+        return reconcileProposal(proposal, hydratedProposal);
+      }),
+    };
+  });
+};
+
 /* ═══════════════════════════════════════════════════════════════════════════ */
 
-function Chatbot({ onClose }) {
+function Chatbot({
+  onClose,
+  queuedWorkflowQuery = null,
+  onQueuedWorkflowQueryConsumed,
+}) {
   /* ── state ─────────────────────────────────────────────────────────────── */
-  const [conversations, setConversations] = useState([]);
-  const [activeConvoId, setActiveConvoId] = useState(null);
-  const [messages, setMessages] = useState([GREETING]);
+  const workflowContext = useWorkflow();
+  const runClientEffects = workflowContext?.runClientEffects;
+  const executeAssistantItem = workflowContext?.executeAssistantItem;
+  const workflow = workflowContext?.workflow;
+  const initialChatStateRef = useRef(null);
+  if (initialChatStateRef.current === null) {
+    initialChatStateRef.current = loadContinuousChatState(workflow?.id);
+  }
+
+  const [activeConvoId, setActiveConvoId] = useState(
+    initialChatStateRef.current.activeConvoId,
+  );
+  const [messages, setMessages] = useState(
+    initialChatStateRef.current.messages,
+  );
   const [inputValue, setInputValue] = useState("");
   const [isSending, setIsSending] = useState(false);
-  const [sidebarOpen, setSidebarOpen] = useState(true);
-  const [isLoadingConvo, setIsLoadingConvo] = useState(false);
 
   const lastMessageRef = useRef(null);
-  const workflowContext = useWorkflow();
+  const handledQueuedQueryRef = useRef(null);
+  const hydratedWorkflowConversationRef = useRef(null);
+
+  const appendLocalProposalToLatestAssistant = useCallback((proposal) => {
+    if (!proposal?.id) return;
+    setMessages((prev) => {
+      const next = [...prev];
+      for (let index = next.length - 1; index >= 0; index -= 1) {
+        if (next[index]?.role !== "assistant") continue;
+        const proposals = next[index].proposals || [];
+        next[index] = {
+          ...next[index],
+          proposals: [...proposals, proposal],
+        };
+        return next;
+      }
+      return prev;
+    });
+  }, []);
+
+  const updateLocalProposalStatus = useCallback(
+    (proposalId, approvalStatus) => {
+      if (!proposalId) return;
+      setMessages((prev) =>
+        prev.map((entry) => {
+          if (!Array.isArray(entry.proposals) || entry.proposals.length === 0) {
+            return entry;
+          }
+          return {
+            ...entry,
+            proposals: entry.proposals.map((proposal) =>
+              proposal.id === proposalId
+                ? { ...proposal, approval_status: approvalStatus }
+                : proposal,
+            ),
+          };
+        }),
+      );
+    },
+    [],
+  );
+
+  const buildTrainingRunProposal = useCallback((item) => {
+    const effects = item?.client_effects || {};
+    const runtimeAction = effects.runtime_action || {};
+    const configPreset = effects.set_training_config_preset || "";
+    const imagePath = effects.set_training_image_path || "";
+    const labelPath = effects.set_training_label_path || "";
+    const outputPath = effects.set_training_output_path || "";
+    const parameterMode = runtimeAction.parameter_mode || "agent_default";
+
+    return {
+      action: "start_training_run",
+      summary: `Approve training run: ${item?.title || item?.label || "start training"}.`,
+      payload: {
+        client_effects: effects,
+        action_card: item?.action_card || null,
+        orchestrator_agent: item?.orchestrator_agent || null,
+        specialist_agent: item?.specialist_agent || null,
+        config_preset: configPreset,
+        image_path: imagePath,
+        label_path: labelPath,
+        output_path: outputPath,
+        parameter_mode: parameterMode,
+        autopick_parameters: Boolean(runtimeAction.autopick_parameters),
+        training_volume_subset: effects.training_volume_subset || null,
+      },
+    };
+  }, []);
+
+  const buildClientEffectsProposal = useCallback((item) => {
+    const effects = item?.client_effects || {};
+    const label = item?.title || item?.label || item?.id || "assistant action";
+    return {
+      action: "run_client_effects",
+      summary: `Approve app action: ${label}.`,
+      payload: {
+        client_effects: effects,
+        action_card: item?.action_card || null,
+        orchestrator_agent: item?.orchestrator_agent || null,
+        specialist_agent: item?.specialist_agent || null,
+        item_id: item?.id || null,
+        item_label: label,
+        item_type: item?.command ? "command" : "action",
+        risk_level: item?.risk_level || null,
+        runtime_action: effects.runtime_action || null,
+        workflow_action: effects.workflow_action || null,
+      },
+    };
+  }, []);
+
+  const populateTrainingReviewForm = useCallback(
+    async (item, itemId) => {
+      if (!runClientEffects) return true;
+      const reviewEffects = clientEffectsWithoutRuntime(item?.client_effects);
+      try {
+        await runClientEffects(reviewEffects);
+        logClientEvent("assistant_item_training_review_populated", {
+          source: "chatbot",
+          message: "Assistant populated the training review form",
+          data: {
+            workflowId: workflow?.id || null,
+            activeConvoId,
+            itemId,
+          },
+        });
+        return true;
+      } catch (error) {
+        const fallbackEffects = {
+          navigate_to: reviewEffects?.navigate_to || "training",
+          set_training_image_path: reviewEffects?.set_training_image_path,
+          set_training_label_path: reviewEffects?.set_training_label_path,
+          set_training_output_path: reviewEffects?.set_training_output_path,
+          set_training_log_path: reviewEffects?.set_training_log_path,
+          refresh_project_progress: reviewEffects?.refresh_project_progress,
+        };
+        try {
+          await runClientEffects(fallbackEffects);
+          logClientEvent("assistant_item_training_review_partial", {
+            level: "WARN",
+            source: "chatbot",
+            message:
+              error.message ||
+              "Training review form populated without every requested effect",
+            data: {
+              workflowId: workflow?.id || null,
+              activeConvoId,
+              itemId,
+            },
+          });
+          message.warning(
+            "I filled the run paths, but one review detail needs attention before launch.",
+          );
+          return false;
+        } catch (fallbackError) {
+          logClientEvent("assistant_item_training_review_failed", {
+            level: "ERROR",
+            source: "chatbot",
+            message:
+              fallbackError.message ||
+              error.message ||
+              "Could not populate the training review form",
+            data: {
+              workflowId: workflow?.id || null,
+              activeConvoId,
+              itemId,
+            },
+          });
+          throw error;
+        }
+      }
+    },
+    [activeConvoId, runClientEffects, workflow?.id],
+  );
 
   const shouldUseWorkflowAgent = (query) => {
     if (!workflowContext?.workflow?.id || !workflowContext?.queryAgent) {
       return false;
     }
-    const lower = query.toLowerCase();
-    return WORKFLOW_QUERY_TERMS.some((term) => lower.includes(term));
+    if (isGibberishQuery(query)) {
+      return false;
+    }
+    return (
+      isWorkflowAgentQuery(query) ||
+      isWorkflowFollowUpQuery(query, messages, workflowContext.workflow.id)
+    );
   };
 
   /* ── scroll ────────────────────────────────────────────────────────────── */
@@ -94,71 +677,211 @@ function Chatbot({ onClose }) {
     scrollToBottom();
   }, [messages, isSending, scrollToBottom]);
 
-  /* ── load conversation list on mount ────────────────────────────────────── */
   useEffect(() => {
+    saveContinuousChatState({ activeConvoId, messages });
+  }, [activeConvoId, messages]);
+
+  useEffect(() => {
+    if (!workflow?.id) return;
+    setMessages((prev) =>
+      prev.map((message) => sanitizeLoadedMessage(message, workflow.id)),
+    );
+  }, [workflow?.id]);
+
+  useEffect(() => {
+    if (!workflow?.id) return;
+    if (hydratedWorkflowConversationRef.current === workflow.id) return;
+    hydratedWorkflowConversationRef.current = workflow.id;
+
     let cancelled = false;
-    (async () => {
-      try {
-        const convos = await listConversations();
-        if (!cancelled && convos) setConversations(convos);
-      } catch {
-        // server may not be ready yet
-      }
-    })();
+    getWorkflowAgentConversation(workflow.id)
+      .then((conversation) => {
+        if (cancelled || !conversation?.messages?.length) return;
+        const serverMessages = conversation.messages
+          .filter(
+            (message) =>
+              message &&
+              (message.role === "assistant" || message.role === "user") &&
+              typeof message.content === "string",
+          )
+          .map((message) =>
+            workflowConversationMessageToChatMessage(message, workflow.id),
+          );
+        if (!serverMessages.length) return;
+        setActiveConvoId(
+          (current) =>
+            current ||
+            conversation.conversation_id ||
+            conversation.conversationId ||
+            null,
+        );
+        setMessages((previousMessages) => {
+          const hasLocalUserMessages = previousMessages.some(
+            (message) => message.role === "user",
+          );
+          if (hasLocalUserMessages) {
+            return reconcileProposalStatuses(previousMessages, serverMessages);
+          }
+          return reconcileProposalStatuses(serverMessages, serverMessages);
+        });
+      })
+      .catch((error) => {
+        logClientEvent("workflow_agent_chat_hydration_failed", {
+          level: "WARNING",
+          source: "chatbot",
+          message: error.message || "Could not hydrate workflow chat history.",
+          data: { workflowId: workflow.id },
+        });
+      });
     return () => {
       cancelled = true;
     };
-  }, []);
+  }, [workflow?.id]);
 
-  /* ── switch conversation ───────────────────────────────────────────────── */
-  const loadConversation = async (convoId) => {
-    if (convoId === activeConvoId) return;
-    setIsLoadingConvo(true);
-    try {
-      const convo = await getConversation(convoId);
-      if (!convo) return;
-      await clearChat(); // reset LangChain in-memory state
-      setActiveConvoId(convo.id);
-      const dbMessages =
-        convo.messages?.map((m) => ({ role: m.role, content: m.content })) ??
-        [];
-      setMessages([GREETING, ...dbMessages]);
-    } finally {
-      setIsLoadingConvo(false);
-    }
-  };
+  const sendWorkflowAgentMessage = useCallback(
+    async (
+      query,
+      {
+        displayQuery = query,
+        source = "chatbot",
+        hideGreetingActions = true,
+      } = {},
+    ) => {
+      if (!query.trim() || isSending) return false;
+      if (!workflowContext?.workflow?.id || !workflowContext?.queryAgent) {
+        return false;
+      }
 
-  /* ── new chat ──────────────────────────────────────────────────────────── */
-  const handleNewChat = async () => {
-    await clearChat();
-    setActiveConvoId(null);
-    setMessages([GREETING]);
-    setInputValue("");
-  };
+      const isGreeting = hideGreetingActions && isGreetingQuery(displayQuery);
+      const { agentQuery, commandAlias } = normalizeWorkflowAgentQuery(query);
+      setMessages((prev) => [...prev, { role: "user", content: displayQuery }]);
+      setIsSending(true);
+      try {
+        logClientEvent("workflow_agent_chat_sent", {
+          source,
+          message: "Workflow-agent chat query sent",
+          data: {
+            workflowId: workflowContext.workflow.id,
+            conversationId: activeConvoId,
+            queryPreview: displayQuery.slice(0, 160),
+            agentQueryPreview: agentQuery.slice(0, 160),
+            commandAlias,
+            queryLength: agentQuery.length,
+          },
+        });
+        const data = await workflowContext.queryAgent(
+          agentQuery,
+          activeConvoId,
+        );
+        const response =
+          data?.response ||
+          "I could not inspect the workflow state for that request.";
+        const returnedConvoId =
+          data?.conversationId ?? data?.conversation_id ?? activeConvoId;
+        setMessages((prev) => [
+          ...prev,
+          {
+            role: "assistant",
+            content: response,
+            source: data?.source || "workflow_orchestrator",
+            workflow_id: workflowContext.workflow.id,
+            actions: isGreeting ? [] : data?.actions || [],
+            commands: isGreeting ? [] : data?.commands || [],
+            proposals: isGreeting ? [] : data?.proposals || [],
+            trace: isGreeting ? [] : data?.trace || [],
+          },
+        ]);
+        if (!activeConvoId && returnedConvoId) {
+          setActiveConvoId(returnedConvoId);
+        }
+        logClientEvent("workflow_agent_chat_completed", {
+          source,
+          message: "Workflow-agent chat query completed",
+          data: {
+            workflowId: workflowContext.workflow.id,
+            conversationId: returnedConvoId,
+            responseSource: data?.source || "workflow_orchestrator",
+            intent: data?.intent || null,
+            commandAlias,
+            actionCount: data?.actions?.length || 0,
+            commandCount: data?.commands?.length || 0,
+            proposalCount: data?.proposals?.length || 0,
+            traceCount: data?.trace?.length || 0,
+          },
+        });
+        return true;
+      } catch (e) {
+        logClientEvent("chat_send_failed", {
+          level: "ERROR",
+          source,
+          message: e.message || "Error contacting chatbot.",
+          data: {
+            workflowId: workflowContext?.workflow?.id || null,
+            activeConvoId,
+            queryPreview: displayQuery.slice(0, 160),
+          },
+        });
+        setMessages((prev) => [
+          ...prev,
+          {
+            role: "assistant",
+            content: e.message || "Error contacting chatbot.",
+          },
+        ]);
+        return false;
+      } finally {
+        setIsSending(false);
+      }
+    },
+    [activeConvoId, isSending, workflowContext],
+  );
+
+  useEffect(() => {
+    if (!queuedWorkflowQuery?.id) return;
+    if (handledQueuedQueryRef.current === queuedWorkflowQuery.id) return;
+    if (isSending) return;
+
+    handledQueuedQueryRef.current = queuedWorkflowQuery.id;
+    onQueuedWorkflowQueryConsumed?.(queuedWorkflowQuery.id);
+    sendWorkflowAgentMessage(queuedWorkflowQuery.query || QUICK_NEXT_QUERY, {
+      displayQuery: queuedWorkflowQuery.displayText || QUICK_NEXT_QUERY,
+      source: queuedWorkflowQuery.source || "quick_next",
+      hideGreetingActions: false,
+    });
+  }, [
+    isSending,
+    onQueuedWorkflowQueryConsumed,
+    queuedWorkflowQuery,
+    sendWorkflowAgentMessage,
+  ]);
 
   /* ── send message ──────────────────────────────────────────────────────── */
   const handleSendMessage = async () => {
     if (!inputValue.trim() || isSending) return;
     const query = inputValue;
     setInputValue("");
-    setMessages((prev) => [...prev, { role: "user", content: query }]);
-    setIsSending(true);
     try {
       if (shouldUseWorkflowAgent(query)) {
-        const data = await workflowContext.queryAgent(query);
-        const response =
-          data?.response ||
-          "I could not inspect the workflow state for that request.";
-        setMessages((prev) => [
-          ...prev,
-          { role: "assistant", content: response },
-        ]);
+        await sendWorkflowAgentMessage(query);
         return;
       }
 
+      setMessages((prev) => [...prev, { role: "user", content: query }]);
+      setIsSending(true);
+      logClientEvent("llm_chat_sent", {
+        source: "chatbot",
+        message: "General assistant chat query sent",
+        data: {
+          workflowId: workflowContext?.workflow?.id || null,
+          conversationId: activeConvoId,
+          queryPreview: query.slice(0, 160),
+          queryLength: query.length,
+        },
+      });
       const data = await queryChatBot(query, activeConvoId);
-      const response =
-        data?.response || "Sorry, I could not generate a response.";
+      const response = normalizeAssistantContent(
+        data?.response || "Sorry, I could not generate a response.",
+      );
       const returnedConvoId = data?.conversationId ?? activeConvoId;
 
       setMessages((prev) => [
@@ -171,10 +894,26 @@ function Chatbot({ onClose }) {
         setActiveConvoId(returnedConvoId);
       }
 
-      // Refresh sidebar so the new / updated conversation appears
-      const convos = await listConversations();
-      if (convos) setConversations(convos);
+      logClientEvent("llm_chat_completed", {
+        source: "chatbot",
+        message: "General assistant chat query completed",
+        data: {
+          workflowId: workflowContext?.workflow?.id || null,
+          conversationId: returnedConvoId,
+          responseLength: response.length,
+        },
+      });
     } catch (e) {
+      logClientEvent("chat_send_failed", {
+        level: "ERROR",
+        source: "chatbot",
+        message: e.message || "Error contacting chatbot.",
+        data: {
+          workflowId: workflowContext?.workflow?.id || null,
+          activeConvoId,
+          queryPreview: query.slice(0, 160),
+        },
+      });
       setMessages((prev) => [
         ...prev,
         {
@@ -194,23 +933,220 @@ function Chatbot({ onClose }) {
     }
   };
 
-  /* ── delete conversation ───────────────────────────────────────────────── */
-  const handleDeleteConvo = async (convoId, e) => {
-    if (e) e.stopPropagation();
-    await deleteConversation(convoId);
-    setConversations((prev) => prev.filter((c) => c.id !== convoId));
-    if (activeConvoId === convoId) {
-      await handleNewChat();
+  const handleRunAssistantItem = async (item) => {
+    const itemId = item?.id || item?.title || item?.label || "assistant-item";
+    logClientEvent("assistant_item_run_started", {
+      source: "chatbot",
+      message: "Assistant in-app item run started",
+      data: {
+        workflowId: workflow?.id || null,
+        activeConvoId,
+        itemId,
+        itemLabel: item?.title || item?.label || null,
+        itemType: item?.command ? "command" : "action",
+        runtimeActionKind: item?.client_effects?.runtime_action?.kind || null,
+      },
+    });
+    try {
+      const runtimeKind = item?.client_effects?.runtime_action?.kind;
+      if (item?.requires_approval && workflowContext?.proposeAgentAction) {
+        const trainingFormReady =
+          runtimeKind === "start_training"
+            ? await populateTrainingReviewForm(item, itemId)
+            : true;
+        const proposal =
+          runtimeKind === "start_training"
+            ? await workflowContext.proposeAgentAction(
+                buildTrainingRunProposal(item),
+              )
+            : await workflowContext.proposeAgentAction(
+                buildClientEffectsProposal(item),
+              );
+        appendLocalProposalToLatestAssistant(proposal);
+        message.info(
+          runtimeKind === "start_training"
+            ? trainingFormReady
+              ? "I filled the training form. Review the run, then approve it to start."
+              : "I filled the training paths. Check the warning, then approve when it looks right."
+            : "Review the proposed app action, then approve it to run.",
+        );
+        logClientEvent("assistant_item_training_proposal_created", {
+          source: "chatbot",
+          message: "Assistant created approval-gated app proposal",
+          data: {
+            workflowId: workflow?.id || null,
+            activeConvoId,
+            itemId,
+            runtimeKind,
+            riskLevel: item?.risk_level || null,
+          },
+        });
+        return;
+      }
+      if (executeAssistantItem) {
+        await executeAssistantItem(item);
+        logClientEvent("assistant_item_run_completed", {
+          source: "chatbot",
+          message: "Assistant in-app item run completed",
+          data: { workflowId: workflow?.id || null, activeConvoId, itemId },
+        });
+        return;
+      }
+      if (!item?.client_effects || !runClientEffects) return;
+      await runClientEffects(item.client_effects);
+      logClientEvent("assistant_item_run_completed", {
+        source: "chatbot",
+        message: "Assistant in-app item run completed",
+        data: { workflowId: workflow?.id || null, activeConvoId, itemId },
+      });
+    } catch (error) {
+      logClientEvent("assistant_item_run_failed", {
+        level: "ERROR",
+        source: "chatbot",
+        message: error.message || "Assistant in-app item run failed",
+        data: { workflowId: workflow?.id || null, activeConvoId, itemId },
+      });
+      throw error;
     }
   };
 
+  const recreateProposalForCurrentWorkflow = useCallback(
+    async (proposal) => {
+      const request = proposalRequestFromEvent(proposal);
+      if (!request || !workflowContext?.proposeAgentAction) {
+        throw new Error("This proposal is stale and cannot be recreated.");
+      }
+      const nextProposal = await workflowContext.proposeAgentAction(request);
+      appendLocalProposalToLatestAssistant(nextProposal);
+      return nextProposal;
+    },
+    [appendLocalProposalToLatestAssistant, workflowContext],
+  );
+
+  const handleApproveProposal = useCallback(
+    async (proposal, overrides = {}) => {
+      if (!proposal?.id || !workflowContext?.approveAgentAction) return;
+      const activeWorkflowId = Number(workflowContext?.workflow?.id || 0);
+      const proposalWorkflowId = Number(
+        proposal.workflow_id || proposal.workflowId || 0,
+      );
+      const isStaleWorkflowProposal =
+        activeWorkflowId &&
+        proposalWorkflowId &&
+        activeWorkflowId !== proposalWorkflowId;
+      let approvalId = proposal.id;
+      let recreated = false;
+      const approvalOverrides =
+        overrides && Object.keys(overrides).length > 0 ? overrides : undefined;
+
+      try {
+        if (isStaleWorkflowProposal) {
+          const nextProposal =
+            await recreateProposalForCurrentWorkflow(proposal);
+          approvalId = nextProposal.id;
+          recreated = true;
+        }
+        if (approvalOverrides) {
+          await workflowContext.approveAgentAction(
+            approvalId,
+            approvalOverrides,
+          );
+        } else {
+          await workflowContext.approveAgentAction(approvalId);
+        }
+        updateLocalProposalStatus(approvalId, "approved");
+        if (recreated) {
+          updateLocalProposalStatus(proposal.id, "superseded");
+        }
+      } catch (error) {
+        if (!recreated && isProposalNotFoundError(error)) {
+          try {
+            const nextProposal =
+              await recreateProposalForCurrentWorkflow(proposal);
+            if (approvalOverrides) {
+              await workflowContext.approveAgentAction(
+                nextProposal.id,
+                approvalOverrides,
+              );
+            } else {
+              await workflowContext.approveAgentAction(nextProposal.id);
+            }
+            updateLocalProposalStatus(nextProposal.id, "approved");
+            updateLocalProposalStatus(proposal.id, "superseded");
+            message.info(
+              "That run card was stale, so I recreated it and approved the fresh one.",
+            );
+            return;
+          } catch (retryError) {
+            logClientEvent("assistant_proposal_recreate_failed", {
+              level: "ERROR",
+              source: "chatbot",
+              message:
+                retryError.message || "Failed to recreate stale proposal.",
+              data: {
+                workflowId: activeWorkflowId || null,
+                proposalId: proposal.id,
+                proposalWorkflowId: proposalWorkflowId || null,
+              },
+            });
+            message.error(
+              retryError.message || "Could not approve that proposal.",
+            );
+            return;
+          }
+        }
+        logClientEvent("assistant_proposal_approval_failed", {
+          level: "ERROR",
+          source: "chatbot",
+          message: error.message || "Failed to approve proposal.",
+          data: {
+            workflowId: activeWorkflowId || null,
+            proposalId: proposal.id,
+            proposalWorkflowId: proposalWorkflowId || null,
+          },
+        });
+        message.error(error.message || "Could not approve that proposal.");
+      }
+    },
+    [
+      recreateProposalForCurrentWorkflow,
+      updateLocalProposalStatus,
+      workflowContext,
+    ],
+  );
+
+  const handleRejectProposal = useCallback(
+    async (proposal) => {
+      if (!proposal?.id || !workflowContext?.rejectAgentAction) return;
+      try {
+        await workflowContext.rejectAgentAction(proposal.id);
+        updateLocalProposalStatus(proposal.id, "rejected");
+      } catch (error) {
+        message.error(error.message || "Could not reject that proposal.");
+      }
+    },
+    [updateLocalProposalStatus, workflowContext],
+  );
+
   /* ── markdown renderers ────────────────────────────────────────────────── */
   const mdComponents = {
+    p: ({ children }) => (
+      <p style={{ margin: "0 0 8px", lineHeight: 1.45 }}>{children}</p>
+    ),
+    h1: ({ children }) => (
+      <h3 style={{ margin: "10px 0 6px", fontSize: 16 }}>{children}</h3>
+    ),
+    h2: ({ children }) => (
+      <h3 style={{ margin: "10px 0 6px", fontSize: 15 }}>{children}</h3>
+    ),
+    h3: ({ children }) => (
+      <h4 style={{ margin: "8px 0 4px", fontSize: 14 }}>{children}</h4>
+    ),
     ul: ({ children }) => (
-      <ul style={{ paddingLeft: "20px", margin: "8px 0" }}>{children}</ul>
+      <ul style={{ paddingLeft: "18px", margin: "6px 0" }}>{children}</ul>
     ),
     ol: ({ children }) => (
-      <ol style={{ paddingLeft: "20px", margin: "8px 0" }}>{children}</ol>
+      <ol style={{ paddingLeft: "18px", margin: "6px 0" }}>{children}</ol>
     ),
     table: ({ children }) => (
       <div style={{ overflowX: "auto", margin: "8px 0" }}>
@@ -279,133 +1215,13 @@ function Chatbot({ onClose }) {
   /* RENDER                                                                 */
   /* ═══════════════════════════════════════════════════════════════════════ */
   return (
-    <div style={{ height: "100vh", display: "flex" }}>
-      {/* ── Sidebar ─────────────────────────────────────────────────────── */}
-      {sidebarOpen && (
-        <div
-          style={{
-            width: 220,
-            minWidth: 220,
-            borderRight: "1px solid #f0f0f0",
-            display: "flex",
-            flexDirection: "column",
-            background: "#fafafa",
-          }}
-        >
-          {/* header */}
-          <div
-            style={{
-              padding: "12px 10px 8px",
-              display: "flex",
-              alignItems: "center",
-              justifyContent: "space-between",
-            }}
-          >
-            <Text strong style={{ fontSize: 13 }}>
-              Chats
-            </Text>
-            <Space size={4}>
-              <Tooltip title="New chat">
-                <Button
-                  type="text"
-                  size="small"
-                  icon={<PlusOutlined />}
-                  onClick={handleNewChat}
-                />
-              </Tooltip>
-              <Tooltip title="Collapse sidebar">
-                <Button
-                  type="text"
-                  size="small"
-                  icon={<MenuFoldOutlined />}
-                  onClick={() => setSidebarOpen(false)}
-                />
-              </Tooltip>
-            </Space>
-          </div>
-
-          {/* conversation list */}
-          <div style={{ flex: 1, overflowY: "auto", padding: "0 6px 8px" }}>
-            {conversations.length === 0 && (
-              <Text
-                type="secondary"
-                style={{
-                  display: "block",
-                  textAlign: "center",
-                  padding: "24px 8px",
-                  fontSize: 12,
-                }}
-              >
-                No past chats yet
-              </Text>
-            )}
-            {conversations.map((c) => (
-              <div
-                key={c.id}
-                onClick={() => loadConversation(c.id)}
-                style={{
-                  padding: "8px",
-                  margin: "2px 0",
-                  borderRadius: 6,
-                  cursor: "pointer",
-                  display: "flex",
-                  alignItems: "center",
-                  gap: 8,
-                  background:
-                    c.id === activeConvoId ? "#e6f4ff" : "transparent",
-                  border:
-                    c.id === activeConvoId
-                      ? "1px solid #91caff"
-                      : "1px solid transparent",
-                  transition: "background 0.15s",
-                }}
-                onMouseEnter={(e) => {
-                  if (c.id !== activeConvoId)
-                    e.currentTarget.style.background = "#f0f0f0";
-                }}
-                onMouseLeave={(e) => {
-                  if (c.id !== activeConvoId)
-                    e.currentTarget.style.background = "transparent";
-                }}
-              >
-                <MessageOutlined
-                  style={{ fontSize: 13, color: "#999", flexShrink: 0 }}
-                />
-                <Text
-                  ellipsis
-                  style={{ flex: 1, fontSize: 13, lineHeight: "18px" }}
-                >
-                  {truncate(c.title)}
-                </Text>
-                <Popconfirm
-                  title="Delete this conversation?"
-                  onConfirm={(e) => handleDeleteConvo(c.id, e)}
-                  onCancel={(e) => e?.stopPropagation()}
-                  okText="Delete"
-                  cancelText="Cancel"
-                >
-                  <Button
-                    type="text"
-                    size="small"
-                    icon={<DeleteOutlined />}
-                    onClick={(e) => e.stopPropagation()}
-                    style={{
-                      flexShrink: 0,
-                      opacity: 0.4,
-                      transition: "opacity 0.15s",
-                    }}
-                    onMouseEnter={(e) => (e.currentTarget.style.opacity = "1")}
-                    onMouseLeave={(e) =>
-                      (e.currentTarget.style.opacity = "0.4")
-                    }
-                  />
-                </Popconfirm>
-              </div>
-            ))}
-          </div>
-        </div>
-      )}
-
+    <div
+      style={{
+        height: "100vh",
+        display: "flex",
+        background: "#f3f4f1",
+      }}
+    >
       {/* ── Main chat area ──────────────────────────────────────────────── */}
       <div
         style={{
@@ -418,104 +1234,252 @@ function Chatbot({ onClose }) {
         {/* header */}
         <div
           style={{
-            padding: "16px",
+            padding: "12px 14px",
             display: "flex",
             justifyContent: "space-between",
             alignItems: "center",
+            borderBottom: "1px solid #e5e7eb",
+            background: "#fafaf9",
           }}
         >
           <Space>
-            {!sidebarOpen && (
-              <Tooltip title="Show conversations">
-                <Button
-                  type="text"
-                  size="small"
-                  icon={<MenuUnfoldOutlined />}
-                  onClick={() => setSidebarOpen(true)}
-                />
-              </Tooltip>
-            )}
-            <Text strong>AI Assistant</Text>
+            <div>
+              <Text
+                strong
+                style={{
+                  color: "#111827",
+                  display: "block",
+                  fontFamily: MONO_FONT,
+                  letterSpacing: "0.02em",
+                }}
+              >
+                Project Manager
+              </Text>
+              <Text type="secondary" style={{ display: "block", fontSize: 12 }}>
+                Orchestrates specialist workflow agents
+              </Text>
+            </div>
+            <Tag color="#111827" style={{ marginInlineEnd: 0 }}>
+              Orchestrator
+            </Tag>
           </Space>
           <Space>
-            <Tooltip title="New chat">
-              <Button
-                type="text"
-                icon={<PlusOutlined />}
-                onClick={handleNewChat}
-                size="small"
-              />
-            </Tooltip>
             <Button
               type="text"
               icon={<CloseOutlined />}
               onClick={onClose}
               size="small"
+              aria-label="Close assistant"
             />
           </Space>
         </div>
 
-        <WorkflowTimeline />
-
         {/* messages */}
-        <div style={{ flex: 1, overflow: "auto", padding: "0 16px 16px" }}>
-          {isLoadingConvo ? (
-            <div style={{ textAlign: "center", padding: 40 }}>
-              <Spin />
-            </div>
-          ) : (
-            <List
-              dataSource={messages}
-              renderItem={(message, index) => {
-                const isLast = index === messages.length - 1;
-                const isUser = message.role === "user";
-                return (
-                  <List.Item
-                    ref={isLast ? lastMessageRef : null}
+        <div
+          style={{
+            flex: 1,
+            overflow: "auto",
+            padding: "14px",
+            background: "#f6f5f2",
+          }}
+        >
+          <List
+            dataSource={messages}
+            renderItem={(message, index) => {
+              const isLast = index === messages.length - 1;
+              const isUser = message.role === "user";
+              const consultedAgents = isUser ? [] : messageAgents(message);
+              return (
+                <List.Item
+                  ref={isLast ? lastMessageRef : null}
+                  style={{
+                    border: "none",
+                    padding: "10px 0",
+                    justifyContent: isUser ? "flex-end" : "flex-start",
+                  }}
+                >
+                  <div
                     style={{
-                      border: "none",
-                      padding: "8px 0",
-                      justifyContent: isUser ? "flex-end" : "flex-start",
+                      width: isUser ? "auto" : "min(100%, 760px)",
+                      maxWidth: isUser ? "78%" : "88%",
+                      padding: isUser ? "10px 12px" : "12px",
+                      borderRadius: isUser ? "14px 14px 4px 14px" : "14px",
+                      background: isUser
+                        ? "var(--seg-accent-primary, #3f37c9)"
+                        : "#ffffff",
+                      color: isUser ? "white" : "black",
+                      border: isUser ? "none" : "1px solid #e5e7eb",
+                      boxShadow: "0 1px 2px rgba(15, 23, 42, 0.05)",
                     }}
                   >
-                    <div
-                      style={{
-                        maxWidth: "80%",
-                        padding: "8px 12px",
-                        borderRadius: "12px",
-                        backgroundColor: isUser ? "#1890ff" : "#f5f5f5",
-                        color: isUser ? "white" : "black",
-                      }}
-                    >
-                      {isUser ? (
-                        <Text style={{ color: "white" }}>
-                          {message.content}
-                        </Text>
-                      ) : (
+                    {isUser ? (
+                      <Text style={{ color: "white" }}>{message.content}</Text>
+                    ) : (
+                      <Space
+                        direction="vertical"
+                        size={10}
+                        style={{ width: "100%" }}
+                      >
+                        {consultedAgents.length > 0 && (
+                          <div
+                            aria-label="Consulted workflow agents"
+                            style={{
+                              display: "flex",
+                              alignItems: "center",
+                              flexWrap: "wrap",
+                              gap: 6,
+                              marginBottom: 2,
+                            }}
+                          >
+                            <Text
+                              type="secondary"
+                              style={{
+                                fontSize: 11,
+                                lineHeight: "18px",
+                                fontFamily: MONO_FONT,
+                              }}
+                            >
+                              Agents
+                            </Text>
+                            {consultedAgents.map((agent) => (
+                              <AgentBadge
+                                key={agent.key}
+                                agent={agent}
+                                compact
+                              />
+                            ))}
+                          </div>
+                        )}
+                        {message.trace?.length > 0 && (
+                          <AssistantTrace trace={message.trace} />
+                        )}
                         <ReactMarkdown
                           remarkPlugins={[remarkGfm]}
                           components={mdComponents}
                         >
                           {message.content}
                         </ReactMarkdown>
-                      )}
-                    </div>
-                  </List.Item>
-                );
-              }}
-            />
-          )}
+                        {(message.actions?.length > 0 ||
+                          message.commands?.length > 0 ||
+                          message.proposals?.length > 0) && (
+                          <div
+                            style={{
+                              display: "grid",
+                              gap: 10,
+                              marginTop: 2,
+                            }}
+                          >
+                            {message.actions?.map((action) => (
+                              <AssistantActionCard
+                                key={action.id}
+                                action={action}
+                                onRun={handleRunAssistantItem}
+                              />
+                            ))}
+                            {message.commands?.map((command) => (
+                              <AssistantCommandCard
+                                key={command.id}
+                                command={command}
+                                onRun={handleRunAssistantItem}
+                              />
+                            ))}
+                            {message.proposals?.map((proposal) => {
+                              const payload = proposal?.payload || {};
+                              const params = payload?.params || {};
+                              const actionCard =
+                                params?.action_card ||
+                                payload?.action_card ||
+                                proposal?.action_card ||
+                                {};
+                              const actionTrace = toList(
+                                params?.trace ||
+                                  payload?.trace ||
+                                  proposal?.trace ||
+                                  actionCard?.trace,
+                              );
+                              const proposalTrace = toList(
+                                proposal.trace ||
+                                  payload?.trace ||
+                                  params?.trace,
+                              );
+                              const specialistAgent =
+                                params?.specialist_agent ||
+                                payload?.specialist_agent ||
+                                actionCard?.specialist_agent ||
+                                proposal?.specialist_agent;
+                              const orchestratorAgent =
+                                params?.orchestrator_agent ||
+                                payload?.orchestrator_agent ||
+                                actionCard?.orchestrator_agent ||
+                                proposal?.orchestrator_agent;
+                              const workflowId =
+                                proposal.workflow_id ||
+                                proposal.workflowId ||
+                                message.workflow_id;
+
+                              return (
+                                <AgentProposalCard
+                                  key={proposal.id}
+                                  proposal={{
+                                    ...(payload || {}),
+                                    ...(params || {}),
+                                    specialist_agent: specialistAgent,
+                                    orchestrator_agent: orchestratorAgent,
+                                    action_card: actionCard,
+                                    id: proposal.id,
+                                    workflow_id: workflowId,
+                                    approval_status: proposal.approval_status,
+                                    type:
+                                      payload.action ||
+                                      proposal.type ||
+                                      "agent_proposal",
+                                    rationale: proposal.summary,
+                                  }}
+                                  onApprove={(_cardProposal, overrides) =>
+                                    handleApproveProposal(
+                                      {
+                                        ...proposal,
+                                        workflow_id: workflowId,
+                                      },
+                                      overrides,
+                                    )
+                                  }
+                                  onReject={() =>
+                                    handleRejectProposal({
+                                      ...proposal,
+                                      workflow_id: workflowId,
+                                    })
+                                  }
+                                  trace={[...actionTrace, ...proposalTrace]}
+                                />
+                              );
+                            })}
+                          </div>
+                        )}
+                      </Space>
+                    )}
+                  </div>
+                </List.Item>
+              );
+            }}
+          />
           {isSending && <Spin size="small" />}
         </div>
 
         {/* input */}
-        <div style={{ padding: "16px" }}>
+        <div
+          style={{
+            padding: "12px 14px 14px",
+            borderTop: "1px solid #e5e7eb",
+            background: "#fafaf9",
+          }}
+        >
           <Space.Compact style={{ width: "100%" }}>
             <TextArea
               value={inputValue}
               onChange={(e) => setInputValue(e.target.value)}
               onKeyPress={handleKeyPress}
-              placeholder="Type your message..."
+              placeholder="Message"
               autoSize={{ minRows: 1, maxRows: 3 }}
             />
             <Button
diff --git a/client/src/components/Chatbot.test.js b/client/src/components/Chatbot.test.js
new file mode 100644
index 00000000..27a03715
--- /dev/null
+++ b/client/src/components/Chatbot.test.js
@@ -0,0 +1,1391 @@
+import React from "react";
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
+
+import Chatbot from "./Chatbot";
+import { WorkflowContext } from "../contexts/WorkflowContext";
+import { getWorkflowAgentConversation, queryChatBot } from "../api";
+
+jest.mock("../api", () => ({
+  getWorkflowAgentConversation: jest.fn().mockResolvedValue({ messages: [] }),
+  queryChatBot: jest.fn(),
+}));
+
+jest.mock("../logging/appEventLog", () => ({
+  logClientEvent: jest.fn(),
+}));
+
+jest.mock("react-markdown", () => {
+  const React = require("react");
+  return function ReactMarkdown({ children }) {
+    return React.createElement("div", null, children);
+  };
+});
+
+jest.mock("remark-gfm", () => () => {});
+
+function renderChatbot(workflowValue = {}, props = {}) {
+  window.matchMedia = jest.fn().mockImplementation((query) => ({
+    matches: false,
+    media: query,
+    onchange: null,
+    addListener: jest.fn(),
+    removeListener: jest.fn(),
+    addEventListener: jest.fn(),
+    removeEventListener: jest.fn(),
+    dispatchEvent: jest.fn(),
+  }));
+  window.HTMLElement.prototype.scrollIntoView = jest.fn();
+
+  const value = {
+    workflow: { id: 1, stage: "inference" },
+    queryAgent: jest.fn().mockResolvedValue({
+      response: "Do this: run the model.",
+      conversationId: 42,
+      source: "workflow_orchestrator",
+      actions: [],
+      commands: [],
+      proposals: [],
+    }),
+    ...workflowValue,
+  };
+
+  const renderResult = render(
+    <WorkflowContext.Provider value={value}>
+      <Chatbot onClose={jest.fn()} {...props} />
+    </WorkflowContext.Provider>,
+  );
+  return { ...value, ...renderResult };
+}
+
+describe("Chatbot workflow routing", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    window.sessionStorage.clear();
+    getWorkflowAgentConversation.mockResolvedValue({ messages: [] });
+    queryChatBot.mockResolvedValue({ response: "generic response" });
+  });
+
+  it("routes segmentation requests to the workflow agent instead of generic chat", async () => {
+    const workflow = renderChatbot();
+
+    fireEvent.change(screen.getByPlaceholderText("Message"), {
+      target: { value: "I want to get my volume segmented" },
+    });
+    fireEvent.keyPress(screen.getByPlaceholderText("Message"), {
+      key: "Enter",
+      code: "Enter",
+      charCode: 13,
+    });
+
+    await waitFor(() => {
+      expect(workflow.queryAgent).toHaveBeenCalledWith(
+        "I want to get my volume segmented",
+        null,
+      );
+    });
+    expect(queryChatBot).not.toHaveBeenCalled();
+    expect(await screen.findByText("Do this: run the model.")).toBeTruthy();
+  });
+
+  it("routes casual segmentation language to the workflow agent", async () => {
+    const workflow = renderChatbot();
+
+    fireEvent.change(screen.getByPlaceholderText("Message"), {
+      target: { value: "i wanna segment some dattaaaaaaaaaaa" },
+    });
+    fireEvent.keyPress(screen.getByPlaceholderText("Message"), {
+      key: "Enter",
+      code: "Enter",
+      charCode: 13,
+    });
+
+    await waitFor(() => {
+      expect(workflow.queryAgent).toHaveBeenCalledWith(
+        "i wanna segment some dattaaaaaaaaaaa",
+        null,
+      );
+    });
+    expect(queryChatBot).not.toHaveBeenCalled();
+  });
+
+  it("keeps one continuous workflow chat across drawer remounts", async () => {
+    const firstQueryAgent = jest.fn().mockResolvedValue({
+      response: "I found the current project state.",
+      conversationId: 77,
+      source: "workflow_orchestrator",
+      actions: [],
+      commands: [],
+      proposals: [],
+    });
+    const first = renderChatbot({ queryAgent: firstQueryAgent });
+
+    fireEvent.change(screen.getByPlaceholderText("Message"), {
+      target: { value: "what are we looking at?" },
+    });
+    fireEvent.keyPress(screen.getByPlaceholderText("Message"), {
+      key: "Enter",
+      code: "Enter",
+      charCode: 13,
+    });
+
+    expect(
+      await screen.findByText("I found the current project state."),
+    ).toBeTruthy();
+    first.unmount();
+
+    const secondQueryAgent = jest.fn().mockResolvedValue({
+      response: "Still on the same thread.",
+      conversationId: 77,
+      source: "workflow_orchestrator",
+      actions: [],
+      commands: [],
+      proposals: [],
+    });
+    renderChatbot({ queryAgent: secondQueryAgent });
+
+    expect(await screen.findByText("what are we looking at?")).toBeTruthy();
+    expect(
+      await screen.findByText("I found the current project state."),
+    ).toBeTruthy();
+
+    fireEvent.change(screen.getByPlaceholderText("Message"), {
+      target: { value: "again" },
+    });
+    fireEvent.keyPress(screen.getByPlaceholderText("Message"), {
+      key: "Enter",
+      code: "Enter",
+      charCode: 13,
+    });
+
+    await waitFor(() => {
+      expect(secondQueryAgent).toHaveBeenCalledWith("again", 77);
+    });
+  });
+
+  it("routes visualization requests to the workflow agent instead of generic chat", async () => {
+    const workflow = renderChatbot({
+      queryAgent: jest.fn().mockResolvedValue({
+        response: "Do this: view the current volume pair.",
+        conversationId: 46,
+        source: "workflow_orchestrator",
+        actions: [
+          {
+            id: "open-visualization",
+            label: "View data",
+            description: "Open the image and mask in the viewer.",
+            client_effects: { navigate_to: "visualization" },
+          },
+        ],
+        commands: [],
+        proposals: [],
+      }),
+    });
+
+    fireEvent.change(screen.getByPlaceholderText("Message"), {
+      target: { value: "can we visualize a volume pair?" },
+    });
+    fireEvent.keyPress(screen.getByPlaceholderText("Message"), {
+      key: "Enter",
+      code: "Enter",
+      charCode: 13,
+    });
+
+    await waitFor(() => {
+      expect(workflow.queryAgent).toHaveBeenCalledWith(
+        "can we visualize a volume pair?",
+        null,
+      );
+    });
+    expect(queryChatBot).not.toHaveBeenCalled();
+    expect(
+      await screen.findByText("Do this: view the current volume pair."),
+    ).toBeTruthy();
+    expect(screen.getAllByText("View data").length).toBeGreaterThan(0);
+  });
+
+  it("routes plain data-viewing requests to the workflow agent action cards", async () => {
+    const workflow = renderChatbot({
+      queryAgent: jest.fn().mockResolvedValue({
+        response: "Do this: view image with seg.",
+        conversationId: 53,
+        source: "workflow_orchestrator",
+        actions: [
+          {
+            id: "open-visualization",
+            label: "View data",
+            description: "Open the selected image and mask in the viewer.",
+            client_effects: {
+              navigate_to: "visualization",
+              set_current_image: "data/image/test_im.h5",
+              set_current_label: "data/seg/test_mito.h5",
+              set_visualization_scales: [1, 1, 1],
+              runtime_action: { kind: "load_visualization" },
+            },
+          },
+        ],
+        commands: [],
+        proposals: [],
+      }),
+    });
+
+    fireEvent.change(screen.getByPlaceholderText("Message"), {
+      target: { value: "can we view some data" },
+    });
+    fireEvent.keyPress(screen.getByPlaceholderText("Message"), {
+      key: "Enter",
+      code: "Enter",
+      charCode: 13,
+    });
+
+    await waitFor(() => {
+      expect(workflow.queryAgent).toHaveBeenCalledWith(
+        "can we view some data",
+        null,
+      );
+    });
+    expect(queryChatBot).not.toHaveBeenCalled();
+    expect(
+      await screen.findByText("Do this: view image with seg."),
+    ).toBeTruthy();
+    expect(screen.getAllByText("View data").length).toBeGreaterThan(0);
+    expect(screen.getByRole("button", { name: "Run in app" })).toBeTruthy();
+  });
+
+  it("shows expandable trace details for workflow-agent context checks", async () => {
+    const workflow = renderChatbot({
+      queryAgent: jest.fn().mockResolvedValue({
+        response: "I checked the mounted project.",
+        conversationId: 56,
+        source: "workflow_orchestrator",
+        actions: [],
+        commands: [],
+        proposals: [],
+        trace: [
+          {
+            label: "Checked project files",
+            detail: "Scanned prepilot_lucchi_pp; found 2 image/seg sets.",
+          },
+        ],
+      }),
+    });
+
+    fireEvent.change(screen.getByPlaceholderText("Message"), {
+      target: { value: "what files are here?" },
+    });
+    fireEvent.keyPress(screen.getByPlaceholderText("Message"), {
+      key: "Enter",
+      code: "Enter",
+      charCode: 13,
+    });
+
+    await waitFor(() => {
+      expect(workflow.queryAgent).toHaveBeenCalledWith(
+        "what files are here?",
+        null,
+      );
+    });
+    const traceToggle = await screen.findByRole("button", {
+      name: /Operational trace/,
+    });
+    fireEvent.click(traceToggle);
+    expect(
+      (await screen.findAllByText("Checked project files")).length,
+    ).toBeGreaterThan(0);
+    expect(
+      await screen.findByText(
+        "Scanned prepilot_lucchi_pp; found 2 image/seg sets.",
+      ),
+    ).toBeTruthy();
+  });
+
+  it("routes abbreviated visualization phrasing to the workflow agent", async () => {
+    const workflow = renderChatbot({
+      queryAgent: jest.fn().mockResolvedValue({
+        response: "Do this: view the mounted data.",
+        conversationId: 54,
+        source: "workflow_orchestrator",
+        actions: [
+          {
+            id: "open-visualization",
+            label: "View data",
+            description: "Open the selected image and mask in the viewer.",
+            client_effects: {
+              navigate_to: "visualization",
+              runtime_action: { kind: "load_visualization" },
+            },
+          },
+        ],
+        commands: [],
+        proposals: [],
+      }),
+    });
+
+    fireEvent.change(screen.getByPlaceholderText("Message"), {
+      target: { value: "can we vis some data" },
+    });
+    fireEvent.keyPress(screen.getByPlaceholderText("Message"), {
+      key: "Enter",
+      code: "Enter",
+      charCode: 13,
+    });
+
+    await waitFor(() => {
+      expect(workflow.queryAgent).toHaveBeenCalledWith(
+        "can we vis some data",
+        null,
+      );
+    });
+    expect(queryChatBot).not.toHaveBeenCalled();
+    expect(
+      await screen.findByText("Do this: view the mounted data."),
+    ).toBeTruthy();
+    expect(screen.getAllByText("View data").length).toBeGreaterThan(0);
+    expect(screen.getByRole("button", { name: "Run in app" })).toBeTruthy();
+  });
+
+  it("defaults readable active-workflow chat to the workflow agent", async () => {
+    const workflow = renderChatbot({
+      queryAgent: jest.fn().mockResolvedValue({
+        response: "Do this: inspect workflow status.",
+        conversationId: 55,
+        source: "workflow_orchestrator",
+        actions: [
+          {
+            id: "show-status",
+            label: "Show status",
+            description: "Open workflow status.",
+            client_effects: { show_workflow_context: true },
+          },
+        ],
+        commands: [],
+        proposals: [],
+      }),
+    });
+
+    fireEvent.change(screen.getByPlaceholderText("Message"), {
+      target: { value: "can you help me figure this out" },
+    });
+    fireEvent.keyPress(screen.getByPlaceholderText("Message"), {
+      key: "Enter",
+      code: "Enter",
+      charCode: 13,
+    });
+
+    await waitFor(() => {
+      expect(workflow.queryAgent).toHaveBeenCalledWith(
+        "can you help me figure this out",
+        null,
+      );
+    });
+    expect(queryChatBot).not.toHaveBeenCalled();
+    expect(
+      await screen.findByText("Do this: inspect workflow status."),
+    ).toBeTruthy();
+    expect(screen.getAllByText("Show status").length).toBeGreaterThan(0);
+  });
+
+  it("lets general conceptual questions use the regular chat path", async () => {
+    const workflow = renderChatbot();
+    queryChatBot.mockResolvedValueOnce({
+      response: "Binary cross entropy is a loss for binary labels.",
+      conversationId: 91,
+    });
+
+    fireEvent.change(screen.getByPlaceholderText("Message"), {
+      target: { value: "what is binary cross entropy?" },
+    });
+    fireEvent.keyPress(screen.getByPlaceholderText("Message"), {
+      key: "Enter",
+      code: "Enter",
+      charCode: 13,
+    });
+
+    await waitFor(() => {
+      expect(queryChatBot).toHaveBeenCalledWith(
+        "what is binary cross entropy?",
+        null,
+      );
+    });
+    expect(workflow.queryAgent).not.toHaveBeenCalled();
+    expect(
+      await screen.findByText(
+        "Binary cross entropy is a loss for binary labels.",
+      ),
+    ).toBeTruthy();
+  });
+
+  it("routes casual label viewing language to the workflow agent", async () => {
+    const workflow = renderChatbot();
+
+    fireEvent.change(screen.getByPlaceholderText("Message"), {
+      target: { value: "can i look at my labels real quick?" },
+    });
+    fireEvent.keyPress(screen.getByPlaceholderText("Message"), {
+      key: "Enter",
+      code: "Enter",
+      charCode: 13,
+    });
+
+    await waitFor(() => {
+      expect(workflow.queryAgent).toHaveBeenCalledWith(
+        "can i look at my labels real quick?",
+        null,
+      );
+    });
+    expect(queryChatBot).not.toHaveBeenCalled();
+  });
+
+  it("routes visualization scale corrections to the workflow agent", async () => {
+    const workflow = renderChatbot({
+      queryAgent: jest.fn().mockResolvedValue({
+        response: "Do this: reload the viewer with 1,1,1 nm voxel scales.",
+        conversationId: 48,
+        source: "workflow_orchestrator",
+        actions: [
+          {
+            id: "reload-visualization-scales",
+            label: "Reload viewer",
+            description: "Reload with updated scales.",
+            client_effects: {
+              navigate_to: "visualization",
+              set_visualization_scales: [1, 1, 1],
+              runtime_action: { kind: "load_visualization" },
+            },
+          },
+        ],
+        commands: [],
+        proposals: [],
+      }),
+    });
+
+    fireEvent.change(screen.getByPlaceholderText("Message"), {
+      target: { value: "the scales are off; reload with 1-1-1" },
+    });
+    fireEvent.keyPress(screen.getByPlaceholderText("Message"), {
+      key: "Enter",
+      code: "Enter",
+      charCode: 13,
+    });
+
+    await waitFor(() => {
+      expect(workflow.queryAgent).toHaveBeenCalledWith(
+        "the scales are off; reload with 1-1-1",
+        null,
+      );
+    });
+    expect(queryChatBot).not.toHaveBeenCalled();
+    expect(
+      await screen.findByText(
+        "Do this: reload the viewer with 1,1,1 nm voxel scales.",
+      ),
+    ).toBeTruthy();
+    expect(
+      (await screen.findAllByText("Reload viewer")).length,
+    ).toBeGreaterThan(0);
+  });
+
+  it("routes greetings to the workflow agent so internal LLM prompts cannot leak", async () => {
+    const workflow = renderChatbot({
+      queryAgent: jest.fn().mockResolvedValue({
+        response: "Hi. I can help with this segmentation loop.",
+        conversationId: 43,
+        source: "workflow_orchestrator",
+        actions: [
+          {
+            id: "start-proofreading",
+            label: "Proofread this data",
+            description: "Open proofreading.",
+            client_effects: {},
+          },
+        ],
+        commands: [
+          {
+            id: "start-proofreading-command",
+            title: "Proofread this data",
+            description: "Open proofreading.",
+            command: "app proofreading start",
+            client_effects: {},
+          },
+        ],
+        proposals: [],
+      }),
+    });
+
+    fireEvent.change(screen.getByPlaceholderText("Message"), {
+      target: { value: "hi!" },
+    });
+    fireEvent.keyPress(screen.getByPlaceholderText("Message"), {
+      key: "Enter",
+      code: "Enter",
+      charCode: 13,
+    });
+
+    await waitFor(() => {
+      expect(workflow.queryAgent).toHaveBeenCalledWith("hi!", null);
+    });
+    expect(queryChatBot).not.toHaveBeenCalled();
+    expect(
+      await screen.findByText("Hi. I can help with this segmentation loop."),
+    ).toBeTruthy();
+    expect(screen.queryByText("Proofread this data")).toBeNull();
+  });
+
+  it("keeps workflow slash commands in chat history while routing them to the orchestrator", async () => {
+    const workflow = renderChatbot();
+
+    fireEvent.change(screen.getByPlaceholderText("Message"), {
+      target: { value: "/infer" },
+    });
+    fireEvent.keyPress(screen.getByPlaceholderText("Message"), {
+      key: "Enter",
+      code: "Enter",
+      charCode: 13,
+    });
+
+    await waitFor(() => {
+      expect(workflow.queryAgent).toHaveBeenCalledWith("run model", null);
+    });
+    expect(queryChatBot).not.toHaveBeenCalled();
+  });
+
+  it("runs a queued quick next-step request through the workflow agent", async () => {
+    const workflow = renderChatbot(
+      {
+        queryAgent: jest.fn().mockResolvedValue({
+          response: "Do this: add a checkpoint or mask/label.",
+          conversationId: 45,
+          source: "workflow_orchestrator",
+          actions: [
+            {
+              id: "open-files",
+              label: "Choose data",
+              description: "Pick data.",
+              client_effects: { navigate_to: "files" },
+            },
+          ],
+          commands: [],
+          proposals: [],
+        }),
+      },
+      {
+        queuedWorkflowQuery: {
+          id: 1,
+          query: "What should I do next?",
+          displayText: "What should I do next?",
+          source: "quick_next",
+        },
+      },
+    );
+
+    await waitFor(() => {
+      expect(workflow.queryAgent).toHaveBeenCalledWith(
+        "What should I do next?",
+        null,
+      );
+    });
+    expect(queryChatBot).not.toHaveBeenCalled();
+    expect(await screen.findByText("What should I do next?")).toBeTruthy();
+    expect(
+      await screen.findByText("Do this: add a checkpoint or mask/label."),
+    ).toBeTruthy();
+    expect((await screen.findAllByText("Choose data")).length).toBeGreaterThan(
+      0,
+    );
+  });
+
+  it("keeps workflow follow-up questions with the orchestrator after a workflow answer", async () => {
+    const workflow = renderChatbot({
+      queryAgent: jest
+        .fn()
+        .mockResolvedValueOnce({
+          response:
+            "Do this: Proofread this data. Watch out: Run inference only after checking the pair.",
+          conversationId: 51,
+          source: "workflow_orchestrator",
+          actions: [],
+          commands: [],
+          proposals: [],
+        })
+        .mockResolvedValueOnce({
+          response: "Do this: open the current image and mask pair first.",
+          conversationId: 51,
+          source: "workflow_orchestrator",
+          actions: [
+            {
+              id: "open-visualization",
+              label: "Show data",
+              description: "Open the current pair.",
+              client_effects: { navigate_to: "visualization" },
+            },
+          ],
+          commands: [],
+          proposals: [],
+        }),
+    });
+
+    fireEvent.change(screen.getByPlaceholderText("Message"), {
+      target: { value: "what should I do?" },
+    });
+    fireEvent.keyPress(screen.getByPlaceholderText("Message"), {
+      key: "Enter",
+      code: "Enter",
+      charCode: 13,
+    });
+
+    expect(
+      await screen.findByText(
+        "Do this: Proofread this data. Watch out: Run inference only after checking the pair.",
+      ),
+    ).toBeTruthy();
+
+    fireEvent.change(screen.getByPlaceholderText("Message"), {
+      target: { value: "can we take a look at it first?" },
+    });
+    fireEvent.keyPress(screen.getByPlaceholderText("Message"), {
+      key: "Enter",
+      code: "Enter",
+      charCode: 13,
+    });
+
+    await waitFor(() => {
+      expect(workflow.queryAgent).toHaveBeenLastCalledWith(
+        "can we take a look at it first?",
+        51,
+      );
+    });
+    expect(queryChatBot).not.toHaveBeenCalled();
+    expect(
+      await screen.findByText(
+        "Do this: open the current image and mask pair first.",
+      ),
+    ).toBeTruthy();
+    expect(screen.getAllByText("Show data").length).toBeGreaterThan(0);
+  });
+
+  it("routes short clarification follow-ups to the orchestrator after a workflow answer", async () => {
+    const workflow = renderChatbot({
+      queryAgent: jest
+        .fn()
+        .mockResolvedValueOnce({
+          response: "Do this: show status before starting another action.",
+          conversationId: 52,
+          source: "workflow_orchestrator",
+          actions: [],
+          commands: [],
+          proposals: [],
+        })
+        .mockResolvedValueOnce({
+          response: "I mean the workflow evidence and readiness status.",
+          conversationId: 52,
+          source: "workflow_orchestrator",
+          actions: [],
+          commands: [],
+          proposals: [],
+        }),
+    });
+
+    fireEvent.change(screen.getByPlaceholderText("Message"), {
+      target: { value: "what should I do?" },
+    });
+    fireEvent.keyPress(screen.getByPlaceholderText("Message"), {
+      key: "Enter",
+      code: "Enter",
+      charCode: 13,
+    });
+
+    expect(
+      await screen.findByText(
+        "Do this: show status before starting another action.",
+      ),
+    ).toBeTruthy();
+
+    fireEvent.change(screen.getByPlaceholderText("Message"), {
+      target: { value: "what?" },
+    });
+    fireEvent.keyPress(screen.getByPlaceholderText("Message"), {
+      key: "Enter",
+      code: "Enter",
+      charCode: 13,
+    });
+
+    await waitFor(() => {
+      expect(workflow.queryAgent).toHaveBeenLastCalledWith("what?", 52);
+    });
+    expect(queryChatBot).not.toHaveBeenCalled();
+    expect(
+      await screen.findByText(
+        "I mean the workflow evidence and readiness status.",
+      ),
+    ).toBeTruthy();
+  });
+
+  it("routes unrelated ambiguous text through the general assistant", async () => {
+    const workflow = renderChatbot({
+      queryAgent: jest.fn().mockResolvedValue({
+        response:
+          "I am not sure which app step that maps to. Current next step: Proofread this data.",
+        conversationId: 44,
+        source: "workflow_orchestrator",
+        actions: [],
+        commands: [],
+        proposals: [],
+      }),
+    });
+
+    fireEvent.change(screen.getByPlaceholderText("Message"), {
+      target: { value: "mmajkf,ansdjs" },
+    });
+    fireEvent.keyPress(screen.getByPlaceholderText("Message"), {
+      key: "Enter",
+      code: "Enter",
+      charCode: 13,
+    });
+
+    await waitFor(() => {
+      expect(queryChatBot).toHaveBeenCalledWith("mmajkf,ansdjs", null);
+    });
+    expect(workflow.queryAgent).not.toHaveBeenCalled();
+    expect(await screen.findByText("generic response")).toBeTruthy();
+  });
+
+  it("does not render raw JSON tool calls from the general assistant", async () => {
+    renderChatbot({ workflow: null, queryAgent: null });
+    queryChatBot.mockResolvedValue({
+      response:
+        '{"name": "visualize_volume_pair", "parameters": {"query": "volume pair visualization"}}',
+      conversationId: 47,
+    });
+
+    fireEvent.change(screen.getByPlaceholderText("Message"), {
+      target: { value: "can we visualize a volume pair?" },
+    });
+    fireEvent.keyPress(screen.getByPlaceholderText("Message"), {
+      key: "Enter",
+      code: "Enter",
+      charCode: 13,
+    });
+
+    await waitFor(() => {
+      expect(queryChatBot).toHaveBeenCalledWith(
+        "can we visualize a volume pair?",
+        null,
+      );
+    });
+    expect(screen.queryByText(/"visualize_volume_pair"/)).toBeNull();
+    expect(
+      await screen.findByText(/I should not have shown that internal command/),
+    ).toBeTruthy();
+  });
+
+  it("does not render embedded JSON tool calls from the general assistant", async () => {
+    renderChatbot({ workflow: null, queryAgent: null });
+    queryChatBot.mockResolvedValue({
+      response:
+        'Here is the revised function call in JSON format:\n{"name":"search_documentation","parameters":{"query":"train"}}',
+      conversationId: 49,
+    });
+
+    fireEvent.change(screen.getByPlaceholderText("Message"), {
+      target: { value: "how do i tune this" },
+    });
+    fireEvent.keyPress(screen.getByPlaceholderText("Message"), {
+      key: "Enter",
+      code: "Enter",
+      charCode: 13,
+    });
+
+    await waitFor(() => {
+      expect(queryChatBot).toHaveBeenCalledWith("how do i tune this", null);
+    });
+    expect(screen.queryByText(/search_documentation/)).toBeNull();
+    expect(
+      await screen.findByText(/I should not have shown that internal command/),
+    ).toBeTruthy();
+  });
+
+  it("does not expose saved chat history controls in the workflow assistant", () => {
+    renderChatbot();
+
+    expect(screen.queryByLabelText("Show conversations")).toBeNull();
+    expect(screen.queryByLabelText("New chat")).toBeNull();
+  });
+
+  it("restores the continuous workflow chat from session storage", async () => {
+    window.sessionStorage.setItem(
+      "pytc.workflowAssistant.continuousChat.v1",
+      JSON.stringify({
+        activeConvoId: 8,
+        messages: [
+          { role: "user", content: "proofread this" },
+          {
+            role: "assistant",
+            content: "Do this: proofread this data.",
+            source: "workflow_orchestrator",
+            actions: [
+              {
+                id: "start-proofreading",
+                label: "Proofread this data",
+                description: "Open proofreading.",
+                client_effects: {},
+              },
+            ],
+            commands: [],
+            proposals: [],
+          },
+        ],
+      }),
+    );
+    renderChatbot();
+
+    expect(
+      await screen.findByText("Do this: proofread this data."),
+    ).toBeTruthy();
+    expect(screen.getAllByText("Proofread this data").length).toBeGreaterThan(
+      0,
+    );
+    expect(screen.getByRole("button", { name: "Run in app" })).toBeTruthy();
+  });
+
+  it("reconciles persisted proposal statuses with the latest server conversation", async () => {
+    window.sessionStorage.setItem(
+      "pytc.workflowAssistant.continuousChat.v1",
+      JSON.stringify({
+        activeConvoId: 8,
+        messages: [
+          {
+            role: "user",
+            content: "train this dataset",
+          },
+          {
+            role: "assistant",
+            content: "Review this run.",
+            source: "workflow_orchestrator",
+            workflow_id: 2,
+            proposals: [
+              {
+                id: 201,
+                summary: "Approve training run.",
+                approval_status: "pending",
+                payload: {
+                  action: "start_training_run",
+                  params: {
+                    config_preset: "/project/config.yaml",
+                    image_path: "/project/image",
+                    label_path: "/project/label",
+                    output_path: "/project/out",
+                  },
+                },
+              },
+            ],
+          },
+        ],
+      }),
+    );
+    const queryResult = {
+      response: "I checked the conversation state.",
+      conversationId: 8,
+      source: "workflow_orchestrator",
+      proposals: [
+        {
+          id: 201,
+          summary: "Approve training run.",
+          approval_status: "approved",
+          payload: {
+            action: "start_training_run",
+            params: {
+              config_preset: "/project/config.yaml",
+              image_path: "/project/image",
+              label_path: "/project/label",
+              output_path: "/project/out",
+            },
+          },
+        },
+      ],
+      actions: [],
+      commands: [],
+    };
+    getWorkflowAgentConversation.mockResolvedValue({
+      conversation_id: 8,
+      messages: [
+        {
+          role: "assistant",
+          content: "Review this run.",
+          source: "workflow_orchestrator",
+          workflow_id: 2,
+          proposals: [
+            {
+              id: 201,
+              summary: "Approve training run.",
+              approval_status: "approved",
+              payload: {
+                action: "start_training_run",
+                params: {
+                  config_preset: "/project/config.yaml",
+                  image_path: "/project/image",
+                  label_path: "/project/label",
+                  output_path: "/project/out",
+                },
+              },
+            },
+          ],
+        },
+      ],
+    });
+    renderChatbot({
+      workflow: { id: 2, stage: "setup" },
+      queryAgent: jest.fn().mockResolvedValue(queryResult),
+    });
+
+    expect(await screen.findByText("Review this run.")).toBeTruthy();
+    await waitFor(() => {
+      expect(getWorkflowAgentConversation).toHaveBeenCalledWith(2);
+    });
+    const approveButton = screen.getByRole("button", { name: "Approve" });
+    expect(approveButton.disabled).toBe(true);
+  });
+
+  it("displays specialist agent badges for persisted proposal metadata", async () => {
+    window.sessionStorage.setItem(
+      "pytc.workflowAssistant.continuousChat.v1",
+      JSON.stringify({
+        activeConvoId: 12,
+        messages: [
+          {
+            role: "assistant",
+            content: "Review this action.",
+            source: "workflow_orchestrator",
+            workflow_id: 44,
+            proposals: [
+              {
+                id: 901,
+                summary: "Approve app action.",
+                payload: {
+                  action: "run_client_effects",
+                  params: {
+                    item_label: "Run inference",
+                  },
+                },
+                specialist_agent: {
+                  agent_label: "Inference Specialist",
+                  agent_short_label: "INFER",
+                  agent_color: "#123abc",
+                  agent_icon_key: "eye",
+                  agent_border_style: "dashed",
+                },
+              },
+            ],
+          },
+        ],
+      }),
+    );
+
+    renderChatbot({
+      workflow: { id: 44, stage: "inference" },
+    });
+
+    expect(await screen.findByText("Review this action.")).toBeTruthy();
+    expect(screen.getByText("INFER")).toBeTruthy();
+  });
+
+  it("proposes approval before running risky non-training app actions", async () => {
+    const proposeAgentAction = jest.fn().mockResolvedValue({
+      id: 88,
+      summary: "Approve app action: Run model.",
+      payload: {
+        action: "run_client_effects",
+        params: { item_label: "Run model" },
+      },
+    });
+    const executeAssistantItem = jest.fn();
+    const workflow = renderChatbot({
+      proposeAgentAction,
+      executeAssistantItem,
+      queryAgent: jest.fn().mockResolvedValue({
+        response: "Do this: run inference.",
+        conversationId: 50,
+        source: "workflow_orchestrator",
+        actions: [
+          {
+            id: "run-inference",
+            label: "Run model",
+            description: "Run inference with the selected inputs.",
+            requires_approval: true,
+            risk_level: "runs_job",
+            client_effects: {
+              navigate_to: "inference",
+              set_inference_output_path: "/tmp/out",
+              runtime_action: { kind: "start_inference" },
+            },
+          },
+        ],
+        commands: [],
+        proposals: [],
+      }),
+    });
+
+    fireEvent.change(screen.getByPlaceholderText("Message"), {
+      target: { value: "run inference" },
+    });
+    fireEvent.keyPress(screen.getByPlaceholderText("Message"), {
+      key: "Enter",
+      code: "Enter",
+      charCode: 13,
+    });
+
+    await waitFor(() => {
+      expect(workflow.queryAgent).toHaveBeenCalledWith("run inference", null);
+    });
+    fireEvent.click(await screen.findByRole("button", { name: "Run in app" }));
+
+    await waitFor(() => {
+      expect(proposeAgentAction).toHaveBeenCalledWith(
+        expect.objectContaining({
+          action: "run_client_effects",
+          payload: expect.objectContaining({
+            item_id: "run-inference",
+            item_label: "Run model",
+            item_type: "action",
+            risk_level: "runs_job",
+            runtime_action: { kind: "start_inference" },
+            client_effects: expect.objectContaining({
+              set_inference_output_path: "/tmp/out",
+            }),
+          }),
+        }),
+      );
+    });
+    expect(executeAssistantItem).not.toHaveBeenCalled();
+  });
+
+  it("populates the training review form before creating the approval card", async () => {
+    const callOrder = [];
+    const runClientEffects = jest.fn().mockImplementation(async () => {
+      callOrder.push("form");
+    });
+    const proposeAgentAction = jest.fn().mockImplementation(async () => {
+      callOrder.push("proposal");
+      return {
+        id: 89,
+        summary: "Approve training run.",
+        payload: {
+          action: "start_training_run",
+          params: { item_label: "Train model" },
+        },
+      };
+    });
+    const workflow = renderChatbot({
+      runClientEffects,
+      proposeAgentAction,
+      queryAgent: jest.fn().mockResolvedValue({
+        response: "I staged a clean training run. Review the run card.",
+        conversationId: 51,
+        source: "workflow_orchestrator",
+        actions: [
+          {
+            id: "start-training",
+            label: "Train model",
+            description: "Start training with the approved volume subset.",
+            requires_approval: true,
+            risk_level: "runs_job",
+            run_label: "Review run",
+            client_effects: {
+              navigate_to: "training",
+              set_training_config_preset: "/project/config.yaml",
+              set_training_image_path: "/project/subset/image",
+              set_training_label_path: "/project/subset/seg",
+              set_training_output_path: "/project/output",
+              set_training_log_path: "/project/log.txt",
+              runtime_action: {
+                kind: "start_training",
+                autopick_parameters: true,
+                parameter_mode: "agent_default",
+              },
+            },
+          },
+        ],
+        commands: [],
+        proposals: [],
+      }),
+    });
+
+    fireEvent.change(screen.getByPlaceholderText("Message"), {
+      target: { value: "train on the good ground truth" },
+    });
+    fireEvent.keyPress(screen.getByPlaceholderText("Message"), {
+      key: "Enter",
+      code: "Enter",
+      charCode: 13,
+    });
+
+    await waitFor(() => {
+      expect(workflow.queryAgent).toHaveBeenCalledWith(
+        "train on the good ground truth",
+        null,
+      );
+    });
+    fireEvent.click(await screen.findByRole("button", { name: "Review run" }));
+
+    await waitFor(() => {
+      expect(proposeAgentAction).toHaveBeenCalled();
+    });
+    expect(callOrder).toEqual(["form", "proposal"]);
+    expect(runClientEffects).toHaveBeenCalledWith({
+      navigate_to: "training",
+      set_training_config_preset: "/project/config.yaml",
+      set_training_image_path: "/project/subset/image",
+      set_training_label_path: "/project/subset/seg",
+      set_training_output_path: "/project/output",
+      set_training_log_path: "/project/log.txt",
+    });
+    expect(proposeAgentAction).toHaveBeenCalledWith(
+      expect.objectContaining({
+        action: "start_training_run",
+        payload: expect.objectContaining({
+          config_preset: "/project/config.yaml",
+          image_path: "/project/subset/image",
+          label_path: "/project/subset/seg",
+          output_path: "/project/output",
+          autopick_parameters: true,
+        }),
+      }),
+    );
+  });
+
+  it("shows operational proposal trace sections for approval cards", async () => {
+    const workflow = renderChatbot({
+      queryAgent: jest.fn().mockResolvedValue({
+        response: "I drafted an execution proposal.",
+        conversationId: 57,
+        source: "workflow_orchestrator",
+        actions: [],
+        commands: [],
+        proposals: [
+          {
+            id: 77,
+            summary: "Approve proposed action.",
+            payload: {
+              action: "run_client_effects",
+              params: {
+                item_label: "Run model",
+                action_card: {
+                  trace: [
+                    {
+                      label: "Checked inputs",
+                      detail: "Model checkpoint and image pair resolved.",
+                      status: "checked",
+                      category: "checked",
+                    },
+                  ],
+                  requires_approval: true,
+                  risk_level: "runs_job",
+                  approval_reason: "Model inference is expensive.",
+                  input_artifacts: [{ path: "/project/images/input.tif" }],
+                  output_artifacts: [{ path: "/project/results/output.tif" }],
+                  project_memory_update: { stage: "inference" },
+                },
+              },
+            },
+          },
+        ],
+      }),
+    });
+
+    fireEvent.change(screen.getByPlaceholderText("Message"), {
+      target: { value: "run inference for review" },
+    });
+    fireEvent.keyPress(screen.getByPlaceholderText("Message"), {
+      key: "Enter",
+      code: "Enter",
+      charCode: 13,
+    });
+
+    await waitFor(() => {
+      expect(workflow.queryAgent).toHaveBeenCalledWith(
+        "run inference for review",
+        null,
+      );
+    });
+    expect(await screen.findByRole("button", { name: "Approve" })).toBeTruthy();
+
+    const traceToggle = await screen.findByRole("button", {
+      name: /Operational trace/,
+    });
+    fireEvent.click(traceToggle);
+    expect(await screen.findByText("Inspected facts")).toBeTruthy();
+    expect(await screen.findByText(/Checked inputs/)).toBeTruthy();
+    expect(await screen.findByText(/Risk level: runs_job/)).toBeTruthy();
+    expect(
+      await screen.findByText(
+        /(Input · path: \/project\/images\/input\.tif)|(Input · artifact: \/project\/images\/input\.tif)/,
+      ),
+    ).toBeTruthy();
+    expect(
+      await screen.findByText(
+        /(Output · path: \/project\/results\/output\.tif)|(Output · artifact: \/project\/results\/output\.tif)/,
+      ),
+    ).toBeTruthy();
+  });
+
+  it("recreates a missing persisted proposal before approving it", async () => {
+    const approveAgentAction = jest
+      .fn()
+      .mockRejectedValueOnce(new Error("404: Agent proposal not found"))
+      .mockResolvedValueOnce({});
+    const freshProposal = {
+      id: 335,
+      summary: "Approve training run.",
+      payload: {
+        action: "start_training_run",
+        params: {
+          config_preset: "/project/config.yaml",
+          image_path: "/project/subset/image",
+          label_path: "/project/subset/seg",
+          output_path: "/project/output",
+        },
+      },
+    };
+    const proposeAgentAction = jest.fn().mockResolvedValue(freshProposal);
+    window.sessionStorage.setItem(
+      "pytc.workflowAssistant.continuousChat.v1",
+      JSON.stringify({
+        activeConvoId: 10,
+        messages: [
+          {
+            role: "assistant",
+            content: "Review this run.",
+            source: "workflow_orchestrator",
+            workflow_id: 112,
+            proposals: [
+              {
+                id: 334,
+                summary: "Approve training run.",
+                payload: {
+                  action: "start_training_run",
+                  params: {
+                    config_preset: "/project/config.yaml",
+                    image_path: "/project/subset/image",
+                    label_path: "/project/subset/seg",
+                    output_path: "/project/output",
+                  },
+                },
+              },
+            ],
+          },
+        ],
+      }),
+    );
+
+    renderChatbot({
+      workflow: { id: 112, stage: "setup" },
+      approveAgentAction,
+      proposeAgentAction,
+    });
+
+    expect(await screen.findByText("Review this run.")).toBeTruthy();
+
+    fireEvent.click(screen.getByRole("button", { name: "Approve" }));
+
+    await waitFor(() => {
+      expect(approveAgentAction).toHaveBeenNthCalledWith(1, 334);
+      expect(proposeAgentAction).toHaveBeenCalledWith({
+        action: "start_training_run",
+        summary: "Approve training run.",
+        payload: {
+          config_preset: "/project/config.yaml",
+          image_path: "/project/subset/image",
+          label_path: "/project/subset/seg",
+          output_path: "/project/output",
+        },
+      });
+      expect(approveAgentAction).toHaveBeenNthCalledWith(2, 335);
+    });
+  });
+
+  it("removes stale workflow action cards from the continuous chat", async () => {
+    window.sessionStorage.setItem(
+      "pytc.workflowAssistant.continuousChat.v1",
+      JSON.stringify({
+        activeConvoId: 9,
+        messages: [
+          {
+            role: "assistant",
+            content: "This message came from another workflow.",
+            source: "workflow_orchestrator",
+            workflow_id: 999,
+            actions: [
+              {
+                id: "stale-action",
+                label: "Stale action",
+                description: "Should not be runnable here.",
+                client_effects: { navigate_to: "training" },
+              },
+            ],
+            commands: [
+              {
+                id: "stale-command",
+                title: "Stale command",
+                description: "Should not be runnable here.",
+                command: "app training start",
+                client_effects: { navigate_to: "training" },
+              },
+            ],
+            proposals: [
+              {
+                id: 100,
+                summary: "Stale approval.",
+                payload: {
+                  action: "run_client_effects",
+                  params: { item_label: "Stale action" },
+                },
+              },
+            ],
+          },
+        ],
+      }),
+    );
+    renderChatbot({ workflow: { id: 1, stage: "setup" } });
+
+    expect(
+      await screen.findByText("This message came from another workflow."),
+    ).toBeTruthy();
+    expect(screen.queryByText("Stale action")).toBeNull();
+    expect(screen.queryByText("Stale command")).toBeNull();
+    expect(screen.queryByRole("button", { name: "Run in app" })).toBeNull();
+    expect(screen.queryByRole("button", { name: "Execute" })).toBeNull();
+    expect(screen.queryByRole("button", { name: "Approve" })).toBeNull();
+  });
+
+  it("explains when a stale reviewed run card was removed", async () => {
+    window.sessionStorage.setItem(
+      "pytc.workflowAssistant.continuousChat.v1",
+      JSON.stringify({
+        activeConvoId: 9,
+        messages: [
+          {
+            role: "assistant",
+            content:
+              "I staged that run. Review the run card before launching it.",
+            source: "workflow_orchestrator",
+            workflow_id: 999,
+            actions: [
+              {
+                id: "start-training",
+                label: "Train model",
+                run_label: "Review run",
+                client_effects: { navigate_to: "training" },
+              },
+            ],
+            commands: [],
+            proposals: [],
+          },
+        ],
+      }),
+    );
+    renderChatbot({ workflow: { id: 1, stage: "setup" } });
+
+    expect(await screen.findByText(/Review the run card/)).toBeTruthy();
+    expect(await screen.findByText(/That run card belonged/)).toBeTruthy();
+    expect(screen.queryByText("Train model")).toBeNull();
+    expect(screen.queryByRole("button", { name: "Review run" })).toBeNull();
+  });
+});
diff --git a/client/src/components/Configurator.js b/client/src/components/Configurator.js
index ed503d54..4eb11d9a 100644
--- a/client/src/components/Configurator.js
+++ b/client/src/components/Configurator.js
@@ -1,4 +1,3 @@
-// global localStorage
 import React, { useContext, useEffect, useMemo, useState } from "react";
 import { Alert, Button, message, Steps, theme } from "antd";
 import YamlFileUploader from "./YamlFileUploader";
@@ -13,7 +12,6 @@ function Configurator(props) {
     type === "training" ? context.trainingState : context.inferenceState;
   const [current, setCurrent] = useState(0);
   const [hasAttemptedAdvance, setHasAttemptedAdvance] = useState(false);
-  const storageKey = `configStep:${type}`;
 
   const next = () => {
     if (missingByStep.length > 0) {
@@ -80,18 +78,9 @@ function Configurator(props) {
   }, [current, missingInputs, missingBase]);
 
   useEffect(() => {
-    const stored = localStorage.getItem(storageKey);
-    if (stored !== null) {
-      const parsed = Number(stored);
-      if (!Number.isNaN(parsed) && parsed >= 0 && parsed <= 2) {
-        setCurrent(parsed);
-      }
-    }
-  }, [storageKey]);
-
-  useEffect(() => {
-    localStorage.setItem(storageKey, String(current));
-  }, [current, storageKey]);
+    setCurrent(0);
+    setHasAttemptedAdvance(false);
+  }, [type]);
 
   const items = [
     {
diff --git a/client/src/components/FilePickerModal.js b/client/src/components/FilePickerModal.js
index c7739888..0ffa724d 100644
--- a/client/src/components/FilePickerModal.js
+++ b/client/src/components/FilePickerModal.js
@@ -1,5 +1,5 @@
-import React, { useState, useEffect } from "react";
-import { Modal, List, Breadcrumb, Button, Spin, message } from "antd";
+import React, { useState, useEffect, useMemo } from "react";
+import { Modal, List, Breadcrumb, Button, Spin, message, Progress } from "antd";
 import {
   FolderFilled,
   FileOutlined,
@@ -11,6 +11,7 @@ import { apiClient } from "../api";
 const HIDDEN_SYSTEM_FILES = new Set([
   "workflow_preference.json",
   ".pytc_proofreading.json",
+  ".pytc_instance_labels.tif",
   ".ds_store",
   "thumbs.db",
 ]);
@@ -23,6 +24,16 @@ const IMAGE_EXTENSIONS = new Set([
   ".tif",
   ".tiff",
   ".webp",
+  ".h5",
+  ".hdf5",
+  ".npy",
+  ".npz",
+  ".zarr",
+  ".n5",
+  ".nii",
+  ".nii.gz",
+  ".mrc",
+  ".mrcs",
 ]);
 
 const FilePickerModal = ({
@@ -37,16 +48,28 @@ const FilePickerModal = ({
   const [loading, setLoading] = useState(false);
   const [previewStatus, setPreviewStatus] = useState({});
   const [onlyImages, setOnlyImages] = useState(false);
+  const [uploading, setUploading] = useState(false);
+  const [uploadProgress, setUploadProgress] = useState(null);
   const previewBaseUrl = apiClient.defaults.baseURL || "http://localhost:4242";
 
   // Refactored fetch to get all files once
   const [allData, setAllData] = useState([]);
+  const folderById = useMemo(() => {
+    const map = new Map();
+    allData.forEach((item) => {
+      if (item?.is_folder) {
+        map.set(String(item.id), item);
+      }
+    });
+    return map;
+  }, [allData]);
 
   useEffect(() => {
     if (visible) {
       setCurrentPath("root");
       setOnlyImages(false);
       setPreviewStatus({});
+      setUploadProgress(null);
       loadAllData();
     }
   }, [visible]);
@@ -86,7 +109,7 @@ const FilePickerModal = ({
 
   const getParentPath = () => {
     if (currentPath === "root") return null;
-    const currentFolderObj = allData.find((f) => String(f.id) === currentPath);
+    const currentFolderObj = folderById.get(String(currentPath));
     return currentFolderObj ? currentFolderObj.path || "root" : "root";
   };
 
@@ -99,7 +122,7 @@ const FilePickerModal = ({
     const parts = [];
     let curr = currentPath;
     while (curr && curr !== "root") {
-      const folder = allData.find((f) => String(f.id) === curr);
+      const folder = folderById.get(String(curr));
       if (folder) {
         parts.unshift({ id: String(folder.id), name: folder.name });
         curr = folder.path;
@@ -121,7 +144,7 @@ const FilePickerModal = ({
     // Safety break to prevent infinite loops
     let attempts = 0;
     while (currParentId && currParentId !== "root" && attempts < 100) {
-      const parent = allData.find((f) => String(f.id) === currParentId);
+      const parent = folderById.get(String(currParentId));
       if (parent) {
         parts.unshift(parent.name);
         currParentId = parent.path;
@@ -147,6 +170,7 @@ const FilePickerModal = ({
   };
 
   const handleUploadFromLocal = () => {
+    if (uploading) return;
     const input = document.createElement("input");
     input.type = "file";
     input.multiple = true;
@@ -154,25 +178,70 @@ const FilePickerModal = ({
       const selectedFiles = Array.from(event.target.files || []);
       if (!selectedFiles.length) return;
       let uploaded = 0;
-      for (const file of selectedFiles) {
-        const form = new FormData();
-        form.append("file", file);
-        form.append("path", currentPath);
-        try {
-          await apiClient.post("/files/upload", form, {
-            headers: { "Content-Type": "multipart/form-data" },
+      let uploadedBytes = 0;
+      const totalBytes = selectedFiles.reduce(
+        (sum, file) => sum + (file.size || 0),
+        0,
+      );
+
+      setUploading(true);
+      try {
+        for (const [index, file] of selectedFiles.entries()) {
+          const form = new FormData();
+          form.append("file", file);
+          form.append("path", currentPath);
+          const bytesBeforeFile = uploadedBytes;
+          setUploadProgress({
+            currentFile: file.name,
+            index: index + 1,
+            total: selectedFiles.length,
+            percent: totalBytes
+              ? Math.round((bytesBeforeFile / totalBytes) * 100)
+              : 0,
           });
-          uploaded += 1;
-        } catch (error) {
-          console.error("Failed to upload file from picker:", error);
-          message.error(`Failed to upload ${file.name}`);
+          try {
+            await apiClient.post("/files/upload", form, {
+              headers: { "Content-Type": "multipart/form-data" },
+              onUploadProgress: (progressEvent) => {
+                const loadedForFile = Math.min(
+                  progressEvent.loaded || 0,
+                  file.size || progressEvent.loaded || 0,
+                );
+                const percent = totalBytes
+                  ? Math.min(
+                      99,
+                      Math.round(
+                        ((bytesBeforeFile + loadedForFile) / totalBytes) * 100,
+                      ),
+                    )
+                  : 0;
+                setUploadProgress({
+                  currentFile: file.name,
+                  index: index + 1,
+                  total: selectedFiles.length,
+                  percent,
+                });
+              },
+            });
+            uploaded += 1;
+            uploadedBytes += file.size || 0;
+          } catch (error) {
+            console.error("Failed to upload file from picker:", error);
+            message.error(`Failed to upload ${file.name}`);
+          }
         }
-      }
-      if (uploaded > 0) {
-        message.success(
-          `Uploaded ${uploaded} file${uploaded > 1 ? "s" : ""} to this folder`,
+        setUploadProgress((current) =>
+          current ? { ...current, percent: 100 } : current,
         );
-        await loadAllData();
+        if (uploaded > 0) {
+          message.success(
+            `Uploaded ${uploaded} file${uploaded > 1 ? "s" : ""} to this folder`,
+          );
+          await loadAllData();
+        }
+      } finally {
+        setUploading(false);
+        setTimeout(() => setUploadProgress(null), 900);
       }
     };
     input.click();
@@ -181,10 +250,9 @@ const FilePickerModal = ({
   const isImageFile = (item) => {
     if (!item || item.is_folder) return false;
     if (item.type && item.type.startsWith("image/")) return true;
-    const ext = `.${String(item.name || "")
-      .split(".")
-      .pop()}`.toLowerCase();
-    return IMAGE_EXTENSIONS.has(ext);
+    const name = String(item.name || "").toLowerCase();
+    const ext = `.${name.split(".").pop()}`;
+    return IMAGE_EXTENSIONS.has(ext) || name.endsWith(".nii.gz");
   };
 
   const getPreviewUrl = (item) => `${previewBaseUrl}/files/preview/${item.id}`;
@@ -214,8 +282,12 @@ const FilePickerModal = ({
             <Button onClick={onCancel} style={{ marginRight: 8 }}>
               Cancel
             </Button>
-            <Button type="primary" onClick={handleSelectCurrentDirectory}>
-              Select Current Directory
+            <Button
+              type="primary"
+              onClick={handleSelectCurrentDirectory}
+              disabled={uploading}
+            >
+              Use Current Folder
             </Button>
           </div>
         ) : null
@@ -240,25 +312,65 @@ const FilePickerModal = ({
         <Breadcrumb>
           {getBreadcrumbs().map((b) => (
             <Breadcrumb.Item key={b.id}>
-              <a onClick={() => setCurrentPath(b.id)}>{b.name}</a>
+              <Button
+                type="link"
+                size="small"
+                onClick={() => setCurrentPath(b.id)}
+                style={{ padding: 0 }}
+              >
+                {b.name}
+              </Button>
             </Breadcrumb.Item>
           ))}
         </Breadcrumb>
         <Button
           icon={<UploadOutlined />}
           onClick={handleUploadFromLocal}
+          disabled={uploading}
           style={{ marginLeft: "auto" }}
         >
-          Upload from Local
+          {uploading ? "Uploading..." : "Upload from Local"}
         </Button>
         <Button
           type={onlyImages ? "primary" : "default"}
           onClick={() => setOnlyImages((prev) => !prev)}
           style={{ marginLeft: 8 }}
         >
-          Images Only
+          Volume files
         </Button>
       </div>
+      {uploadProgress && (
+        <div
+          style={{
+            padding: "10px 16px",
+            borderBottom: "1px solid #f0f0f0",
+            background: "#fbfbfa",
+          }}
+        >
+          <div
+            style={{
+              display: "flex",
+              justifyContent: "space-between",
+              gap: 12,
+              fontSize: 12,
+              color: "#6b7280",
+              marginBottom: 4,
+            }}
+          >
+            <span>
+              Uploading {uploadProgress.index}/{uploadProgress.total}:{" "}
+              {uploadProgress.currentFile}
+            </span>
+            <span>{uploadProgress.percent}%</span>
+          </div>
+          <Progress
+            percent={uploadProgress.percent}
+            size="small"
+            status={uploadProgress.percent >= 100 ? "success" : "active"}
+            showInfo={false}
+          />
+        </div>
+      )}
 
       <div style={{ height: "400px", overflow: "auto" }}>
         {loading ? (
@@ -289,6 +401,18 @@ const FilePickerModal = ({
                   }
                 }}
                 actions={[
+                  item.is_folder && (
+                    <Button
+                      type="link"
+                      size="small"
+                      onClick={(e) => {
+                        e.stopPropagation();
+                        setCurrentPath(String(item.id));
+                      }}
+                    >
+                      Open
+                    </Button>
+                  ),
                   (selectionType === "file" ||
                     selectionType === "fileOrDirectory") &&
                     !item.is_folder && (
@@ -301,7 +425,7 @@ const FilePickerModal = ({
                           onSelect({ ...item, logical_path: fullPath });
                         }}
                       >
-                        Select
+                        Select file
                       </Button>
                     ),
                   (selectionType === "directory" ||
@@ -316,7 +440,7 @@ const FilePickerModal = ({
                           onSelect({ ...item, logical_path: fullPath });
                         }}
                       >
-                        Select
+                        Use folder
                       </Button>
                     ),
                 ]}
@@ -325,7 +449,10 @@ const FilePickerModal = ({
                   avatar={
                     item.is_folder ? (
                       <FolderFilled
-                        style={{ color: "#1890ff", fontSize: "20px" }}
+                        style={{
+                          color: "var(--seg-accent-primary, #3f37c9)",
+                          fontSize: "20px",
+                        }}
                       />
                     ) : isImageFile(item) ? (
                       <div
@@ -381,9 +508,11 @@ const FilePickerModal = ({
                               padding: "2px 6px",
                               fontSize: 10,
                               borderRadius: 10,
-                              background: "#f0f5ff",
-                              color: "#2f54eb",
-                              border: "1px solid #adc6ff",
+                              background:
+                                "var(--seg-accent-primary-soft, #f0efff)",
+                              color: "var(--seg-accent-primary, #3f37c9)",
+                              border:
+                                "1px solid var(--seg-accent-primary-border, #c7c2ff)",
                             }}
                           >
                             Mounted
diff --git a/client/src/components/InlineHelpChat.js b/client/src/components/InlineHelpChat.js
index ba0b6ca2..2afc0e38 100644
--- a/client/src/components/InlineHelpChat.js
+++ b/client/src/components/InlineHelpChat.js
@@ -1,7 +1,12 @@
 import React, { useEffect, useMemo, useRef, useState } from "react";
 import ReactDOM from "react-dom";
 import { Button, Input, Space, Spin, Typography } from "antd";
-import { QuestionCircleOutlined, SendOutlined } from "@ant-design/icons";
+import {
+  ArrowsAltOutlined,
+  QuestionCircleOutlined,
+  SendOutlined,
+  ShrinkOutlined,
+} from "@ant-design/icons";
 import ReactMarkdown from "react-markdown";
 import remarkGfm from "remark-gfm";
 import { queryHelperChat } from "../api";
@@ -21,7 +26,7 @@ const buildInitialPrompt = ({
   taskContext,
 }) => {
   return [
-    `Explain this setting and recommend a concrete value if possible:`,
+    `Give concise help for this setting:`,
     `- Label: ${label}`,
     yamlKey ? `- YAML key: ${yamlKey}` : null,
     value !== undefined && value !== null && value !== ""
@@ -29,7 +34,7 @@ const buildInitialPrompt = ({
       : null,
     projectContext ? `- Project context: ${projectContext}` : null,
     taskContext ? `- Task context: ${taskContext}` : null,
-    `Use plain language for non-technical users and give a recommended setting.`,
+    `Answer in at most 3 short bullets. Put the recommended action first. Do not paste documentation excerpts or headings.`,
   ]
     .filter(Boolean)
     .join("\n");
@@ -60,20 +65,28 @@ function InlineHelpChat({
 }) {
   const anchorRef = useRef(null);
   const panelRef = useRef(null);
+  const savedPanelPosRef = useRef(null);
   const dragState = useRef({ dragging: false, offsetX: 0, offsetY: 0 });
+  const resizeState = useRef({
+    resizing: false,
+    startX: 0,
+    startY: 0,
+    width: 430,
+    height: 340,
+  });
   const messagesEndRef = useRef(null);
 
   const [open, setOpen] = useState(false);
   const [messages, setMessages] = useState([]);
   const [inputValue, setInputValue] = useState("");
   const [isSending, setIsSending] = useState(false);
+  const [expanded, setExpanded] = useState(false);
   const [panelPos, setPanelPos] = useState({
     top: 0,
     left: 0,
-    width: 360,
-    height: 300,
+    width: 430,
+    height: 340,
   });
-  const [anchorPoint, setAnchorPoint] = useState({ x: 0, y: 0 });
 
   const initialPrompt = useMemo(
     () =>
@@ -117,6 +130,10 @@ function InlineHelpChat({
         helperTaskKey,
         text,
         fieldContext,
+        messages.slice(-8).map((message) => ({
+          role: message.isUser ? "user" : "assistant",
+          content: message.text,
+        })),
       );
       setMessages((prev) => [
         ...prev,
@@ -142,14 +159,10 @@ function InlineHelpChat({
   const openPanel = () => {
     if (!anchorRef.current) return;
     const rect = anchorRef.current.getBoundingClientRect();
-    const anchor = {
-      x: rect.left + rect.width / 2,
-      y: rect.top + rect.height / 2,
-    };
     const viewportW = window.innerWidth;
     const viewportH = window.innerHeight;
-    const width = panelPos.width || 360;
-    const height = panelPos.height || 300;
+    const width = panelPos.width || 430;
+    const height = panelPos.height || 340;
 
     // Prefer placing panel to the right of the "?" icon
     let left = rect.right + 12;
@@ -165,7 +178,6 @@ function InlineHelpChat({
     }
     if (top < 16) top = 16;
 
-    setAnchorPoint(anchor);
     setPanelPos((prev) => ({ ...prev, top, left }));
     setOpen(true);
 
@@ -187,6 +199,36 @@ function InlineHelpChat({
   useEffect(() => {
     if (!open) return;
     const onMove = (event) => {
+      if (resizeState.current.resizing) {
+        const viewportMaxWidth = Math.max(
+          340,
+          window.innerWidth - panelPos.left - 8,
+        );
+        const viewportMaxHeight = Math.max(
+          280,
+          window.innerHeight - panelPos.top - 8,
+        );
+        const nextWidth = clamp(
+          resizeState.current.width +
+            event.clientX -
+            resizeState.current.startX,
+          340,
+          viewportMaxWidth,
+        );
+        const nextHeight = clamp(
+          resizeState.current.height +
+            event.clientY -
+            resizeState.current.startY,
+          280,
+          viewportMaxHeight,
+        );
+        setPanelPos((prev) => ({
+          ...prev,
+          width: nextWidth,
+          height: nextHeight,
+        }));
+        return;
+      }
       if (!dragState.current.dragging) return;
       const nextLeft = clamp(
         event.clientX - dragState.current.offsetX,
@@ -202,6 +244,7 @@ function InlineHelpChat({
     };
     const onUp = () => {
       dragState.current.dragging = false;
+      resizeState.current.resizing = false;
     };
     window.addEventListener("mousemove", onMove);
     window.addEventListener("mouseup", onUp);
@@ -209,78 +252,83 @@ function InlineHelpChat({
       window.removeEventListener("mousemove", onMove);
       window.removeEventListener("mouseup", onUp);
     };
-  }, [open, panelPos.width, panelPos.height]);
+  }, [open, panelPos.height, panelPos.left, panelPos.top, panelPos.width]);
 
   const startDrag = (event) => {
     if (!panelRef.current) return;
+    if (expanded) return;
     dragState.current.dragging = true;
     dragState.current.offsetX = event.clientX - panelPos.left;
     dragState.current.offsetY = event.clientY - panelPos.top;
   };
 
-  // Track panel resize via CSS resize: both
-  const handlePanelMouseUp = () => {
-    const newRect = panelRef.current?.getBoundingClientRect();
-    if (newRect) {
-      setPanelPos((prev) => ({
-        ...prev,
-        width: newRect.width,
-        height: newRect.height,
-      }));
+  const startResize = (event) => {
+    if (expanded) return;
+    event.preventDefault();
+    event.stopPropagation();
+    resizeState.current = {
+      resizing: true,
+      startX: event.clientX,
+      startY: event.clientY,
+      width: panelPos.width,
+      height: panelPos.height,
+    };
+  };
+
+  const toggleExpanded = () => {
+    if (expanded) {
+      setExpanded(false);
+      if (savedPanelPosRef.current) {
+        setPanelPos(savedPanelPosRef.current);
+      }
+      return;
     }
+    savedPanelPosRef.current = panelPos;
+    setExpanded(true);
   };
 
+  const resolvedPanelStyle = expanded
+    ? {
+        top: 24,
+        left: 24,
+        width: "calc(100vw - 48px)",
+        height: "calc(100vh - 48px)",
+      }
+    : {
+        top: panelPos.top,
+        left: panelPos.left,
+        width: panelPos.width,
+        height: panelPos.height,
+      };
+
   // ------- Render the floating panel via portal -------
   const panel = open ? (
     <>
-      {/* SVG tether line from "?" icon to the panel */}
-      <svg
-        style={{
-          position: "fixed",
-          top: 0,
-          left: 0,
-          width: "100vw",
-          height: "100vh",
-          pointerEvents: "none",
-          zIndex: 1000,
-        }}
-      >
-        <line
-          x1={anchorPoint.x}
-          y1={anchorPoint.y}
-          x2={panelPos.left}
-          y2={panelPos.top}
-          stroke="#bfbfbf"
-          strokeDasharray="4 4"
-        />
-      </svg>
-
       {/* The floating panel */}
       <div
         ref={panelRef}
         style={{
           position: "fixed",
-          top: panelPos.top,
-          left: panelPos.left,
-          width: panelPos.width,
-          height: panelPos.height,
+          ...resolvedPanelStyle,
+          minWidth: 340,
+          minHeight: 280,
+          maxWidth: "calc(100vw - 16px)",
+          maxHeight: "calc(100vh - 16px)",
           zIndex: 1001,
           background: "#fff",
-          border: "1px dashed #d9d9d9",
-          borderRadius: 12,
-          boxShadow: "0 12px 28px rgba(0,0,0,0.12)",
+          border: "1px solid #e5e7eb",
+          borderRadius: 10,
+          boxShadow: "0 10px 24px rgba(15, 23, 42, 0.14)",
           display: "flex",
           flexDirection: "column",
-          resize: "both",
-          overflow: "auto",
+          overflow: "hidden",
         }}
-        onMouseUp={handlePanelMouseUp}
       >
         {/* Draggable header */}
         <div
           onMouseDown={startDrag}
           style={{
-            cursor: "move",
+            cursor: expanded ? "default" : "move",
             padding: "8px 12px",
             borderBottom: "1px solid #f0f0f0",
             fontWeight: 600,
@@ -291,10 +339,25 @@ function InlineHelpChat({
             userSelect: "none",
           }}
         >
-          <span>{label}</span>
-          <Button type="text" size="small" onClick={() => setOpen(false)}>
-            Close
-          </Button>
+          <span>Help: {label}</span>
+          <Space size={4}>
+            <Button
+              type="text"
+              size="small"
+              icon={expanded ? <ShrinkOutlined /> : <ArrowsAltOutlined />}
+              onMouseDown={(event) => event.stopPropagation()}
+              onClick={toggleExpanded}
+              aria-label={expanded ? "Restore helper size" : "Expand helper"}
+            />
+            <Button
+              type="text"
+              size="small"
+              onMouseDown={(event) => event.stopPropagation()}
+              onClick={() => setOpen(false)}
+            >
+              Close
+            </Button>
+          </Space>
         </div>
 
         {/* Messages area */}
@@ -312,7 +375,9 @@ function InlineHelpChat({
                 marginBottom: 8,
                 padding: "8px 10px",
                 borderRadius: 10,
-                background: msg.isUser ? "#e6f7ff" : "#fafafa",
+                background: msg.isUser
+                  ? "var(--seg-accent-primary-soft, #f0efff)"
+                  : "#fafafa",
               }}
             >
               {msg.isUser ? (
@@ -426,7 +491,12 @@ function InlineHelpChat({
         </div>
 
         {/* Input area */}
-        <div style={{ padding: "8px 12px", borderTop: "1px solid #f0f0f0" }}>
+        <div
+          style={{
+            padding: "8px 34px 8px 12px",
+            borderTop: "1px solid #f0f0f0",
+          }}
+        >
           <Space.Compact style={{ width: "100%" }}>
             <TextArea
               value={inputValue}
@@ -448,6 +518,44 @@ function InlineHelpChat({
             />
           </Space.Compact>
         </div>
+        <button
+          type="button"
+          aria-label={expanded ? "Restore helper size" : "Resize helper"}
+          title="Drag to resize. Double-click to expand or restore."
+          onMouseDown={startResize}
+          onDoubleClick={toggleExpanded}
+          style={{
+            position: "absolute",
+            right: 0,
+            bottom: 0,
+            width: 34,
+            height: 34,
+            border: 0,
+            padding: 0,
+            zIndex: 4,
+            background:
+              "linear-gradient(135deg, transparent 0 46%, rgba(248, 250, 252, 0.96) 47% 100%)",
+            cursor: expanded ? "zoom-out" : "nwse-resize",
+          }}
+        >
+          {[0, 1, 2].map((index) => (
+            <span
+              key={index}
+              aria-hidden="true"
+              style={{
+                position: "absolute",
+                right: 7 + index * 5,
+                bottom: 6,
+                width: 2,
+                height: 18 - index * 5,
+                borderRadius: 1,
+                background: index === 0 ? "#4b5563" : "#9ca3af",
+                transform: "rotate(45deg)",
+                transformOrigin: "bottom center",
+              }}
+            />
+          ))}
+        </button>
       </div>
     </>
   ) : null;
@@ -460,6 +568,7 @@ function InlineHelpChat({
         size="small"
         icon={<QuestionCircleOutlined />}
         onClick={() => (open ? setOpen(false) : openPanel())}
+        aria-label={`Help for ${label}`}
         style={{ color: "#8c8c8c" }}
       />
       {open ? ReactDOM.createPortal(panel, document.body) : null}
diff --git a/client/src/components/RuntimeLogPanel.js b/client/src/components/RuntimeLogPanel.js
index 9a938a7e..c2f833c8 100644
--- a/client/src/components/RuntimeLogPanel.js
+++ b/client/src/components/RuntimeLogPanel.js
@@ -1,5 +1,5 @@
-import React from "react";
-import { Alert, Button, Space, Tag, Typography, message } from "antd";
+import React, { useEffect, useMemo, useRef, useState } from "react";
+import { Alert, Button, Space, Tag, Tooltip, Typography, message } from "antd";
 
 const phaseColors = {
   idle: "default",
@@ -17,10 +17,105 @@ function formatValue(value) {
   return String(value);
 }
 
+const ERROR_PATTERNS = [
+  { label: "Python error", regex: /traceback|exception|runtimeerror/i },
+  { label: "missing file", regex: /no such file|not found|does not exist/i },
+  { label: "memory error", regex: /out of memory|cuda.*memory|mps.*memory/i },
+  { label: "failed step", regex: /failed|error/i },
+];
+
+function countMatches(text, regex) {
+  return (text.match(regex) || []).length;
+}
+
+function summarizeRuntime(runtime, text) {
+  const phase = runtime?.phase || "idle";
+  const exitCode = runtime?.exitCode;
+  const numericExitCode = Number(exitCode);
+  const hasNonZeroExit =
+    exitCode !== null &&
+    exitCode !== undefined &&
+    exitCode !== "" &&
+    Number.isFinite(numericExitCode) &&
+    numericExitCode !== 0;
+  const firstError = ERROR_PATTERNS.find((item) => item.regex.test(text || ""));
+  const warningCount = countMatches(text || "", /\bwarning\b/gi);
+
+  if (phase === "running" || phase === "starting") {
+    return {
+      type: "info",
+      label: phase === "starting" ? "Starting" : "Running",
+      message:
+        "The run is active. You do not need to read the log unless it fails.",
+    };
+  }
+
+  if (phase === "finished" && !hasNonZeroExit && !firstError) {
+    return {
+      type: warningCount ? "warning" : "success",
+      label: warningCount ? "Completed with warnings" : "Completed",
+      message: warningCount
+        ? `${warningCount} warning${warningCount === 1 ? "" : "s"} found. Outputs may still be usable.`
+        : "Run completed successfully.",
+    };
+  }
+
+  if (phase === "failed" || hasNonZeroExit || firstError) {
+    return {
+      type: "error",
+      label: "Needs attention",
+      message: firstError
+        ? `${firstError.label} detected. Open the log if you need details.`
+        : "The run exited with an error.",
+    };
+  }
+
+  if (phase === "stopped") {
+    return {
+      type: "warning",
+      label: "Stopped",
+      message: "The run was stopped before completion.",
+    };
+  }
+
+  return {
+    type: "info",
+    label: "Idle",
+    message: "No run is active.",
+  };
+}
+
 function RuntimeLogPanel({ title, runtime, onRefresh }) {
   const text = runtime?.text || "";
   const phase = runtime?.phase || "idle";
   const metadata = runtime?.metadata || {};
+  const [showDetails, setShowDetails] = useState(false);
+  const [showLog, setShowLog] = useState(false);
+  const previousPhaseRef = useRef(phase);
+  const hasObservedRuntimeRef = useRef(false);
+  const summary = useMemo(
+    () => summarizeRuntime(runtime, text),
+    [runtime, text],
+  );
+
+  useEffect(() => {
+    if (!hasObservedRuntimeRef.current) {
+      hasObservedRuntimeRef.current = true;
+      previousPhaseRef.current = phase;
+      return;
+    }
+    const previousPhase = previousPhaseRef.current;
+    if (previousPhase !== phase) {
+      if (phase === "finished" && summary.type === "success") {
+        message.success(`${title} completed.`);
+      } else if (phase === "finished" && summary.type === "warning") {
+        message.warning(`${title} completed with warnings.`);
+      } else if (phase === "failed" || summary.type === "error") {
+        message.error(`${title} needs attention.`);
+      }
+    }
+    previousPhaseRef.current = phase;
+  }, [phase, summary.type, title]);
 
   const handleCopy = async () => {
     try {
@@ -54,19 +149,28 @@ function RuntimeLogPanel({ title, runtime, onRefresh }) {
         }}
       >
         <Space wrap size={8}>
-          <Typography.Text strong>{title}</Typography.Text>
+          <Tooltip
+            title={`PID ${formatValue(runtime?.pid)} · Exit ${formatValue(runtime?.exitCode)} · Lines ${formatValue(runtime?.lineCount)}`}
+          >
+            <Typography.Text strong>{title}</Typography.Text>
+          </Tooltip>
           <Tag color={phaseColors[phase] || "default"}>{phase}</Tag>
-          <Typography.Text type="secondary">
-            PID {formatValue(runtime?.pid)}
-          </Typography.Text>
-          <Typography.Text type="secondary">
-            Exit {formatValue(runtime?.exitCode)}
-          </Typography.Text>
-          <Typography.Text type="secondary">
-            Lines {formatValue(runtime?.lineCount)}
-          </Typography.Text>
         </Space>
         <Space wrap size={8}>
+          <Button
+            size="small"
+            type="text"
+            onClick={() => setShowDetails((value) => !value)}
+          >
+            {showDetails ? "Hide details" : "Details"}
+          </Button>
+          <Button
+            size="small"
+            type={showLog ? "default" : "text"}
+            onClick={() => setShowLog((value) => !value)}
+          >
+            {showLog ? "Hide log" : "Show log"}
+          </Button>
           <Button size="small" onClick={onRefresh}>
             Refresh
           </Button>
@@ -87,66 +191,80 @@ function RuntimeLogPanel({ title, runtime, onRefresh }) {
         </div>
       )}
 
-      <div style={{ padding: "0 16px 12px 16px" }}>
-        <div
-          style={{
-            display: "grid",
-            gridTemplateColumns: "repeat(auto-fit, minmax(240px, 1fr))",
-            gap: 8,
-            marginBottom: 12,
-            fontSize: 12,
-            color: "#595959",
-          }}
-        >
-          <div>Started: {formatValue(runtime?.startedAt)}</div>
-          <div>Ended: {formatValue(runtime?.endedAt)}</div>
-          <div>Updated: {formatValue(runtime?.lastUpdatedAt)}</div>
-          <div>Config path: {formatValue(runtime?.configPath)}</div>
-          <div>Config origin: {formatValue(runtime?.configOriginPath)}</div>
-          <div>Output path: {formatValue(metadata.outputPath)}</div>
-          <div>Checkpoint: {formatValue(metadata.checkpointPath)}</div>
-          <div>Log path: {formatValue(metadata.logPath)}</div>
-        </div>
+      <div style={{ padding: "12px 16px" }}>
+        <Alert
+          type={summary.type}
+          showIcon
+          message={summary.label}
+          description={summary.message}
+          style={{ marginBottom: showDetails || showLog ? 12 : 0 }}
+        />
+
+        {showDetails && (
+          <>
+            <div
+              style={{
+                display: "grid",
+                gridTemplateColumns: "repeat(auto-fit, minmax(240px, 1fr))",
+                gap: 8,
+                marginBottom: 12,
+                fontSize: 12,
+                color: "#595959",
+              }}
+            >
+              <div>Started: {formatValue(runtime?.startedAt)}</div>
+              <div>Ended: {formatValue(runtime?.endedAt)}</div>
+              <div>Updated: {formatValue(runtime?.lastUpdatedAt)}</div>
+              <div>Config path: {formatValue(runtime?.configPath)}</div>
+              <div>Config origin: {formatValue(runtime?.configOriginPath)}</div>
+              <div>Output path: {formatValue(metadata.outputPath)}</div>
+              <div>Checkpoint: {formatValue(metadata.checkpointPath)}</div>
+              <div>Log path: {formatValue(metadata.logPath)}</div>
+            </div>
+
+            {runtime?.command && (
+              <div
+                style={{
+                  marginBottom: 12,
+                  padding: "8px 10px",
+                  borderRadius: 6,
+                  background: "#fff",
+                  border: "1px solid #f0f0f0",
+                  fontFamily:
+                    "ui-monospace, SFMono-Regular, SF Mono, Menlo, Consolas, monospace",
+                  fontSize: 12,
+                  color: "#262626",
+                  wordBreak: "break-word",
+                }}
+              >
+                {runtime.command}
+              </div>
+            )}
+          </>
+        )}
 
-        {runtime?.command && (
-          <div
+        {showLog && (
+          <pre
             style={{
-              marginBottom: 12,
-              padding: "8px 10px",
+              margin: 0,
+              minHeight: 220,
+              maxHeight: 420,
+              overflow: "auto",
+              padding: 12,
               borderRadius: 6,
-              background: "#fff",
-              border: "1px solid #f0f0f0",
-              fontFamily:
-                'ui-monospace, SFMono-Regular, SF Mono, Menlo, Consolas, monospace',
+              background: "#111827",
+              color: "#f3f4f6",
               fontSize: 12,
-              color: "#262626",
+              lineHeight: 1.5,
+              whiteSpace: "pre-wrap",
               wordBreak: "break-word",
+              fontFamily:
+                "ui-monospace, SFMono-Regular, SF Mono, Menlo, Consolas, monospace",
             }}
           >
-            {runtime.command}
-          </div>
+            {text || "No runtime logs captured yet."}
+          </pre>
         )}
-
-        <pre
-          style={{
-            margin: 0,
-            minHeight: 220,
-            maxHeight: 420,
-            overflow: "auto",
-            padding: 12,
-            borderRadius: 6,
-            background: "#111827",
-            color: "#f3f4f6",
-            fontSize: 12,
-            lineHeight: 1.5,
-            whiteSpace: "pre-wrap",
-            wordBreak: "break-word",
-            fontFamily:
-              'ui-monospace, SFMono-Regular, SF Mono, Menlo, Consolas, monospace',
-          }}
-        >
-          {text || "No runtime logs captured yet."}
-        </pre>
       </div>
     </div>
   );
diff --git a/client/src/components/UnifiedFileInput.js b/client/src/components/UnifiedFileInput.js
index 7fe8dec0..36ad63d2 100644
--- a/client/src/components/UnifiedFileInput.js
+++ b/client/src/components/UnifiedFileInput.js
@@ -1,5 +1,5 @@
 import React, { useState } from "react";
-import { Input, message } from "antd";
+import { Button, Input, message, Space, Tooltip } from "antd";
 import { FolderOpenOutlined } from "@ant-design/icons";
 import FilePickerModal from "./FilePickerModal";
 
@@ -88,6 +88,12 @@ const UnifiedFileInput = ({
     onChange({ path: val, display: val });
   };
 
+  const handlePrefixBrowse = (event) => {
+    event.preventDefault();
+    event.stopPropagation();
+    handleBrowse();
+  };
+
   // Extract display value
   const getDisplayValue = () => {
     if (!value) return "";
@@ -108,27 +114,47 @@ const UnifiedFileInput = ({
           ...style,
         }}
       >
-        <Input
-          value={getDisplayValue()}
-          onChange={handleInputChange}
-          placeholder={placeholder}
-          disabled={disabled}
-          style={{
-            borderColor: isDragOver ? "#1890ff" : undefined,
-            boxShadow: isDragOver
-              ? "0 0 0 2px rgba(24, 144, 255, 0.2)"
-              : undefined,
-          }}
-          prefix={
-            <FolderOpenOutlined
-              style={{
-                cursor: disabled ? "not-allowed" : "pointer",
-                color: disabled ? "#ccc" : "#1890ff",
-              }}
-              onClick={handleBrowse}
-            />
-          }
-        />
+        <Space.Compact style={{ width: "100%" }}>
+          <Input
+            value={getDisplayValue()}
+            onChange={handleInputChange}
+            placeholder={placeholder}
+            disabled={disabled}
+            style={{
+              borderColor: isDragOver
+                ? "var(--seg-accent-primary, #3f37c9)"
+                : undefined,
+              boxShadow: isDragOver
+                ? "0 0 0 2px var(--seg-focus-ring, rgba(63, 55, 201, 0.22))"
+                : undefined,
+            }}
+            prefix={
+              <Tooltip title="Browse files">
+                <Button
+                  type="text"
+                  size="small"
+                  aria-label="Browse files"
+                  disabled={disabled}
+                  icon={<FolderOpenOutlined />}
+                  onClick={handlePrefixBrowse}
+                  style={{
+                    color: disabled
+                      ? "#ccc"
+                      : "var(--seg-accent-primary, #3f37c9)",
+                    height: 22,
+                    width: 22,
+                    minWidth: 22,
+                    padding: 0,
+                    marginInlineStart: -4,
+                  }}
+                />
+              </Tooltip>
+            }
+          />
+          <Button onClick={handleBrowse} disabled={disabled}>
+            Browse
+          </Button>
+        </Space.Compact>
         {isDragOver && (
           <div
             style={{
@@ -137,13 +163,13 @@ const UnifiedFileInput = ({
               left: 0,
               right: 0,
               bottom: 0,
-              background: "rgba(24, 144, 255, 0.1)",
+              background: "var(--seg-selection-fill, rgba(63, 55, 201, 0.12))",
               pointerEvents: "none",
               zIndex: 10,
               display: "flex",
               alignItems: "center",
               justifyContent: "center",
-              color: "#1890ff",
+              color: "var(--seg-accent-primary, #3f37c9)",
               fontWeight: "bold",
             }}
           >
diff --git a/client/src/components/UnifiedFileInput.test.js b/client/src/components/UnifiedFileInput.test.js
new file mode 100644
index 00000000..2cb20887
--- /dev/null
+++ b/client/src/components/UnifiedFileInput.test.js
@@ -0,0 +1,50 @@
+import React from "react";
+import { fireEvent, render, screen } from "@testing-library/react";
+
+import UnifiedFileInput from "./UnifiedFileInput";
+
+jest.mock(
+  "./FilePickerModal",
+  () => (props) =>
+    props.visible ? (
+      <div
+        data-testid="file-picker-modal"
+        data-selection-type={props.selectionType}
+      />
+    ) : null,
+);
+
+beforeAll(() => {
+  Object.defineProperty(window, "matchMedia", {
+    writable: true,
+    value: jest.fn().mockImplementation((query) => ({
+      matches: false,
+      media: query,
+      onchange: null,
+      addListener: jest.fn(),
+      removeListener: jest.fn(),
+      addEventListener: jest.fn(),
+      removeEventListener: jest.fn(),
+      dispatchEvent: jest.fn(),
+    })),
+  });
+});
+
+describe("UnifiedFileInput", () => {
+  it("opens the file picker from the folder icon", () => {
+    render(
+      <UnifiedFileInput
+        value=""
+        onChange={jest.fn()}
+        placeholder="Image path"
+        selectionType="fileOrDirectory"
+      />,
+    );
+
+    fireEvent.click(screen.getByLabelText("Browse files"));
+
+    const modal = screen.getByTestId("file-picker-modal");
+    expect(modal).toBeTruthy();
+    expect(modal.getAttribute("data-selection-type")).toBe("fileOrDirectory");
+  });
+});
diff --git a/client/src/components/WorkflowTimeline.js b/client/src/components/WorkflowTimeline.js
index f2569f9b..2920bd81 100644
--- a/client/src/components/WorkflowTimeline.js
+++ b/client/src/components/WorkflowTimeline.js
@@ -1,29 +1,63 @@
 import React, { useMemo, useState } from "react";
-import { Button, Empty, Input, List, Select, Space, Tag, Typography } from "antd";
+import {
+  Button,
+  Empty,
+  Input,
+  List,
+  Select,
+  Space,
+  Tag,
+  Typography,
+} from "antd";
 import { useWorkflow } from "../contexts/WorkflowContext";
 import AgentProposalCard from "./chat/AgentProposalCard";
+import StageHeader from "./workflow/StageHeader";
 import {
   DEFAULT_TIMELINE_FILTERS,
   filterTimelineEvents,
   normalizeTimelineFilters,
   TIMELINE_ACTOR_OPTIONS,
 } from "../contexts/workflow/timelineFilters";
+import {
+  getApprovalMeta,
+  getSeverityMeta,
+} from "../design/workflowDesignSystem";
 
 const { Text } = Typography;
+const toList = (value) => (Array.isArray(value) ? value : []);
 
-const STAGE_LABELS = {
-  setup: "Setup",
-  visualization: "Visualization",
-  inference: "Inference",
-  proofreading: "Proofreading",
-  retraining_staged: "Retraining staged",
-  evaluation: "Evaluation",
+const parsePayload = (payload) => {
+  if (!payload) return {};
+  if (typeof payload === "string") {
+    try {
+      const parsed = JSON.parse(payload);
+      return parsed && typeof parsed === "object" ? parsed : {};
+    } catch {
+      return {};
+    }
+  }
+  if (typeof payload === "object" && !Array.isArray(payload)) return payload;
+  return {};
 };
 
-const SEVERITY_COLORS = {
-  low: "default",
-  medium: "orange",
-  high: "red",
+const toProposalPayload = (event = {}) => {
+  const rawPayload = parsePayload(event.payload || event.payload_json);
+  const params = parsePayload(rawPayload?.params);
+  return {
+    ...rawPayload,
+    ...(params || {}),
+    action_card: rawPayload.action_card || params.action_card || null,
+    specialist_agent: rawPayload.specialist_agent || params.specialist_agent,
+    orchestrator_agent:
+      rawPayload.orchestrator_agent || params.orchestrator_agent,
+    trace: toList(
+      params.trace ||
+        rawPayload.trace ||
+        params.action_card?.trace ||
+        rawPayload?.action_card?.trace,
+    ),
+    type: rawPayload.action || rawPayload.type || "agent_proposal",
+  };
 };
 
 function formatEventTime(value) {
@@ -33,7 +67,7 @@ function formatEventTime(value) {
   return date.toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" });
 }
 
-function WorkflowTimeline({ limit = 8 }) {
+function WorkflowTimeline({ limit = 8, showFilters = true }) {
   const workflowContext = useWorkflow();
   const workflow = workflowContext?.workflow;
   const events = workflowContext?.events;
@@ -48,7 +82,6 @@ function WorkflowTimeline({ limit = 8 }) {
   const visibleEvents = useMemo(() => {
     return filterTimelineEvents(reversedEvents, filters).slice(0, limit);
   }, [reversedEvents, filters, limit]);
-  const stageLabel = STAGE_LABELS[workflow?.stage] || workflow?.stage || "Loading";
   const topHotspot = hotspots[0] || null;
 
   if (!workflowContext) return null;
@@ -57,56 +90,31 @@ function WorkflowTimeline({ limit = 8 }) {
     <div
       data-testid="workflow-timeline"
       style={{
-        borderTop: "1px solid #f0f0f0",
-        borderBottom: "1px solid #f0f0f0",
+        borderTop: "1px solid var(--seg-border-subtle)",
+        borderBottom: "1px solid var(--seg-border-subtle)",
         padding: "10px 16px",
-        background: "#fbfbfb",
+        background: "var(--seg-bg-canvas)",
       }}
     >
-      <Space
-        size="small"
-        style={{ display: "flex", justifyContent: "space-between" }}
-      >
-        <Space size="small">
-          <Text strong style={{ fontSize: 13 }}>
-            Workflow
-          </Text>
-          <Tag color="blue" style={{ margin: 0 }}>
-            {stageLabel}
-          </Tag>
-        </Space>
-        <Space size="small">
-          <Text type="secondary" style={{ fontSize: 12 }}>
-            {workflow?.title || "Segmentation Workflow"}
-          </Text>
-          <Button
-            size="small"
-            type="text"
-            onClick={() => refreshInsights?.()}
-            style={{ paddingInline: 4 }}
-          >
-            Refresh Insights
-          </Button>
-        </Space>
-      </Space>
+      <StageHeader
+        stage={workflow?.stage}
+        title={workflow?.title || "Segmentation Workflow"}
+        actionLabel="Refresh Insights"
+        onAction={() => refreshInsights?.()}
+      />
 
       {(topHotspot || impactPreview) && (
-        <div
-          style={{
-            marginTop: 8,
-            padding: "6px 8px",
-            background: "#fff",
-            border: "1px solid #f0f0f0",
-            borderRadius: 6,
-          }}
-        >
+        <div className="workflow-insight-card">
           {topHotspot && (
             <Space size="small" wrap>
               <Text style={{ fontSize: 12 }} strong>
                 Hotspot
               </Text>
-              <Tag color={SEVERITY_COLORS[topHotspot.severity] || "default"}>
-                {topHotspot.severity}
+              <Tag
+                color={getSeverityMeta(topHotspot.severity).color}
+                style={{ margin: 0 }}
+              >
+                {getSeverityMeta(topHotspot.severity).label}
               </Tag>
               <Text style={{ fontSize: 12 }}>{topHotspot.summary}</Text>
             </Space>
@@ -124,39 +132,46 @@ function WorkflowTimeline({ limit = 8 }) {
         </div>
       )}
 
-      <Space size="small" style={{ marginTop: 8, display: "flex" }} wrap>
-        <Select
-          aria-label="Actor filter"
-          size="small"
-          value={filters.actor}
-          style={{ minWidth: 124 }}
-          options={TIMELINE_ACTOR_OPTIONS.map((value) => ({
-            value,
-            label: value === "all" ? "All actors" : value,
-          }))}
-          onChange={(value) =>
-            setFilters((prev) => normalizeTimelineFilters({ ...prev, actor: value }))
-          }
-        />
-        <Input
-          aria-label="Event type filter"
-          size="small"
-          value={filters.eventType}
-          placeholder="Filter event type"
-          style={{ maxWidth: 180 }}
-          onChange={(event) =>
-            setFilters((prev) =>
-              normalizeTimelineFilters({ ...prev, eventType: event.target.value }),
-            )
-          }
-        />
-        <Button
-          size="small"
-          onClick={() => setFilters(DEFAULT_TIMELINE_FILTERS)}
-        >
-          Clear
-        </Button>
-      </Space>
+      {showFilters && (
+        <Space size="small" style={{ marginTop: 8, display: "flex" }} wrap>
+          <Select
+            aria-label="Actor filter"
+            size="small"
+            value={filters.actor}
+            style={{ minWidth: 124 }}
+            options={TIMELINE_ACTOR_OPTIONS.map((value) => ({
+              value,
+              label: value === "all" ? "All actors" : value,
+            }))}
+            onChange={(value) =>
+              setFilters((prev) =>
+                normalizeTimelineFilters({ ...prev, actor: value }),
+              )
+            }
+          />
+          <Input
+            aria-label="Event type filter"
+            size="small"
+            value={filters.eventType}
+            placeholder="Filter event type"
+            style={{ maxWidth: 180 }}
+            onChange={(event) =>
+              setFilters((prev) =>
+                normalizeTimelineFilters({
+                  ...prev,
+                  eventType: event.target.value,
+                }),
+              )
+            }
+          />
+          <Button
+            size="small"
+            onClick={() => setFilters(DEFAULT_TIMELINE_FILTERS)}
+          >
+            Clear
+          </Button>
+        </Space>
+      )}
 
       {visibleEvents.length === 0 ? (
         <Empty
@@ -173,6 +188,9 @@ function WorkflowTimeline({ limit = 8 }) {
             const isPendingProposal =
               event.event_type === "agent.proposal_created" &&
               event.approval_status === "pending";
+            const proposalPayload = isPendingProposal
+              ? toProposalPayload(event)
+              : null;
             return (
               <List.Item
                 style={{
@@ -195,8 +213,11 @@ function WorkflowTimeline({ limit = 8 }) {
                     <Space size="small" wrap>
                       <Text style={{ fontSize: 12 }}>{event.summary}</Text>
                       {event.approval_status !== "not_required" && (
-                        <Tag style={{ margin: 0 }}>
-                          {event.approval_status}
+                        <Tag
+                          color={getApprovalMeta(event.approval_status).color}
+                          style={{ margin: 0 }}
+                        >
+                          {getApprovalMeta(event.approval_status).label}
                         </Tag>
                       )}
                     </Space>
@@ -214,15 +235,24 @@ function WorkflowTimeline({ limit = 8 }) {
                           {formatEventTime(event.created_at)}
                         </Text>
                       </Space>
-                      {isPendingProposal && (
+                      {proposalPayload && (
                         <AgentProposalCard
                           proposal={{
-                            ...(event.payload || {}),
-                            type: event.payload?.action || "agent_proposal",
+                            ...proposalPayload,
+                            type: proposalPayload.type,
                             rationale: event.summary,
-                            ...(event.payload?.params || {}),
                           }}
-                          onApprove={() => approveAgentAction?.(event.id)}
+                          trace={proposalPayload.trace}
+                          onApprove={(_proposal, overrides) => {
+                            if (
+                              overrides &&
+                              Object.keys(overrides).length > 0
+                            ) {
+                              approveAgentAction?.(event.id, overrides);
+                              return;
+                            }
+                            approveAgentAction?.(event.id);
+                          }}
                           onReject={() => rejectAgentAction?.(event.id)}
                         />
                       )}
diff --git a/client/src/components/WorkflowTimeline.test.js b/client/src/components/WorkflowTimeline.test.js
index 4792681f..3583c09a 100644
--- a/client/src/components/WorkflowTimeline.test.js
+++ b/client/src/components/WorkflowTimeline.test.js
@@ -43,6 +43,7 @@ jest.mock("antd", () => {
     Input: ({ ...props }) => <input {...props} />,
     Empty,
     List,
+    Progress: ({ percent }) => <div>{`progress-${percent}`}</div>,
     Select: ({ options = [], value, onChange, ...props }) => (
       <select
         value={value}
@@ -58,6 +59,7 @@ jest.mock("antd", () => {
     ),
     Space: ({ children }) => <span>{children}</span>,
     Tag: ({ children }) => <span>{children}</span>,
+    Tooltip: ({ children }) => <>{children}</>,
     Typography: {
       Text: ({ children }) => <span>{children}</span>,
     },
@@ -69,6 +71,16 @@ jest.mock("@ant-design/icons", () => {
   return {
     CheckOutlined: Icon,
     CloseOutlined: Icon,
+    DownOutlined: Icon,
+    RightOutlined: Icon,
+    BarChartOutlined: Icon,
+    BugOutlined: Icon,
+    ExperimentOutlined: Icon,
+    EyeOutlined: Icon,
+    FileDoneOutlined: Icon,
+    FolderOpenOutlined: Icon,
+    ProjectOutlined: Icon,
+    ThunderboltOutlined: Icon,
   };
 });
 
@@ -122,7 +134,7 @@ describe("WorkflowTimeline", () => {
       ],
     });
 
-    expect(screen.getByText("Proofreading")).toBeTruthy();
+    expect(screen.getByText("Test Workflow")).toBeTruthy();
     expect(screen.getByText("Loaded dataset.")).toBeTruthy();
     expect(screen.getByText("dataset.loaded")).toBeTruthy();
   });
@@ -176,9 +188,7 @@ describe("WorkflowTimeline", () => {
 
     expect(screen.getByText("z:12 has repeated failures.")).toBeTruthy();
     expect(
-      screen.getByText(
-        /Corrections are ready to stage\. \(confidence: high\)/,
-      ),
+      screen.getByText(/Corrections are ready to stage\. \(confidence: high\)/),
     ).toBeTruthy();
 
     fireEvent.click(screen.getByText("Refresh Insights"));
@@ -217,12 +227,61 @@ describe("WorkflowTimeline", () => {
       target: { value: "agent" },
     });
     expect(screen.queryByText("Loaded dataset.")).toBeNull();
-    expect(screen.getAllByText("Stage corrected masks.").length).toBeGreaterThan(0);
+    expect(
+      screen.getAllByText("Stage corrected masks.").length,
+    ).toBeGreaterThan(0);
 
     fireEvent.change(screen.getByLabelText("Event type filter"), {
       target: { value: "proposal" },
     });
-    expect(screen.getAllByText("Stage corrected masks.").length).toBeGreaterThan(0);
+    expect(
+      screen.getAllByText("Stage corrected masks.").length,
+    ).toBeGreaterThan(0);
     expect(screen.getByText("Stage Retraining From Corrections")).toBeTruthy();
   });
+
+  it("shows operational trace for pending proposal events with payload_json", () => {
+    renderTimeline({
+      events: [
+        {
+          id: 8,
+          actor: "agent",
+          event_type: "agent.proposal_created",
+          stage: "inference",
+          summary: "Approve training run.",
+          approval_status: "pending",
+          payload_json: JSON.stringify({
+            action: "start_training_run",
+            params: {
+              config_preset: "/tmp/config.yaml",
+              image_path: "/tmp/image.tif",
+              label_path: "/tmp/label.tif",
+              output_path: "/tmp/out.tif",
+              action_card: {
+                trace: [
+                  {
+                    label: "Checked training resources",
+                    detail: "Data, labels, and checkpoints are ready.",
+                    category: "checked",
+                  },
+                ],
+                input_artifacts: [{ path: "/tmp/image.tif" }],
+                output_artifacts: [{ path: "/tmp/out.tif" }],
+              },
+            },
+          }),
+          created_at: "2026-04-12T12:04:00Z",
+        },
+      ],
+    });
+
+    const traceToggle = screen.getByRole("button", {
+      name: /Operational trace/,
+    });
+    fireEvent.click(traceToggle);
+    expect(screen.getByText(/Inspected facts/i)).toBeTruthy();
+    expect(screen.getByText(/Checked training resources/)).toBeTruthy();
+    expect(screen.getByText(/Input · .*tmp\/image\.tif/)).toBeTruthy();
+    expect(screen.getByText(/Output · .*tmp\/out\.tif/)).toBeTruthy();
+  });
 });
diff --git a/client/src/components/YamlConfigHelpChat.test.js b/client/src/components/YamlConfigHelpChat.test.js
new file mode 100644
index 00000000..2332f20f
--- /dev/null
+++ b/client/src/components/YamlConfigHelpChat.test.js
@@ -0,0 +1,185 @@
+import React from "react";
+import { render, screen } from "@testing-library/react";
+
+import YamlFileEditor from "./YamlFileEditor";
+import YamlFileUploader from "./YamlFileUploader";
+import { AppContext } from "../contexts/GlobalContext";
+import { YamlContext } from "../contexts/YamlContext";
+
+jest.mock("antd", () => {
+  const React = require("react");
+  const message = {
+    success: jest.fn(),
+    error: jest.fn(),
+    warning: jest.fn(),
+    info: jest.fn(),
+  };
+
+  const Space = ({ children }) => <div>{children}</div>;
+  Space.Compact = ({ children }) => <div>{children}</div>;
+
+  const Input = ({ value = "", onChange, ...props }) => (
+    <input value={value} onChange={onChange} {...props} />
+  );
+  Input.TextArea = ({ value = "", onChange, ...props }) => (
+    <textarea value={value} onChange={onChange} {...props} />
+  );
+
+  return {
+    Button: ({ children, ...props }) => <button {...props}>{children}</button>,
+    Col: ({ children }) => <div>{children}</div>,
+    Divider: ({ children }) => <div>{children}</div>,
+    Input,
+    InputNumber: ({ value = "", ...props }) => (
+      <input type="number" value={value} readOnly {...props} />
+    ),
+    Modal: ({ children, open, title }) =>
+      open ? (
+        <div>
+          <div>{title}</div>
+          {children}
+        </div>
+      ) : null,
+    Row: ({ children }) => <div>{children}</div>,
+    Select: ({ placeholder, value, options = [] }) => (
+      <select
+        aria-label={placeholder || "select"}
+        value={value || ""}
+        onChange={() => {}}
+      >
+        <option value="" />
+        {options.map((option) => (
+          <option key={option.value} value={option.value}>
+            {option.label}
+          </option>
+        ))}
+      </select>
+    ),
+    Slider: ({ value = 0 }) => <input type="range" readOnly value={value} />,
+    Space,
+    Switch: ({ checked }) => (
+      <input type="checkbox" readOnly checked={Boolean(checked)} />
+    ),
+    Upload: ({ children }) => <div>{children}</div>,
+    message,
+  };
+});
+
+jest.mock("@ant-design/icons", () => ({
+  UploadOutlined: () => <span />,
+}));
+
+jest.mock("./InlineHelpChat", () => (props) => (
+  <span data-testid="inline-help-chat">
+    {`help:${props.label}:${props.yamlKey || "none"}`}
+  </span>
+));
+
+jest.mock("../api", () => ({
+  getConfigPresets: jest.fn().mockResolvedValue({ configs: [] }),
+  getConfigPresetContent: jest.fn(),
+  getModelArchitectures: jest.fn().mockResolvedValue({
+    architectures: ["UNet"],
+  }),
+}));
+
+function createAppContextValue({
+  trainingConfig = "",
+  inferenceConfig = "",
+} = {}) {
+  return {
+    trainingConfig,
+    setTrainingConfig: jest.fn(),
+    inferenceConfig,
+    setInferenceConfig: jest.fn(),
+    trainingState: {
+      uploadedYamlFile: "",
+      selectedYamlPreset: "",
+      inputImage: "",
+      inputLabel: "",
+      outputPath: "",
+      setUploadedYamlFile: jest.fn(),
+      setSelectedYamlPreset: jest.fn(),
+      setConfigOriginPath: jest.fn(),
+    },
+    inferenceState: {
+      uploadedYamlFile: "",
+      selectedYamlPreset: "",
+      inputImage: "",
+      inputLabel: "",
+      outputPath: "",
+      checkpointPath: "",
+      setUploadedYamlFile: jest.fn(),
+      setSelectedYamlPreset: jest.fn(),
+      setConfigOriginPath: jest.fn(),
+    },
+  };
+}
+
+const yamlContextValue = {
+  numGPUs: 1,
+  setNumGPUs: jest.fn(),
+  numCPUs: 8,
+  setNumCPUs: jest.fn(),
+  solverSamplesPerBatch: 4,
+  setSolverSamplesPerBatch: jest.fn(),
+  learningRate: 0.001,
+  setLearningRate: jest.fn(),
+  inferenceSamplesPerBatch: 2,
+  setInferenceSamplesPerBatch: jest.fn(),
+  augNum: 4,
+  setAugNum: jest.fn(),
+};
+
+describe("config help chat", () => {
+  it("renders on-demand help for base training knobs", async () => {
+    const trainingConfig = `
+MODEL:
+  ARCHITECTURE: UNet
+SOLVER:
+  SAMPLES_PER_BATCH: 4
+SYSTEM:
+  NUM_GPUS: 1
+  NUM_CPUS: 8
+`;
+
+    render(
+      <AppContext.Provider value={createAppContextValue({ trainingConfig })}>
+        <YamlContext.Provider value={yamlContextValue}>
+          <YamlFileUploader type="training" />
+        </YamlContext.Provider>
+      </AppContext.Provider>,
+    );
+
+    expect(
+      await screen.findByText("help:Model architecture:MODEL.ARCHITECTURE"),
+    ).toBeTruthy();
+    expect(
+      screen.getByText("help:Batch size:SOLVER.SAMPLES_PER_BATCH"),
+    ).toBeTruthy();
+    expect(screen.getByText("help:GPUs:SYSTEM.NUM_GPUS")).toBeTruthy();
+    expect(screen.getByText("help:CPUs:SYSTEM.NUM_CPUS")).toBeTruthy();
+  });
+
+  it("renders on-demand help for advanced inference controls", async () => {
+    const inferenceConfig = `
+INFERENCE:
+  SAMPLES_PER_BATCH: 2
+  AUG_NUM: 4
+  BLENDING: gaussian
+  DO_EVAL: true
+`;
+
+    render(
+      <AppContext.Provider value={createAppContextValue({ inferenceConfig })}>
+        <YamlFileEditor type="inference" />
+      </AppContext.Provider>,
+    );
+
+    expect(
+      await screen.findByText("help:Batch size:INFERENCE.SAMPLES_PER_BATCH"),
+    ).toBeTruthy();
+    expect(screen.getByText("help:Blending:INFERENCE.BLENDING")).toBeTruthy();
+    expect(screen.getByText("help:Eval mode:INFERENCE.DO_EVAL")).toBeTruthy();
+  });
+});
diff --git a/client/src/components/YamlFileEditor.js b/client/src/components/YamlFileEditor.js
index eff46726..f5736bf9 100644
--- a/client/src/components/YamlFileEditor.js
+++ b/client/src/components/YamlFileEditor.js
@@ -13,6 +13,21 @@ import {
 import yaml from "js-yaml";
 import { AppContext } from "../contexts/GlobalContext";
 import { hasPath } from "../configSchema";
+import InlineHelpChat from "./InlineHelpChat";
+import { logClientEvent } from "../logging/appEventLog";
+import {
+  detectConfigDiagnostics,
+  summarizeConfigObject,
+  summarizeConfigText,
+} from "../logging/configLogSummary";
+
+const PROJECT_CONTEXT =
+  "Biomedical image segmentation using PyTorch Connectomics.";
+
+const ADVANCED_CONFIG_TASK_CONTEXT = {
+  training: "Model training configuration — Step 3: Advanced Configuration.",
+  inference: "Model inference configuration — Step 3: Advanced Configuration.",
+};
 
 const getYamlValue = (data, path) => {
   if (!data) return undefined;
@@ -236,7 +251,7 @@ const CONTROL_SECTIONS = {
           label: "Augmentations",
           path: ["INFERENCE", "AUG_NUM"],
           type: "number",
-          min: 1,
+          min: 4,
         },
         {
           label: "Blending",
@@ -306,6 +321,20 @@ const YamlFileEditor = (props) => {
     } else {
       context.setInferenceConfig(updatedText);
     }
+    const configSummary = summarizeConfigObject(updated, type);
+    const diagnostics = detectConfigDiagnostics({ config: configSummary });
+    logClientEvent("yaml_advanced_control_updated", {
+      level: diagnostics.length ? "WARNING" : "INFO",
+      message: `Advanced YAML control updated: ${path.join(".")}`,
+      source: "yaml-editor",
+      data: {
+        type,
+        path: path.join("."),
+        value,
+        configSummary,
+        diagnostics,
+      },
+    });
   };
 
   const [rawError, setRawError] = useState("");
@@ -326,6 +355,19 @@ const YamlFileEditor = (props) => {
     }
   };
 
+  useEffect(() => {
+    if (!rawError) return;
+    logClientEvent("yaml_raw_validation_failed", {
+      level: "WARNING",
+      message: rawError,
+      source: "yaml-editor",
+      data: {
+        type,
+        textLength: yamlContent.length || 0,
+      },
+    });
+  }, [rawError, type, yamlContent]);
+
   useEffect(() => {
     if (type === "training") {
       setYamlContent(context.trainingConfig || "");
@@ -345,6 +387,19 @@ const YamlFileEditor = (props) => {
   const displayName =
     workflow.uploadedYamlFile?.name || workflow.selectedYamlPreset;
 
+  const advancedConfigTaskContext = ADVANCED_CONFIG_TASK_CONTEXT[type];
+
+  const renderControlHelp = (control) => (
+    <InlineHelpChat
+      taskKey={`${type}:advanced-config`}
+      label={control.label}
+      yamlKey={control.path.join(".")}
+      value={getYamlValue(yamlData, control.path)}
+      projectContext={PROJECT_CONTEXT}
+      taskContext={advancedConfigTaskContext}
+    />
+  );
+
   const renderControl = (control) => {
     const value = getYamlValue(yamlData, control.path);
     const isSupported = hasPath(yamlData, control.path);
@@ -460,15 +515,21 @@ const YamlFileEditor = (props) => {
                               }}
                             >
                               {renderControl(control)}
-                              <span style={{ fontSize: 12 }}>
-                                {control.label}
-                              </span>
+                              <Space align="center" size={4}>
+                                <span style={{ fontSize: 12 }}>
+                                  {control.label}
+                                </span>
+                                {renderControlHelp(control)}
+                              </Space>
                             </div>
                           ) : (
                             <>
-                              <span style={{ fontSize: 12 }}>
-                                {control.label}
-                              </span>
+                              <Space align="center" size={4}>
+                                <span style={{ fontSize: 12 }}>
+                                  {control.label}
+                                </span>
+                                {renderControlHelp(control)}
+                              </Space>
                               <div style={{ width: "100%" }}>
                                 {renderControl(control)}
                               </div>
@@ -484,7 +545,22 @@ const YamlFileEditor = (props) => {
           ))}
 
           <Space style={{ marginBottom: 8 }}>
-            <Button size="small" onClick={() => setShowRaw(true)}>
+            <Button
+              size="small"
+              onClick={() => {
+                logClientEvent("yaml_raw_editor_opened", {
+                  level: "INFO",
+                  message: "Opened raw YAML editor",
+                  source: "yaml-editor",
+                  data: {
+                    type,
+                    displayName: displayName || null,
+                    configSummary: summarizeConfigText(yamlContent, type),
+                  },
+                });
+                setShowRaw(true);
+              }}
+            >
               Open raw YAML
             </Button>
           </Space>
@@ -517,8 +593,27 @@ const YamlFileEditor = (props) => {
                     } else {
                       context.setInferenceConfig(formatted);
                     }
+                    logClientEvent("yaml_raw_formatted", {
+                      level: "INFO",
+                      message: "Formatted raw YAML",
+                      source: "yaml-editor",
+                      data: {
+                        type,
+                        configSummary: summarizeConfigText(formatted, type),
+                      },
+                    });
                     setRawError("");
                   } catch (error) {
+                    logClientEvent("yaml_raw_format_failed", {
+                      level: "ERROR",
+                      message: "Could not format YAML",
+                      source: "yaml-editor",
+                      data: {
+                        type,
+                        error: error.message || "unknown error",
+                        textLength: yamlContent.length || 0,
+                      },
+                    });
                     message.error("Could not format YAML.");
                   }
                 }}
diff --git a/client/src/components/YamlFileUploader.js b/client/src/components/YamlFileUploader.js
index e7a33c5a..88bfac95 100644
--- a/client/src/components/YamlFileUploader.js
+++ b/client/src/components/YamlFileUploader.js
@@ -1,6 +1,7 @@
 // global FileReader
 import React, {
   Fragment,
+  useCallback,
   useContext,
   useEffect,
   useMemo,
@@ -26,16 +27,32 @@ import {
   getConfigPresetContent,
   getModelArchitectures,
 } from "../api";
+import InlineHelpChat from "./InlineHelpChat";
 import { findCommonPartOfString } from "../utils";
 import {
   applyInputPaths,
+  getArchitecturePath,
   getArchitectureValue,
+  getSliderPath,
   getSliderValue,
   isArchitectureSupported,
   isSliderSupported,
   setArchitectureValue,
   setSliderValue,
 } from "../configSchema";
+import { logClientEvent } from "../logging/appEventLog";
+import {
+  detectConfigDiagnostics,
+  summarizeConfigObject,
+} from "../logging/configLogSummary";
+
+const PROJECT_CONTEXT =
+  "Biomedical image segmentation using PyTorch Connectomics.";
+
+const BASE_CONFIG_TASK_CONTEXT = {
+  training: "Model training configuration — Step 2: Base Configuration.",
+  inference: "Model inference configuration — Step 2: Base Configuration.",
+};
 
 const YamlFileUploader = (props) => {
   const context = useContext(AppContext);
@@ -43,6 +60,20 @@ const YamlFileUploader = (props) => {
   const { type } = props;
   const workflow =
     type === "training" ? context.trainingState : context.inferenceState;
+  const {
+    trainingConfig,
+    inferenceConfig,
+    setTrainingConfig,
+    setInferenceConfig,
+  } = context;
+  const {
+    setAugNum,
+    setInferenceSamplesPerBatch,
+    setLearningRate,
+    setNumCPUs,
+    setNumGPUs,
+    setSolverSamplesPerBatch,
+  } = YAMLContext;
 
   const [yamlContent, setYamlContent] = useState("");
   const [presetOptions, setPresetOptions] = useState([]);
@@ -50,6 +81,11 @@ const YamlFileUploader = (props) => {
   const [architectureOptions, setArchitectureOptions] = useState([]);
   const [isLoadingPresets, setIsLoadingPresets] = useState(false);
   const [isLoadingArchitectures, setIsLoadingArchitectures] = useState(false);
+  const currentConfig = type === "training" ? trainingConfig : inferenceConfig;
+  const setConfigOriginPath = workflow.setConfigOriginPath;
+  const selectedYamlPreset = workflow.selectedYamlPreset;
+  const configOriginPath = workflow.configOriginPath;
+  const setSelectedYamlPreset = workflow.setSelectedYamlPreset;
 
   const sliderData = useMemo(() => {
     if (type === "training") {
@@ -97,11 +133,11 @@ const YamlFileUploader = (props) => {
       {
         key: "augmentations",
         label: "Augmentations",
-        min: 1,
+        min: 4,
         max: 16,
-        marks: { 1: 1, 8: 8, 16: 16 },
+        marks: { 4: 4, 8: 8, 16: 16 },
         value: YAMLContext.augNum,
-        step: 1,
+        step: null,
       },
     ];
   }, [
@@ -113,27 +149,30 @@ const YamlFileUploader = (props) => {
     YAMLContext.inferenceSamplesPerBatch,
   ]);
 
-  const getCurrentConfig = () =>
-    type === "training" ? context.trainingConfig : context.inferenceConfig;
-
-  const setCurrentOriginPath = (nextOriginPath) => {
-    workflow.setConfigOriginPath(nextOriginPath || "");
-  };
+  const setCurrentOriginPath = useCallback(
+    (nextOriginPath) => {
+      setConfigOriginPath(nextOriginPath || "");
+    },
+    [setConfigOriginPath],
+  );
 
-  const setCurrentConfig = (nextContent) => {
-    if (type === "training") {
-      context.setTrainingConfig(nextContent);
-    } else {
-      context.setInferenceConfig(nextContent);
-    }
-    setYamlContent(nextContent);
-  };
+  const setCurrentConfig = useCallback(
+    (nextContent) => {
+      if (type === "training") {
+        setTrainingConfig(nextContent);
+      } else {
+        setInferenceConfig(nextContent);
+      }
+      setYamlContent(nextContent);
+    },
+    [setInferenceConfig, setTrainingConfig, type],
+  );
 
-  const getPathValue = (val) => {
+  const getPathValue = useCallback((val) => {
     if (!val) return "";
     if (typeof val === "string") return val;
     return val.path || val.folderPath || "";
-  };
+  }, []);
 
   const getFileName = (path) => {
     if (!path) return "";
@@ -141,70 +180,117 @@ const YamlFileUploader = (props) => {
     return parts[parts.length - 1];
   };
 
-  const updateInputSelectorInformation = (yamlData) => {
-    const inputImagePath = getPathValue(workflow.inputImage);
-    const inputLabelPath = getPathValue(workflow.inputLabel);
-    const inputPath = findCommonPartOfString(inputImagePath, inputLabelPath);
-    const outputPath = getPathValue(workflow.outputPath);
-    applyInputPaths(yamlData, {
-      mode: type,
-      inputImagePath,
-      inputLabelPath,
-      inputPath,
-      outputPath,
-    });
-  };
+  const updateInputSelectorInformation = useCallback(
+    (yamlData) => {
+      const inputImagePath = getPathValue(workflow.inputImage);
+      const inputLabelPath = getPathValue(workflow.inputLabel);
+      const inputPath = findCommonPartOfString(inputImagePath, inputLabelPath);
+      const outputPath = getPathValue(workflow.outputPath);
+      applyInputPaths(yamlData, {
+        mode: type,
+        inputImagePath,
+        inputLabelPath,
+        inputPath,
+        outputPath,
+      });
+    },
+    [
+      getPathValue,
+      type,
+      workflow.inputImage,
+      workflow.inputLabel,
+      workflow.outputPath,
+    ],
+  );
 
-  const syncYamlContext = (yamlData) => {
-    if (!yamlData) return;
-    const gpus = getSliderValue(yamlData, "training", "gpus");
-    if (typeof gpus === "number") {
-      YAMLContext.setNumGPUs(gpus);
-    }
-    const cpus = getSliderValue(yamlData, "training", "cpus");
-    if (typeof cpus === "number") {
-      YAMLContext.setNumCPUs(cpus);
-    }
-    const trainBatch = getSliderValue(yamlData, "training", "batch_size");
-    if (typeof trainBatch === "number") {
-      YAMLContext.setSolverSamplesPerBatch(trainBatch);
-    }
-    const inferenceBatch = getSliderValue(yamlData, "inference", "batch_size");
-    if (typeof inferenceBatch === "number") {
-      YAMLContext.setInferenceSamplesPerBatch(inferenceBatch);
-    }
-    const augNum = getSliderValue(yamlData, "inference", "augmentations");
-    if (typeof augNum === "number") {
-      YAMLContext.setAugNum(augNum);
-    }
-    const learningRate =
-      yamlData.SOLVER?.BASE_LR ?? yamlData.optimization?.optimizer?.lr;
-    if (typeof learningRate === "number") {
-      YAMLContext.setLearningRate(learningRate);
-    }
-  };
+  const syncYamlContext = useCallback(
+    (yamlData) => {
+      if (!yamlData) return;
+      const gpus = getSliderValue(yamlData, "training", "gpus");
+      if (typeof gpus === "number") {
+        setNumGPUs(gpus);
+      }
+      const cpus = getSliderValue(yamlData, "training", "cpus");
+      if (typeof cpus === "number") {
+        setNumCPUs(cpus);
+      }
+      const trainBatch = getSliderValue(yamlData, "training", "batch_size");
+      if (typeof trainBatch === "number") {
+        setSolverSamplesPerBatch(trainBatch);
+      }
+      const inferenceBatch = getSliderValue(
+        yamlData,
+        "inference",
+        "batch_size",
+      );
+      if (typeof inferenceBatch === "number") {
+        setInferenceSamplesPerBatch(inferenceBatch);
+      }
+      const augNum = getSliderValue(yamlData, "inference", "augmentations");
+      if (typeof augNum === "number") {
+        setAugNum(augNum);
+      }
+      const learningRate =
+        yamlData.SOLVER?.BASE_LR ?? yamlData.optimization?.optimizer?.lr;
+      if (typeof learningRate === "number") {
+        setLearningRate(learningRate);
+      }
+    },
+    [
+      setAugNum,
+      setInferenceSamplesPerBatch,
+      setLearningRate,
+      setNumCPUs,
+      setNumGPUs,
+      setSolverSamplesPerBatch,
+    ],
+  );
 
-  const applyYamlData = (yamlData, sourceLabel) => {
-    if (!yamlData) {
-      message.error("Failed to load YAML configuration.");
-      return;
-    }
+  const applyYamlData = useCallback(
+    (yamlData, sourceLabel, originPath = "") => {
+      if (!yamlData) {
+        message.error("Failed to load YAML configuration.");
+        return;
+      }
 
-    updateInputSelectorInformation(yamlData);
-    const serialized = yaml
-      .dump(yamlData, { indent: 2 })
-      .replace(/^\s*\n/gm, "");
-    setCurrentConfig(serialized);
-    syncYamlContext(yamlData);
-
-    if (sourceLabel) {
-      message.success(`${sourceLabel} loaded.`);
-    }
-  };
+      updateInputSelectorInformation(yamlData);
+      const serialized = yaml
+        .dump(yamlData, { indent: 2 })
+        .replace(/^\s*\n/gm, "");
+      setCurrentConfig(serialized);
+      syncYamlContext(yamlData);
+
+      const configSummary = summarizeConfigObject(yamlData, type);
+      const diagnostics = detectConfigDiagnostics({ config: configSummary });
+      logClientEvent("yaml_config_applied", {
+        level: diagnostics.length ? "WARNING" : "INFO",
+        message: sourceLabel || `${type} YAML updated`,
+        source: "yaml-uploader",
+        data: {
+          type,
+          sourceLabel: sourceLabel || null,
+          originPath: originPath || workflow.configOriginPath || "",
+          configSummary,
+          diagnostics,
+        },
+      });
+
+      if (sourceLabel) {
+        message.success(`${sourceLabel} loaded.`);
+      }
+    },
+    [
+      setCurrentConfig,
+      syncYamlContext,
+      type,
+      updateInputSelectorInformation,
+      workflow.configOriginPath,
+    ],
+  );
 
-  const serializeYaml = (yamlData) => {
+  const serializeYaml = useCallback((yamlData) => {
     return yaml.dump(yamlData, { indent: 2 }).replace(/^\s*\n/gm, "");
-  };
+  }, []);
 
   const normalizeYamlText = (text) => {
     if (!text) return "";
@@ -216,17 +302,31 @@ const YamlFileUploader = (props) => {
     }
   };
 
-  const parseYaml = (yamlText, showError = true) => {
-    if (!yamlText) return null;
-    try {
-      return yaml.load(yamlText);
-    } catch (error) {
-      if (showError) {
-        message.error("Error parsing YAML content.");
+  const parseYaml = useCallback(
+    (yamlText, showError = true) => {
+      if (!yamlText) return null;
+      try {
+        return yaml.load(yamlText);
+      } catch (error) {
+        logClientEvent("yaml_parse_failed", {
+          level: "ERROR",
+          message: "Failed to parse YAML in uploader",
+          source: "yaml-uploader",
+          data: {
+            type,
+            showError,
+            error: error.message || "unknown error",
+            textLength: yamlText.length || 0,
+          },
+        });
+        if (showError) {
+          message.error("Error parsing YAML content.");
+        }
+        return null;
       }
-      return null;
-    }
-  };
+    },
+    [type],
+  );
 
   const handleFileUpload = (file) => {
     workflow.setUploadedYamlFile(file);
@@ -238,7 +338,7 @@ const YamlFileUploader = (props) => {
       const contents = e.target.result;
       const yamlData = parseYaml(contents);
       if (!yamlData) return;
-      applyYamlData(yamlData, "YAML file");
+      applyYamlData(yamlData, "YAML file", getPathValue(file));
     };
     reader.readAsText(file);
   };
@@ -253,7 +353,7 @@ const YamlFileUploader = (props) => {
       workflow.setSelectedYamlPreset(value);
       workflow.setUploadedYamlFile("");
       setCurrentOriginPath(value);
-      applyYamlData(yamlData, "Preset config");
+      applyYamlData(yamlData, "Preset config", value);
     } catch (error) {
       message.error(error?.message || "Failed to load preset config.");
     } finally {
@@ -265,11 +365,10 @@ const YamlFileUploader = (props) => {
     if (!presetYamlText) return;
     const yamlData = parseYaml(presetYamlText);
     if (!yamlData) return;
-    applyYamlData(yamlData, "Preset restored");
+    applyYamlData(yamlData, "Preset restored", workflow.selectedYamlPreset);
   };
 
   const handleSliderChange = (sliderKey, newValue) => {
-    const currentConfig = getCurrentConfig();
     if (!currentConfig) {
       message.warning("Load a preset or upload a YAML file first.");
       return;
@@ -284,7 +383,6 @@ const YamlFileUploader = (props) => {
   };
 
   const handleArchitectureChange = (value) => {
-    const currentConfig = getCurrentConfig();
     if (!currentConfig) {
       message.warning("Load a preset or upload a YAML file first.");
       return;
@@ -336,7 +434,38 @@ const YamlFileUploader = (props) => {
   }, []);
 
   useEffect(() => {
-    const currentConfig = getCurrentConfig();
+    if (!selectedYamlPreset || !presetOptions.length) return;
+    const selectedPresetStillExists = presetOptions.some(
+      (option) => option.value === selectedYamlPreset,
+    );
+    if (selectedPresetStillExists) return;
+
+    logClientEvent("yaml_preset_missing", {
+      level: "WARNING",
+      message: "Persisted YAML preset was not found in the current preset list",
+      source: "yaml-uploader",
+      data: {
+        type,
+        missingPreset: selectedYamlPreset,
+        currentOriginPath: configOriginPath || "",
+      },
+    });
+
+    setSelectedYamlPreset("");
+    setPresetYamlText(null);
+    if (configOriginPath === selectedYamlPreset) {
+      setCurrentOriginPath("");
+    }
+  }, [
+    configOriginPath,
+    presetOptions,
+    selectedYamlPreset,
+    setCurrentOriginPath,
+    setSelectedYamlPreset,
+    type,
+  ]);
+
+  useEffect(() => {
     if (currentConfig) {
       setYamlContent(currentConfig);
       const yamlData = parseYaml(currentConfig);
@@ -344,10 +473,9 @@ const YamlFileUploader = (props) => {
         syncYamlContext(yamlData);
       }
     }
-  }, [context.trainingConfig, context.inferenceConfig, type]);
+  }, [currentConfig, parseYaml, syncYamlContext]);
 
   useEffect(() => {
-    const currentConfig = getCurrentConfig();
     if (!currentConfig) return;
 
     const yamlData = parseYaml(currentConfig, false);
@@ -359,28 +487,32 @@ const YamlFileUploader = (props) => {
       setCurrentConfig(nextSerialized);
     }
   }, [
-    workflow.inputImage,
-    workflow.inputLabel,
-    workflow.outputPath,
-    context.trainingConfig,
-    context.inferenceConfig,
-    type,
+    currentConfig,
+    parseYaml,
+    serializeYaml,
+    setCurrentConfig,
+    updateInputSelectorInformation,
   ]);
 
   const currentYamlData = useMemo(() => {
-    const currentConfig = getCurrentConfig();
     if (!currentConfig) return null;
     return parseYaml(currentConfig, false);
-  }, [context.trainingConfig, context.inferenceConfig, type]);
+  }, [currentConfig, parseYaml]);
 
   const currentArchitecture = useMemo(() => {
     return getArchitectureValue(currentYamlData);
   }, [currentYamlData]);
 
+  const currentArchitecturePath = useMemo(() => {
+    return getArchitecturePath(currentYamlData);
+  }, [currentYamlData]);
+
   const architectureSupported = useMemo(() => {
     return isArchitectureSupported(currentYamlData);
   }, [currentYamlData]);
 
+  const baseConfigTaskContext = BASE_CONFIG_TASK_CONTEXT[type];
+
   return (
     <div style={{ margin: "10px" }}>
       <Space wrap size={12} style={{ marginBottom: 12 }}>
@@ -415,12 +547,12 @@ const YamlFileUploader = (props) => {
           {workflow.selectedYamlPreset && presetYamlText && (
             <>
               <span style={{ color: "#fa8c16", fontSize: 12 }}>
-                {normalizeYamlText(getCurrentConfig()) !==
+                {normalizeYamlText(currentConfig) !==
                 normalizeYamlText(presetYamlText)
                   ? "Modified"
                   : "Preset"}
               </span>
-              {normalizeYamlText(getCurrentConfig()) !==
+              {normalizeYamlText(currentConfig) !==
                 normalizeYamlText(presetYamlText) && (
                 <Button size="small" type="link" onClick={handleRevertPreset}>
                   Revert to preset
@@ -469,7 +601,21 @@ const YamlFileUploader = (props) => {
       <Row gutter={[16, 16]}>
         <Col span={12}>
           <div>
-            <h4>Model architecture</h4>
+            <Space align="center" size={4}>
+              <h4 style={{ marginBottom: 0 }}>Model architecture</h4>
+              <InlineHelpChat
+                taskKey={`${type}:base-config`}
+                label="Model architecture"
+                yamlKey={
+                  currentArchitecturePath
+                    ? currentArchitecturePath.join(".")
+                    : undefined
+                }
+                value={currentArchitecture}
+                projectContext={PROJECT_CONTEXT}
+                taskContext={baseConfigTaskContext}
+              />
+            </Space>
             <Space style={{ width: "100%" }} align="start">
               <Select
                 placeholder="Select architecture"
@@ -490,7 +636,12 @@ const YamlFileUploader = (props) => {
       {yamlContent ? (
         <Row>
           {sliderData.map((param, index) => {
-            const sliderValue = getSliderValue(currentYamlData, type, param.key);
+            const sliderValue = getSliderValue(
+              currentYamlData,
+              type,
+              param.key,
+            );
+            const sliderPath = getSliderPath(currentYamlData, type, param.key);
             const sliderSupported = isSliderSupported(
               currentYamlData,
               type,
@@ -502,12 +653,28 @@ const YamlFileUploader = (props) => {
                   <div>
                     <Space align="center">
                       <h4 style={{ marginBottom: 0 }}>{param.label}</h4>
+                      <InlineHelpChat
+                        taskKey={`${type}:base-config`}
+                        label={param.label}
+                        yamlKey={sliderPath ? sliderPath.join(".") : undefined}
+                        value={
+                          typeof sliderValue === "number"
+                            ? sliderValue
+                            : param.value
+                        }
+                        projectContext={PROJECT_CONTEXT}
+                        taskContext={baseConfigTaskContext}
+                      />
                     </Space>
                     <Slider
                       min={param.min}
                       max={param.max}
                       marks={param.marks}
-                      value={typeof sliderValue === "number" ? sliderValue : param.value}
+                      value={
+                        typeof sliderValue === "number"
+                          ? sliderValue
+                          : param.value
+                      }
                       disabled={!sliderSupported}
                       onChange={(newValue) =>
                         handleSliderChange(param.key, newValue)
diff --git a/client/src/components/chat/AgentProposalCard.js b/client/src/components/chat/AgentProposalCard.js
index d6f06ab2..182a89b8 100644
--- a/client/src/components/chat/AgentProposalCard.js
+++ b/client/src/components/chat/AgentProposalCard.js
@@ -1,54 +1,527 @@
-import React from "react";
-import { Button, Space, Tag, Typography } from "antd";
+import React, { useMemo, useState } from "react";
+import { DownOutlined, RightOutlined } from "@ant-design/icons";
+import { Button, Input, Space, Tag, Typography } from "antd";
 
 import { getProposalCardContent } from "../../contexts/workflow/proposalCardConfig";
+import { getApprovalMeta } from "../../design/workflowDesignSystem";
+import AgentBadge, {
+  getAgentBorderStyles,
+  getAgentVisual,
+} from "./AgentVisuals";
 
 const { Text } = Typography;
 
-function AgentProposalCard({ proposal, onApprove, onReject, disabled = false }) {
+const asObject = (value) =>
+  value && typeof value === "object" && !Array.isArray(value) ? value : null;
+
+const toList = (value) => (Array.isArray(value) ? value : []);
+
+const asText = (value) => {
+  if (value === null || value === undefined) return "";
+  if (typeof value === "string") return value.trim();
+  return String(value);
+};
+
+const collectArtifacts = (artifacts = []) =>
+  toList(artifacts)
+    .map((artifact, index) => {
+      if (typeof artifact === "string") {
+        return artifact;
+      }
+      if (!artifact || typeof artifact !== "object") return null;
+      const fallbackKind =
+        artifact.path !== undefined
+          ? "path"
+          : artifact.name !== undefined
+            ? "name"
+            : artifact.id !== undefined
+              ? "id"
+              : artifact.uri !== undefined
+                ? "uri"
+                : null;
+      const kind = asText(
+        artifact.kind || artifact.artifact_type || artifact.type,
+      );
+      const identifier = asText(
+        artifact.path ||
+          artifact.label ||
+          artifact.name ||
+          artifact.uri ||
+          artifact.value ||
+          artifact.id,
+      );
+      const prefix = kind || fallbackKind || "artifact";
+      return identifier
+        ? `${prefix}: ${identifier}`
+        : `${prefix} (#${index + 1})`;
+    })
+    .filter(Boolean);
+
+const collectTracedFacts = (trace = []) =>
+  toList(trace)
+    .filter((item) =>
+      ["checked", "inferred", "proposed", "policy"].includes(
+        item.category || item.status || item.state || "checked",
+      ),
+    )
+    .map((item) => {
+      const label = asText(item.label) || "Operational check";
+      const detail = asText(item.detail);
+      return detail ? `${label}: ${detail}` : label;
+    });
+
+const collectPolicyLines = (proposal = {}, actionCard = {}) => {
+  const policy =
+    asObject(proposal.policy_decision) || asObject(actionCard.policy_decision);
+  const lines = [];
+
+  const decision = asText(
+    policy?.decision ||
+      proposal.decision ||
+      actionCard.policyDecision ||
+      actionCard.decision,
+  );
+  if (decision) {
+    lines.push(`Decision: ${decision}`);
+  }
+
+  const requiresApproval =
+    policy && typeof policy.requires_approval === "boolean"
+      ? policy.requires_approval
+      : typeof actionCard.requires_approval === "boolean"
+        ? actionCard.requires_approval
+        : typeof actionCard.requiresApproval === "boolean"
+          ? actionCard.requiresApproval
+          : typeof proposal.requires_approval === "boolean"
+            ? proposal.requires_approval
+            : typeof proposal.requiresApproval === "boolean"
+              ? proposal.requiresApproval
+              : null;
+  if (typeof requiresApproval === "boolean") {
+    lines.push(requiresApproval ? "Approval required" : "No approval required");
+  }
+
+  const blockers = [
+    ...toList(policy?.blocking_reasons),
+    ...toList(actionCard.blocking_reasons),
+  ].filter(Boolean);
+  if (blockers.length) {
+    lines.push(
+      `Blockers: ${blockers
+        .map(
+          (blocker) => blocker?.reason || blocker?.message || String(blocker),
+        )
+        .join(", ")}`,
+    );
+  }
+  const blockedBy = toList(actionCard.blockers).filter(Boolean);
+  if (blockedBy.length) {
+    lines.push(`Blocked by: ${blockedBy.join(", ")}`);
+  }
+
+  const riskLevel = asText(
+    actionCard.risk_level ||
+      actionCard.riskLevel ||
+      proposal.risk_level ||
+      proposal.riskLevel,
+  );
+  if (riskLevel) {
+    lines.push(`Risk level: ${riskLevel}`);
+  }
+
+  const reason = asText(
+    policy?.reason || actionCard.approval_reason || proposal.approval_reason,
+  );
+  if (reason) {
+    lines.push(reason);
+  }
+
+  const reasonCode = asText(policy?.reason_code || proposal.reason_code);
+  if (reasonCode) {
+    lines.push(`Reason code: ${reasonCode}`);
+  }
+
+  return lines.filter(Boolean);
+};
+
+const collectStatusLines = (proposal = {}) => {
+  const status = asText(proposal.approval_status || "not_required");
+  const statusMeta = getApprovalMeta(status);
+  const lines = [`Approval status: ${statusMeta.label}`];
+
+  const executionStatus = asText(
+    proposal.execution_status ||
+      proposal.executionStatus ||
+      proposal.execution_state ||
+      proposal.executionState,
+  );
+  if (executionStatus) {
+    lines.push(`Execution status: ${executionStatus}`);
+  }
+  const executionReason = asText(
+    proposal.execution_reason || proposal.executionReason,
+  );
+  if (executionReason) {
+    lines.push(`Execution reason: ${executionReason}`);
+  }
+  return lines;
+};
+
+const collectProjectMemoryLines = (proposal = {}, actionCard = {}) => {
+  const updates =
+    asObject(actionCard.project_memory_update) ||
+    asObject(actionCard.project_context_update) ||
+    asObject(proposal.project_memory_update) ||
+    asObject(proposal.project_memory) ||
+    asObject(proposal.project_context_update);
+
+  if (!updates) {
+    return [];
+  }
+
+  return Object.entries(updates)
+    .filter(
+      ([, value]) => value !== undefined && value !== null && value !== "",
+    )
+    .map(([key, value]) => {
+      if (typeof value === "object") {
+        return `${key}: ${asText(JSON.stringify(value))}`;
+      }
+      return `${key}: ${asText(value)}`;
+    });
+};
+
+function ProposalTraceLine({ title, lines }) {
+  if (!lines.length) return null;
+
+  return (
+    <div className="workflow-proposal-card__trace-block">
+      <Text className="workflow-proposal-card__trace-block-title" strong>
+        {title}
+      </Text>
+      <div className="workflow-proposal-card__trace-block-body">
+        {lines.map((line, index) => (
+          <Text
+            key={`${title}-${index}`}
+            className="workflow-proposal-card__trace-line"
+            type="secondary"
+          >
+            {line}
+          </Text>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+function AgentProposalCard({
+  proposal,
+  onApprove,
+  onReject,
+  disabled = false,
+  trace = [],
+}) {
   const content = getProposalCardContent(proposal || {});
+  const approvalMeta = getApprovalMeta(proposal?.approval_status || "pending");
+  const isPending = (proposal?.approval_status || "pending") === "pending";
+  const actionCard = useMemo(
+    () => asObject(proposal?.action_card) || {},
+    [proposal?.action_card],
+  );
+  const specialist = useMemo(
+    () =>
+      asObject(proposal?.specialist_agent) ||
+      asObject(actionCard?.specialist_agent) ||
+      {},
+    [actionCard?.specialist_agent, proposal?.specialist_agent],
+  );
+  const agentVisual = getAgentVisual({
+    ...specialist,
+    agent_label: proposal?.agent_label,
+    agent_color: proposal?.agent_color,
+    agent_icon_key: proposal?.agent_icon_key,
+    agent_border_style: proposal?.agent_border_style,
+  });
+
+  const traceItems = useMemo(
+    () => (Array.isArray(trace) ? trace : []),
+    [trace],
+  );
+  const fields = useMemo(() => content.fields || [], [content.fields]);
+  const editableFields = useMemo(
+    () => fields.filter((field) => field.editable),
+    [fields],
+  );
+
+  const [editing, setEditing] = useState(false);
+  const [draft, setDraft] = useState(() =>
+    editableFields.reduce(
+      (acc, field) => ({
+        ...acc,
+        [field.key]: field.rawValue ?? proposal?.[field.key] ?? "",
+      }),
+      {},
+    ),
+  );
+  const [traceOpen, setTraceOpen] = useState(false);
+
+  const hasEditableFields = editableFields.length > 0;
+  const changedFields = useMemo(() => {
+    if (!hasEditableFields) return {};
+    return editableFields.reduce((acc, field) => {
+      const original = field.rawValue ?? proposal?.[field.key] ?? "";
+      const nextValue = draft[field.key] ?? "";
+      if (String(nextValue) !== String(original)) {
+        acc[field.key] = nextValue;
+      }
+      return acc;
+    }, {});
+  }, [draft, editableFields, hasEditableFields, proposal]);
+
+  const traceSections = useMemo(() => {
+    const inspectedFacts = [
+      ...collectTracedFacts(traceItems),
+      ...(asText(actionCard.inspected_facts)
+        ? [asText(actionCard.inspected_facts)]
+        : []),
+      ...(asText(proposal.inspected_facts)
+        ? [asText(proposal.inspected_facts)]
+        : []),
+    ].filter(Boolean);
+
+    const policyLines = collectPolicyLines(proposal, actionCard);
+    const statusLines = collectStatusLines(proposal);
+    const artifactLines = [
+      ...collectArtifacts(actionCard.input_artifacts).map(
+        (item) => `Input · ${item}`,
+      ),
+      ...collectArtifacts(actionCard.output_artifacts).map(
+        (item) => `Output · ${item}`,
+      ),
+    ];
+    const projectMemoryLines = collectProjectMemoryLines(proposal, actionCard);
+
+    return [
+      {
+        title: "Inspected facts",
+        lines: inspectedFacts,
+      },
+      {
+        title: "Policy decision",
+        lines: policyLines,
+      },
+      {
+        title: "Approval / execution status",
+        lines: statusLines,
+      },
+      {
+        title: "Affected artifacts",
+        lines: artifactLines,
+      },
+      {
+        title: "Project-memory updates",
+        lines: projectMemoryLines,
+      },
+    ].filter((section) => section.lines.length > 0);
+  }, [actionCard, proposal, traceItems]);
+
+  const hasChanges = Object.keys(changedFields).length > 0;
+
+  const resetDraft = () => {
+    setDraft(
+      editableFields.reduce(
+        (acc, field) => ({
+          ...acc,
+          [field.key]: field.rawValue ?? proposal?.[field.key] ?? "",
+        }),
+        {},
+      ),
+    );
+  };
+
+  const beginEditing = () => {
+    if (!isPending || disabled) return;
+    setEditing(true);
+  };
+
+  const endEditing = () => {
+    setEditing(false);
+    resetDraft();
+  };
+
+  const handleEditToggle = () => {
+    if (!editing) {
+      beginEditing();
+      return;
+    }
+    endEditing();
+  };
+
+  const setFieldValue = (field, value) => {
+    setDraft((previous) => ({
+      ...previous,
+      [field]: value,
+    }));
+  };
+
+  const approveLabel = hasChanges ? "Approve with edits" : "Approve";
 
   return (
     <section
       aria-label={`proposal-${content.type}`}
-      style={{
-        border: "1px solid #d9d9d9",
-        borderRadius: 6,
-        padding: 10,
-        background: "#fff",
-        marginTop: 6,
-      }}
+      className={`workflow-proposal-card workflow-tone-${approvalMeta.tone}`}
+      style={getAgentBorderStyles(agentVisual.borderStyle, agentVisual.color)}
     >
       <Space direction="vertical" size={4} style={{ width: "100%" }}>
-        <Space size="small" wrap>
-          <Text strong style={{ fontSize: 12 }}>
+        <div className="workflow-proposal-card__header">
+          <Text className="workflow-proposal-card__title" strong>
             {content.title}
           </Text>
-          <Tag style={{ margin: 0 }}>{content.type}</Tag>
-        </Space>
-        <Text style={{ fontSize: 12 }}>{content.rationale}</Text>
+          <span className="workflow-proposal-card__agent-badge">
+            <AgentBadge agent={agentVisual} />
+          </span>
+          <Tag
+            className="workflow-proposal-card__type-tag"
+            style={{ margin: 0 }}
+          >
+            {content.type}
+          </Tag>
+          <Tag
+            className="workflow-proposal-card__status-tag"
+            color={approvalMeta.color}
+            style={{ margin: 0 }}
+          >
+            {approvalMeta.label}
+          </Tag>
+        </div>
+        <Text
+          className="workflow-proposal-card__rationale"
+          style={{
+            fontSize: 12,
+            whiteSpace: "pre-wrap",
+            wordBreak: "break-word",
+          }}
+        >
+          {content.rationale}
+        </Text>
         {content.fields?.length > 0 && (
-          <div style={{ display: "grid", gridTemplateColumns: "auto 1fr", columnGap: 8, rowGap: 4 }}>
+          <div className="workflow-proposal-card__fields">
             {content.fields.map((field) => (
               <React.Fragment key={field.key}>
-                <Text type="secondary" style={{ fontSize: 11, textTransform: "capitalize" }}>
+                <Text
+                  type="secondary"
+                  className="workflow-proposal-card__field-label"
+                >
                   {field.label}
                 </Text>
-                <Text style={{ fontSize: 11 }}>{field.value}</Text>
+                {editing && isPending ? (
+                  field.editable ? (
+                    <Input.TextArea
+                      autoSize={{ minRows: 1, maxRows: 3 }}
+                      value={draft[field.key] ?? ""}
+                      onChange={(event) =>
+                        setFieldValue(field.key, event.target.value)
+                      }
+                      style={{ fontSize: 11 }}
+                      aria-label={`Edit ${field.label}`}
+                    />
+                  ) : (
+                    <Text
+                      className="workflow-proposal-card__field-value"
+                      style={{
+                        fontSize: 11,
+                        whiteSpace: "pre-wrap",
+                        wordBreak: "break-word",
+                      }}
+                    >
+                      {field.value}
+                    </Text>
+                  )
+                ) : (
+                  <Text
+                    className={
+                      field.editable
+                        ? `workflow-proposal-card__field-value${
+                            isPending
+                              ? " workflow-proposal-card__field-value--editable"
+                              : ""
+                          }`
+                        : "workflow-proposal-card__field-value"
+                    }
+                    style={{
+                      fontSize: 11,
+                      whiteSpace: "pre-wrap",
+                      wordBreak: "break-word",
+                    }}
+                    role={field.editable ? "button" : undefined}
+                    tabIndex={field.editable && isPending ? 0 : -1}
+                    onClick={field.editable ? beginEditing : undefined}
+                    onKeyDown={
+                      field.editable
+                        ? (event) => {
+                            if (event.key === "Enter" || event.key === " ") {
+                              event.preventDefault();
+                              beginEditing();
+                            }
+                          }
+                        : undefined
+                    }
+                    aria-label={
+                      field.editable ? `Edit ${field.label}` : undefined
+                    }
+                  >
+                    {field.value}
+                  </Text>
+                )}
               </React.Fragment>
             ))}
           </div>
         )}
+
+        {traceSections.length > 0 && (
+          <div className="workflow-proposal-card__trace">
+            <Button
+              type="text"
+              size="small"
+              icon={traceOpen ? <DownOutlined /> : <RightOutlined />}
+              onClick={() => setTraceOpen((value) => !value)}
+              style={{ paddingInline: 0, height: 24 }}
+            >
+              Operational trace
+            </Button>
+            {traceOpen && (
+              <div className="workflow-proposal-card__trace-body">
+                {traceSections.map((section) => (
+                  <ProposalTraceLine
+                    key={section.title}
+                    title={section.title}
+                    lines={section.lines}
+                  />
+                ))}
+              </div>
+            )}
+          </div>
+        )}
+
         <Space size="small">
           <Button
             type="primary"
             size="small"
-            onClick={() => onApprove?.(proposal)}
-            disabled={disabled}
+            onClick={() => onApprove?.(proposal, changedFields)}
+            disabled={disabled || !isPending}
           >
-            Approve
+            {approveLabel}
           </Button>
-          <Button size="small" onClick={() => onReject?.(proposal)} disabled={disabled}>
+          {hasEditableFields && isPending && (
+            <Button size="small" onClick={handleEditToggle} disabled={disabled}>
+              {editing ? "Cancel edits" : "Edit details"}
+            </Button>
+          )}
+          <Button
+            size="small"
+            onClick={() => onReject?.(proposal)}
+            disabled={disabled || !isPending}
+          >
             Reject
           </Button>
         </Space>
diff --git a/client/src/components/chat/AgentProposalCard.test.js b/client/src/components/chat/AgentProposalCard.test.js
new file mode 100644
index 00000000..515a09b1
--- /dev/null
+++ b/client/src/components/chat/AgentProposalCard.test.js
@@ -0,0 +1,137 @@
+import React from "react";
+import { fireEvent, render, screen, cleanup } from "@testing-library/react";
+
+import AgentProposalCard from "./AgentProposalCard";
+
+jest.mock("antd", () => ({
+  TextArea: ({ autoSize, children, ...props }) => (
+    <textarea {...props}>{children}</textarea>
+  ),
+  Button: ({ children, ...props }) => (
+    <button type="button" {...props}>
+      {children}
+    </button>
+  ),
+  Input: {
+    TextArea: ({ autoSize, children, ...props }) => (
+      <textarea {...props}>{children}</textarea>
+    ),
+  },
+  Space: ({ children }) => <div>{children}</div>,
+  Tag: ({ children, ...props }) => <span {...props}>{children}</span>,
+  Typography: {
+    Text: ({ children, strong, type, ...props }) => (
+      <span {...props}>{children}</span>
+    ),
+  },
+}));
+
+describe("AgentProposalCard", () => {
+  it("lets users click fields or tap Edit details before approval", () => {
+    const onApprove = jest.fn();
+    const proposal = {
+      id: 12,
+      approval_status: "pending",
+      type: "start_training_run",
+      config_preset: "/project/configs/base.yaml",
+      image_path: "/project/subsets/image",
+      label_path: "/project/subsets/seg",
+      output_path: "/project/outputs/original",
+      autopick_parameters: true,
+    };
+
+    render(<AgentProposalCard proposal={proposal} onApprove={onApprove} />);
+
+    fireEvent.click(screen.getByRole("button", { name: "Edit details" }));
+    fireEvent.change(screen.getByLabelText("Edit Output"), {
+      target: { value: "/project/outputs/edited" },
+    });
+    fireEvent.click(screen.getByRole("button", { name: "Approve with edits" }));
+
+    expect(onApprove).toHaveBeenCalledWith(proposal, {
+      output_path: "/project/outputs/edited",
+    });
+
+    cleanup();
+    render(<AgentProposalCard proposal={proposal} onApprove={onApprove} />);
+    fireEvent.click(screen.getByText("/project/outputs/original"));
+    fireEvent.change(screen.getByLabelText("Edit Output"), {
+      target: { value: "/project/outputs/edited-direct" },
+    });
+    fireEvent.click(screen.getByRole("button", { name: "Approve with edits" }));
+
+    expect(onApprove).toHaveBeenLastCalledWith(proposal, {
+      output_path: "/project/outputs/edited-direct",
+    });
+  });
+
+  it("exposes client-effect paths as editable approval fields", () => {
+    const onApprove = jest.fn();
+    const proposal = {
+      id: 13,
+      approval_status: "pending",
+      type: "run_client_effects",
+      item_label: "Run inference",
+      client_effects: {
+        set_inference_output_path: "/project/outputs/inference",
+      },
+    };
+
+    render(<AgentProposalCard proposal={proposal} onApprove={onApprove} />);
+
+    fireEvent.click(screen.getByRole("button", { name: "Edit details" }));
+    fireEvent.change(screen.getByLabelText("Edit Output"), {
+      target: { value: "/project/outputs/inference-edited" },
+    });
+    fireEvent.click(screen.getByRole("button", { name: "Approve with edits" }));
+
+    expect(onApprove).toHaveBeenCalledWith(proposal, {
+      inference_output_path: "/project/outputs/inference-edited",
+    });
+  });
+
+  it("disables actions after decision is recorded", () => {
+    render(
+      <AgentProposalCard
+        proposal={{
+          approval_status: "approved",
+          type: "start_training_run",
+          config_preset: "/tmp/config.yaml",
+          image_path: "/tmp/image.tif",
+          label_path: "/tmp/label.tif",
+        }}
+      />,
+    );
+
+    expect(screen.getByRole("button", { name: "Approve" }).disabled).toBe(true);
+    expect(screen.getByRole("button", { name: "Reject" }).disabled).toBe(true);
+    expect(screen.queryByRole("button", { name: "Edit details" })).toBeNull();
+  });
+
+  it("keeps long labels and specialist agent badges visible", () => {
+    render(
+      <AgentProposalCard
+        proposal={{
+          type: "specialist_inference_validation_and_retraining_review_pipeline",
+          rationale: "Verify specialist pipeline visibility.",
+          specialist_agent: {
+            agent_label: "Inference Specialist Pipeline Visualization",
+            agent_short_label: "Inference Specialist",
+            agent_color: "#123abc",
+            agent_icon_key: "eye",
+            agent_border_style: "dashed",
+          },
+          foo: "bar",
+        }}
+      />,
+    );
+
+    expect(
+      screen.getByText(
+        "specialist_inference_validation_and_retraining_review_pipeline",
+      ).className,
+    ).toContain("workflow-proposal-card__type-tag");
+    expect(screen.getByText("Inference Specialist")).toBeTruthy();
+    expect(screen.getByText("bar")).toBeTruthy();
+  });
+});
diff --git a/client/src/components/chat/AgentVisuals.js b/client/src/components/chat/AgentVisuals.js
new file mode 100644
index 00000000..4cd04f97
--- /dev/null
+++ b/client/src/components/chat/AgentVisuals.js
@@ -0,0 +1,174 @@
+import React from "react";
+import { Tag } from "antd";
+import {
+  BarChartOutlined,
+  BugOutlined,
+  ExperimentOutlined,
+  EyeOutlined,
+  FileDoneOutlined,
+  FolderOpenOutlined,
+  ProjectOutlined,
+  ThunderboltOutlined,
+} from "@ant-design/icons";
+
+const ICONS = {
+  bar_chart: BarChartOutlined,
+  bug: BugOutlined,
+  experiment: ExperimentOutlined,
+  eye: EyeOutlined,
+  file_done: FileDoneOutlined,
+  folder: FolderOpenOutlined,
+  project: ProjectOutlined,
+  thunderbolt: ThunderboltOutlined,
+};
+
+const ALLOWED_BORDER_STYLES = new Set([
+  "solid",
+  "dotted",
+  "double",
+  "dashed",
+  "thick",
+  "dashdot",
+  "top",
+  "rail",
+]);
+
+const normalizeAgentText = (value) => {
+  if (typeof value !== "string") return "";
+  return value.trim();
+};
+
+const normalizeAgentColor = (value) => {
+  const text = normalizeAgentText(value);
+  if (!text) return DEFAULT_AGENT_VISUAL.color;
+  return text;
+};
+
+const normalizeAgentIconKey = (value) => {
+  const text = normalizeAgentText(value);
+  return ICONS[text] ? text : DEFAULT_AGENT_VISUAL.icon_key;
+};
+
+const normalizeBorderStyle = (value) => {
+  const text = normalizeAgentText(value).toLowerCase();
+  return ALLOWED_BORDER_STYLES.has(text)
+    ? text
+    : DEFAULT_AGENT_VISUAL.border_style;
+};
+
+export const DEFAULT_AGENT_VISUAL = {
+  label: "Project Manager",
+  shortLabel: "PM",
+  color: "#111827",
+  icon_key: "project",
+  border_style: "solid",
+};
+
+export function getAgentVisual(agent = {}) {
+  const explicitLabel =
+    normalizeAgentText(agent.agent_label) || normalizeAgentText(agent.label);
+  const shortLabel =
+    normalizeAgentText(agent.agent_short_label) ||
+    normalizeAgentText(agent.short_label) ||
+    normalizeAgentText(agent.shortLabel);
+
+  return {
+    label: explicitLabel || DEFAULT_AGENT_VISUAL.label,
+    shortLabel: shortLabel || explicitLabel || DEFAULT_AGENT_VISUAL.shortLabel,
+    color: normalizeAgentColor(agent.agent_color || agent.color),
+    iconKey: normalizeAgentIconKey(agent.agent_icon_key || agent.icon_key),
+    borderStyle: normalizeBorderStyle(
+      agent.agent_border_style || agent.border_style,
+    ),
+  };
+}
+
+export function getAgentBorderStyles(borderStyle, color, width = 4) {
+  const accent = color || DEFAULT_AGENT_VISUAL.color;
+  const base = {
+    borderLeft: `${width}px solid ${accent}`,
+  };
+
+  switch (borderStyle) {
+    case "dotted":
+      return { borderLeft: `${width}px dotted ${accent}` };
+    case "double":
+      return { borderLeft: `${Math.max(width + 1, 5)}px double ${accent}` };
+    case "dashed":
+      return { borderLeft: `${width}px dashed ${accent}` };
+    case "thick":
+      return { borderLeft: `${Math.max(width + 2, 6)}px solid ${accent}` };
+    case "dashdot":
+      return {
+        borderLeft: `${width}px solid ${accent}`,
+        borderTop: `2px dashed ${accent}`,
+      };
+    case "top":
+      return {
+        borderLeft: `${width}px solid ${accent}`,
+        borderTop: `3px solid ${accent}`,
+      };
+    case "rail":
+      return {
+        borderLeft: `${width}px solid ${accent}`,
+        boxShadow: `inset ${width + 2}px 0 0 rgba(0, 166, 166, 0.14)`,
+      };
+    default:
+      return base;
+  }
+}
+
+function AgentIcon({ iconKey }) {
+  const Icon = ICONS[iconKey] || ICONS.project;
+  return <Icon aria-hidden="true" />;
+}
+
+function AgentBadge({
+  agent,
+  label,
+  color,
+  iconKey,
+  compact = false,
+  labelMode = "short",
+}) {
+  const visual = getAgentVisual({
+    ...(agent || {}),
+    label,
+    color,
+    icon_key: iconKey,
+  });
+  const displayLabel =
+    labelMode === "full" ? visual.label : visual.shortLabel || visual.label;
+
+  return (
+    <Tag
+      color={visual.color}
+      style={{
+        alignItems: "center",
+        display: "inline-flex",
+        flexShrink: 0,
+        gap: 4,
+        lineHeight: compact ? "16px" : "18px",
+        marginInlineEnd: 0,
+        maxWidth: "none",
+        overflow: "visible",
+        whiteSpace: "normal",
+        fontSize: compact ? 10 : 11,
+      }}
+      title={visual.label}
+    >
+      <AgentIcon iconKey={visual.iconKey} />
+      <span
+        style={{
+          overflowWrap: "anywhere",
+          whiteSpace: "normal",
+          minWidth: 0,
+        }}
+      >
+        {displayLabel}
+      </span>
+    </Tag>
+  );
+}
+
+export default AgentBadge;
diff --git a/client/src/components/chat/AssistantActionCard.js b/client/src/components/chat/AssistantActionCard.js
new file mode 100644
index 00000000..ed106520
--- /dev/null
+++ b/client/src/components/chat/AssistantActionCard.js
@@ -0,0 +1,138 @@
+import React from "react";
+import { Button, Tag, Typography } from "antd";
+import AgentBadge, {
+  DEFAULT_AGENT_VISUAL,
+  getAgentBorderStyles,
+  getAgentVisual,
+} from "./AgentVisuals";
+
+const { Text } = Typography;
+const MONO_FONT =
+  "'SFMono-Regular', Menlo, Monaco, Consolas, 'Liberation Mono', monospace";
+
+const RISK_LABELS = {
+  read_only: "view only",
+  prefills_form: "sets form",
+  loads_editor: "opens editor",
+  runs_job: "runs job",
+  writes_workflow_record: "writes record",
+  exports_evidence: "exports",
+};
+
+function AssistantActionCard({ action, onRun, disabled = false }) {
+  const buttonType = action?.variant === "primary" ? "primary" : "default";
+  const riskLabel = RISK_LABELS[action?.risk_level] || action?.risk_level;
+  const isDisabled = disabled || Boolean(action?.disabled_reason);
+  const specialist = action?.specialist_agent || {};
+  const agentVisual = getAgentVisual({
+    ...specialist,
+    agent_label: action?.agent_label,
+    agent_color: action?.agent_color,
+    agent_icon_key: action?.agent_icon_key,
+    agent_border_style: action?.agent_border_style,
+  });
+  const summaryFields = Array.isArray(action?.summary_fields)
+    ? action.summary_fields.slice(0, 3)
+    : [];
+
+  return (
+    <section
+      aria-label={`assistant-action-${action?.id || "unknown"}`}
+      style={{
+        border: "1px solid #e5e7eb",
+        ...getAgentBorderStyles(
+          agentVisual.borderStyle || DEFAULT_AGENT_VISUAL.border_style,
+          agentVisual.color,
+        ),
+        borderRadius: 12,
+        padding: 12,
+        background: "#fbfbfa",
+      }}
+    >
+      <div
+        style={{
+          display: "flex",
+          justifyContent: "space-between",
+          alignItems: "flex-start",
+          gap: 12,
+        }}
+      >
+        <div style={{ minWidth: 0 }}>
+          <div style={{ display: "flex", alignItems: "center", gap: 6 }}>
+            <AgentBadge agent={agentVisual} />
+            <Text
+              strong
+              style={{ fontSize: 12, display: "block", fontFamily: MONO_FONT }}
+            >
+              {action?.label || "Action"}
+            </Text>
+            {riskLabel && (
+              <Tag
+                style={{
+                  marginInlineEnd: 0,
+                  fontSize: 11,
+                  lineHeight: "18px",
+                }}
+              >
+                {riskLabel}
+              </Tag>
+            )}
+          </div>
+          {action?.description && (
+            <Text
+              type="secondary"
+              style={{ fontSize: 12, display: "block", marginTop: 4 }}
+            >
+              {action.description}
+            </Text>
+          )}
+          {summaryFields.length > 0 && (
+            <div
+              style={{
+                display: "grid",
+                gridTemplateColumns: "auto minmax(0, 1fr)",
+                gap: "2px 8px",
+                marginTop: 8,
+              }}
+            >
+              {summaryFields.map((field, index) => (
+                <React.Fragment key={`${field.label || "field"}-${index}`}>
+                  <Text type="secondary" style={{ fontSize: 11 }}>
+                    {field.label}
+                  </Text>
+                  <Text
+                    style={{
+                      fontSize: 11,
+                      overflow: "hidden",
+                      textOverflow: "ellipsis",
+                      whiteSpace: "nowrap",
+                    }}
+                    title={field.value}
+                  >
+                    {field.value}
+                  </Text>
+                </React.Fragment>
+              ))}
+            </div>
+          )}
+          {action?.disabled_reason && (
+            <Text type="danger" style={{ fontSize: 12, display: "block" }}>
+              {action.disabled_reason}
+            </Text>
+          )}
+        </div>
+        <Button
+          size="small"
+          type={buttonType}
+          onClick={() => onRun?.(action)}
+          disabled={isDisabled}
+          style={{ flexShrink: 0 }}
+        >
+          {action?.run_label || "Run in app"}
+        </Button>
+      </div>
+    </section>
+  );
+}
+
+export default AssistantActionCard;
diff --git a/client/src/components/chat/AssistantCommandCard.js b/client/src/components/chat/AssistantCommandCard.js
new file mode 100644
index 00000000..9a5d33ba
--- /dev/null
+++ b/client/src/components/chat/AssistantCommandCard.js
@@ -0,0 +1,118 @@
+import React, { useState } from "react";
+import { Button, Tag, Typography } from "antd";
+
+const { Text } = Typography;
+const MONO_FONT =
+  "'SFMono-Regular', Menlo, Monaco, Consolas, 'Liberation Mono', monospace";
+
+const RISK_LABELS = {
+  read_only: "view only",
+  prefills_form: "sets form",
+  loads_editor: "opens editor",
+  runs_job: "runs job",
+  writes_workflow_record: "writes record",
+  exports_evidence: "exports",
+};
+
+function AssistantCommandCard({ command, onRun, disabled = false }) {
+  const [showDetails, setShowDetails] = useState(false);
+  const riskLabel = RISK_LABELS[command?.risk_level] || command?.risk_level;
+
+  return (
+    <section
+      aria-label={`assistant-command-${command?.id || "unknown"}`}
+      style={{
+        border: "1px solid #d9d9d9",
+        borderRadius: 12,
+        overflow: "hidden",
+        background: "#ffffff",
+      }}
+    >
+      <div
+        style={{
+          display: "flex",
+          alignItems: "center",
+          justifyContent: "space-between",
+          gap: 12,
+          padding: "10px 12px",
+          borderBottom: "1px solid #f0f0f0",
+          background: "#fafafa",
+        }}
+      >
+        <div style={{ minWidth: 0 }}>
+          <Text
+            strong
+            style={{
+              display: "block",
+              fontSize: 12,
+              fontFamily: MONO_FONT,
+            }}
+          >
+            {command?.title || "App Command"}
+          </Text>
+          {riskLabel && (
+            <Tag
+              style={{
+                marginTop: 4,
+                marginInlineEnd: 0,
+                fontSize: 11,
+                lineHeight: "18px",
+              }}
+            >
+              {riskLabel}
+            </Tag>
+          )}
+        </div>
+        <div style={{ display: "flex", gap: 8, flexShrink: 0 }}>
+          <Button
+            size="small"
+            type="text"
+            onClick={() => setShowDetails((current) => !current)}
+          >
+            {showDetails ? "Hide route" : "Route"}
+          </Button>
+          <Button
+            size="small"
+            type="primary"
+            onClick={() => onRun?.(command)}
+            disabled={disabled}
+          >
+            {command?.run_label || "Execute"}
+          </Button>
+        </div>
+      </div>
+      <div style={{ padding: "10px 12px" }}>
+        {command?.description && (
+          <Text
+            style={{
+              display: "block",
+              fontSize: 12,
+            }}
+            type="secondary"
+          >
+            {command.description}
+          </Text>
+        )}
+        {showDetails && (
+          <pre
+            style={{
+              margin: "10px 0 0",
+              background: "#111827",
+              color: "#f3f4f6",
+              padding: 12,
+              borderRadius: 8,
+              fontSize: 12,
+              overflowX: "auto",
+              fontFamily: MONO_FONT,
+              lineHeight: 1.6,
+            }}
+          >
+            <code>{command?.command}</code>
+          </pre>
+        )}
+      </div>
+    </section>
+  );
+}
+
+export default AssistantCommandCard;
diff --git a/client/src/components/chat/AssistantTrace.js b/client/src/components/chat/AssistantTrace.js
new file mode 100644
index 00000000..0986fad5
--- /dev/null
+++ b/client/src/components/chat/AssistantTrace.js
@@ -0,0 +1,131 @@
+import React, { useState } from "react";
+import { Button, Typography } from "antd";
+import { DownOutlined, RightOutlined } from "@ant-design/icons";
+import AgentBadge, {
+  getAgentBorderStyles,
+  getAgentVisual,
+} from "./AgentVisuals";
+
+const { Text } = Typography;
+
+const CATEGORY_LABELS = {
+  checked: "Checked",
+  inferred: "Inferred",
+  proposed: "Proposed",
+  blocked_by: "Blocked",
+};
+
+const TRACE_SECTION_LABELS = {
+  checked: "Inspected facts",
+  inferred: "Inferred context",
+  proposed: "Decision",
+  blocked_by: "Policy gate",
+};
+
+const getCategory = (item = {}) => item.category || item.status || "checked";
+
+function summarizeTraceSections(traceItems = []) {
+  const grouped = {};
+  traceItems.forEach((item) => {
+    const normalizedCategory = getCategory(item);
+    if (!grouped[normalizedCategory]) grouped[normalizedCategory] = [];
+    grouped[normalizedCategory].push(item);
+  });
+  return Object.keys(TRACE_SECTION_LABELS)
+    .map((category) => ({
+      key: category,
+      label: TRACE_SECTION_LABELS[category],
+      items: grouped[category] || [],
+    }))
+    .concat(
+      Object.keys(grouped)
+        .filter((key) => !(key in TRACE_SECTION_LABELS))
+        .map((key) => ({
+          key,
+          label: CATEGORY_LABELS[key] || key,
+          items: grouped[key] || [],
+        })),
+    )
+    .filter((section) => section.items.length > 0);
+}
+
+function AssistantTrace({ trace = [] }) {
+  const [open, setOpen] = useState(false);
+  const items = Array.isArray(trace) ? trace.filter(Boolean) : [];
+  if (!items.length) return null;
+  const traceSections = summarizeTraceSections(items);
+
+  return (
+    <div style={{ marginTop: 2 }}>
+      <Button
+        type="text"
+        size="small"
+        icon={open ? <DownOutlined /> : <RightOutlined />}
+        onClick={() => setOpen((value) => !value)}
+        style={{
+          height: 24,
+          paddingInline: 0,
+          color: "#6b7280",
+          fontSize: 12,
+          fontWeight: 500,
+        }}
+      >
+        Operational trace
+      </Button>
+      {open && (
+        <div className="assistant-trace__panel">
+          {traceSections.map((section) => (
+            <div key={section.key} className="assistant-trace__section">
+              <Text style={{ fontSize: 11 }} strong>
+                {section.label}
+              </Text>
+              <div className="assistant-trace__items">
+                {section.items.map((item, index) => (
+                  <div
+                    key={`${item.label || "trace"}-${section.key}-${index}`}
+                    className="assistant-trace__item"
+                    style={{
+                      ...getAgentBorderStyles(
+                        item.agent_border_style,
+                        item.agent_color,
+                        3,
+                      ),
+                    }}
+                  >
+                    <div
+                      style={{
+                        alignItems: "center",
+                        display: "flex",
+                        gap: 6,
+                      }}
+                    >
+                      <AgentBadge agent={getAgentVisual(item)} compact />
+                      <Text type="secondary" style={{ fontSize: 11 }}>
+                        {CATEGORY_LABELS[getCategory(item)] ||
+                          getCategory(item) ||
+                          "Step"}
+                      </Text>
+                      <Text style={{ color: "#374151", fontSize: 11 }}>
+                        {item.label || "Operational step"}
+                      </Text>
+                    </div>
+                    {item.detail && (
+                      <Text
+                        type="secondary"
+                        style={{ display: "block", fontSize: 11 }}
+                      >
+                        {item.detail}
+                      </Text>
+                    )}
+                  </div>
+                ))}
+              </div>
+            </div>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
+
+export default AssistantTrace;
diff --git a/client/src/components/workflow/StageHeader.js b/client/src/components/workflow/StageHeader.js
new file mode 100644
index 00000000..c8853b4b
--- /dev/null
+++ b/client/src/components/workflow/StageHeader.js
@@ -0,0 +1,36 @@
+import React from "react";
+import { Button, Space, Tooltip, Typography } from "antd";
+
+import { getStageMeta } from "../../design/workflowDesignSystem";
+
+const { Text } = Typography;
+
+function StageHeader({
+  stage,
+  title = "Segmentation Workflow",
+  subtitle,
+  actionLabel,
+  onAction,
+}) {
+  const meta = getStageMeta(stage);
+  return (
+    <div className={`workflow-stage-header workflow-tone-${meta.tone}`}>
+      <div className="workflow-stage-copy">
+        <Space size="small" wrap>
+          <Tooltip title={subtitle || meta.description}>
+            <Text strong className="workflow-stage-title">
+              {title}
+            </Text>
+          </Tooltip>
+        </Space>
+      </div>
+      {actionLabel && (
+        <Button size="small" type="text" onClick={onAction}>
+          {actionLabel}
+        </Button>
+      )}
+    </div>
+  );
+}
+
+export default StageHeader;
diff --git a/client/src/components/workflow/WorkflowEvidencePanel.js b/client/src/components/workflow/WorkflowEvidencePanel.js
new file mode 100644
index 00000000..2208849d
--- /dev/null
+++ b/client/src/components/workflow/WorkflowEvidencePanel.js
@@ -0,0 +1,1032 @@
+import React, { useMemo, useState } from "react";
+import { Button, Card, Empty, Input, Space, Tag, Typography } from "antd";
+import {
+  computeWorkflowEvaluationResult,
+  exportWorkflowBundle,
+} from "../../api";
+import { useWorkflow } from "../../contexts/WorkflowContext";
+
+const { Text } = Typography;
+
+const METRIC_ROWS = [
+  { key: "dice", label: "Dice", direction: "higher" },
+  { key: "iou", label: "IoU", direction: "higher" },
+  { key: "voxel_accuracy", label: "Voxel accuracy", direction: "higher" },
+  {
+    key: "adapted_rand_error",
+    label: "Adapted Rand error",
+    direction: "lower",
+  },
+  { key: "vi_total", label: "VI total", direction: "lower" },
+];
+
+const EMPTY_ARRAY = [];
+
+function latestByCreatedAt(items = []) {
+  return (
+    [...items].sort((left, right) => {
+      const leftTime = new Date(left.created_at || 0).getTime();
+      const rightTime = new Date(right.created_at || 0).getTime();
+      if (leftTime !== rightTime) return rightTime - leftTime;
+      return (right.id || 0) - (left.id || 0);
+    })[0] || null
+  );
+}
+
+function normalizeText(value) {
+  return String(value || "").toLowerCase();
+}
+
+function findArtifactByPath(artifacts, path) {
+  if (!path) return null;
+  return artifacts.find((artifact) => artifact.path === path) || null;
+}
+
+function findArtifactByHints(artifacts, hints) {
+  return (
+    artifacts.find((artifact) => {
+      const haystack = [
+        artifact.artifact_type,
+        artifact.role,
+        artifact.name,
+        artifact.path,
+        artifact.metadata?.source_payload_key,
+      ]
+        .map(normalizeText)
+        .join(" ");
+      return hints.some((hint) => haystack.includes(hint));
+    }) || null
+  );
+}
+
+function formatMetric(value, { signed = false } = {}) {
+  if (value === null || value === undefined || value === "") return "-";
+  if (typeof value !== "number") return String(value);
+  const rounded = Math.abs(value) >= 10 ? value.toFixed(2) : value.toFixed(4);
+  const trimmed = rounded.replace(/\.?0+$/, "");
+  return signed && value > 0 ? `+${trimmed}` : trimmed;
+}
+
+function formatPath(path) {
+  if (!path) return "Not recorded";
+  return path;
+}
+
+function formatShortPath(path) {
+  if (!path) return "Not selected";
+  const parts = String(path)
+    .split(/[\\/]+/)
+    .filter(Boolean);
+  if (parts.length <= 2) return parts.join("/");
+  return parts.slice(-2).join("/");
+}
+
+function statusForPath(artifacts, path) {
+  if (!path) return { label: "Needed", color: "red" };
+  const artifact = findArtifactByPath(artifacts, path);
+  if (!artifact) return { label: "Selected", color: "default" };
+  return artifact.exists
+    ? { label: "Ready", color: "green" }
+    : { label: "Can't find file", color: "orange" };
+}
+
+function compactObject(value) {
+  return Object.fromEntries(
+    Object.entries(value).filter(
+      ([, entry]) => entry !== undefined && entry !== null && entry !== "",
+    ),
+  );
+}
+
+function summarizeEvidence({
+  workflow,
+  artifacts,
+  modelRuns,
+  correctionSets,
+  evaluationResults,
+}) {
+  const latestEvaluation = latestByCreatedAt(evaluationResults);
+  const latestCorrection = latestByCreatedAt(correctionSets);
+  const completedInferenceRuns = modelRuns.filter(
+    (run) =>
+      run.run_type === "inference" &&
+      run.status === "completed" &&
+      run.output_path,
+  );
+  const baselineRun = completedInferenceRuns[0] || null;
+  const candidateRun =
+    completedInferenceRuns.length > 1
+      ? completedInferenceRuns[completedInferenceRuns.length - 1]
+      : null;
+  const inferenceArtifacts = artifacts.filter(
+    (artifact) => artifact.artifact_type === "inference_output",
+  );
+  const correctionArtifacts = artifacts.filter(
+    (artifact) => artifact.artifact_type === "correction_set",
+  );
+  const labelArtifacts = artifacts.filter((artifact) =>
+    ["label_volume", "mask_volume", "dataset"].includes(artifact.artifact_type),
+  );
+  const baselineArtifact = findArtifactByHints(inferenceArtifacts, [
+    "baseline",
+    "initial",
+  ]);
+  const candidateArtifact = findArtifactByHints(inferenceArtifacts, [
+    "candidate",
+    "after",
+    "result_xy",
+  ]);
+  const correctedArtifact = findArtifactByHints(correctionArtifacts, [
+    "corrected",
+    "correction",
+  ]);
+  const groundTruthArtifact = findArtifactByHints(labelArtifacts, [
+    "ground",
+    "truth",
+    "label",
+  ]);
+
+  const baselinePath =
+    latestEvaluation?.metadata?.baseline_prediction_path ||
+    baselineRun?.output_path ||
+    baselineArtifact?.path ||
+    null;
+  const candidatePath =
+    latestEvaluation?.metadata?.candidate_prediction_path ||
+    candidateRun?.output_path ||
+    workflow?.inference_output_path ||
+    candidateArtifact?.path ||
+    null;
+  const correctedPath =
+    latestCorrection?.corrected_mask_path ||
+    workflow?.corrected_mask_path ||
+    correctedArtifact?.path ||
+    null;
+  const groundTruthPath =
+    latestEvaluation?.metadata?.ground_truth_path ||
+    workflow?.label_path ||
+    workflow?.mask_path ||
+    groundTruthArtifact?.path ||
+    null;
+
+  return {
+    latestEvaluation,
+    latestCorrection,
+    baselineRun,
+    candidateRun,
+    baselinePath,
+    candidatePath,
+    correctedPath,
+    groundTruthPath,
+  };
+}
+
+function parseOptionalInteger(value) {
+  if (value === null || value === undefined || value === "") return undefined;
+  const parsed = Number.parseInt(String(value), 10);
+  return Number.isNaN(parsed) ? undefined : parsed;
+}
+
+function getEvaluationOptions(workflow, latestEvaluation, evaluationInputs) {
+  const metadata = {
+    ...(workflow?.metadata || {}),
+    ...(latestEvaluation?.metadata || {}),
+  };
+  return compactObject({
+    baseline_dataset:
+      evaluationInputs.baselineDataset || metadata.baseline_dataset,
+    candidate_dataset:
+      evaluationInputs.candidateDataset || metadata.candidate_dataset,
+    ground_truth_dataset:
+      evaluationInputs.groundTruthDataset ||
+      metadata.ground_truth_dataset ||
+      metadata.label_dataset ||
+      metadata.mask_dataset,
+    crop: evaluationInputs.crop || metadata.crop || metadata.evaluation_crop,
+    baseline_channel: parseOptionalInteger(
+      evaluationInputs.baselineChannel || metadata.baseline_channel,
+    ),
+    candidate_channel: parseOptionalInteger(
+      evaluationInputs.candidateChannel || metadata.candidate_channel,
+    ),
+    ground_truth_channel: parseOptionalInteger(
+      evaluationInputs.groundTruthChannel || metadata.ground_truth_channel,
+    ),
+  });
+}
+
+function getMissingEvaluationInputs(evidence) {
+  return [
+    ["previous result", evidence.baselinePath],
+    ["new result", evidence.candidatePath],
+    ["reference mask", evidence.groundTruthPath],
+  ]
+    .filter(([, value]) => !value)
+    .map(([label]) => label);
+}
+
+function getPipelineSteps({
+  workflow,
+  artifacts,
+  modelRuns,
+  modelVersions,
+  correctionSets,
+  evaluationResults,
+  events,
+  evidence,
+}) {
+  const hasSourceVolume = Boolean(
+    workflow?.dataset_path ||
+    workflow?.image_path ||
+    artifacts.some((artifact) =>
+      ["dataset", "image_volume"].includes(artifact.artifact_type),
+    ),
+  );
+  const completedTrainingRuns = modelRuns.filter(
+    (run) => run.run_type === "training" && run.status === "completed",
+  );
+  const hasCandidatePrediction = Boolean(
+    evidence.candidateRun ||
+    (evidence.candidatePath &&
+      evidence.candidatePath !== evidence.baselinePath),
+  );
+
+  const hasBundleExport = events.some(
+    (event) => event.event_type === "workflow.bundle_exported",
+  );
+
+  return [
+    {
+      key: "data",
+      label: "Data loaded",
+      complete: hasSourceVolume && Boolean(evidence.groundTruthPath),
+      detail: hasSourceVolume
+        ? "image and reference detected"
+        : "choose image and mask",
+    },
+    {
+      key: "baseline",
+      label: "First result",
+      complete: Boolean(evidence.baselinePath),
+      detail: evidence.baselineRun
+        ? `run #${evidence.baselineRun.id}`
+        : "run model",
+    },
+    {
+      key: "proofreading",
+      label: "Edits saved",
+      complete: Boolean(evidence.correctedPath || correctionSets.length),
+      detail: correctionSets.length
+        ? `${correctionSets.length} saved edit set(s)`
+        : "save or export edits",
+    },
+    {
+      key: "training",
+      label: "Training run",
+      complete: Boolean(completedTrainingRuns.length || modelVersions.length),
+      detail: modelVersions.length
+        ? `${modelVersions.length} model version(s)`
+        : "train on edits",
+    },
+    {
+      key: "candidate",
+      label: "New result",
+      complete: hasCandidatePrediction,
+      detail: evidence.candidateRun
+        ? `run #${evidence.candidateRun.id}`
+        : "run model again",
+    },
+    {
+      key: "evaluation",
+      label: "Improvement check",
+      complete: Boolean(evaluationResults.length),
+      detail: evaluationResults.length
+        ? `${evaluationResults.length} comparison(s)`
+        : "compare results",
+    },
+    {
+      key: "bundle",
+      label: "Research report",
+      complete: hasBundleExport,
+      detail: evaluationResults.length ? "ready to export" : "compare first",
+    },
+  ];
+}
+
+function PipelineMap({ steps }) {
+  const nextBlocked = steps.find((step) => !step.complete);
+
+  return (
+    <div
+      style={{
+        border: "1px solid var(--seg-border-subtle, #e5e7eb)",
+        borderRadius: 10,
+        padding: 12,
+        background: "#fffdf7",
+      }}
+    >
+      <Space size={8} wrap style={{ marginBottom: 10 }}>
+        <Text strong>Loop progress</Text>
+        <Tag color={nextBlocked ? "orange" : "green"} style={{ margin: 0 }}>
+          {nextBlocked ? `next: ${nextBlocked.label}` : "ready"}
+        </Tag>
+      </Space>
+      <div
+        style={{
+          display: "grid",
+          gridTemplateColumns: "repeat(auto-fit, minmax(140px, 1fr))",
+          gap: 8,
+        }}
+      >
+        {steps.map((step, index) => (
+          <div
+            key={step.key}
+            style={{
+              borderRadius: 10,
+              padding: 10,
+              border: step.complete ? "1px solid #b7eb8f" : "1px solid #ffe58f",
+              background: step.complete ? "#f6ffed" : "#fffbe6",
+            }}
+          >
+            <Text style={{ display: "block", fontSize: 11, fontWeight: 700 }}>
+              {index + 1}. {step.label}
+            </Text>
+            <Text type="secondary" style={{ display: "block", fontSize: 11 }}>
+              {step.complete ? "complete" : step.detail}
+            </Text>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+function EvidencePathCard({ title, path, status, detail }) {
+  return (
+    <div
+      style={{
+        border: "1px solid var(--seg-border-subtle, #e5e7eb)",
+        borderRadius: 10,
+        padding: 12,
+        background: "#fff",
+        minWidth: 0,
+      }}
+    >
+      <Space size={6} wrap>
+        <Text strong style={{ fontSize: 12 }}>
+          {title}
+        </Text>
+        <Tag color={status.color} style={{ margin: 0 }}>
+          {status.label}
+        </Tag>
+      </Space>
+      <div
+        style={{
+          marginTop: 8,
+          fontFamily:
+            '"IBM Plex Mono", "SFMono-Regular", Menlo, Monaco, Consolas, monospace',
+          fontSize: 11,
+          color: path ? "#374151" : "#9ca3af",
+          wordBreak: "break-word",
+        }}
+      >
+        {formatPath(path)}
+      </div>
+      {detail && (
+        <Text
+          type="secondary"
+          style={{ display: "block", marginTop: 6, fontSize: 11 }}
+        >
+          {detail}
+        </Text>
+      )}
+    </div>
+  );
+}
+
+function CompactEvidenceRow({ label, path, status }) {
+  return (
+    <div
+      style={{
+        display: "grid",
+        gridTemplateColumns: "96px auto",
+        gap: 8,
+        alignItems: "baseline",
+        padding: "4px 0",
+        borderBottom: "1px solid #f0ece3",
+      }}
+    >
+      <Space size={4}>
+        <Tag color={status.color} style={{ margin: 0 }}>
+          {status.label}
+        </Tag>
+      </Space>
+      <div style={{ minWidth: 0 }}>
+        <Text strong style={{ display: "block", fontSize: 12 }}>
+          {label}
+        </Text>
+        <Text
+          type="secondary"
+          style={{
+            display: "block",
+            overflow: "hidden",
+            fontSize: 11,
+            textOverflow: "ellipsis",
+            whiteSpace: "nowrap",
+          }}
+          title={path || "Not recorded"}
+        >
+          {formatShortPath(path)}
+        </Text>
+      </div>
+    </div>
+  );
+}
+
+function MetricGrid({ evaluation }) {
+  const metrics = evaluation?.metrics || {};
+  const baseline = metrics.baseline || {};
+  const candidate = metrics.candidate || {};
+  const delta = metrics.delta || {};
+  const rows = METRIC_ROWS.filter(
+    (row) =>
+      baseline[row.key] !== undefined ||
+      candidate[row.key] !== undefined ||
+      delta[row.key] !== undefined,
+  );
+
+  if (!evaluation || rows.length === 0) {
+    return (
+      <Empty
+        image={Empty.PRESENTED_IMAGE_SIMPLE}
+        description="No comparison yet"
+        style={{ margin: "8px 0" }}
+      />
+    );
+  }
+
+  return (
+    <div
+      style={{
+        display: "grid",
+        gridTemplateColumns:
+          "minmax(120px, 1.2fr) repeat(3, minmax(72px, 0.8fr)) minmax(86px, 0.8fr)",
+        gap: 8,
+        alignItems: "center",
+        overflowX: "auto",
+      }}
+    >
+      {["Metric", "Previous", "New", "Change", "Goal"].map((label) => (
+        <Text
+          key={label}
+          type="secondary"
+          style={{ fontSize: 11, fontWeight: 700 }}
+        >
+          {label}
+        </Text>
+      ))}
+      {rows.map((row) => {
+        const deltaValue = delta[row.key];
+        const improved =
+          typeof deltaValue === "number"
+            ? row.direction === "higher"
+              ? deltaValue >= 0
+              : deltaValue <= 0
+            : null;
+        return (
+          <React.Fragment key={row.key}>
+            <Text style={{ fontSize: 12 }}>{row.label}</Text>
+            <Text style={{ fontSize: 12 }}>
+              {formatMetric(baseline[row.key])}
+            </Text>
+            <Text style={{ fontSize: 12 }}>
+              {formatMetric(candidate[row.key])}
+            </Text>
+            <Text style={{ fontSize: 12 }}>
+              {formatMetric(deltaValue, { signed: true })}
+            </Text>
+            <Tag
+              color={
+                improved === null ? "default" : improved ? "green" : "orange"
+              }
+              style={{ width: "fit-content", margin: 0 }}
+            >
+              {row.direction === "higher" ? "higher better" : "lower better"}
+            </Tag>
+          </React.Fragment>
+        );
+      })}
+    </div>
+  );
+}
+
+function WorkflowEvidencePanel({ compact = false }) {
+  const workflowContext = useWorkflow();
+  const workflow = workflowContext?.workflow;
+  const events = workflowContext?.events || EMPTY_ARRAY;
+  const artifacts = workflowContext?.artifacts || EMPTY_ARRAY;
+  const modelRuns = workflowContext?.modelRuns || EMPTY_ARRAY;
+  const modelVersions = workflowContext?.modelVersions || EMPTY_ARRAY;
+  const correctionSets = workflowContext?.correctionSets || EMPTY_ARRAY;
+  const evaluationResults = workflowContext?.evaluationResults || EMPTY_ARRAY;
+  const refreshEvidence = workflowContext?.refreshEvidence;
+  const refreshEvents = workflowContext?.refreshEvents;
+  const [computingEvaluation, setComputingEvaluation] = useState(false);
+  const [exportingBundle, setExportingBundle] = useState(false);
+  const [showMetricOptions, setShowMetricOptions] = useState(false);
+  const [computeError, setComputeError] = useState("");
+  const [computeNotice, setComputeNotice] = useState("");
+  const [bundleNotice, setBundleNotice] = useState("");
+  const [evaluationInputs, setEvaluationInputs] = useState({
+    baselineDataset: "",
+    candidateDataset: "",
+    groundTruthDataset: "",
+    crop: "",
+    baselineChannel: "",
+    candidateChannel: "",
+    groundTruthChannel: "",
+  });
+
+  const evidence = useMemo(
+    () =>
+      summarizeEvidence({
+        workflow,
+        artifacts,
+        modelRuns,
+        correctionSets,
+        evaluationResults,
+      }),
+    [workflow, artifacts, modelRuns, correctionSets, evaluationResults],
+  );
+
+  if (!workflowContext || !workflow?.id) {
+    return (
+      <Card size={compact ? "small" : "default"} title="Review status">
+        <Empty
+          image={Empty.PRESENTED_IMAGE_SIMPLE}
+          description="No active workflow yet"
+        />
+      </Card>
+    );
+  }
+
+  const summary = evidence.latestEvaluation?.metrics?.summary || {};
+  const missingEvaluationInputs = getMissingEvaluationInputs(evidence);
+  const pipelineSteps = getPipelineSteps({
+    workflow,
+    artifacts,
+    modelRuns,
+    modelVersions,
+    correctionSets,
+    evaluationResults,
+    events,
+    evidence,
+  });
+  const canComputeEvaluation = missingEvaluationInputs.length === 0;
+  const improved = summary.candidate_improved_dice;
+  const statusTag =
+    improved === true
+      ? { label: "new result improved", color: "green" }
+      : improved === false
+        ? { label: "no Dice gain", color: "orange" }
+        : { label: "not compared yet", color: "default" };
+
+  const handleComputeEvaluation = async () => {
+    if (!canComputeEvaluation || computingEvaluation) return;
+    setComputingEvaluation(true);
+    setComputeError("");
+    setComputeNotice("");
+    try {
+      const result = await computeWorkflowEvaluationResult(
+        workflow.id,
+        compactObject({
+          name: "workflow-before-after-evaluation",
+          baseline_prediction_path: evidence.baselinePath,
+          candidate_prediction_path: evidence.candidatePath,
+          ground_truth_path: evidence.groundTruthPath,
+          baseline_run_id: evidence.baselineRun?.id,
+          candidate_run_id: evidence.candidateRun?.id,
+          metadata: {
+            source: "workflow_evidence_panel",
+            corrected_mask_path: evidence.correctedPath,
+          },
+          ...getEvaluationOptions(
+            workflow,
+            evidence.latestEvaluation,
+            evaluationInputs,
+          ),
+        }),
+      );
+      setComputeNotice(result?.summary || "Comparison computed.");
+      await refreshEvidence?.();
+    } catch (error) {
+      setComputeError(error.message || "Failed to compute evaluation metrics.");
+    } finally {
+      setComputingEvaluation(false);
+    }
+  };
+
+  const handleExportBundle = async () => {
+    if (exportingBundle) return;
+    setExportingBundle(true);
+    setComputeError("");
+    setBundleNotice("");
+    try {
+      const bundle = await exportWorkflowBundle(workflow.id);
+      const artifactPaths = bundle?.artifact_paths || [];
+      const missingCount = artifactPaths.filter(
+        (entry) => !entry.exists,
+      ).length;
+      setBundleNotice(
+        `Report exported: ${bundle?.artifacts?.length || 0} files, ${bundle?.model_runs?.length || 0} runs, ${bundle?.evaluation_results?.length || 0} comparisons, ${missingCount} missing paths.`,
+      );
+      await refreshEvents?.();
+    } catch (error) {
+      setComputeError(error.message || "Failed to export report bundle.");
+    } finally {
+      setExportingBundle(false);
+    }
+  };
+
+  if (compact) {
+    const completeEvidenceCount = [
+      evidence.baselinePath,
+      evidence.candidatePath,
+      evidence.correctedPath,
+      evidence.groundTruthPath,
+    ].filter(Boolean).length;
+
+    return (
+      <Card
+        size="small"
+        title={
+          <Space size={6} wrap>
+            <span>Review status</span>
+            <Tag color={statusTag.color} style={{ margin: 0 }}>
+              {statusTag.label}
+            </Tag>
+            <Tag
+              color={completeEvidenceCount === 4 ? "green" : "gold"}
+              style={{ margin: 0 }}
+            >
+              {completeEvidenceCount}/4 ready
+            </Tag>
+          </Space>
+        }
+        extra={
+          <Button size="small" type="text" onClick={() => refreshEvidence?.()}>
+            Refresh
+          </Button>
+        }
+      >
+        <Space direction="vertical" size={8} style={{ width: "100%" }}>
+          <div>
+            <CompactEvidenceRow
+              label="Previous result"
+              path={evidence.baselinePath}
+              status={statusForPath(artifacts, evidence.baselinePath)}
+            />
+            <CompactEvidenceRow
+              label="New result"
+              path={evidence.candidatePath}
+              status={statusForPath(artifacts, evidence.candidatePath)}
+            />
+            <CompactEvidenceRow
+              label="Your edits"
+              path={evidence.correctedPath}
+              status={statusForPath(artifacts, evidence.correctedPath)}
+            />
+            <CompactEvidenceRow
+              label="Reference mask"
+              path={evidence.groundTruthPath}
+              status={statusForPath(artifacts, evidence.groundTruthPath)}
+            />
+          </div>
+          <Space size={6} wrap>
+            <Text strong style={{ fontSize: 12 }}>
+              Metrics
+            </Text>
+            {summary.dice_delta !== undefined ? (
+              <Tag color={summary.dice_delta >= 0 ? "green" : "orange"}>
+                Dice {formatMetric(summary.dice_delta, { signed: true })}
+              </Tag>
+            ) : (
+              <Text type="secondary" style={{ fontSize: 12 }}>
+                Not computed
+              </Text>
+            )}
+          </Space>
+          {!canComputeEvaluation && (
+            <Text type="secondary" style={{ fontSize: 12 }}>
+              Needed: {missingEvaluationInputs.join(", ")}
+            </Text>
+          )}
+        </Space>
+      </Card>
+    );
+  }
+
+  return (
+    <Card
+      size="default"
+      title={
+        <Space size={8} wrap>
+          <span>Review status</span>
+          <Tag color={statusTag.color} style={{ margin: 0 }}>
+            {statusTag.label}
+          </Tag>
+        </Space>
+      }
+      extra={
+        <Space size={8} wrap>
+          <Button
+            size="small"
+            onClick={handleComputeEvaluation}
+            disabled={!canComputeEvaluation || computingEvaluation}
+            loading={computingEvaluation}
+          >
+            Compare results
+          </Button>
+          <Button size="small" onClick={() => refreshEvidence?.()}>
+            Refresh
+          </Button>
+          <Button
+            size="small"
+            onClick={handleExportBundle}
+            loading={exportingBundle}
+          >
+            Export report
+          </Button>
+        </Space>
+      }
+    >
+      <Space direction="vertical" size={12} style={{ width: "100%" }}>
+        <div
+          style={{
+            display: "grid",
+            gridTemplateColumns: compact
+              ? "1fr"
+              : "repeat(auto-fit, minmax(220px, 1fr))",
+            gap: 10,
+          }}
+        >
+          <EvidencePathCard
+            title="Previous result"
+            path={evidence.baselinePath}
+            status={statusForPath(artifacts, evidence.baselinePath)}
+            detail={
+              evidence.baselineRun
+                ? `run #${evidence.baselineRun.id}`
+                : "first model output"
+            }
+          />
+          <EvidencePathCard
+            title="New result"
+            path={evidence.candidatePath}
+            status={statusForPath(artifacts, evidence.candidatePath)}
+            detail={
+              evidence.candidateRun
+                ? `run #${evidence.candidateRun.id}`
+                : "latest model output"
+            }
+          />
+          <EvidencePathCard
+            title="Your saved edits"
+            path={evidence.correctedPath}
+            status={statusForPath(artifacts, evidence.correctedPath)}
+            detail={
+              evidence.latestCorrection
+                ? `${evidence.latestCorrection.edit_count || 0} edits, ${evidence.latestCorrection.region_count || 0} regions`
+                : "save or export edits from proofreading"
+            }
+          />
+          <EvidencePathCard
+            title="Reference mask"
+            path={evidence.groundTruthPath}
+            status={statusForPath(artifacts, evidence.groundTruthPath)}
+            detail="mask used to check improvement"
+          />
+        </div>
+
+        {!compact && <PipelineMap steps={pipelineSteps} />}
+
+        <div
+          style={{
+            border: "1px solid var(--seg-border-subtle, #e5e7eb)",
+            borderRadius: 10,
+            padding: 12,
+            background: "#fbfbfa",
+          }}
+        >
+          {!compact && (
+            <div style={{ marginBottom: showMetricOptions ? 12 : 8 }}>
+              <Button
+                size="small"
+                type="text"
+                onClick={() => setShowMetricOptions((current) => !current)}
+              >
+                {showMetricOptions ? "Hide metric options" : "Metric options"}
+              </Button>
+            </div>
+          )}
+          {!compact && showMetricOptions && (
+            <div
+              style={{
+                marginBottom: 12,
+                display: "grid",
+                gridTemplateColumns: "repeat(auto-fit, minmax(160px, 1fr))",
+                gap: 8,
+              }}
+            >
+              <Input
+                size="small"
+                aria-label="Baseline dataset key"
+                placeholder="previous result dataset key"
+                value={evaluationInputs.baselineDataset}
+                onChange={(event) =>
+                  setEvaluationInputs((current) => ({
+                    ...current,
+                    baselineDataset: event.target.value,
+                  }))
+                }
+              />
+              <Input
+                size="small"
+                aria-label="Candidate dataset key"
+                placeholder="new result dataset key"
+                value={evaluationInputs.candidateDataset}
+                onChange={(event) =>
+                  setEvaluationInputs((current) => ({
+                    ...current,
+                    candidateDataset: event.target.value,
+                  }))
+                }
+              />
+              <Input
+                size="small"
+                aria-label="Ground truth dataset key"
+                placeholder="reference mask dataset key"
+                value={evaluationInputs.groundTruthDataset}
+                onChange={(event) =>
+                  setEvaluationInputs((current) => ({
+                    ...current,
+                    groundTruthDataset: event.target.value,
+                  }))
+                }
+              />
+              <Input
+                size="small"
+                aria-label="Evaluation crop"
+                placeholder="crop e.g. 0:32,0:256,0:256"
+                value={evaluationInputs.crop}
+                onChange={(event) =>
+                  setEvaluationInputs((current) => ({
+                    ...current,
+                    crop: event.target.value,
+                  }))
+                }
+              />
+              <Input
+                size="small"
+                aria-label="Baseline channel"
+                placeholder="previous result channel"
+                value={evaluationInputs.baselineChannel}
+                onChange={(event) =>
+                  setEvaluationInputs((current) => ({
+                    ...current,
+                    baselineChannel: event.target.value,
+                  }))
+                }
+              />
+              <Input
+                size="small"
+                aria-label="Candidate channel"
+                placeholder="new result channel"
+                value={evaluationInputs.candidateChannel}
+                onChange={(event) =>
+                  setEvaluationInputs((current) => ({
+                    ...current,
+                    candidateChannel: event.target.value,
+                  }))
+                }
+              />
+              <Input
+                size="small"
+                aria-label="Ground truth channel"
+                placeholder="reference mask channel"
+                value={evaluationInputs.groundTruthChannel}
+                onChange={(event) =>
+                  setEvaluationInputs((current) => ({
+                    ...current,
+                    groundTruthChannel: event.target.value,
+                  }))
+                }
+              />
+            </div>
+          )}
+          <Space size={8} wrap style={{ marginBottom: 8 }}>
+            <Text strong>Improvement</Text>
+            {summary.dice_delta !== undefined && (
+              <Tag color={summary.dice_delta >= 0 ? "green" : "orange"}>
+                Dice {formatMetric(summary.dice_delta, { signed: true })}
+              </Tag>
+            )}
+            {summary.iou_delta !== undefined && (
+              <Tag color={summary.iou_delta >= 0 ? "green" : "orange"}>
+                IoU {formatMetric(summary.iou_delta, { signed: true })}
+              </Tag>
+            )}
+            {summary.voxel_accuracy_delta !== undefined && (
+              <Tag
+                color={summary.voxel_accuracy_delta >= 0 ? "green" : "orange"}
+              >
+                Accuracy{" "}
+                {formatMetric(summary.voxel_accuracy_delta, { signed: true })}
+              </Tag>
+            )}
+          </Space>
+          <MetricGrid evaluation={evidence.latestEvaluation} />
+          {!canComputeEvaluation && (
+            <Text
+              type="secondary"
+              style={{ display: "block", marginTop: 8, fontSize: 12 }}
+            >
+              Need {missingEvaluationInputs.join(", ")} before metrics can be
+              computed.
+            </Text>
+          )}
+          {computeNotice && (
+            <Text
+              style={{
+                display: "block",
+                marginTop: 8,
+                fontSize: 12,
+                color: "#2f7d32",
+              }}
+            >
+              {computeNotice}
+            </Text>
+          )}
+          {bundleNotice && (
+            <Text
+              style={{
+                display: "block",
+                marginTop: 8,
+                fontSize: 12,
+                color: "var(--seg-accent-primary, #3f37c9)",
+              }}
+            >
+              {bundleNotice}
+            </Text>
+          )}
+          {computeError && (
+            <Text
+              style={{
+                display: "block",
+                marginTop: 8,
+                fontSize: 12,
+                color: "#b13a2f",
+              }}
+            >
+              {computeError}
+            </Text>
+          )}
+        </div>
+
+        {evidence.latestEvaluation ? (
+          <div>
+            <Text strong style={{ fontSize: 12 }}>
+              Latest comparison
+            </Text>
+            <Text style={{ display: "block", fontSize: 12 }}>
+              {evidence.latestEvaluation.summary ||
+                evidence.latestEvaluation.name ||
+                "Comparison recorded."}
+            </Text>
+            {evidence.latestEvaluation.report_path && (
+              <Text
+                type="secondary"
+                style={{
+                  display: "block",
+                  fontSize: 11,
+                  wordBreak: "break-word",
+                  fontFamily:
+                    '"IBM Plex Mono", "SFMono-Regular", Menlo, Monaco, Consolas, monospace',
+                }}
+              >
+                Report: {evidence.latestEvaluation.report_path}
+              </Text>
+            )}
+          </div>
+        ) : (
+          <Text type="secondary" style={{ fontSize: 12 }}>
+            No comparison yet. Register previous and new results, then compare
+            them.
+          </Text>
+        )}
+      </Space>
+    </Card>
+  );
+}
+
+export default WorkflowEvidencePanel;
diff --git a/client/src/components/workflow/WorkflowEvidencePanel.test.js b/client/src/components/workflow/WorkflowEvidencePanel.test.js
new file mode 100644
index 00000000..06de192b
--- /dev/null
+++ b/client/src/components/workflow/WorkflowEvidencePanel.test.js
@@ -0,0 +1,318 @@
+import React from "react";
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
+
+import WorkflowEvidencePanel from "./WorkflowEvidencePanel";
+import { WorkflowContext } from "../../contexts/WorkflowContext";
+import {
+  computeWorkflowEvaluationResult,
+  exportWorkflowBundle,
+} from "../../api";
+
+jest.mock("../../api", () => ({
+  computeWorkflowEvaluationResult: jest.fn(),
+  exportWorkflowBundle: jest.fn(),
+}));
+
+jest.mock("antd", () => {
+  const React = require("react");
+  const Card = ({ title, extra, children }) => (
+    <section>
+      <header>
+        {title}
+        {extra}
+      </header>
+      {children}
+    </section>
+  );
+  const Empty = ({ description }) => <div>{description}</div>;
+  Empty.PRESENTED_IMAGE_SIMPLE = "simple";
+  return {
+    Button: ({ children, loading, ...props }) => (
+      <button type="button" {...props}>
+        {children}
+      </button>
+    ),
+    Card,
+    Empty,
+    Input: ({ ...props }) => <input {...props} />,
+    Space: ({ children }) => <div>{children}</div>,
+    Tag: ({ children }) => <span>{children}</span>,
+    Typography: {
+      Text: ({ children }) => <span>{children}</span>,
+    },
+  };
+});
+
+jest.mock("../../contexts/WorkflowContext", () => {
+  const React = require("react");
+  const WorkflowContext = React.createContext(null);
+  return {
+    WorkflowContext,
+    useWorkflow: () => React.useContext(WorkflowContext),
+  };
+});
+
+function renderPanel(value = {}) {
+  const contextValue = {
+    workflow: {
+      id: 11,
+      stage: "evaluation",
+      image_path: "/tmp/image.tif",
+      corrected_mask_path: "/tmp/corrected-mask.tif",
+    },
+    events: [
+      {
+        id: 9,
+        event_type: "workflow.bundle_exported",
+      },
+    ],
+    artifacts: [
+      {
+        id: 1,
+        artifact_type: "inference_output",
+        role: "prediction",
+        path: "/tmp/baseline-prediction.tif",
+        exists: true,
+      },
+      {
+        id: 2,
+        artifact_type: "inference_output",
+        role: "prediction",
+        path: "/tmp/candidate-prediction.tif",
+        exists: true,
+      },
+      {
+        id: 3,
+        artifact_type: "correction_set",
+        role: "corrected_mask",
+        path: "/tmp/corrected-mask.tif",
+        exists: true,
+      },
+    ],
+    modelRuns: [
+      {
+        id: 4,
+        run_type: "inference",
+        status: "completed",
+        output_path: "/tmp/baseline-prediction.tif",
+        created_at: "2026-04-25T10:00:00Z",
+      },
+      {
+        id: 5,
+        run_type: "inference",
+        status: "completed",
+        output_path: "/tmp/candidate-prediction.tif",
+        created_at: "2026-04-25T10:10:00Z",
+      },
+    ],
+    modelVersions: [
+      {
+        id: 8,
+        version_label: "candidate",
+        status: "candidate",
+      },
+    ],
+    correctionSets: [
+      {
+        id: 6,
+        corrected_mask_path: "/tmp/corrected-mask.tif",
+        edit_count: 12,
+        region_count: 3,
+        created_at: "2026-04-25T10:05:00Z",
+      },
+    ],
+    evaluationResults: [
+      {
+        id: 7,
+        name: "before-after",
+        summary: "Before/after evaluation computed.",
+        report_path: "/tmp/evaluation-report.json",
+        created_at: "2026-04-25T10:15:00Z",
+        metadata: {
+          baseline_prediction_path: "/tmp/baseline-prediction.tif",
+          candidate_prediction_path: "/tmp/candidate-prediction.tif",
+          ground_truth_path: "/tmp/ground-truth.tif",
+        },
+        metrics: {
+          baseline: { dice: 0.5, iou: 0.4, voxel_accuracy: 0.8 },
+          candidate: { dice: 0.75, iou: 0.6, voxel_accuracy: 0.9 },
+          delta: { dice: 0.25, iou: 0.2, voxel_accuracy: 0.1 },
+          summary: {
+            dice_delta: 0.25,
+            iou_delta: 0.2,
+            voxel_accuracy_delta: 0.1,
+            candidate_improved_dice: true,
+          },
+        },
+      },
+    ],
+    refreshEvidence: jest.fn(),
+    refreshEvents: jest.fn(),
+    ...value,
+  };
+
+  render(
+    <WorkflowContext.Provider value={contextValue}>
+      <WorkflowEvidencePanel />
+    </WorkflowContext.Provider>,
+  );
+  return contextValue;
+}
+
+describe("WorkflowEvidencePanel", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    computeWorkflowEvaluationResult.mockResolvedValue({
+      summary: "Before/after evaluation computed. Dice delta: 0.25.",
+    });
+    exportWorkflowBundle.mockResolvedValue({
+      artifacts: [{ id: 1 }, { id: 2 }],
+      model_runs: [{ id: 3 }],
+      evaluation_results: [{ id: 4 }],
+      artifact_paths: [
+        { path: "/tmp/a.tif", exists: true },
+        { path: "/tmp/missing.tif", exists: false },
+      ],
+    });
+  });
+
+  it("renders baseline, candidate, corrected mask, and metric deltas", () => {
+    renderPanel();
+
+    expect(screen.getByText("Review status")).toBeTruthy();
+    expect(screen.getByText("new result improved")).toBeTruthy();
+    expect(screen.getByText("Previous result")).toBeTruthy();
+    expect(screen.getByText("/tmp/baseline-prediction.tif")).toBeTruthy();
+    expect(screen.getByText("New result")).toBeTruthy();
+    expect(screen.getByText("/tmp/candidate-prediction.tif")).toBeTruthy();
+    expect(screen.getByText("Your saved edits")).toBeTruthy();
+    expect(screen.getByText("/tmp/corrected-mask.tif")).toBeTruthy();
+    expect(screen.getByText("Dice +0.25")).toBeTruthy();
+    expect(screen.getByText("IoU +0.2")).toBeTruthy();
+    expect(screen.getByText("Accuracy +0.1")).toBeTruthy();
+    expect(screen.getByText("Before/after evaluation computed.")).toBeTruthy();
+    expect(
+      screen.getByText("Report: /tmp/evaluation-report.json"),
+    ).toBeTruthy();
+    expect(screen.getByText("Loop progress")).toBeTruthy();
+    expect(screen.getByText("ready")).toBeTruthy();
+  });
+
+  it("exposes a refresh action for current workflow evidence", () => {
+    const value = renderPanel();
+
+    fireEvent.click(screen.getByText("Refresh"));
+
+    expect(value.refreshEvidence).toHaveBeenCalledTimes(1);
+  });
+
+  it("computes before/after metrics from recorded evidence paths", async () => {
+    const value = renderPanel();
+
+    fireEvent.click(screen.getByText("Compare results"));
+
+    await waitFor(() => {
+      expect(computeWorkflowEvaluationResult).toHaveBeenCalledWith(
+        11,
+        expect.objectContaining({
+          name: "workflow-before-after-evaluation",
+          baseline_prediction_path: "/tmp/baseline-prediction.tif",
+          candidate_prediction_path: "/tmp/candidate-prediction.tif",
+          ground_truth_path: "/tmp/ground-truth.tif",
+          baseline_run_id: 4,
+          candidate_run_id: 5,
+          metadata: expect.objectContaining({
+            source: "workflow_evidence_panel",
+            corrected_mask_path: "/tmp/corrected-mask.tif",
+          }),
+        }),
+      );
+    });
+    await waitFor(() => {
+      expect(value.refreshEvidence).toHaveBeenCalledTimes(1);
+      expect(
+        screen.getByText("Before/after evaluation computed. Dice delta: 0.25."),
+      ).toBeTruthy();
+    });
+  });
+
+  it("passes dataset, crop, and channel controls into metric computation", async () => {
+    renderPanel();
+
+    fireEvent.click(screen.getByText("Metric options"));
+    fireEvent.change(screen.getByLabelText("Baseline dataset key"), {
+      target: { value: "vol0" },
+    });
+    fireEvent.change(screen.getByLabelText("Candidate dataset key"), {
+      target: { value: "vol0" },
+    });
+    fireEvent.change(screen.getByLabelText("Ground truth dataset key"), {
+      target: { value: "data" },
+    });
+    fireEvent.change(screen.getByLabelText("Evaluation crop"), {
+      target: { value: "0:4,0:128,0:128" },
+    });
+    fireEvent.change(screen.getByLabelText("Baseline channel"), {
+      target: { value: "1" },
+    });
+    fireEvent.change(screen.getByLabelText("Candidate channel"), {
+      target: { value: "1" },
+    });
+
+    fireEvent.click(screen.getByText("Compare results"));
+
+    await waitFor(() => {
+      expect(computeWorkflowEvaluationResult).toHaveBeenCalledWith(
+        11,
+        expect.objectContaining({
+          baseline_dataset: "vol0",
+          candidate_dataset: "vol0",
+          ground_truth_dataset: "data",
+          crop: "0:4,0:128,0:128",
+          baseline_channel: 1,
+          candidate_channel: 1,
+        }),
+      );
+    });
+  });
+
+  it("exports a workflow bundle and summarizes artifact existence", async () => {
+    const value = renderPanel();
+
+    fireEvent.click(screen.getByText("Export report"));
+
+    await waitFor(() => {
+      expect(exportWorkflowBundle).toHaveBeenCalledWith(11);
+      expect(
+        screen.getByText(
+          "Report exported: 2 files, 1 runs, 1 comparisons, 1 missing paths.",
+        ),
+      ).toBeTruthy();
+    });
+    expect(value.refreshEvents).toHaveBeenCalledTimes(1);
+  });
+
+  it("blocks metric computation until all required paths are recorded", () => {
+    renderPanel({
+      evaluationResults: [],
+      modelRuns: [],
+      artifacts: [],
+      workflow: { id: 11, stage: "evaluation" },
+    });
+
+    expect(screen.getByText("Compare results").disabled).toBe(true);
+    expect(
+      screen.getByText(/Need previous result, new result, reference mask/),
+    ).toBeTruthy();
+  });
+
+  it("shows an empty state without an active workflow", () => {
+    render(
+      <WorkflowContext.Provider value={{ workflow: null }}>
+        <WorkflowEvidencePanel />
+      </WorkflowContext.Provider>,
+    );
+
+    expect(screen.getByText("No active workflow yet")).toBeTruthy();
+  });
+});
diff --git a/client/src/configSchema.js b/client/src/configSchema.js
index 23e6ca86..b5db2f3e 100644
--- a/client/src/configSchema.js
+++ b/client/src/configSchema.js
@@ -110,6 +110,10 @@ function resolveSliderPath(configObj, type, key) {
   return pickFirstExistingPath(configObj, candidates);
 }
 
+export function getSliderPath(configObj, type, key) {
+  return resolveSliderPath(configObj, type, key);
+}
+
 export function getSliderValue(configObj, type, key) {
   const path = resolveSliderPath(configObj, type, key);
   return path ? getPathValue(configObj, path) : undefined;
@@ -135,14 +139,26 @@ export function setTrainingOutputPath(configObj, outputPath) {
   }
   const checkpointsPath = joinPath(outputPath, "checkpoints");
   if (hasPath(configObj, ["train", "monitor", "checkpoint", "dirpath"])) {
-    setPathValue(configObj, ["train", "monitor", "checkpoint", "dirpath"], checkpointsPath);
+    setPathValue(
+      configObj,
+      ["train", "monitor", "checkpoint", "dirpath"],
+      checkpointsPath,
+    );
     return;
   }
   if (hasPath(configObj, ["monitor", "checkpoint", "dirpath"])) {
-    setPathValue(configObj, ["monitor", "checkpoint", "dirpath"], checkpointsPath);
+    setPathValue(
+      configObj,
+      ["monitor", "checkpoint", "dirpath"],
+      checkpointsPath,
+    );
     return;
   }
-  setPathValue(configObj, ["monitor", "checkpoint", "dirpath"], checkpointsPath);
+  setPathValue(
+    configObj,
+    ["monitor", "checkpoint", "dirpath"],
+    checkpointsPath,
+  );
 }
 
 export function setInferenceOutputPath(configObj, outputPath) {
@@ -152,7 +168,11 @@ export function setInferenceOutputPath(configObj, outputPath) {
     setPathValue(configObj, ["INFERENCE", "OUTPUT_PATH"], outputPath);
     return;
   }
-  setPathValue(configObj, ["inference", "save_prediction", "output_path"], outputPath);
+  setPathValue(
+    configObj,
+    ["inference", "save_prediction", "output_path"],
+    outputPath,
+  );
 }
 
 export function setInferenceExecutionDefaults(configObj) {
@@ -192,6 +212,14 @@ export function applyInputPaths(
       ["DATASET", "IMAGE_NAME"],
       inputImagePath.replace(inputPath, ""),
     );
+    if (mode === "inference") {
+      setPathValue(configObj, ["INFERENCE", "INPUT_PATH"], inputPath || null);
+      setPathValue(
+        configObj,
+        ["INFERENCE", "IMAGE_NAME"],
+        inputImagePath.replace(inputPath, ""),
+      );
+    }
     if (hasLabelPath) {
       setPathValue(
         configObj,
@@ -212,16 +240,14 @@ export function applyInputPaths(
   }
 
   if (mode === "training") {
-    const imagePath =
-      pickFirstExistingPath(configObj, [
-        ["train", "data", "train", "image"],
-        ["data", "train", "image"],
-      ]) || ["train", "data", "train", "image"];
-    const labelPath =
-      pickFirstExistingPath(configObj, [
-        ["train", "data", "train", "label"],
-        ["data", "train", "label"],
-      ]) || ["train", "data", "train", "label"];
+    const imagePath = pickFirstExistingPath(configObj, [
+      ["train", "data", "train", "image"],
+      ["data", "train", "image"],
+    ]) || ["train", "data", "train", "image"];
+    const labelPath = pickFirstExistingPath(configObj, [
+      ["train", "data", "train", "label"],
+      ["data", "train", "label"],
+    ]) || ["train", "data", "train", "label"];
     setPathValue(configObj, imagePath, inputImagePath);
     setPathValue(configObj, labelPath, inputLabelPath);
     if (outputPath) {
@@ -230,16 +256,14 @@ export function applyInputPaths(
     return;
   }
 
-  const imagePath =
-    pickFirstExistingPath(configObj, [
-      ["test", "data", "test", "image"],
-      ["data", "test", "image"],
-    ]) || ["test", "data", "test", "image"];
-  const labelPath =
-    pickFirstExistingPath(configObj, [
-      ["test", "data", "test", "label"],
-      ["data", "test", "label"],
-    ]) || ["test", "data", "test", "label"];
+  const imagePath = pickFirstExistingPath(configObj, [
+    ["test", "data", "test", "image"],
+    ["data", "test", "image"],
+  ]) || ["test", "data", "test", "image"];
+  const labelPath = pickFirstExistingPath(configObj, [
+    ["test", "data", "test", "label"],
+    ["data", "test", "label"],
+  ]) || ["test", "data", "test", "label"];
   setPathValue(configObj, imagePath, inputImagePath);
   if (hasLabelPath) {
     setPathValue(configObj, labelPath, inputLabelPath);
@@ -251,34 +275,27 @@ export function applyInputPaths(
   }
 }
 
-export function getArchitectureValue(configObj) {
-  if (!isObject(configObj)) return undefined;
-  const path = pickFirstExistingPath(configObj, [
+export function getArchitecturePath(configObj) {
+  if (!isObject(configObj)) return null;
+  return pickFirstExistingPath(configObj, [
     ["MODEL", "ARCHITECTURE"],
     ["model", "arch", "type"],
     ["default", "model", "arch", "profile"],
   ]);
+}
+
+export function getArchitectureValue(configObj) {
+  const path = getArchitecturePath(configObj);
   return path ? getPathValue(configObj, path) : undefined;
 }
 
 export function isArchitectureSupported(configObj) {
-  if (!isObject(configObj)) return false;
-  return Boolean(
-    pickFirstExistingPath(configObj, [
-      ["MODEL", "ARCHITECTURE"],
-      ["model", "arch", "type"],
-      ["default", "model", "arch", "profile"],
-    ]),
-  );
+  return Boolean(getArchitecturePath(configObj));
 }
 
 export function setArchitectureValue(configObj, value) {
   if (!isObject(configObj)) return false;
-  const existingPath = pickFirstExistingPath(configObj, [
-    ["MODEL", "ARCHITECTURE"],
-    ["model", "arch", "type"],
-    ["default", "model", "arch", "profile"],
-  ]);
+  const existingPath = getArchitecturePath(configObj);
   if (existingPath) {
     setPathValue(configObj, existingPath, value);
     return true;
diff --git a/client/src/contexts/GlobalContext.js b/client/src/contexts/GlobalContext.js
index 9eb4ecad..43297b93 100644
--- a/client/src/contexts/GlobalContext.js
+++ b/client/src/contexts/GlobalContext.js
@@ -1,4 +1,4 @@
-import React, { createContext, useState, useEffect, useCallback } from "react";
+import React, { createContext, useState, useCallback, useEffect } from "react";
 import localforage from "localforage";
 
 export const AppContext = createContext(null);
@@ -10,99 +10,71 @@ const FILE_STATE_DEFAULTS = {
   labelFileList: [],
   currentImage: null,
   currentLabel: null,
+  trainingConfig: null,
+  inferenceConfig: null,
+  trainingConfigOriginPath: "",
+  inferenceConfigOriginPath: "",
+  trainingUploadedYamlFile: "",
+  inferenceUploadedYamlFile: "",
+  trainingSelectedYamlPreset: "",
+  inferenceSelectedYamlPreset: "",
+  trainingOutputPath: null,
+  inferenceOutputPath: null,
+  trainingLogPath: null,
+  inferenceCheckpointPath: null,
   trainingInputImage: null,
   trainingInputLabel: null,
   inferenceInputImage: null,
   inferenceInputLabel: null,
+  viewer: null,
+  tensorBoardURL: null,
+  visualizationScales: "",
 };
 
 const FILE_CACHE_KEYS = Object.keys(FILE_STATE_DEFAULTS);
-const FILE_OBJECT_STATE_KEYS = [
-  ...FILE_CACHE_KEYS.filter((key) => key !== "fileList"),
-  "trainingUploadedYamlFile",
-  "inferenceUploadedYamlFile",
-];
+const NON_PERSISTED_FILE_STATE_KEYS = new Set(["viewer"]);
 
-const sanitizeFileEntry = (file) => {
-  if (!file || typeof file !== "object") return file;
-  const {
-    uid,
-    name,
-    originalName,
-    path,
-    folderPath,
-    thumbUrl,
-    type,
-    status,
-    percent,
-    size,
-    response,
-    error,
-    lastModified,
-    lastModifiedDate,
-    url,
-  } = file;
-  return {
-    uid,
-    name,
-    originalName: originalName || name,
-    path,
-    folderPath,
-    thumbUrl,
-    type,
-    status,
-    percent,
-    size,
-    response,
-    error,
-    lastModified,
-    lastModifiedDate,
-    url,
-  };
-};
-
-const sanitizePersistedState = (key, state) => {
-  if (!FILE_OBJECT_STATE_KEYS.includes(key)) {
-    return state;
-  }
-  if (Array.isArray(state)) {
-    return state.map((entry) => sanitizeFileEntry(entry));
-  }
-  return sanitizeFileEntry(state);
-};
-
-// Solve delete button error issue
 function usePersistedState(key, defaultValue) {
   const [state, setState] = useState(defaultValue);
-  const [isLoaded, setIsLoaded] = useState(false);
+  const shouldPersist = !NON_PERSISTED_FILE_STATE_KEYS.has(key);
 
   useEffect(() => {
-    // Fetch the stored value asynchronously when the component mounts
+    if (!shouldPersist) return undefined;
+    let cancelled = false;
     localforage
       .getItem(key)
       .then((storedValue) => {
-        if (storedValue !== null) {
+        if (!cancelled && storedValue !== null && storedValue !== undefined) {
           setState(storedValue);
         }
-        setIsLoaded(true);
       })
-      .catch((err) => {
-        console.error("Error retrieving value from localforage:", err);
-        setIsLoaded(true);
+      .catch((error) => {
+        console.warn(`Failed to hydrate cached state for ${key}:`, error);
       });
-  }, [key]);
+    return () => {
+      cancelled = true;
+    };
+  }, [key, shouldPersist]);
 
-  useEffect(() => {
-    if (isLoaded) {
-      // Save the state to localforage asynchronously whenever it changes
-      const valueToPersist = sanitizePersistedState(key, state);
-      localforage.setItem(key, valueToPersist).catch((err) => {
-        console.error("Error setting value to localforage:", err);
+  const setPersistedState = useCallback(
+    (nextValueOrUpdater) => {
+      setState((previousValue) => {
+        const nextValue =
+          typeof nextValueOrUpdater === "function"
+            ? nextValueOrUpdater(previousValue)
+            : nextValueOrUpdater;
+        if (shouldPersist) {
+          localforage.setItem(key, nextValue).catch((error) => {
+            console.warn(`Failed to persist cached state for ${key}:`, error);
+          });
+        }
+        return nextValue;
       });
-    }
-  }, [key, state, isLoaded]);
+    },
+    [key, shouldPersist],
+  );
 
-  return [state, setState];
+  return [state, setPersistedState];
 }
 
 // function safeParseJSON(jsonString, defaultValue) {
@@ -130,25 +102,13 @@ export const ContextWrapper = (props) => {
   const [inferenceConfigOriginPath, setInferenceConfigOriginPath] =
     usePersistedState("inferenceConfigOriginPath", "");
   const [trainingUploadedYamlFile, setTrainingUploadedYamlFile] =
-    usePersistedState(
-      "trainingUploadedYamlFile",
-      "",
-    );
+    usePersistedState("trainingUploadedYamlFile", "");
   const [inferenceUploadedYamlFile, setInferenceUploadedYamlFile] =
-    usePersistedState(
-      "inferenceUploadedYamlFile",
-      "",
-    );
+    usePersistedState("inferenceUploadedYamlFile", "");
   const [trainingSelectedYamlPreset, setTrainingSelectedYamlPreset] =
-    usePersistedState(
-      "trainingSelectedYamlPreset",
-      "",
-    );
+    usePersistedState("trainingSelectedYamlPreset", "");
   const [inferenceSelectedYamlPreset, setInferenceSelectedYamlPreset] =
-    usePersistedState(
-      "inferenceSelectedYamlPreset",
-      "",
-    );
+    usePersistedState("inferenceSelectedYamlPreset", "");
   const [imageFileList, setImageFileList] = usePersistedState(
     "imageFileList",
     [],
@@ -170,10 +130,7 @@ export const ContextWrapper = (props) => {
     null,
   );
   const [inferenceCheckpointPath, setInferenceCheckpointPath] =
-    usePersistedState(
-      "inferenceCheckpointPath",
-      null,
-    );
+    usePersistedState("inferenceCheckpointPath", null);
   const [currentImage, setCurrentImage] = usePersistedState(
     "currentImage",
     null,
@@ -182,6 +139,10 @@ export const ContextWrapper = (props) => {
     "currentLabel",
     null,
   );
+  const [visualizationScales, setVisualizationScales] = usePersistedState(
+    "visualizationScales",
+    FILE_STATE_DEFAULTS.visualizationScales,
+  );
   const [trainingInputImage, setTrainingInputImage] = usePersistedState(
     "trainingInputImage",
     null,
@@ -216,24 +177,62 @@ export const ContextWrapper = (props) => {
       setFileList(FILE_STATE_DEFAULTS.fileList);
       setImageFileList(FILE_STATE_DEFAULTS.imageFileList);
       setLabelFileList(FILE_STATE_DEFAULTS.labelFileList);
+      setTrainingConfig(FILE_STATE_DEFAULTS.trainingConfig);
+      setInferenceConfig(FILE_STATE_DEFAULTS.inferenceConfig);
+      setTrainingConfigOriginPath(FILE_STATE_DEFAULTS.trainingConfigOriginPath);
+      setInferenceConfigOriginPath(
+        FILE_STATE_DEFAULTS.inferenceConfigOriginPath,
+      );
+      setTrainingUploadedYamlFile(FILE_STATE_DEFAULTS.trainingUploadedYamlFile);
+      setInferenceUploadedYamlFile(
+        FILE_STATE_DEFAULTS.inferenceUploadedYamlFile,
+      );
+      setTrainingSelectedYamlPreset(
+        FILE_STATE_DEFAULTS.trainingSelectedYamlPreset,
+      );
+      setInferenceSelectedYamlPreset(
+        FILE_STATE_DEFAULTS.inferenceSelectedYamlPreset,
+      );
+      setTrainingOutputPath(FILE_STATE_DEFAULTS.trainingOutputPath);
+      setInferenceOutputPath(FILE_STATE_DEFAULTS.inferenceOutputPath);
+      setTrainingLogPath(FILE_STATE_DEFAULTS.trainingLogPath);
+      setInferenceCheckpointPath(FILE_STATE_DEFAULTS.inferenceCheckpointPath);
       setCurrentImage(FILE_STATE_DEFAULTS.currentImage);
       setCurrentLabel(FILE_STATE_DEFAULTS.currentLabel);
+      setVisualizationScales(FILE_STATE_DEFAULTS.visualizationScales);
       setTrainingInputImage(FILE_STATE_DEFAULTS.trainingInputImage);
       setTrainingInputLabel(FILE_STATE_DEFAULTS.trainingInputLabel);
       setInferenceInputImage(FILE_STATE_DEFAULTS.inferenceInputImage);
       setInferenceInputLabel(FILE_STATE_DEFAULTS.inferenceInputLabel);
+      setViewer(FILE_STATE_DEFAULTS.viewer);
+      setTensorBoardURL(FILE_STATE_DEFAULTS.tensorBoardURL);
     }
   }, [
     setFiles,
     setFileList,
     setImageFileList,
     setLabelFileList,
+    setTrainingConfig,
+    setInferenceConfig,
+    setTrainingConfigOriginPath,
+    setInferenceConfigOriginPath,
+    setTrainingUploadedYamlFile,
+    setInferenceUploadedYamlFile,
+    setTrainingSelectedYamlPreset,
+    setInferenceSelectedYamlPreset,
+    setTrainingOutputPath,
+    setInferenceOutputPath,
+    setTrainingLogPath,
+    setInferenceCheckpointPath,
     setCurrentImage,
     setCurrentLabel,
+    setVisualizationScales,
     setTrainingInputImage,
     setTrainingInputLabel,
     setInferenceInputImage,
     setInferenceInputLabel,
+    setViewer,
+    setTensorBoardURL,
   ]);
 
   const trainingState = {
@@ -281,6 +280,8 @@ export const ContextWrapper = (props) => {
         setCurrentImage,
         currentLabel,
         setCurrentLabel,
+        visualizationScales,
+        setVisualizationScales,
         viewer,
         setViewer,
         trainingConfig,
diff --git a/client/src/contexts/WorkflowContext.js b/client/src/contexts/WorkflowContext.js
index fc9f23d1..0a651299 100644
--- a/client/src/contexts/WorkflowContext.js
+++ b/client/src/contexts/WorkflowContext.js
@@ -3,37 +3,188 @@ import React, {
   useCallback,
   useContext,
   useEffect,
+  useRef,
   useState,
 } from "react";
 import { message } from "antd";
 import {
   appendWorkflowEvent,
   approveAgentAction as approveAgentActionApi,
+  computeWorkflowEvaluationResult,
   createAgentAction,
+  exportWorkflowBundle,
+  getConfigPresetContent,
   getCurrentWorkflow,
+  getWorkflowAgentRecommendation,
   getWorkflowHotspots,
   getWorkflowImpactPreview,
+  getWorkflowOverview,
+  getWorkflowPreflight,
+  getWorkflowProjectProgress,
+  listWorkflowArtifacts,
+  listWorkflowCorrectionSets,
   listWorkflowEvents,
+  listWorkflowEvaluationResults,
+  listWorkflowModelRuns,
+  listWorkflowModelVersions,
+  mountProjectDirectory,
   queryWorkflowAgent,
   rejectAgentAction as rejectAgentActionApi,
+  resetFileWorkspace,
+  runWorkflowCommand,
+  startNewWorkflow as startNewWorkflowApi,
+  stopModelInference,
+  stopModelTraining,
   updateWorkflow as updateWorkflowApi,
+  updateWorkflowProjectProgressVolume,
 } from "../api";
 import { AppContext } from "./GlobalContext";
+import { logClientEvent } from "../logging/appEventLog";
 
 export const WorkflowContext = createContext(null);
 
+const PENDING_RUNTIME_ACTION_KEY = "pytc.workflow.pendingRuntimeAction.v1";
+const PENDING_RUNTIME_ACTION_TTL_MS = 6 * 60 * 60 * 1000;
+const PERSISTABLE_RUNTIME_KINDS = new Set(["monitor_training"]);
+
+const isPersistableRuntimeAction = (kind) =>
+  PERSISTABLE_RUNTIME_KINDS.has(kind);
+
+const readPersistedRuntimeAction = (workflowId = null) => {
+  if (typeof window === "undefined" || !window.sessionStorage) return null;
+  if (!workflowId) return null;
+
+  try {
+    const raw = window.sessionStorage.getItem(PENDING_RUNTIME_ACTION_KEY);
+    if (!raw) return null;
+    const parsed = JSON.parse(raw);
+    if (
+      parsed?.kind !== "pending_runtime_action" ||
+      parsed?.workflowId !== workflowId ||
+      !parsed?.action?.kind
+    ) {
+      if (parsed?.kind || parsed?.action) {
+        window.sessionStorage.removeItem(PENDING_RUNTIME_ACTION_KEY);
+      }
+      return null;
+    }
+    const savedAt = Number(parsed.savedAt || 0);
+    const age = Date.now() - savedAt;
+    if (!Number.isFinite(age) || age > PENDING_RUNTIME_ACTION_TTL_MS) {
+      window.sessionStorage.removeItem(PENDING_RUNTIME_ACTION_KEY);
+      return null;
+    }
+    return parsed.action;
+  } catch {
+    return null;
+  }
+};
+
+const writePersistedRuntimeAction = (workflowId = null, action = null) => {
+  if (typeof window === "undefined" || !window.sessionStorage) return;
+  if (!workflowId || !action) {
+    window.sessionStorage.removeItem(PENDING_RUNTIME_ACTION_KEY);
+    return;
+  }
+  try {
+    window.sessionStorage.setItem(
+      PENDING_RUNTIME_ACTION_KEY,
+      JSON.stringify({
+        kind: "pending_runtime_action",
+        workflowId,
+        action,
+        savedAt: Date.now(),
+      }),
+    );
+  } catch {
+    // Persisting pending runtime actions is best-effort; it should not block runtime.
+  }
+};
+
 export function useWorkflow() {
   return useContext(WorkflowContext);
 }
 
+const buildRuntimeOverridesFromEffects = (
+  effects = {},
+  {
+    resolvedTrainingConfig = "",
+    resolvedTrainingConfigOrigin = "",
+    resolvedInferenceConfig = "",
+    resolvedInferenceConfigOrigin = "",
+  } = {},
+) => ({
+  inputLabelPath:
+    effects.set_training_label_path || effects.set_inference_label_path || "",
+  inputImagePath:
+    effects.set_training_image_path || effects.set_inference_image_path || "",
+  logPath: effects.set_training_log_path || "",
+  outputPath:
+    effects.set_training_output_path || effects.set_inference_output_path || "",
+  trainingConfig: resolvedTrainingConfig || undefined,
+  configOriginPath: resolvedTrainingConfigOrigin || undefined,
+  autoParameters: Boolean(effects.runtime_action?.autopick_parameters),
+  checkpointPath: effects.set_inference_checkpoint_path || "",
+  inferenceConfig: resolvedInferenceConfig || undefined,
+  inferenceConfigOriginPath: resolvedInferenceConfigOrigin || undefined,
+  inferenceInputImagePath: effects.set_inference_image_path || "",
+  inferenceInputLabelPath: effects.set_inference_label_path || "",
+  datasetPath: effects.set_proofreading_dataset_path || "",
+  maskPath: effects.set_proofreading_mask_path || "",
+  projectName: effects.set_proofreading_project_name || "",
+  visualizationImagePath: effects.set_visualization_image_path || "",
+  visualizationLabelPath: effects.set_visualization_label_path || "",
+  visualizationScales: effects.set_visualization_scales || "",
+});
+
 export function WorkflowProvider({ children }) {
   const appContext = useContext(AppContext);
   const [workflow, setWorkflow] = useState(null);
   const [events, setEvents] = useState([]);
   const [hotspots, setHotspots] = useState([]);
   const [impactPreview, setImpactPreview] = useState(null);
+  const [agentRecommendation, setAgentRecommendation] = useState(null);
+  const [preflight, setPreflight] = useState(null);
+  const [workflowOverview, setWorkflowOverview] = useState(null);
+  const [projectProgress, setProjectProgress] = useState(null);
+  const [artifacts, setArtifacts] = useState([]);
+  const [modelRuns, setModelRuns] = useState([]);
+  const [modelVersions, setModelVersions] = useState([]);
+  const [correctionSets, setCorrectionSets] = useState([]);
+  const [evaluationResults, setEvaluationResults] = useState([]);
   const [loading, setLoading] = useState(true);
   const [lastClientEffects, setLastClientEffects] = useState(null);
+  const [pendingRuntimeAction, setPendingRuntimeAction] = useState(null);
+  const hydratedPendingRuntimeRef = useRef(false);
+
+  const clearPersistedRuntimeAction = useCallback(() => {
+    writePersistedRuntimeAction(null, null);
+  }, []);
+
+  const registerPendingRuntimeAction = useCallback(
+    (action, persist = false) => {
+      if (!action) return;
+      const nextAction = {
+        id: action.id || `${action.kind}:${Date.now()}`,
+        ...action,
+      };
+      setPendingRuntimeAction(nextAction);
+      const shouldPersist = persist || isPersistableRuntimeAction(action.kind);
+      if (shouldPersist) {
+        writePersistedRuntimeAction(workflow?.id, nextAction);
+      } else if (workflow?.id) {
+        writePersistedRuntimeAction(workflow?.id, null);
+      }
+      return nextAction;
+    },
+    [workflow?.id],
+  );
+
+  const clientEffectsWithoutRuntime = useCallback((effects) => {
+    if (!effects || typeof effects !== "object") return effects;
+    const { runtime_action: _runtimeAction, ...rest } = effects;
+    return rest;
+  }, []);
 
   const refreshWorkflow = useCallback(async () => {
     setLoading(true);
@@ -50,6 +201,24 @@ export function WorkflowProvider({ children }) {
     }
   }, []);
 
+  const applyWorkflowDetail = useCallback((data) => {
+    setWorkflow(data?.workflow || null);
+    setEvents(data?.events || []);
+    setHotspots([]);
+    setImpactPreview(null);
+    setAgentRecommendation(null);
+    setPreflight(null);
+    setWorkflowOverview(null);
+    setProjectProgress(null);
+    setArtifacts([]);
+    setModelRuns([]);
+    setModelVersions([]);
+    setCorrectionSets([]);
+    setEvaluationResults([]);
+    setLastClientEffects(null);
+    setPendingRuntimeAction(null);
+  }, []);
+
   const refreshEvents = useCallback(async () => {
     if (!workflow?.id) return [];
     const nextEvents = await listWorkflowEvents(workflow.id);
@@ -79,9 +248,126 @@ export function WorkflowProvider({ children }) {
     }
   }, [workflow?.id]);
 
-  useEffect(() => {
-    refreshWorkflow();
-  }, [refreshWorkflow]);
+  const refreshAgentRecommendation = useCallback(async () => {
+    if (!workflow?.id) {
+      setAgentRecommendation(null);
+      return null;
+    }
+    try {
+      const recommendation = await getWorkflowAgentRecommendation(workflow.id);
+      setAgentRecommendation(recommendation || null);
+      return recommendation || null;
+    } catch (error) {
+      console.warn("Workflow agent recommendation refresh failed:", error);
+      return null;
+    }
+  }, [workflow?.id]);
+
+  const refreshPreflight = useCallback(async () => {
+    if (!workflow?.id) {
+      setPreflight(null);
+      return null;
+    }
+    try {
+      const nextPreflight = await getWorkflowPreflight(workflow.id);
+      setPreflight(nextPreflight || null);
+      return nextPreflight || null;
+    } catch (error) {
+      console.warn("Workflow preflight refresh failed:", error);
+      return null;
+    }
+  }, [workflow?.id]);
+
+  const refreshProjectProgress = useCallback(async () => {
+    if (!workflow?.id) {
+      setProjectProgress(null);
+      return null;
+    }
+    try {
+      const progress = await getWorkflowProjectProgress(workflow.id);
+      setProjectProgress(progress || null);
+      return progress || null;
+    } catch (error) {
+      console.warn("Workflow project progress refresh failed:", error);
+      return null;
+    }
+  }, [workflow?.id]);
+
+  const refreshWorkflowOverview = useCallback(
+    async ({ refresh = true } = {}) => {
+      if (!workflow?.id) {
+        setWorkflowOverview(null);
+        return null;
+      }
+      try {
+        const overview = await getWorkflowOverview(workflow.id, { refresh });
+        setWorkflowOverview(overview || null);
+        if (overview?.project_progress) {
+          setProjectProgress(overview.project_progress);
+        }
+        return overview || null;
+      } catch (error) {
+        console.warn("Workflow overview refresh failed:", error);
+        return null;
+      }
+    },
+    [workflow?.id],
+  );
+
+  const updateProjectProgressVolume = useCallback(
+    async (body) => {
+      if (!workflow?.id) return null;
+      const progress = await updateWorkflowProjectProgressVolume(
+        workflow.id,
+        body,
+      );
+      setProjectProgress(progress || null);
+      await refreshWorkflowOverview({ refresh: false });
+      return progress || null;
+    },
+    [refreshWorkflowOverview, workflow?.id],
+  );
+
+  const refreshEvidence = useCallback(async () => {
+    if (!workflow?.id) {
+      setArtifacts([]);
+      setModelRuns([]);
+      setModelVersions([]);
+      setCorrectionSets([]);
+      setEvaluationResults([]);
+      return null;
+    }
+    try {
+      const [
+        nextArtifacts,
+        nextModelRuns,
+        nextModelVersions,
+        nextCorrectionSets,
+        nextEvaluationResults,
+      ] = await Promise.all([
+        listWorkflowArtifacts(workflow.id),
+        listWorkflowModelRuns(workflow.id),
+        listWorkflowModelVersions(workflow.id),
+        listWorkflowCorrectionSets(workflow.id),
+        listWorkflowEvaluationResults(workflow.id),
+      ]);
+      setArtifacts(nextArtifacts || []);
+      setModelRuns(nextModelRuns || []);
+      setModelVersions(nextModelVersions || []);
+      setCorrectionSets(nextCorrectionSets || []);
+      setEvaluationResults(nextEvaluationResults || []);
+      return {
+        artifacts: nextArtifacts || [],
+        modelRuns: nextModelRuns || [],
+        modelVersions: nextModelVersions || [],
+        correctionSets: nextCorrectionSets || [],
+        evaluationResults: nextEvaluationResults || [],
+      };
+    } catch (error) {
+      console.warn("Workflow evidence refresh failed:", error);
+      return null;
+    }
+  }, [workflow?.id]);
 
   useEffect(() => {
     if (!workflow?.id) {
@@ -98,6 +384,65 @@ export function WorkflowProvider({ children }) {
     refreshInsights,
   ]);
 
+  useEffect(() => {
+    refreshEvidence();
+  }, [
+    workflow?.id,
+    workflow?.stage,
+    workflow?.inference_output_path,
+    workflow?.corrected_mask_path,
+    workflow?.training_output_path,
+    events.length,
+    refreshEvidence,
+  ]);
+
+  useEffect(() => {
+    refreshAgentRecommendation();
+  }, [
+    workflow?.id,
+    workflow?.stage,
+    workflow?.inference_output_path,
+    workflow?.corrected_mask_path,
+    workflow?.training_output_path,
+    events.length,
+    refreshAgentRecommendation,
+  ]);
+
+  useEffect(() => {
+    refreshPreflight();
+  }, [
+    workflow?.id,
+    workflow?.stage,
+    workflow?.dataset_path,
+    workflow?.image_path,
+    workflow?.label_path,
+    workflow?.mask_path,
+    workflow?.inference_output_path,
+    workflow?.checkpoint_path,
+    workflow?.config_path,
+    workflow?.corrected_mask_path,
+    workflow?.training_output_path,
+    events.length,
+    refreshPreflight,
+  ]);
+
+  useEffect(() => {
+    refreshWorkflowOverview();
+  }, [
+    workflow?.id,
+    workflow?.stage,
+    workflow?.dataset_path,
+    workflow?.image_path,
+    workflow?.label_path,
+    workflow?.mask_path,
+    workflow?.inference_output_path,
+    workflow?.checkpoint_path,
+    workflow?.corrected_mask_path,
+    workflow?.training_output_path,
+    events.length,
+    refreshWorkflowOverview,
+  ]);
+
   const updateWorkflow = useCallback(
     async (patch) => {
       if (!workflow?.id) return null;
@@ -111,13 +456,99 @@ export function WorkflowProvider({ children }) {
   const appendEvent = useCallback(
     async (event) => {
       if (!workflow?.id) return null;
-      const nextEvent = await appendWorkflowEvent(workflow.id, event);
-      setEvents((prev) => [...prev, nextEvent]);
-      return nextEvent;
+      try {
+        const nextEvent = await appendWorkflowEvent(workflow.id, event);
+        if (nextEvent) {
+          setEvents((prev) => [...prev, nextEvent]);
+        }
+        return nextEvent;
+      } catch (error) {
+        console.warn("Workflow event append failed:", error);
+        return null;
+      }
     },
     [workflow?.id],
   );
 
+  const clearLocalWorkflowInputs = useCallback(async () => {
+    await appContext?.resetFileState?.();
+    appContext?.setTrainingConfig?.(null);
+    appContext?.setInferenceConfig?.(null);
+    appContext?.setViewer?.(null);
+    appContext?.setTensorBoardURL?.(null);
+    appContext?.trainingState?.setConfigOriginPath?.("");
+    appContext?.trainingState?.setUploadedYamlFile?.("");
+    appContext?.trainingState?.setSelectedYamlPreset?.("");
+    appContext?.trainingState?.setOutputPath?.(null);
+    appContext?.trainingState?.setLogPath?.(null);
+    appContext?.inferenceState?.setConfigOriginPath?.("");
+    appContext?.inferenceState?.setUploadedYamlFile?.("");
+    appContext?.inferenceState?.setSelectedYamlPreset?.("");
+    appContext?.inferenceState?.setOutputPath?.(null);
+    appContext?.inferenceState?.setCheckpointPath?.(null);
+  }, [appContext]);
+
+  const startNewWorkflow = useCallback(
+    async (body = {}) => {
+      await resetFileWorkspace();
+      await clearLocalWorkflowInputs();
+      const data = await startNewWorkflowApi(body);
+      applyWorkflowDetail(data);
+      return data;
+    },
+    [applyWorkflowDetail, clearLocalWorkflowInputs],
+  );
+
+  useEffect(() => {
+    let cancelled = false;
+    const resumeWorkflowSession = async () => {
+      setLoading(true);
+      try {
+        const data = await getCurrentWorkflow();
+        if (cancelled) return;
+        applyWorkflowDetail(data);
+
+        const mountedProjectPath = data?.workflow?.dataset_path;
+        if (mountedProjectPath) {
+          try {
+            await mountProjectDirectory({
+              directoryPath: mountedProjectPath,
+              mountName: data?.workflow?.title || "",
+              destinationPath: "root",
+            });
+          } catch (mountError) {
+            console.warn("Initial project remount failed:", mountError);
+          }
+        }
+      } catch (error) {
+        console.warn("Workflow session resume failed:", error);
+        if (!cancelled) {
+          message.error("Failed to load workflow session.");
+        }
+      } finally {
+        if (!cancelled) setLoading(false);
+      }
+    };
+    resumeWorkflowSession();
+    return () => {
+      cancelled = true;
+    };
+  }, [applyWorkflowDetail]);
+
+  useEffect(() => {
+    if (!workflow?.id) return;
+    const workflowId = workflow.id;
+    if (hydratedPendingRuntimeRef.current === workflowId) return;
+    hydratedPendingRuntimeRef.current = workflowId;
+
+    const restored = readPersistedRuntimeAction(workflowId);
+    if (restored) {
+      setPendingRuntimeAction(restored);
+    } else {
+      clearPersistedRuntimeAction();
+    }
+  }, [clearPersistedRuntimeAction, workflow?.id]);
+
   const proposeAgentAction = useCallback(
     async (action) => {
       if (!workflow?.id) return null;
@@ -128,30 +559,417 @@ export function WorkflowProvider({ children }) {
     [workflow?.id, refreshEvents],
   );
 
-  const applyClientEffects = useCallback(
-    (effects) => {
+  const runClientEffects = useCallback(
+    async (effects) => {
       if (!effects) return;
       if (effects.set_training_label_path && appContext?.trainingState) {
         appContext.trainingState.setInputLabel(effects.set_training_label_path);
       }
-      setLastClientEffects(effects);
+      if (effects.set_training_image_path && appContext?.trainingState) {
+        appContext.trainingState.setInputImage?.(
+          effects.set_training_image_path,
+        );
+      }
+      if (effects.set_training_log_path && appContext?.trainingState) {
+        appContext.trainingState.setLogPath(effects.set_training_log_path);
+      }
+      if (effects.set_training_output_path && appContext?.trainingState) {
+        appContext.trainingState.setOutputPath(
+          effects.set_training_output_path,
+        );
+      }
+      let resolvedTrainingConfig = "";
+      let resolvedTrainingConfigOrigin = "";
+      if (effects.set_training_config_preset && appContext?.trainingState) {
+        try {
+          const preset = await getConfigPresetContent(
+            effects.set_training_config_preset,
+          );
+          resolvedTrainingConfig = preset?.content || "";
+          resolvedTrainingConfigOrigin =
+            preset?.path || effects.set_training_config_preset;
+          if (resolvedTrainingConfig) {
+            appContext.setTrainingConfig?.(resolvedTrainingConfig);
+            appContext.trainingState.setConfigOriginPath?.(
+              resolvedTrainingConfigOrigin,
+            );
+            appContext.trainingState.setSelectedYamlPreset?.(
+              resolvedTrainingConfigOrigin,
+            );
+            appContext.trainingState.setUploadedYamlFile?.("");
+          }
+        } catch (error) {
+          logClientEvent("workflow_action_training_preset_load_failed", {
+            level: "ERROR",
+            source: "workflow_context",
+            message: error.message || "Training preset load failed",
+            data: {
+              workflowId: workflow?.id || null,
+              preset: effects.set_training_config_preset,
+            },
+          });
+          throw error;
+        }
+      }
+      if (effects.set_inference_checkpoint_path && appContext?.inferenceState) {
+        appContext.inferenceState.setCheckpointPath(
+          effects.set_inference_checkpoint_path,
+        );
+      }
+      if (effects.set_inference_image_path && appContext?.inferenceState) {
+        appContext.inferenceState.setInputImage?.(
+          effects.set_inference_image_path,
+        );
+      }
+      if (effects.set_inference_label_path && appContext?.inferenceState) {
+        appContext.inferenceState.setInputLabel?.(
+          effects.set_inference_label_path,
+        );
+      }
+      if (effects.set_inference_output_path && appContext?.inferenceState) {
+        appContext.inferenceState.setOutputPath(
+          effects.set_inference_output_path,
+        );
+      }
+      let resolvedInferenceConfig = "";
+      let resolvedInferenceConfigOrigin = "";
+      if (effects.set_inference_config_preset && appContext?.inferenceState) {
+        try {
+          const preset = await getConfigPresetContent(
+            effects.set_inference_config_preset,
+          );
+          resolvedInferenceConfig = preset?.content || "";
+          resolvedInferenceConfigOrigin =
+            preset?.path || effects.set_inference_config_preset;
+          if (resolvedInferenceConfig) {
+            appContext.setInferenceConfig?.(resolvedInferenceConfig);
+            appContext.inferenceState.setConfigOriginPath?.(
+              resolvedInferenceConfigOrigin,
+            );
+            appContext.inferenceState.setSelectedYamlPreset?.(
+              resolvedInferenceConfigOrigin,
+            );
+            appContext.inferenceState.setUploadedYamlFile?.("");
+          }
+        } catch (error) {
+          logClientEvent("workflow_action_inference_preset_load_failed", {
+            level: "ERROR",
+            source: "workflow_context",
+            message: error.message || "Inference preset load failed",
+            data: {
+              workflowId: workflow?.id || null,
+              preset: effects.set_inference_config_preset,
+            },
+          });
+          throw error;
+        }
+      }
+      if (effects.set_visualization_image_path && appContext?.setCurrentImage) {
+        appContext.setCurrentImage(effects.set_visualization_image_path);
+      }
+      if (effects.set_visualization_label_path && appContext?.setCurrentLabel) {
+        appContext.setCurrentLabel(effects.set_visualization_label_path);
+      }
+      if (
+        effects.set_visualization_scales &&
+        appContext?.setVisualizationScales
+      ) {
+        const nextScales = Array.isArray(effects.set_visualization_scales)
+          ? effects.set_visualization_scales.join(",")
+          : String(effects.set_visualization_scales);
+        appContext.setVisualizationScales(nextScales);
+      }
+      if (effects.runtime_action?.kind) {
+        if (effects.runtime_action.kind === "stop_inference") {
+          await stopModelInference();
+          message.info("Inference stop requested.");
+        } else if (effects.runtime_action.kind === "stop_training") {
+          await stopModelTraining();
+          message.info("Training stop requested.");
+        }
+        const nextRuntimeAction = {
+          id: `${effects.runtime_action.kind}:${Date.now()}`,
+          ...effects.runtime_action,
+          overrides: buildRuntimeOverridesFromEffects(effects, {
+            resolvedTrainingConfig,
+            resolvedTrainingConfigOrigin,
+            resolvedInferenceConfig,
+            resolvedInferenceConfigOrigin,
+          }),
+        };
+        registerPendingRuntimeAction(nextRuntimeAction);
+      }
+      if (effects.reset_workspace) {
+        const resetResult = await resetFileWorkspace();
+        await appContext?.resetFileState?.();
+        if (workflow?.id) {
+          await updateWorkflowApi(workflow.id, {
+            metadata: {
+              project_context: null,
+              visualization_scales: null,
+              visualization_scales_source: null,
+              active_volume_pair: null,
+              needs_project_context: true,
+            },
+          });
+          await refreshWorkflow();
+        }
+        message.success(
+          `Workspace reset. Removed ${resetResult?.deleted_count ?? 0} indexed item(s).`,
+        );
+      }
+      if (effects.start_new_workflow) {
+        const resetBody =
+          typeof effects.start_new_workflow === "object"
+            ? effects.start_new_workflow
+            : {};
+        await resetFileWorkspace();
+        await clearLocalWorkflowInputs();
+        await startNewWorkflowApi(resetBody);
+        await refreshWorkflow();
+      }
+      if (effects.mount_project?.directory_path) {
+        const mountResult = await mountProjectDirectory({
+          directoryPath: effects.mount_project.directory_path,
+          mountName: effects.mount_project.mount_name || "",
+          destinationPath: effects.mount_project.destination_path || "root",
+        });
+        message.success(mountResult?.message || "Project mounted.");
+        if (effects.mount_project.workflow_patch && workflow?.id) {
+          await updateWorkflowApi(
+            workflow.id,
+            effects.mount_project.workflow_patch,
+          );
+        }
+        await refreshWorkflow();
+      }
+      if (effects.workflow_action?.kind === "propose_retraining_stage") {
+        const correctedMaskPath =
+          effects.workflow_action.corrected_mask_path ||
+          workflow?.corrected_mask_path ||
+          "";
+        if (workflow?.id && correctedMaskPath) {
+          await createAgentAction(workflow.id, {
+            action: "stage_retraining_from_corrections",
+            summary: "Stage corrected masks for retraining.",
+            payload: { corrected_mask_path: correctedMaskPath },
+          });
+          await refreshEvents();
+          message.info("Agent proposed a retraining handoff.");
+        } else {
+          message.warning("No corrected mask path is available to stage.");
+        }
+      }
+      if (effects.workflow_action?.kind === "compute_evaluation") {
+        const action = effects.workflow_action;
+        logClientEvent("workflow_action_compute_evaluation_started", {
+          source: "workflow_context",
+          message: "Assistant-triggered evaluation started",
+          data: { workflowId: workflow?.id || null },
+        });
+        if (
+          !workflow?.id ||
+          !action.baseline_prediction_path ||
+          !action.candidate_prediction_path ||
+          !action.ground_truth_path
+        ) {
+          message.warning(
+            "Metrics need a previous result, a new result, and a reference mask.",
+          );
+        } else {
+          try {
+            const result = await computeWorkflowEvaluationResult(workflow.id, {
+              name: action.name || "workflow-before-after-evaluation",
+              baseline_prediction_path: action.baseline_prediction_path,
+              candidate_prediction_path: action.candidate_prediction_path,
+              ground_truth_path: action.ground_truth_path,
+              baseline_run_id: action.baseline_run_id || undefined,
+              candidate_run_id: action.candidate_run_id || undefined,
+              model_version_id: action.model_version_id || undefined,
+              metadata: action.metadata || { source: "workflow_agent" },
+            });
+            message.success(result?.summary || "Metrics computed.");
+            await refreshEvidence();
+            await refreshEvents();
+            logClientEvent("workflow_action_compute_evaluation_completed", {
+              source: "workflow_context",
+              message: "Assistant-triggered evaluation completed",
+              data: {
+                workflowId: workflow.id,
+                evaluationId: result?.id || null,
+              },
+            });
+          } catch (error) {
+            logClientEvent("workflow_action_compute_evaluation_failed", {
+              level: "ERROR",
+              source: "workflow_context",
+              message: error.message || "Assistant-triggered evaluation failed",
+              data: { workflowId: workflow.id },
+            });
+            throw error;
+          }
+        }
+      }
+      if (effects.workflow_action?.kind === "export_bundle") {
+        logClientEvent("workflow_action_export_bundle_started", {
+          source: "workflow_context",
+          message: "Assistant-triggered evidence export started",
+          data: { workflowId: workflow?.id || null },
+        });
+        if (!workflow?.id) return;
+        try {
+          const bundle = await exportWorkflowBundle(workflow.id);
+          const missingCount = (bundle?.artifact_paths || []).filter(
+            (entry) => !entry.exists,
+          ).length;
+          message.success(
+            `Evidence exported: ${bundle?.artifacts?.length || 0} artifacts, ${missingCount} missing paths.`,
+          );
+          await refreshEvidence();
+          await refreshEvents();
+          logClientEvent("workflow_action_export_bundle_completed", {
+            source: "workflow_context",
+            message: "Assistant-triggered evidence export completed",
+            data: { workflowId: workflow.id, missingCount },
+          });
+        } catch (error) {
+          logClientEvent("workflow_action_export_bundle_failed", {
+            level: "ERROR",
+            source: "workflow_context",
+            message:
+              error.message || "Assistant-triggered evidence export failed",
+            data: { workflowId: workflow.id },
+          });
+          throw error;
+        }
+      }
+      if (effects.refresh_insights) {
+        await refreshInsights();
+      }
+      if (effects.refresh_project_progress) {
+        await refreshProjectProgress();
+      }
+      await refreshAgentRecommendation();
+      setLastClientEffects({ ...effects });
+    },
+    [
+      appContext,
+      clearLocalWorkflowInputs,
+      registerPendingRuntimeAction,
+      refreshAgentRecommendation,
+      refreshEvidence,
+      refreshEvents,
+      refreshWorkflow,
+      refreshInsights,
+      refreshProjectProgress,
+      workflow?.corrected_mask_path,
+      workflow?.id,
+    ],
+  );
+
+  const consumeRuntimeAction = useCallback(
+    (actionId = null) => {
+      setPendingRuntimeAction((current) => {
+        if (!current) return null;
+        if (!actionId || current.id === actionId) {
+          clearPersistedRuntimeAction();
+          return null;
+        }
+        return current;
+      });
+    },
+    [clearPersistedRuntimeAction],
+  );
+
+  const executeAssistantItem = useCallback(
+    async (item) => {
+      if (!item) return;
+      if (workflow?.id) {
+        try {
+          await appendEvent({
+            actor: "user",
+            event_type: "assistant.command.invoked",
+            stage: workflow.stage,
+            summary: `Executed assistant item: ${item.title || item.label || item.id || "action"}.`,
+            payload: {
+              item_id: item.id || null,
+              item_label: item.title || item.label || null,
+              item_type: item.command ? "command" : "action",
+              runtime_action: item.client_effects?.runtime_action || null,
+            },
+          });
+        } catch (_error) {
+          // Do not block command execution on audit-log failures.
+        }
+      }
+      await runClientEffects(item.client_effects);
     },
-    [appContext],
+    [appendEvent, runClientEffects, workflow?.id, workflow?.stage],
   );
 
   const approveAgentAction = useCallback(
-    async (eventId) => {
+    async (eventId, overrides = {}) => {
       if (!workflow?.id) return null;
-      const result = await approveAgentActionApi(workflow.id, eventId);
+      const result = await approveAgentActionApi(
+        workflow.id,
+        eventId,
+        overrides,
+      );
       if (result?.workflow) {
         setWorkflow(result.workflow);
       }
-      applyClientEffects(result?.client_effects);
+      const durableCommand = result?.commands?.find?.((command) =>
+        Number.isFinite(Number(command?.id)),
+      );
+      if (durableCommand) {
+        const approvedEffects = result?.client_effects || {};
+        await runClientEffects(clientEffectsWithoutRuntime(approvedEffects));
+        const commandResult = await runWorkflowCommand(
+          workflow.id,
+          durableCommand.id,
+        );
+        if ((approvedEffects?.runtime_action || {}).kind === "start_training") {
+          registerPendingRuntimeAction(
+            {
+              id: `monitor_training:${Date.now()}`,
+              kind: "monitor_training",
+              commandId: durableCommand.id,
+              commandResult,
+              clientEffects: approvedEffects,
+              overrides: buildRuntimeOverridesFromEffects(approvedEffects),
+            },
+            true,
+          );
+        }
+        await Promise.allSettled([
+          refreshWorkflow(),
+          refreshEvents(),
+          refreshEvidence(),
+          refreshAgentRecommendation(),
+          refreshPreflight(),
+          refreshWorkflowOverview(),
+          refreshProjectProgress(),
+        ]);
+      } else {
+        await runClientEffects(result?.client_effects);
+      }
       await refreshEvents();
       message.success("Agent proposal approved.");
       return result;
     },
-    [workflow?.id, refreshEvents, applyClientEffects],
+    [
+      clientEffectsWithoutRuntime,
+      registerPendingRuntimeAction,
+      refreshAgentRecommendation,
+      refreshEvents,
+      refreshEvidence,
+      refreshPreflight,
+      refreshWorkflowOverview,
+      refreshProjectProgress,
+      refreshWorkflow,
+      runClientEffects,
+      workflow?.id,
+    ],
   );
 
   const rejectAgentAction = useCallback(
@@ -166,15 +984,32 @@ export function WorkflowProvider({ children }) {
   );
 
   const queryAgent = useCallback(
-    async (query) => {
+    async (query, conversationId = null) => {
       if (!workflow?.id) return null;
-      const result = await queryWorkflowAgent(workflow.id, query);
+      const result = await queryWorkflowAgent(
+        workflow.id,
+        query,
+        conversationId,
+      );
       if (result?.proposals?.length) {
         await refreshEvents();
       }
+      await Promise.allSettled([
+        refreshWorkflow(),
+        refreshAgentRecommendation(),
+        refreshWorkflowOverview(),
+        refreshProjectProgress(),
+      ]);
       return result;
     },
-    [workflow?.id, refreshEvents],
+    [
+      workflow?.id,
+      refreshEvents,
+      refreshWorkflow,
+      refreshAgentRecommendation,
+      refreshWorkflowOverview,
+      refreshProjectProgress,
+    ],
   );
 
   const consumeClientEffects = useCallback(() => {
@@ -190,17 +1025,37 @@ export function WorkflowProvider({ children }) {
         events,
         hotspots,
         impactPreview,
+        agentRecommendation,
+        preflight,
+        workflowOverview,
+        projectProgress,
+        artifacts,
+        modelRuns,
+        modelVersions,
+        correctionSets,
+        evaluationResults,
         loading,
         lastClientEffects,
+        pendingRuntimeAction,
         refreshWorkflow,
         refreshEvents,
         refreshInsights,
+        refreshAgentRecommendation,
+        refreshPreflight,
+        refreshWorkflowOverview,
+        refreshProjectProgress,
+        updateProjectProgressVolume,
+        refreshEvidence,
+        startNewWorkflow,
         updateWorkflow,
         appendEvent,
         proposeAgentAction,
         approveAgentAction,
         rejectAgentAction,
         queryAgent,
+        runClientEffects,
+        executeAssistantItem,
+        consumeRuntimeAction,
         consumeClientEffects,
       }}
     >
diff --git a/client/src/contexts/WorkflowContext.test.js b/client/src/contexts/WorkflowContext.test.js
index 57549833..ce6602d1 100644
--- a/client/src/contexts/WorkflowContext.test.js
+++ b/client/src/contexts/WorkflowContext.test.js
@@ -5,23 +5,67 @@ import { AppContext } from "./GlobalContext";
 import { WorkflowProvider, useWorkflow } from "./WorkflowContext";
 import {
   approveAgentAction,
+  appendWorkflowEvent,
+  computeWorkflowEvaluationResult,
+  createAgentAction,
+  exportWorkflowBundle,
+  getConfigPresetContent,
   getCurrentWorkflow,
+  getWorkflowAgentRecommendation,
   getWorkflowHotspots,
   getWorkflowImpactPreview,
+  getWorkflowOverview,
+  getWorkflowPreflight,
+  getWorkflowProjectProgress,
+  listWorkflowArtifacts,
+  listWorkflowCorrectionSets,
   listWorkflowEvents,
+  listWorkflowEvaluationResults,
+  listWorkflowModelRuns,
+  listWorkflowModelVersions,
+  mountProjectDirectory,
+  resetFileWorkspace,
+  runWorkflowCommand,
+  startNewWorkflow,
+  stopModelInference,
+  stopModelTraining,
+  updateWorkflowProjectProgressVolume,
 } from "../api";
 
 jest.mock("../api", () => ({
   approveAgentAction: jest.fn(),
   appendWorkflowEvent: jest.fn(),
+  computeWorkflowEvaluationResult: jest.fn(),
   createAgentAction: jest.fn(),
+  exportWorkflowBundle: jest.fn(),
+  getConfigPresetContent: jest.fn(),
   getCurrentWorkflow: jest.fn(),
+  getWorkflowAgentRecommendation: jest.fn(),
   getWorkflowHotspots: jest.fn(),
   getWorkflowImpactPreview: jest.fn(),
+  getWorkflowOverview: jest.fn(),
+  getWorkflowPreflight: jest.fn(),
+  getWorkflowProjectProgress: jest.fn(),
+  listWorkflowArtifacts: jest.fn(),
+  listWorkflowCorrectionSets: jest.fn(),
   listWorkflowEvents: jest.fn(),
+  listWorkflowEvaluationResults: jest.fn(),
+  listWorkflowModelRuns: jest.fn(),
+  listWorkflowModelVersions: jest.fn(),
+  mountProjectDirectory: jest.fn(),
   queryWorkflowAgent: jest.fn(),
   rejectAgentAction: jest.fn(),
+  resetFileWorkspace: jest.fn(),
+  runWorkflowCommand: jest.fn(),
+  startNewWorkflow: jest.fn(),
+  stopModelInference: jest.fn(),
+  stopModelTraining: jest.fn(),
   updateWorkflow: jest.fn(),
+  updateWorkflowProjectProgressVolume: jest.fn(),
+}));
+
+jest.mock("../logging/appEventLog", () => ({
+  logClientEvent: jest.fn(),
 }));
 
 const baseWorkflow = {
@@ -35,15 +79,191 @@ function Probe() {
   return (
     <div>
       <div>{workflowContext.workflow?.stage || "loading"}</div>
-      <div>{workflowContext.events.map((event) => event.event_type).join(",")}</div>
+      <div>
+        {workflowContext.events.map((event) => event.event_type).join(",")}
+      </div>
       <div>{workflowContext.hotspots?.[0]?.summary || "no-hotspot"}</div>
       <div>{workflowContext.impactPreview?.confidence || "no-impact"}</div>
+      <div>{workflowContext.agentRecommendation?.decision || "no-agent"}</div>
+      <div>{workflowContext.preflight?.overall_status || "no-preflight"}</div>
+      <div>{`artifacts:${workflowContext.artifacts.length}`}</div>
+      <div>{`runs:${workflowContext.modelRuns.length}`}</div>
+      <div>{`corrections:${workflowContext.correctionSets.length}`}</div>
+      <div>{`evaluations:${workflowContext.evaluationResults.length}`}</div>
       <button
         type="button"
         onClick={() => workflowContext.approveAgentAction(7)}
       >
         Approve proposal
       </button>
+      <button
+        type="button"
+        onClick={() =>
+          workflowContext.runClientEffects({
+            navigate_to: "inference",
+            set_inference_output_path: "/tmp/inference-out",
+          })
+        }
+      >
+        Run effects
+      </button>
+      <button
+        type="button"
+        onClick={() =>
+          workflowContext.runClientEffects({
+            navigate_to: "visualization",
+            set_visualization_image_path: "/tmp/view-image.h5",
+            set_visualization_label_path: "/tmp/view-label.h5",
+            set_visualization_scales: [1, 1, 1],
+          })
+        }
+      >
+        View data effects
+      </button>
+      <button
+        type="button"
+        onClick={() =>
+          workflowContext.runClientEffects({
+            navigate_to: "inference",
+            set_inference_config_preset: "configs/MitoEM/Mito25-Local-BC.yaml",
+            set_inference_image_path: "/tmp/image.h5",
+            set_inference_label_path: "/tmp/mask.h5",
+            set_inference_checkpoint_path: "/tmp/checkpoint.pth.tar",
+            set_inference_output_path: "/tmp/out",
+          })
+        }
+      >
+        Configure inference
+      </button>
+      <button
+        type="button"
+        onClick={() =>
+          workflowContext.runClientEffects({
+            reset_workspace: true,
+            mount_project: {
+              directory_path: "/tmp/project",
+              mount_name: "project",
+            },
+          })
+        }
+      >
+        Reset remount
+      </button>
+      <button
+        type="button"
+        onClick={() =>
+          workflowContext.runClientEffects({
+            runtime_action: { kind: "stop_inference" },
+          })
+        }
+      >
+        Stop inference
+      </button>
+      <button
+        type="button"
+        onClick={() =>
+          workflowContext.executeAssistantItem({
+            id: "start-inference",
+            title: "Start inference in app",
+            command: "app inference run",
+            client_effects: {
+              navigate_to: "inference",
+              set_inference_image_path: "/tmp/runtime-image.h5",
+              set_inference_output_path: "/tmp/runtime-out",
+              runtime_action: { kind: "start_inference" },
+            },
+          })
+        }
+      >
+        Execute assistant item
+      </button>
+      <button
+        type="button"
+        onClick={() =>
+          workflowContext.runClientEffects({
+            navigate_to: "mask-proofreading",
+            set_proofreading_dataset_path: "/tmp/image.tif",
+            set_proofreading_mask_path: "/tmp/mask.tif",
+            set_proofreading_project_name: "Proofread me",
+            runtime_action: { kind: "start_proofreading" },
+          })
+        }
+      >
+        Start proofreading
+      </button>
+      <button
+        type="button"
+        onClick={() =>
+          workflowContext.runClientEffects({
+            workflow_action: {
+              kind: "propose_retraining_stage",
+              corrected_mask_path: "/tmp/corrected.tif",
+            },
+            refresh_insights: true,
+          })
+        }
+      >
+        Propose retraining
+      </button>
+      <button
+        type="button"
+        onClick={() =>
+          workflowContext.runClientEffects({
+            navigate_to: "training",
+            set_training_config_preset: "configs/MitoEM/Mito25-Local-BC.yaml",
+            set_training_image_path: "/tmp/image.h5",
+            set_training_label_path: "/tmp/corrected.tif",
+            set_training_output_path: "/tmp/output",
+            set_training_log_path: "/tmp/output",
+            runtime_action: {
+              kind: "start_training",
+              autopick_parameters: true,
+            },
+          })
+        }
+      >
+        Auto train
+      </button>
+      <button
+        type="button"
+        onClick={() =>
+          workflowContext.appendEvent({
+            actor: "system",
+            event_type: "test.event",
+            summary: "Append test event.",
+          })
+        }
+      >
+        Append event
+      </button>
+      <div>
+        {workflowContext.pendingRuntimeAction?.kind || "no-runtime-action"}
+      </div>
+      <div>
+        {workflowContext.pendingRuntimeAction?.overrides?.datasetPath ||
+          "no-dataset-override"}
+      </div>
+      <div>
+        {workflowContext.pendingRuntimeAction?.overrides?.inputImagePath ||
+          "no-training-image-override"}
+      </div>
+      <div>
+        {workflowContext.pendingRuntimeAction?.overrides?.inputLabelPath ||
+          "no-training-label-override"}
+      </div>
+      <div>
+        {workflowContext.pendingRuntimeAction?.overrides?.outputPath ||
+          "no-training-output-override"}
+      </div>
+      <div>
+        {workflowContext.pendingRuntimeAction?.overrides?.logPath ||
+          "no-training-log-override"}
+      </div>
+      <div>
+        {workflowContext.pendingRuntimeAction?.overrides?.autoParameters
+          ? "auto-parameters"
+          : "manual-parameters"}
+      </div>
     </div>
   );
 }
@@ -65,20 +285,120 @@ describe("WorkflowProvider", () => {
       workflow: baseWorkflow,
       events: [{ id: 1, event_type: "workflow.created" }],
     });
+    startNewWorkflow.mockResolvedValue({
+      workflow: baseWorkflow,
+      events: [{ id: 1, event_type: "workflow.created" }],
+    });
     listWorkflowEvents.mockResolvedValue([]);
     getWorkflowHotspots.mockResolvedValue({
       workflow_id: 1,
-      hotspots: [{ region_key: "z:9", summary: "Top hotspot", severity: "high" }],
+      hotspots: [
+        { region_key: "z:9", summary: "Top hotspot", severity: "high" },
+      ],
     });
     getWorkflowImpactPreview.mockResolvedValue({
       workflow_id: 1,
       confidence: "medium",
       summary: "Impact summary",
     });
+    getWorkflowAgentRecommendation.mockResolvedValue({
+      workflow_id: 1,
+      stage: "setup",
+      decision: "Proofread this data if the mask is ready.",
+      rationale:
+        "A human review pass is the fastest way to create useful edits.",
+      confidence: "medium",
+      next_stage: "proofreading",
+      readiness: [],
+      actions: [],
+      commands: [],
+    });
+    getWorkflowPreflight.mockResolvedValue({
+      workflow_id: 1,
+      overall_status: "image_only",
+      summary: "Image volume is loaded; add a checkpoint or mask/label next.",
+      items: [],
+    });
+    getWorkflowProjectProgress.mockResolvedValue({
+      workflow_id: 1,
+      summary: { total: 0, tracked_total: 0 },
+      volumes: [],
+    });
+    getWorkflowOverview.mockResolvedValue({
+      workflow_id: 1,
+      project_name: "Segmentation Workflow",
+      workflow_stage: "setup",
+      phase: "setup",
+      phase_label: "Setup",
+      phase_reason: "No project data is mounted yet.",
+      phase_index: 0,
+      volume_summary: { total: 0, tracked_total: 0 },
+      project_progress: {
+        workflow_id: 1,
+        summary: { total: 0, tracked_total: 0 },
+        volumes: [],
+      },
+      stages: [],
+      blockers: [],
+      recommended_next_actions: [],
+      active_runs: [],
+      recent_events: [],
+    });
+    updateWorkflowProjectProgressVolume.mockResolvedValue({
+      workflow_id: 1,
+      summary: { total: 1, tracked_total: 1, ground_truth: 1 },
+      volumes: [],
+    });
+    createAgentAction.mockResolvedValue({
+      id: 8,
+      event_type: "agent.proposal_created",
+    });
+    computeWorkflowEvaluationResult.mockResolvedValue({
+      id: 9,
+      summary: "Before/after evaluation computed.",
+    });
+    exportWorkflowBundle.mockResolvedValue({
+      artifacts: [{ id: 1 }],
+      artifact_paths: [],
+    });
+    mountProjectDirectory.mockResolvedValue({
+      mounted_root_id: 5,
+      message: "Project mounted.",
+    });
+    resetFileWorkspace.mockResolvedValue({
+      deleted_count: 2,
+      mounted_root_count: 1,
+    });
+    runWorkflowCommand.mockResolvedValue({ submitted: true });
+    stopModelInference.mockResolvedValue();
+    stopModelTraining.mockResolvedValue();
+    getConfigPresetContent.mockResolvedValue({
+      path: "configs/MitoEM/Mito25-Local-BC.yaml",
+      content: "DATASET: {}\nSOLVER: {}\n",
+    });
+    listWorkflowArtifacts.mockResolvedValue([
+      { id: 1, artifact_type: "image_volume" },
+    ]);
+    listWorkflowModelRuns.mockResolvedValue([{ id: 2, run_type: "inference" }]);
+    listWorkflowModelVersions.mockResolvedValue([]);
+    listWorkflowCorrectionSets.mockResolvedValue([
+      { id: 3, corrected_mask_path: "/tmp/corrected.tif" },
+    ]);
+    listWorkflowEvaluationResults.mockResolvedValue([
+      { id: 4, metrics: { summary: { dice_delta: 0.1 } } },
+    ]);
   });
 
-  it("loads the current workflow and events on startup", async () => {
-    renderProvider({ trainingState: { setInputLabel: jest.fn() } });
+  it("resumes the current workflow and remounts the boot project on startup", async () => {
+    const resetFileState = jest.fn();
+    getCurrentWorkflow.mockResolvedValueOnce({
+      workflow: { ...baseWorkflow, dataset_path: "/tmp/boot-project" },
+      events: [{ id: 1, event_type: "workflow.created" }],
+    });
+    renderProvider({
+      resetFileState,
+      trainingState: { setInputLabel: jest.fn() },
+    });
 
     expect(await screen.findByText("setup")).toBeTruthy();
     expect(screen.getByText("workflow.created")).toBeTruthy();
@@ -89,8 +409,31 @@ describe("WorkflowProvider", () => {
     await waitFor(() => {
       expect(screen.getByText("Top hotspot")).toBeTruthy();
       expect(screen.getByText("medium")).toBeTruthy();
+      expect(
+        screen.getByText("Proofread this data if the mask is ready."),
+      ).toBeTruthy();
+      expect(screen.getByText("image_only")).toBeTruthy();
     });
-    expect(getCurrentWorkflow).toHaveBeenCalledTimes(1);
+    await waitFor(() => {
+      expect(screen.getByText("artifacts:1")).toBeTruthy();
+      expect(screen.getByText("runs:1")).toBeTruthy();
+      expect(screen.getByText("corrections:1")).toBeTruthy();
+      expect(screen.getByText("evaluations:1")).toBeTruthy();
+    });
+    expect(listWorkflowArtifacts).toHaveBeenCalledWith(1);
+    expect(listWorkflowEvaluationResults).toHaveBeenCalledWith(1);
+    expect(resetFileWorkspace).not.toHaveBeenCalled();
+    expect(resetFileState).not.toHaveBeenCalled();
+    expect(startNewWorkflow).not.toHaveBeenCalled();
+    expect(mountProjectDirectory).toHaveBeenCalledWith({
+      directoryPath: "/tmp/boot-project",
+      mountName: baseWorkflow.title,
+      destinationPath: "root",
+    });
+    expect(getCurrentWorkflow).toHaveBeenCalled();
+    expect(getWorkflowAgentRecommendation).toHaveBeenCalledWith(1);
+    expect(getWorkflowPreflight).toHaveBeenCalledWith(1);
+    expect(getWorkflowOverview).toHaveBeenCalledWith(1, { refresh: true });
   });
 
   it("applies client effects when an agent proposal is approved", async () => {
@@ -115,4 +458,395 @@ describe("WorkflowProvider", () => {
       expect(screen.getByText("retraining_staged")).toBeTruthy();
     });
   });
+
+  it("submits durable commands after approval without queueing runtime effects locally", async () => {
+    const setInputLabel = jest.fn();
+    const setInputImage = jest.fn();
+    const setOutputPath = jest.fn();
+    const setLogPath = jest.fn();
+    approveAgentAction.mockResolvedValue({
+      workflow: { ...baseWorkflow, stage: "training_ready" },
+      client_effects: {
+        navigate_to: "training",
+        set_training_image_path: "/tmp/image.h5",
+        set_training_label_path: "/tmp/corrected.tif",
+        set_training_output_path: "/tmp/training-output",
+        set_training_log_path: "/tmp/training-log",
+        runtime_action: { kind: "start_training" },
+      },
+      commands: [
+        {
+          id: 22,
+          title: "Start training",
+          command: "pytc train",
+        },
+      ],
+    });
+
+    renderProvider({
+      trainingState: {
+        setInputImage,
+        setInputLabel,
+        setOutputPath,
+        setLogPath,
+      },
+    });
+    await screen.findByText("setup");
+
+    fireEvent.click(screen.getByText("Approve proposal"));
+
+    await waitFor(() => {
+      expect(setInputImage).toHaveBeenCalledWith("/tmp/image.h5");
+      expect(setInputLabel).toHaveBeenCalledWith("/tmp/corrected.tif");
+      expect(setOutputPath).toHaveBeenCalledWith("/tmp/training-output");
+      expect(setLogPath).toHaveBeenCalledWith("/tmp/training-log");
+      expect(runWorkflowCommand).toHaveBeenCalledWith(1, 22);
+    });
+    await waitFor(() => {
+      expect(screen.getByText("monitor_training")).toBeTruthy();
+      expect(screen.getByText("/tmp/image.h5")).toBeTruthy();
+      expect(screen.getByText("/tmp/corrected.tif")).toBeTruthy();
+      expect(screen.getByText("/tmp/training-output")).toBeTruthy();
+      expect(screen.getByText("/tmp/training-log")).toBeTruthy();
+    });
+  });
+
+  it("exposes direct client-effect execution for chat action cards", async () => {
+    const setOutputPath = jest.fn();
+
+    renderProvider({
+      trainingState: { setInputLabel: jest.fn() },
+      inferenceState: { setOutputPath },
+    });
+    await screen.findByText("setup");
+
+    fireEvent.click(screen.getByText("Run effects"));
+
+    await waitFor(() => {
+      expect(setOutputPath).toHaveBeenCalledWith("/tmp/inference-out");
+    });
+  });
+
+  it("applies agent-selected visualization paths", async () => {
+    const setCurrentImage = jest.fn();
+    const setCurrentLabel = jest.fn();
+    const setVisualizationScales = jest.fn();
+
+    renderProvider({
+      setCurrentImage,
+      setCurrentLabel,
+      setVisualizationScales,
+      trainingState: { setInputLabel: jest.fn() },
+    });
+    await screen.findByText("setup");
+
+    fireEvent.click(screen.getByText("View data effects"));
+
+    await waitFor(() => {
+      expect(setCurrentImage).toHaveBeenCalledWith("/tmp/view-image.h5");
+      expect(setCurrentLabel).toHaveBeenCalledWith("/tmp/view-label.h5");
+      expect(setVisualizationScales).toHaveBeenCalledWith("1,1,1");
+    });
+  });
+
+  it("prefills inference config, inputs, checkpoint, and output", async () => {
+    const setInputImage = jest.fn();
+    const setInputLabel = jest.fn();
+    const setCheckpointPath = jest.fn();
+    const setOutputPath = jest.fn();
+    const setConfigOriginPath = jest.fn();
+    const setSelectedYamlPreset = jest.fn();
+    const setUploadedYamlFile = jest.fn();
+    const setInferenceConfig = jest.fn();
+
+    renderProvider({
+      setInferenceConfig,
+      inferenceState: {
+        setInputImage,
+        setInputLabel,
+        setCheckpointPath,
+        setOutputPath,
+        setConfigOriginPath,
+        setSelectedYamlPreset,
+        setUploadedYamlFile,
+      },
+    });
+    await screen.findByText("setup");
+
+    fireEvent.click(screen.getByText("Configure inference"));
+
+    await waitFor(() => {
+      expect(setInferenceConfig).toHaveBeenCalledWith(
+        "DATASET: {}\nSOLVER: {}\n",
+      );
+      expect(setInputImage).toHaveBeenCalledWith("/tmp/image.h5");
+      expect(setInputLabel).toHaveBeenCalledWith("/tmp/mask.h5");
+      expect(setCheckpointPath).toHaveBeenCalledWith("/tmp/checkpoint.pth.tar");
+      expect(setOutputPath).toHaveBeenCalledWith("/tmp/out");
+    });
+  });
+
+  it("resets cached file state, remounts a project, and stops inference", async () => {
+    const resetFileState = jest.fn();
+
+    renderProvider({
+      resetFileState,
+      inferenceState: {
+        setOutputPath: jest.fn(),
+        setCheckpointPath: jest.fn(),
+      },
+    });
+    await screen.findByText("setup");
+
+    fireEvent.click(screen.getByText("Reset remount"));
+
+    await waitFor(() => {
+      expect(resetFileWorkspace).toHaveBeenCalled();
+      expect(resetFileState).toHaveBeenCalled();
+      expect(mountProjectDirectory).toHaveBeenCalledWith({
+        directoryPath: "/tmp/project",
+        mountName: "project",
+        destinationPath: "root",
+      });
+    });
+
+    fireEvent.click(screen.getByText("Stop inference"));
+
+    await waitFor(() => {
+      expect(stopModelInference).toHaveBeenCalled();
+      expect(screen.getByText("stop_inference")).toBeTruthy();
+    });
+  });
+
+  it("queues runtime actions and logs assistant command execution", async () => {
+    const setOutputPath = jest.fn();
+
+    renderProvider({
+      trainingState: { setInputLabel: jest.fn(), setLogPath: jest.fn() },
+      inferenceState: { setOutputPath, setCheckpointPath: jest.fn() },
+    });
+    await screen.findByText("setup");
+
+    fireEvent.click(screen.getByText("Execute assistant item"));
+
+    await waitFor(() => {
+      expect(setOutputPath).toHaveBeenCalledWith("/tmp/runtime-out");
+    });
+    await waitFor(() => {
+      expect(screen.getByText("start_inference")).toBeTruthy();
+    });
+    expect(screen.getByText("/tmp/runtime-image.h5")).toBeTruthy();
+    expect(appendWorkflowEvent).toHaveBeenCalledWith(
+      1,
+      expect.objectContaining({
+        actor: "user",
+        event_type: "assistant.command.invoked",
+      }),
+    );
+  });
+
+  it("loads agent-selected training config before queueing training", async () => {
+    const setInputImage = jest.fn();
+    const setInputLabel = jest.fn();
+    const setOutputPath = jest.fn();
+    const setLogPath = jest.fn();
+    const setConfigOriginPath = jest.fn();
+    const setSelectedYamlPreset = jest.fn();
+    const setUploadedYamlFile = jest.fn();
+    const setTrainingConfig = jest.fn();
+
+    renderProvider({
+      setTrainingConfig,
+      trainingState: {
+        setInputImage,
+        setInputLabel,
+        setOutputPath,
+        setLogPath,
+        setConfigOriginPath,
+        setSelectedYamlPreset,
+        setUploadedYamlFile,
+      },
+      inferenceState: {
+        setOutputPath: jest.fn(),
+        setCheckpointPath: jest.fn(),
+      },
+    });
+    await screen.findByText("setup");
+    fireEvent.click(screen.getByText("Auto train"));
+
+    await waitFor(() => {
+      expect(getConfigPresetContent).toHaveBeenCalledWith(
+        "configs/MitoEM/Mito25-Local-BC.yaml",
+      );
+      expect(setTrainingConfig).toHaveBeenCalledWith(
+        "DATASET: {}\nSOLVER: {}\n",
+      );
+      expect(setInputImage).toHaveBeenCalledWith("/tmp/image.h5");
+      expect(setInputLabel).toHaveBeenCalledWith("/tmp/corrected.tif");
+      expect(setOutputPath).toHaveBeenCalledWith("/tmp/output");
+      expect(screen.getByText("start_training")).toBeTruthy();
+      expect(screen.getByText("/tmp/image.h5")).toBeTruthy();
+      expect(screen.getByText("auto-parameters")).toBeTruthy();
+    });
+  });
+
+  it("queues proofreading runtime actions with image and mask overrides", async () => {
+    renderProvider({
+      trainingState: { setInputLabel: jest.fn(), setLogPath: jest.fn() },
+      inferenceState: {
+        setOutputPath: jest.fn(),
+        setCheckpointPath: jest.fn(),
+      },
+    });
+    await screen.findByText("setup");
+
+    fireEvent.click(screen.getByText("Start proofreading"));
+
+    await waitFor(() => {
+      expect(screen.getByText("start_proofreading")).toBeTruthy();
+      expect(screen.getByText("/tmp/image.tif")).toBeTruthy();
+    });
+  });
+
+  it("creates approval-gated retraining proposals from client workflow actions", async () => {
+    renderProvider({
+      trainingState: { setInputLabel: jest.fn() },
+      inferenceState: { setOutputPath: jest.fn() },
+    });
+    await screen.findByText("setup");
+
+    fireEvent.click(screen.getByText("Propose retraining"));
+
+    await waitFor(() => {
+      expect(createAgentAction).toHaveBeenCalledWith(
+        1,
+        expect.objectContaining({
+          action: "stage_retraining_from_corrections",
+          payload: { corrected_mask_path: "/tmp/corrected.tif" },
+        }),
+      );
+    });
+    expect(getWorkflowHotspots).toHaveBeenCalledWith(1);
+  });
+
+  it("does not throw when noncritical workflow event append fails", async () => {
+    appendWorkflowEvent.mockRejectedValueOnce(new Error("Network Error"));
+
+    renderProvider({
+      trainingState: { setInputLabel: jest.fn() },
+      inferenceState: { setOutputPath: jest.fn() },
+    });
+    await screen.findByText("setup");
+
+    fireEvent.click(screen.getByText("Append event"));
+
+    await waitFor(() => {
+      expect(appendWorkflowEvent).toHaveBeenCalledWith(
+        1,
+        expect.objectContaining({ event_type: "test.event" }),
+      );
+    });
+    expect(screen.getByText("workflow.created")).toBeTruthy();
+  });
+
+  it("restores a persisted training monitor action after provider remount", async () => {
+    window.sessionStorage.setItem(
+      "pytc.workflow.pendingRuntimeAction.v1",
+      JSON.stringify({
+        kind: "pending_runtime_action",
+        workflowId: 1,
+        action: {
+          id: "monitor_training:123",
+          kind: "monitor_training",
+          commandId: 22,
+          commandResult: { submitted: true },
+          clientEffects: {
+            set_training_config_preset: "configs/MitoEM/Mito25-Local-BC.yaml",
+            set_training_image_path: "/persist/image.tif",
+            set_training_label_path: "/persist/label.tif",
+            set_training_output_path: "/persist/out",
+            set_training_log_path: "/persist/log.txt",
+          },
+          overrides: {
+            inputImagePath: "/persist/image.tif",
+            inputLabelPath: "/persist/label.tif",
+            outputPath: "/persist/out",
+            logPath: "/persist/log.txt",
+          },
+        },
+        savedAt: Date.now(),
+      }),
+    );
+
+    renderProvider({
+      setTrainingConfig: jest.fn(),
+      trainingState: {
+        setInputImage: jest.fn(),
+        setInputLabel: jest.fn(),
+        setOutputPath: jest.fn(),
+        setLogPath: jest.fn(),
+      },
+      inferenceState: {
+        setInputImage: jest.fn(),
+        setInputLabel: jest.fn(),
+      },
+    });
+
+    expect(await screen.findByText("monitor_training")).toBeTruthy();
+    const storageEntry = window.sessionStorage.getItem(
+      "pytc.workflow.pendingRuntimeAction.v1",
+    );
+    expect(storageEntry).toBeTruthy();
+  });
+
+  it("persists an approved durable training proposal as monitor training action", async () => {
+    const setInputImage = jest.fn();
+    const setInputLabel = jest.fn();
+    const setOutputPath = jest.fn();
+    const setLogPath = jest.fn();
+    approveAgentAction.mockResolvedValue({
+      workflow: { ...baseWorkflow, stage: "training_ready" },
+      client_effects: {
+        navigate_to: "training",
+        set_training_image_path: "/tmp/image.h5",
+        set_training_label_path: "/tmp/corrected.tif",
+        set_training_output_path: "/tmp/training-output",
+        set_training_log_path: "/tmp/training-log",
+        runtime_action: { kind: "start_training" },
+      },
+      commands: [
+        {
+          id: 22,
+          title: "Start training",
+          command: "pytc train",
+        },
+      ],
+    });
+
+    renderProvider({
+      setTrainingConfig: jest.fn(),
+      trainingState: {
+        setInputImage,
+        setInputLabel,
+        setOutputPath,
+        setLogPath,
+      },
+      inferenceState: {
+        setInputImage: jest.fn(),
+        setInputLabel: jest.fn(),
+      },
+    });
+
+    await screen.findByText("setup");
+    fireEvent.click(screen.getByText("Approve proposal"));
+
+    await waitFor(() => {
+      expect(screen.getByText("monitor_training")).toBeTruthy();
+    });
+    const persisted = JSON.parse(
+      window.sessionStorage.getItem("pytc.workflow.pendingRuntimeAction.v1"),
+    );
+    expect(persisted?.kind).toBe("pending_runtime_action");
+    expect(persisted?.action?.kind).toBe("monitor_training");
+  });
 });
diff --git a/client/src/contexts/workflow/proposalCardConfig.js b/client/src/contexts/workflow/proposalCardConfig.js
index febf263a..c5cb8440 100644
--- a/client/src/contexts/workflow/proposalCardConfig.js
+++ b/client/src/contexts/workflow/proposalCardConfig.js
@@ -6,17 +6,37 @@ const toDisplayValue = (value) => {
     return value.length ? value.join(", ") : "—";
   }
   if (typeof value === "object") {
-    return JSON.stringify(value);
+    if (value.kind) return String(value.kind);
+    return "configured";
   }
   return String(value);
 };
 
+const compactPath = (value) => {
+  if (!value) return "—";
+  const normalized = String(value).replace(/\\/g, "/");
+  const parts = normalized.split("/").filter(Boolean);
+  if (parts.length <= 3) return normalized;
+  return `.../${parts.slice(-3).join("/")}`;
+};
+
 const compactRationale = (rationale) => {
   if (!rationale) return "No rationale provided.";
   const trimmed = String(rationale).trim();
   return trimmed.length > 160 ? `${trimmed.slice(0, 157)}…` : trimmed;
 };
 
+const field = (key, label, value, options = {}) => ({
+  key,
+  label,
+  rawValue: value,
+  value:
+    options.displayValue !== undefined
+      ? toDisplayValue(options.displayValue)
+      : toDisplayValue(value),
+  editable: Boolean(options.editable),
+});
+
 const pickEntries = (proposal, keys) =>
   keys
     .filter((key) => key in proposal)
@@ -26,8 +46,99 @@ const pickEntries = (proposal, keys) =>
       value: toDisplayValue(proposal[key]),
     }));
 
+const CLIENT_EFFECT_FIELD_SPECS = [
+  ["set_training_config_preset", "Config", "config_preset"],
+  ["set_training_image_path", "Images", "image_path"],
+  ["set_training_label_path", "Labels", "label_path"],
+  ["set_training_output_path", "Output", "output_path"],
+  ["set_training_log_path", "Log", "log_path"],
+  ["set_inference_config_preset", "Config", "inference_config_preset"],
+  ["set_inference_checkpoint_path", "Checkpoint", "checkpoint_path"],
+  ["set_inference_image_path", "Image", "inference_image_path"],
+  ["set_inference_label_path", "Label", "inference_label_path"],
+  ["set_inference_output_path", "Output", "inference_output_path"],
+  ["set_visualization_image_path", "Image", "visualization_image_path"],
+  ["set_visualization_label_path", "Label", "visualization_label_path"],
+  ["set_visualization_scales", "Scales", "visualization_scales"],
+  ["set_proofreading_dataset_path", "Image", "proofreading_dataset_path"],
+  ["set_proofreading_mask_path", "Mask", "proofreading_mask_path"],
+  ["set_proofreading_project_name", "Project", "proofreading_project_name"],
+];
+
+const clientEffectFields = (clientEffects = {}) => {
+  if (!clientEffects || typeof clientEffects !== "object") return [];
+  return CLIENT_EFFECT_FIELD_SPECS.filter(
+    ([effectKey]) => clientEffects[effectKey] !== undefined,
+  ).map(([effectKey, label, overrideKey]) => {
+    const rawValue = clientEffects[effectKey];
+    const shouldCompact =
+      typeof rawValue === "string" &&
+      (rawValue.includes("/") || rawValue.includes("\\"));
+    return field(overrideKey, label, rawValue, {
+      editable: true,
+      displayValue: shouldCompact ? compactPath(rawValue) : rawValue,
+    });
+  });
+};
+
+const trainingSubsetFields = (subset = {}) => {
+  if (!subset || typeof subset !== "object") return [];
+  const statuses = Array.isArray(subset.training_statuses)
+    ? subset.training_statuses
+    : [];
+  const source =
+    statuses.length === 1 && statuses[0] === "ground_truth"
+      ? "fully good GT"
+      : statuses.join(", ") || "selected labels";
+  const fields = [];
+  if (subset.train_volume_count !== undefined) {
+    fields.push(
+      field(
+        "training_subset_train",
+        "Training set",
+        `${subset.train_volume_count} ${source} volume${
+          Number(subset.train_volume_count) === 1 ? "" : "s"
+        }`,
+      ),
+    );
+  }
+  if (subset.target_volume_count !== undefined) {
+    fields.push(
+      field(
+        "training_subset_targets",
+        "After training",
+        `${subset.target_volume_count} image-only target${
+          Number(subset.target_volume_count) === 1 ? "" : "s"
+        }`,
+      ),
+    );
+  }
+  if (subset.review_volume_count) {
+    fields.push(
+      field(
+        "training_subset_review",
+        "Left out",
+        `${subset.review_volume_count} draft mask${
+          Number(subset.review_volume_count) === 1 ? "" : "s"
+        }`,
+      ),
+    );
+  }
+  if (subset.manifest_path) {
+    fields.push(
+      field(
+        "training_subset_manifest",
+        "Manifest",
+        compactPath(subset.manifest_path),
+      ),
+    );
+  }
+  return fields;
+};
+
 export const getProposalCardContent = (proposal = {}) => {
-  const type = proposal.type || proposal.proposal_type || proposal.action || "proposal";
+  const type =
+    proposal.type || proposal.proposal_type || proposal.action || "proposal";
 
   if (type === "prioritize_failure_hotspots") {
     return {
@@ -70,12 +181,86 @@ export const getProposalCardContent = (proposal = {}) => {
         "corrected_mask_path",
         "written_path",
         "training_output_path",
-      ]),
+      ]).map((item) =>
+        [
+          "corrected_mask_path",
+          "written_path",
+          "training_output_path",
+        ].includes(item.key)
+          ? {
+              ...item,
+              rawValue: proposal[item.key],
+              value: compactPath(proposal[item.key]),
+              editable: true,
+            }
+          : item,
+      ),
+    };
+  }
+
+  if (type === "start_training_run") {
+    const subset = proposal.training_volume_subset;
+    return {
+      type,
+      title: "Approve Training Run",
+      rationale: compactRationale(
+        proposal.rationale ||
+          proposal.why ||
+          "Start training with the proposed inputs and safe defaults.",
+      ),
+      fields: [
+        field("config_preset", "Config", proposal.config_preset, {
+          editable: true,
+          displayValue: compactPath(proposal.config_preset),
+        }),
+        field("image_path", "Images", proposal.image_path, {
+          editable: true,
+          displayValue: compactPath(proposal.image_path),
+        }),
+        field("label_path", "Labels", proposal.label_path, {
+          editable: true,
+          displayValue: compactPath(proposal.label_path),
+        }),
+        field("output_path", "Output", proposal.output_path, {
+          editable: true,
+          displayValue: compactPath(proposal.output_path),
+        }),
+        ...trainingSubsetFields(subset),
+        field(
+          "parameters",
+          "Parameters",
+          proposal.autopick_parameters
+            ? "safe defaults"
+            : proposal.parameter_mode,
+          { editable: false },
+        ),
+      ].filter((item) => item.value !== "—"),
+    };
+  }
+
+  if (type === "run_client_effects") {
+    return {
+      type,
+      title: "Approve App Action",
+      rationale: compactRationale(
+        proposal.rationale ||
+          proposal.why ||
+          "Run the proposed assistant action inside the app.",
+      ),
+      fields: pickEntries(proposal, [
+        "item_label",
+        "item_type",
+        "risk_level",
+        "runtime_action",
+        "workflow_action",
+      ]).concat(clientEffectFields(proposal.client_effects)),
     };
   }
 
   const fallbackFields = Object.entries(proposal)
-    .filter(([key]) => !["type", "proposal_type", "rationale", "why"].includes(key))
+    .filter(
+      ([key]) => !["type", "proposal_type", "rationale", "why"].includes(key),
+    )
     .slice(0, 4)
     .map(([key, value]) => ({
       key,
diff --git a/client/src/design/workflowDesignSystem.js b/client/src/design/workflowDesignSystem.js
new file mode 100644
index 00000000..75acf041
--- /dev/null
+++ b/client/src/design/workflowDesignSystem.js
@@ -0,0 +1,107 @@
+export const antdWorkflowTheme = {
+  token: {
+    colorPrimary: "#3f37c9",
+    colorInfo: "#3f37c9",
+    colorSuccess: "#2f7d32",
+    colorWarning: "#b8660f",
+    colorError: "#b13a2f",
+    borderRadius: 8,
+    fontFamily:
+      '"IBM Plex Sans", "Aptos", "Segoe UI", -apple-system, BlinkMacSystemFont, sans-serif',
+    fontFamilyCode:
+      '"IBM Plex Mono", "SFMono-Regular", Menlo, Monaco, Consolas, monospace',
+  },
+};
+
+export const STAGE_META = {
+  setup: {
+    label: "Setup",
+    tone: "neutral",
+    color: "default",
+    description: "Define project context and source artifacts.",
+  },
+  visualization: {
+    label: "Visualization",
+    tone: "teal",
+    color: "cyan",
+    description: "Inspect source image and labels.",
+  },
+  inference: {
+    label: "Inference",
+    tone: "blue",
+    color: "blue",
+    description: "Run model prediction and inspect output.",
+  },
+  proofreading: {
+    label: "Proofreading",
+    tone: "amber",
+    color: "gold",
+    description: "Correct masks and classify failure regions.",
+  },
+  retraining_staged: {
+    label: "Retraining Staged",
+    tone: "orange",
+    color: "orange",
+    description: "Corrections are linked to the next training run.",
+  },
+  evaluation: {
+    label: "Evaluation",
+    tone: "green",
+    color: "green",
+    description: "Compare before/after model behavior.",
+  },
+};
+
+export const SEVERITY_META = {
+  low: { label: "Low", color: "default", tone: "neutral" },
+  medium: { label: "Medium", color: "orange", tone: "amber" },
+  high: { label: "High", color: "red", tone: "red" },
+};
+
+export const APPROVAL_META = {
+  not_required: { label: "Logged", color: "default", tone: "neutral" },
+  pending: { label: "Needs Review", color: "gold", tone: "amber" },
+  approved: { label: "Approved", color: "green", tone: "green" },
+  rejected: { label: "Rejected", color: "red", tone: "red" },
+};
+
+export const ARTIFACT_META = {
+  dataset: { label: "Dataset", color: "blue" },
+  image_volume: { label: "Image", color: "cyan" },
+  label_volume: { label: "Label", color: "geekblue" },
+  mask_volume: { label: "Mask", color: "purple" },
+  correction_set: { label: "CorrectionSet", color: "gold" },
+  model_checkpoint: { label: "Checkpoint", color: "green" },
+  training_output: { label: "Training Run", color: "lime" },
+  inference_output: { label: "Prediction", color: "blue" },
+  evaluation_report: { label: "Evaluation", color: "volcano" },
+  evidence_bundle: { label: "Evidence Bundle", color: "magenta" },
+};
+
+export function getStageMeta(stage) {
+  return (
+    STAGE_META[stage] || {
+      label: stage || "No Workflow",
+      tone: "neutral",
+      color: "default",
+      description: "No active workflow stage.",
+    }
+  );
+}
+
+export function getSeverityMeta(severity) {
+  return SEVERITY_META[severity] || SEVERITY_META.low;
+}
+
+export function getApprovalMeta(status) {
+  return APPROVAL_META[status] || APPROVAL_META.not_required;
+}
+
+export function getArtifactMeta(type) {
+  return (
+    ARTIFACT_META[type] || {
+      label: type || "Artifact",
+      color: "default",
+    }
+  );
+}
diff --git a/client/src/electronApi.js b/client/src/electronApi.js
index 172c3079..2d90b243 100644
--- a/client/src/electronApi.js
+++ b/client/src/electronApi.js
@@ -14,6 +14,10 @@ export function openLocalFile(options = {}) {
   return api.openLocalFile(options);
 }
 
+export function canOpenLocalFile() {
+  return Boolean(getElectronAPI()?.openLocalFile);
+}
+
 export function revealInFinder(targetPath) {
   const api = getElectronAPI();
   if (!api) {
diff --git a/client/src/index.js b/client/src/index.js
index df868170..71d95547 100644
--- a/client/src/index.js
+++ b/client/src/index.js
@@ -1,11 +1,18 @@
 import React from "react";
 import ReactDOM from "react-dom/client";
+import { ConfigProvider } from "antd";
 import "./index.css";
 import App from "./App";
+import { antdWorkflowTheme } from "./design/workflowDesignSystem";
+import { installClientLogging } from "./logging/appEventLog";
+
+installClientLogging();
 
 const root = ReactDOM.createRoot(document.getElementById("root"));
 root.render(
   <React.StrictMode>
-    <App />
+    <ConfigProvider theme={antdWorkflowTheme}>
+      <App />
+    </ConfigProvider>
   </React.StrictMode>,
 );
diff --git a/client/src/logging/appEventLog.js b/client/src/logging/appEventLog.js
new file mode 100644
index 00000000..49b29dc0
--- /dev/null
+++ b/client/src/logging/appEventLog.js
@@ -0,0 +1,597 @@
+const isLocalHost = (hostname) =>
+  /^(localhost|127\.0\.0\.1)$/.test(hostname || "");
+
+const removeTrailingSlash = (value) => value.replace(/\/+$/, "");
+
+const getDefaultBaseUrl = () => {
+  if (
+    typeof window !== "undefined" &&
+    window.location?.origin &&
+    !isLocalHost(window.location.hostname)
+  ) {
+    return `${window.location.origin}/api`;
+  }
+
+  return `${process.env.REACT_APP_SERVER_PROTOCOL || "http"}://${process.env.REACT_APP_SERVER_URL || "localhost:4242"}`;
+};
+
+const BASE_URL = removeTrailingSlash(
+  process.env.REACT_APP_API_BASE_URL || getDefaultBaseUrl(),
+);
+const LOG_ENDPOINT = `${BASE_URL}/app/log-event`;
+const CLIENT_SESSION_ID = `client-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+const envFlagEnabled = (name, defaultValue = true) => {
+  const rawValue = process.env[name];
+  if (rawValue === undefined || rawValue === "") return defaultValue;
+  return !["0", "false", "off", "no"].includes(String(rawValue).toLowerCase());
+};
+
+const CAPTURE_CONSOLE_LOGS = envFlagEnabled(
+  "REACT_APP_CAPTURE_CONSOLE_LOGS",
+  true,
+);
+const CAPTURE_BROWSER_NETWORK = envFlagEnabled(
+  "REACT_APP_CAPTURE_BROWSER_NETWORK",
+  true,
+);
+const CAPTURE_DOM_EVENTS = envFlagEnabled("REACT_APP_CAPTURE_DOM_EVENTS", true);
+const CAPTURE_RESOURCE_TIMING = envFlagEnabled(
+  "REACT_APP_CAPTURE_RESOURCE_TIMING",
+  true,
+);
+const MAX_SEND_FAILURES = 3;
+const DOM_EVENT_TYPES = [
+  "click",
+  "dblclick",
+  "submit",
+  "change",
+  "input",
+  "keydown",
+  "keyup",
+  "focusin",
+  "focusout",
+  "dragstart",
+  "drop",
+  "paste",
+];
+const LOG_ENDPOINT_PATH = (() => {
+  try {
+    return new URL(LOG_ENDPOINT).pathname;
+  } catch {
+    return "/app/log-event";
+  }
+})();
+
+let installed = false;
+const originalConsole = {};
+let originalFetch = null;
+let originalXHROpen = null;
+let originalXHRSend = null;
+let originalPushState = null;
+let originalReplaceState = null;
+let sendFailures = 0;
+let loggingDisabledUntil = 0;
+let lastDomEventAtByKey = {};
+
+const normalizeValue = (value, depth = 0, seen = new WeakSet()) => {
+  if (depth > 3) {
+    return "[max-depth]";
+  }
+  if (
+    value === null ||
+    value === undefined ||
+    typeof value === "string" ||
+    typeof value === "number" ||
+    typeof value === "boolean"
+  ) {
+    return value;
+  }
+  if (value instanceof Error) {
+    return {
+      name: value.name,
+      message: value.message,
+      stack: value.stack,
+    };
+  }
+  if (Array.isArray(value)) {
+    return value
+      .slice(0, 20)
+      .map((item) => normalizeValue(item, depth + 1, seen));
+  }
+  if (typeof value === "object") {
+    if (seen.has(value)) {
+      return "[circular]";
+    }
+    seen.add(value);
+    const output = {};
+    Object.entries(value)
+      .slice(0, 20)
+      .forEach(([key, item]) => {
+        output[key] = normalizeValue(item, depth + 1, seen);
+      });
+    return output;
+  }
+  return String(value);
+};
+
+const normalizeUrl = (url) => {
+  if (!url) return "";
+  if (typeof url === "string") return url;
+  if (typeof URL !== "undefined" && url instanceof URL) return url.toString();
+  if (typeof Request !== "undefined" && url instanceof Request) return url.url;
+  return String(url);
+};
+
+const shouldSkipLogUrl = (url) => {
+  const normalized = normalizeUrl(url);
+  if (!normalized) return false;
+  try {
+    const parsed = new URL(
+      normalized,
+      typeof window !== "undefined" ? window.location.href : undefined,
+    );
+    return parsed.pathname === LOG_ENDPOINT_PATH;
+  } catch {
+    return normalized.includes("/app/log-event");
+  }
+};
+
+const nowMs = () =>
+  typeof performance !== "undefined" ? performance.now() : Date.now();
+
+const formatConsoleArgs = (args) =>
+  args
+    .map((arg) => {
+      if (typeof arg === "string") return arg;
+      try {
+        return JSON.stringify(normalizeValue(arg));
+      } catch {
+        return String(arg);
+      }
+    })
+    .join(" ");
+
+const sendPayload = (payload) => {
+  if (
+    sendFailures >= MAX_SEND_FAILURES &&
+    typeof Date !== "undefined" &&
+    Date.now() < loggingDisabledUntil
+  ) {
+    return;
+  }
+
+  const body = JSON.stringify(payload);
+
+  try {
+    const fetchImpl =
+      originalFetch ||
+      (typeof window !== "undefined" && window.fetch
+        ? window.fetch.bind(window)
+        : null);
+    if (!fetchImpl) return;
+
+    fetchImpl(LOG_ENDPOINT, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body,
+      keepalive: true,
+    })
+      .then((response) => {
+        if (response.ok) {
+          sendFailures = 0;
+          return;
+        }
+        sendFailures += 1;
+        if (sendFailures >= MAX_SEND_FAILURES) {
+          loggingDisabledUntil = Date.now() + 60000;
+        }
+      })
+      .catch(() => {
+        sendFailures += 1;
+        if (sendFailures >= MAX_SEND_FAILURES) {
+          loggingDisabledUntil = Date.now() + 60000;
+        }
+      });
+  } catch {
+    // Swallow client logging failures.
+  }
+};
+
+export const logClientEvent = (
+  event,
+  { level = "INFO", message = "", data = null, source = "client", url } = {},
+) => {
+  sendPayload({
+    event,
+    level,
+    message,
+    data: data ? normalizeValue(data) : undefined,
+    source,
+    sessionId: CLIENT_SESSION_ID,
+    url:
+      url || (typeof window !== "undefined" ? window.location.href : undefined),
+  });
+};
+
+const installConsoleLogging = () => {
+  ["log", "info", "warn", "error", "debug"].forEach((method) => {
+    const original = console[method].bind(console);
+    originalConsole[method] = original;
+    console[method] = (...args) => {
+      original(...args);
+      logClientEvent("console_output", {
+        level: method === "debug" ? "INFO" : method.toUpperCase(),
+        message: formatConsoleArgs(args),
+        data: { method, args: args.map((arg) => normalizeValue(arg)) },
+        source: "console",
+      });
+    };
+  });
+};
+
+const summarizeElement = (target) => {
+  if (!target || !target.tagName) return {};
+  const text = String(target.innerText || target.textContent || "")
+    .replace(/\s+/g, " ")
+    .trim();
+  const value =
+    "value" in target && typeof target.value === "string" ? target.value : "";
+  return {
+    tagName: target.tagName,
+    id: target.id || "",
+    className: String(target.className || "").slice(0, 160),
+    name: target.name || "",
+    role: target.getAttribute?.("role") || "",
+    ariaLabel: target.getAttribute?.("aria-label") || "",
+    title: target.getAttribute?.("title") || "",
+    textPreview: text.slice(0, 120),
+    valueLength: value.length,
+    checked: typeof target.checked === "boolean" ? target.checked : undefined,
+    href: target.href || undefined,
+    src: target.src || undefined,
+  };
+};
+
+const shouldLogDomEvent = (event) => {
+  if (event.type !== "input") return true;
+  const key = [
+    event.type,
+    event.target?.tagName || "",
+    event.target?.id || "",
+    event.target?.name || "",
+    event.target?.className || "",
+  ].join("|");
+  const current = Date.now();
+  if (current - (lastDomEventAtByKey[key] || 0) < 750) {
+    return false;
+  }
+  lastDomEventAtByKey[key] = current;
+  return true;
+};
+
+const installDomEventLogging = () => {
+  DOM_EVENT_TYPES.forEach((eventType) => {
+    document.addEventListener(
+      eventType,
+      (event) => {
+        if (!shouldLogDomEvent(event)) return;
+        logClientEvent(`dom_${eventType}`, {
+          level: "INFO",
+          message: `${eventType} ${event.target?.tagName || "target"}`,
+          source: "dom",
+          data: {
+            eventType,
+            key: event.key,
+            code: event.code,
+            altKey: event.altKey,
+            ctrlKey: event.ctrlKey,
+            metaKey: event.metaKey,
+            shiftKey: event.shiftKey,
+            button: event.button,
+            target: summarizeElement(event.target),
+          },
+        });
+      },
+      true,
+    );
+  });
+
+  document.addEventListener(
+    "error",
+    (event) => {
+      const target = event.target;
+      if (!target || target === window) return;
+      logClientEvent("resource_error", {
+        level: "ERROR",
+        message: `Resource failed to load: ${target.tagName || "target"}`,
+        source: "resource",
+        data: { target: summarizeElement(target) },
+      });
+    },
+    true,
+  );
+};
+
+const installFetchLogging = () => {
+  if (typeof window.fetch !== "function") return;
+  originalFetch = window.fetch.bind(window);
+  window.fetch = async (...args) => {
+    const [input, init = {}] = args;
+    const url = normalizeUrl(input);
+    const startedAt = nowMs();
+    const skip = shouldSkipLogUrl(url);
+    if (!skip) {
+      logClientEvent("browser_fetch_request", {
+        level: "INFO",
+        message: `${init?.method || input?.method || "GET"} ${url}`,
+        source: "fetch",
+        data: {
+          method: init?.method || input?.method || "GET",
+          url,
+          keepalive: Boolean(init?.keepalive),
+        },
+      });
+    }
+    try {
+      const response = await originalFetch(...args);
+      if (!skip) {
+        logClientEvent("browser_fetch_response", {
+          level: response.ok ? "INFO" : "ERROR",
+          message: `${init?.method || input?.method || "GET"} ${url} -> ${response.status}`,
+          source: "fetch",
+          data: {
+            method: init?.method || input?.method || "GET",
+            url,
+            status: response.status,
+            ok: response.ok,
+            latencyMs: Number((nowMs() - startedAt).toFixed(2)),
+          },
+        });
+      }
+      return response;
+    } catch (error) {
+      if (!skip) {
+        logClientEvent("browser_fetch_failed", {
+          level: "ERROR",
+          message: `${init?.method || input?.method || "GET"} ${url} failed`,
+          source: "fetch",
+          data: {
+            method: init?.method || input?.method || "GET",
+            url,
+            latencyMs: Number((nowMs() - startedAt).toFixed(2)),
+            error: normalizeValue(error),
+          },
+        });
+      }
+      throw error;
+    }
+  };
+};
+
+const installXhrLogging = () => {
+  if (typeof XMLHttpRequest === "undefined") return;
+  originalXHROpen = XMLHttpRequest.prototype.open;
+  originalXHRSend = XMLHttpRequest.prototype.send;
+
+  XMLHttpRequest.prototype.open = function open(method, url, ...rest) {
+    this.__pytcLog = {
+      method: method || "GET",
+      url: normalizeUrl(url),
+      startedAt: null,
+      skip: shouldSkipLogUrl(url),
+    };
+    return originalXHROpen.call(this, method, url, ...rest);
+  };
+
+  XMLHttpRequest.prototype.send = function send(body) {
+    const meta = this.__pytcLog || {};
+    meta.startedAt = nowMs();
+    if (!meta.skip) {
+      logClientEvent("browser_xhr_request", {
+        level: "INFO",
+        message: `${meta.method || "GET"} ${meta.url}`,
+        source: "xhr",
+        data: {
+          method: meta.method || "GET",
+          url: meta.url,
+          bodyType: body ? Object.prototype.toString.call(body) : null,
+        },
+      });
+    }
+
+    this.addEventListener("loadend", () => {
+      if (meta.skip) return;
+      logClientEvent("browser_xhr_response", {
+        level: this.status >= 400 ? "ERROR" : "INFO",
+        message: `${meta.method || "GET"} ${meta.url} -> ${this.status}`,
+        source: "xhr",
+        data: {
+          method: meta.method || "GET",
+          url: meta.url,
+          status: this.status,
+          latencyMs:
+            meta.startedAt !== null
+              ? Number((nowMs() - meta.startedAt).toFixed(2))
+              : null,
+        },
+      });
+    });
+
+    this.addEventListener("error", () => {
+      if (meta.skip) return;
+      logClientEvent("browser_xhr_failed", {
+        level: "ERROR",
+        message: `${meta.method || "GET"} ${meta.url} failed`,
+        source: "xhr",
+        data: {
+          method: meta.method || "GET",
+          url: meta.url,
+          latencyMs:
+            meta.startedAt !== null
+              ? Number((nowMs() - meta.startedAt).toFixed(2))
+              : null,
+        },
+      });
+    });
+
+    return originalXHRSend.call(this, body);
+  };
+};
+
+const logNavigation = (event, extra = {}) => {
+  logClientEvent(event, {
+    level: "INFO",
+    message: `${event}: ${window.location.href}`,
+    source: "navigation",
+    data: {
+      href: window.location.href,
+      pathname: window.location.pathname,
+      search: window.location.search,
+      hash: window.location.hash,
+      ...extra,
+    },
+  });
+};
+
+const installNavigationLogging = () => {
+  originalPushState = window.history.pushState;
+  originalReplaceState = window.history.replaceState;
+  window.history.pushState = function pushState(state, title, url) {
+    const result = originalPushState.apply(this, arguments);
+    logNavigation("history_push_state", {
+      targetUrl: normalizeUrl(url),
+      state,
+    });
+    return result;
+  };
+  window.history.replaceState = function replaceState(state, title, url) {
+    const result = originalReplaceState.apply(this, arguments);
+    logNavigation("history_replace_state", {
+      targetUrl: normalizeUrl(url),
+      state,
+    });
+    return result;
+  };
+  window.addEventListener("popstate", (event) =>
+    logNavigation("history_pop_state", { state: event.state }),
+  );
+  window.addEventListener("hashchange", () => logNavigation("hash_change"));
+  window.addEventListener("online", () => logNavigation("browser_online"));
+  window.addEventListener("offline", () => logNavigation("browser_offline"));
+  document.addEventListener("visibilitychange", () =>
+    logClientEvent("visibility_change", {
+      level: "INFO",
+      message: `document visibility: ${document.visibilityState}`,
+      source: "browser",
+      data: { visibilityState: document.visibilityState },
+    }),
+  );
+  window.addEventListener("focus", () => logNavigation("window_focus"));
+  window.addEventListener("blur", () => logNavigation("window_blur"));
+  window.addEventListener("message", (event) => {
+    logClientEvent("window_message", {
+      level: "INFO",
+      message: `message from ${event.origin || "unknown origin"}`,
+      source: "window",
+      data: {
+        origin: event.origin,
+        data: normalizeValue(event.data),
+      },
+    });
+  });
+};
+
+const installResourceTimingLogging = () => {
+  if (
+    typeof PerformanceObserver === "undefined" ||
+    !PerformanceObserver.supportedEntryTypes?.includes("resource")
+  ) {
+    return;
+  }
+  const observer = new PerformanceObserver((list) => {
+    list.getEntries().forEach((entry) => {
+      if (shouldSkipLogUrl(entry.name)) return;
+      logClientEvent("resource_timing", {
+        level: "INFO",
+        message: `${entry.initiatorType || "resource"} ${entry.name}`,
+        source: "performance",
+        data: {
+          name: entry.name,
+          initiatorType: entry.initiatorType,
+          durationMs: Number(entry.duration?.toFixed?.(2) || 0),
+          transferSize: entry.transferSize,
+          encodedBodySize: entry.encodedBodySize,
+          decodedBodySize: entry.decodedBodySize,
+          nextHopProtocol: entry.nextHopProtocol,
+        },
+      });
+    });
+  });
+  observer.observe({ type: "resource", buffered: true });
+};
+
+export const installClientLogging = () => {
+  if (installed || typeof window === "undefined") {
+    return;
+  }
+  installed = true;
+  originalFetch =
+    typeof window.fetch === "function"
+      ? window.fetch.bind(window)
+      : originalFetch;
+
+  if (CAPTURE_CONSOLE_LOGS) {
+    installConsoleLogging();
+  }
+  if (CAPTURE_BROWSER_NETWORK) {
+    installFetchLogging();
+    installXhrLogging();
+  }
+  installNavigationLogging();
+  if (CAPTURE_DOM_EVENTS) {
+    installDomEventLogging();
+  }
+  if (CAPTURE_RESOURCE_TIMING) {
+    installResourceTimingLogging();
+  }
+
+  window.addEventListener("error", (event) => {
+    if (
+      typeof event.message === "string" &&
+      event.message.includes("ResizeObserver loop completed")
+    ) {
+      return;
+    }
+    logClientEvent("window_error", {
+      level: "ERROR",
+      message: event.message || "Unhandled window error",
+      data: {
+        filename: event.filename,
+        lineno: event.lineno,
+        colno: event.colno,
+        error: normalizeValue(event.error),
+      },
+      source: "window",
+    });
+  });
+
+  window.addEventListener("unhandledrejection", (event) => {
+    logClientEvent("unhandled_rejection", {
+      level: "ERROR",
+      message: "Unhandled promise rejection",
+      data: {
+        reason: normalizeValue(event.reason),
+      },
+      source: "window",
+    });
+  });
+
+  logClientEvent("app_boot", {
+    level: "INFO",
+    message: "React client booted",
+    data: {
+      userAgent: navigator.userAgent,
+    },
+    source: "client",
+  });
+};
diff --git a/client/src/logging/appEventLog.test.js b/client/src/logging/appEventLog.test.js
new file mode 100644
index 00000000..44b5e024
--- /dev/null
+++ b/client/src/logging/appEventLog.test.js
@@ -0,0 +1,65 @@
+const loadAppEventLogModule = (baseUrl) => {
+  const originalFetch = window.fetch;
+  const fetchMock = jest.fn().mockResolvedValue({ ok: true });
+  window.fetch = fetchMock;
+  process.env.REACT_APP_API_BASE_URL = baseUrl;
+
+  jest.resetModules();
+  const appEventLog = require("./appEventLog");
+
+  return { appEventLog, fetchMock, originalFetch };
+};
+
+describe("appEventLog canonicalization", () => {
+  let originalFetch;
+
+  beforeEach(() => {
+    originalFetch = window.fetch;
+  });
+
+  afterEach(() => {
+    delete process.env.REACT_APP_API_BASE_URL;
+    if (originalFetch) {
+      window.fetch = originalFetch;
+    }
+    jest.clearAllMocks();
+  });
+
+  it("posts logging events to /app/log-event when base URL already has /api", async () => {
+    const { appEventLog, fetchMock } = loadAppEventLogModule(
+      "https://demo.example/api",
+    );
+
+    appEventLog.logClientEvent("api_test_event", {
+      message: "from test",
+      level: "INFO",
+    });
+
+    await Promise.resolve();
+
+    expect(fetchMock).toHaveBeenCalledWith(
+      "https://demo.example/api/app/log-event",
+      expect.objectContaining({
+        method: "POST",
+      }),
+    );
+  });
+
+  it("posts logging events to the app log endpoint on the configured base", async () => {
+    const { appEventLog, fetchMock } = loadAppEventLogModule(
+      "https://demo.example",
+    );
+
+    appEventLog.logClientEvent("api_test_event", {
+      message: "from test",
+      level: "INFO",
+    });
+
+    await Promise.resolve();
+
+    expect(fetchMock).toHaveBeenCalledWith(
+      "https://demo.example/app/log-event",
+      expect.objectContaining({ method: "POST" }),
+    );
+  });
+});
diff --git a/client/src/logging/configLogSummary.js b/client/src/logging/configLogSummary.js
new file mode 100644
index 00000000..b9288716
--- /dev/null
+++ b/client/src/logging/configLogSummary.js
@@ -0,0 +1,168 @@
+import yaml from "js-yaml";
+
+const DIRECT_VOLUME_SUFFIXES = [
+  ".h5",
+  ".hdf5",
+  ".hdf",
+  ".tif",
+  ".tiff",
+  ".ome.tif",
+  ".ome.tiff",
+  ".zarr",
+  ".n5",
+  ".npy",
+  ".npz",
+  ".nii",
+  ".nii.gz",
+  ".mrc",
+  ".map",
+  ".rec",
+  ".png",
+  ".jpg",
+  ".jpeg",
+  ".bmp",
+];
+const VALID_INFERENCE_AUG_NUMS = [4, 8, 16];
+
+const getNestedValue = (data, path) =>
+  path.reduce(
+    (current, key) =>
+      current && current[key] !== undefined ? current[key] : undefined,
+    data,
+  );
+
+const trimPath = (value) =>
+  typeof value === "string" && value.trim() ? value.trim() : null;
+
+const pathBasename = (value) => {
+  const normalized = trimPath(value);
+  if (!normalized) return null;
+  const segments = normalized.split(/[/\\]/);
+  return segments[segments.length - 1] || normalized;
+};
+
+const looksLikeDirectVolume = (value) => {
+  const normalized = trimPath(value)?.toLowerCase();
+  if (!normalized) return false;
+  return DIRECT_VOLUME_SUFFIXES.some((suffix) => normalized.endsWith(suffix));
+};
+
+export const summarizeConfigObject = (configObj, modeHint = null) => {
+  if (!configObj || typeof configObj !== "object") {
+    return null;
+  }
+
+  const datasetImageName = getNestedValue(configObj, ["DATASET", "IMAGE_NAME"]);
+  const datasetLabelName = getNestedValue(configObj, ["DATASET", "LABEL_NAME"]);
+  const inferenceImageName = getNestedValue(configObj, [
+    "INFERENCE",
+    "IMAGE_NAME",
+  ]);
+
+  return {
+    modeHint,
+    architecture: getNestedValue(configObj, ["MODEL", "ARCHITECTURE"]) || null,
+    blockType: getNestedValue(configObj, ["MODEL", "BLOCK_TYPE"]) || null,
+    dataset: {
+      imageName: pathBasename(datasetImageName),
+      labelName: pathBasename(datasetLabelName),
+      outputPath: trimPath(
+        getNestedValue(configObj, ["DATASET", "OUTPUT_PATH"]),
+      ),
+      doChunkTitle: getNestedValue(configObj, ["DATASET", "DO_CHUNK_TITLE"]),
+      validRatio: getNestedValue(configObj, ["DATASET", "VALID_RATIO"]),
+      rejectSamplingProbability: getNestedValue(configObj, [
+        "DATASET",
+        "REJECT_SAMPLING",
+        "P",
+      ]),
+      isAbsolutePath: getNestedValue(configObj, [
+        "DATASET",
+        "IS_ABSOLUTE_PATH",
+      ]),
+      usesDirectVolumePaths:
+        looksLikeDirectVolume(datasetImageName) ||
+        looksLikeDirectVolume(datasetLabelName),
+    },
+    inference: {
+      imageName: pathBasename(inferenceImageName),
+      outputPath: trimPath(
+        getNestedValue(configObj, ["INFERENCE", "OUTPUT_PATH"]),
+      ),
+      augNum: getNestedValue(configObj, ["INFERENCE", "AUG_NUM"]),
+      samplesPerBatch: getNestedValue(configObj, [
+        "INFERENCE",
+        "SAMPLES_PER_BATCH",
+      ]),
+    },
+    solver: {
+      baseLr: getNestedValue(configObj, ["SOLVER", "BASE_LR"]),
+      batchSize: getNestedValue(configObj, ["SOLVER", "SAMPLES_PER_BATCH"]),
+      totalIterations: getNestedValue(configObj, ["SOLVER", "ITERATION_TOTAL"]),
+    },
+    system: {
+      numGpus: getNestedValue(configObj, ["SYSTEM", "NUM_GPUS"]),
+      numCpus: getNestedValue(configObj, ["SYSTEM", "NUM_CPUS"]),
+      parallel: getNestedValue(configObj, ["SYSTEM", "PARALLEL"]),
+      distributed: getNestedValue(configObj, ["SYSTEM", "DISTRIBUTED"]),
+    },
+  };
+};
+
+export const summarizeConfigText = (configText, modeHint = null) => {
+  const summary = {
+    modeHint,
+    textLength: configText?.length || 0,
+    lineCount: configText ? configText.split("\n").length : 0,
+  };
+
+  if (!configText) {
+    return summary;
+  }
+
+  try {
+    const parsed = yaml.load(configText);
+    return {
+      ...summary,
+      parsed: true,
+      config: summarizeConfigObject(parsed, modeHint),
+    };
+  } catch (error) {
+    return {
+      ...summary,
+      parsed: false,
+      parseError: error.message || "Unknown YAML parse error",
+    };
+  }
+};
+
+export const detectConfigDiagnostics = (summary) => {
+  const diagnostics = [];
+  const config = summary?.config;
+  if (!config) {
+    return diagnostics;
+  }
+
+  if (config.dataset?.doChunkTitle && config.dataset?.usesDirectVolumePaths) {
+    diagnostics.push({
+      code: "tile_dataset_direct_volume_mismatch",
+      severity: "warning",
+      message:
+        "DO_CHUNK_TITLE is enabled while IMAGE_NAME/LABEL_NAME look like direct volume files.",
+    });
+  }
+
+  if (
+    config.inference?.augNum !== null &&
+    config.inference?.augNum !== undefined &&
+    !VALID_INFERENCE_AUG_NUMS.includes(config.inference.augNum)
+  ) {
+    diagnostics.push({
+      code: "unsupported_inference_aug_num",
+      severity: "warning",
+      message: `INFERENCE.AUG_NUM is ${config.inference.augNum}; supported values are ${VALID_INFERENCE_AUG_NUMS.join(", ")}.`,
+    });
+  }
+
+  return diagnostics;
+};
diff --git a/client/src/runtime/modelLaunch.js b/client/src/runtime/modelLaunch.js
new file mode 100644
index 00000000..aea5975a
--- /dev/null
+++ b/client/src/runtime/modelLaunch.js
@@ -0,0 +1,354 @@
+import yaml from "js-yaml";
+import { startModelInference, startModelTraining } from "../api";
+import { applyInputPaths, detectConfigSchema } from "../configSchema";
+import { logClientEvent } from "../logging/appEventLog";
+import {
+  detectConfigDiagnostics,
+  summarizeConfigText,
+} from "../logging/configLogSummary";
+
+export function getPathValue(value) {
+  if (!value) return "";
+  if (typeof value === "string") return value;
+  return value.path || value.originFileObj?.path || value.folderPath || "";
+}
+
+function getTrainingConfigOriginPath(trainingState) {
+  return (
+    trainingState?.configOriginPath ||
+    trainingState?.selectedYamlPreset ||
+    getPathValue(trainingState?.uploadedYamlFile)
+  );
+}
+
+function getInferenceConfigOriginPath(inferenceState) {
+  return (
+    inferenceState?.configOriginPath ||
+    inferenceState?.selectedYamlPreset ||
+    getPathValue(inferenceState?.uploadedYamlFile)
+  );
+}
+
+function parseConfigText(configText) {
+  if (!configText) return null;
+  try {
+    const yamlData = yaml.load(configText);
+    return yamlData && typeof yamlData === "object" ? yamlData : null;
+  } catch (error) {
+    return null;
+  }
+}
+
+function resolveInferenceConfigSource(appContext, overrides = {}) {
+  const inferenceState = appContext?.inferenceState || {};
+  const trainingState = appContext?.trainingState || {};
+  const explicitInferenceConfig = overrides.inferenceConfig;
+  const explicitOriginPath = overrides.configOriginPath;
+  const inferenceConfig =
+    explicitInferenceConfig ?? appContext?.inferenceConfig;
+  const inferenceOriginPath =
+    explicitOriginPath || getInferenceConfigOriginPath(inferenceState);
+  const trainingConfig = appContext?.trainingConfig;
+  const trainingOriginPath = getTrainingConfigOriginPath(trainingState);
+
+  if (explicitInferenceConfig || explicitOriginPath) {
+    return {
+      configText: inferenceConfig,
+      originPath: inferenceOriginPath,
+      source: "inference",
+      reason: null,
+    };
+  }
+
+  const inferenceSchema = detectConfigSchema(parseConfigText(inferenceConfig));
+  const trainingSchema = detectConfigSchema(parseConfigText(trainingConfig));
+  const needsTrainingFallback =
+    Boolean(trainingConfig) &&
+    (!inferenceConfig ||
+      (inferenceSchema !== "legacy" && trainingSchema === "legacy") ||
+      (inferenceOriginPath &&
+        inferenceOriginPath.startsWith("tutorials/") &&
+        trainingSchema === "legacy"));
+
+  if (!needsTrainingFallback) {
+    return {
+      configText: inferenceConfig,
+      originPath: inferenceOriginPath,
+      source: "inference",
+      reason: null,
+    };
+  }
+
+  let reason = "missing_inference_config";
+  if (inferenceConfig) {
+    if (inferenceSchema !== "legacy" && trainingSchema === "legacy") {
+      reason = "incompatible_inference_schema";
+    } else if (inferenceOriginPath?.startsWith("tutorials/")) {
+      reason = "stale_inference_preset";
+    }
+  }
+
+  logClientEvent("inference_config_fallback_to_training", {
+    level: "WARNING",
+    message: "Inference launch fell back to the latest training config",
+    source: "modelLaunch",
+    data: {
+      reason,
+      inferenceOriginPath,
+      trainingOriginPath,
+      inferenceSchema,
+      trainingSchema,
+    },
+  });
+
+  return {
+    configText: trainingConfig,
+    originPath: trainingOriginPath,
+    source: "training",
+    reason,
+  };
+}
+
+function prepareConfig(configText, mutator) {
+  try {
+    const yamlData = yaml.load(configText);
+    if (!yamlData || typeof yamlData !== "object") {
+      return configText;
+    }
+    mutator(yamlData);
+    return yaml.dump(yamlData, { indent: 2 }).replace(/^\s*\n/gm, "");
+  } catch (error) {
+    console.warn("Failed to prepare model launch config:", error);
+    logClientEvent("model_launch_config_prepare_failed", {
+      level: "WARNING",
+      message: "Failed to prepare model launch config",
+      source: "modelLaunch",
+      data: {
+        error: error.message || "unknown error",
+        configLength: configText?.length || 0,
+      },
+    });
+    return configText;
+  }
+}
+
+function ensureObject(parent, key) {
+  if (!parent[key] || typeof parent[key] !== "object") {
+    parent[key] = {};
+  }
+  return parent[key];
+}
+
+function applyAgentTrainingDefaults(yamlData) {
+  const solver = ensureObject(yamlData, "SOLVER");
+  const system = ensureObject(yamlData, "SYSTEM");
+  const model = ensureObject(yamlData, "MODEL");
+  const inference = ensureObject(yamlData, "INFERENCE");
+  const dataset = ensureObject(yamlData, "DATASET");
+
+  // Memory-safe defaults: large biomedical volumes are more likely to fail from
+  // over-aggressive batches than from conservative throughput.
+  solver.SAMPLES_PER_BATCH = 1;
+  solver.ITERATION_SAVE = 80;
+  solver.ITERATION_TOTAL = 80;
+  solver.ITERATION_VAL = 80;
+  solver.WARMUP_ITERS = 10;
+  system.NUM_CPUS = 2;
+  system.NUM_GPUS = 1;
+  model.INPUT_SIZE = [65, 65, 65];
+  model.OUTPUT_SIZE = [65, 65, 65];
+  model.FILTERS = [8, 12, 16, 24, 32];
+  dataset.PAD_SIZE = [4, 16, 16];
+  inference.INPUT_SIZE = [65, 65, 65];
+  inference.OUTPUT_SIZE = [65, 65, 65];
+  inference.STRIDE = [32, 32, 32];
+  inference.SAMPLES_PER_BATCH = 1;
+  inference.PAD_SIZE = [4, 16, 16];
+}
+
+export function buildTrainingLaunchRequest(
+  appContext,
+  workflowId = null,
+  overrides = {},
+) {
+  const trainingState = appContext?.trainingState || {};
+  const trainingConfig = overrides.trainingConfig || appContext?.trainingConfig;
+
+  if (!trainingConfig) {
+    throw new Error(
+      "Please load a preset or upload a YAML configuration first.",
+    );
+  }
+
+  const outputPath = getPathValue(
+    overrides.outputPath ?? trainingState.outputPath,
+  );
+  if (!outputPath) {
+    throw new Error("Please set output path first in Step 1.");
+  }
+
+  const inputImagePath = getPathValue(
+    overrides.inputImagePath ?? trainingState.inputImage,
+  );
+  const inputLabelPath = getPathValue(
+    overrides.inputLabelPath ?? trainingState.inputLabel,
+  );
+  const logPath =
+    getPathValue(overrides.logPath ?? trainingState.logPath) || outputPath;
+  const configOriginPath =
+    overrides.configOriginPath || getTrainingConfigOriginPath(trainingState);
+
+  const preparedTrainingConfig = prepareConfig(trainingConfig, (yamlData) => {
+    applyInputPaths(yamlData, {
+      mode: "training",
+      inputImagePath,
+      inputLabelPath,
+      inputPath: "",
+      outputPath,
+    });
+    if (overrides.autoParameters) {
+      applyAgentTrainingDefaults(yamlData);
+    }
+  });
+  const configSummary = summarizeConfigText(preparedTrainingConfig, "training");
+  const diagnostics = detectConfigDiagnostics(configSummary);
+
+  logClientEvent("training_launch_request_built", {
+    level: diagnostics.length ? "WARNING" : "INFO",
+    message: "Training launch request built",
+    source: "modelLaunch",
+    data: {
+      workflowId: overrides.workflowId ?? workflowId,
+      configOriginPath,
+      outputPath,
+      logPath,
+      inputImagePath,
+      inputLabelPath,
+      autoParameters: Boolean(overrides.autoParameters),
+      configSummary,
+      diagnostics,
+    },
+  });
+
+  return {
+    trainingConfig: preparedTrainingConfig,
+    logPath,
+    outputPath,
+    inputImagePath,
+    inputLabelPath,
+    configOriginPath,
+    workflowId: overrides.workflowId ?? workflowId,
+    autoParameters: Boolean(overrides.autoParameters),
+  };
+}
+
+export async function launchTrainingFromContext(
+  appContext,
+  workflowId = null,
+  overrides = {},
+) {
+  const request = buildTrainingLaunchRequest(appContext, workflowId, overrides);
+  return startModelTraining(
+    request.trainingConfig,
+    request.logPath,
+    request.outputPath,
+    request.configOriginPath,
+    request.workflowId,
+    request.autoParameters,
+    request.inputImagePath,
+    request.inputLabelPath,
+  );
+}
+
+export function buildInferenceLaunchRequest(
+  appContext,
+  workflowId = null,
+  overrides = {},
+) {
+  const inferenceState = appContext?.inferenceState || {};
+  const inferenceConfigSource = resolveInferenceConfigSource(
+    appContext,
+    overrides,
+  );
+  const inferenceConfig = inferenceConfigSource.configText;
+
+  if (!inferenceConfig) {
+    throw new Error("Please load or upload an inference configuration first.");
+  }
+
+  const checkpointPath = getPathValue(
+    overrides.checkpointPath ?? inferenceState.checkpointPath,
+  );
+  if (!checkpointPath) {
+    throw new Error("Please set checkpoint path first.");
+  }
+
+  const outputPath = getPathValue(
+    overrides.outputPath ?? inferenceState.outputPath,
+  );
+  const inputImagePath = getPathValue(
+    overrides.inputImagePath ?? inferenceState.inputImage,
+  );
+  const configOriginPath = inferenceConfigSource.originPath;
+
+  const preparedInferenceConfig = prepareConfig(inferenceConfig, (yamlData) => {
+    applyInputPaths(yamlData, {
+      mode: "inference",
+      inputImagePath,
+      inputLabelPath: "",
+      inputPath: "",
+      outputPath,
+    });
+  });
+  const configSummary = summarizeConfigText(
+    preparedInferenceConfig,
+    "inference",
+  );
+  const diagnostics = detectConfigDiagnostics(configSummary);
+
+  logClientEvent("inference_launch_request_built", {
+    level: diagnostics.length ? "WARNING" : "INFO",
+    message: "Inference launch request built",
+    source: "modelLaunch",
+    data: {
+      workflowId: overrides.workflowId ?? workflowId,
+      configOriginPath,
+      configSource: inferenceConfigSource.source,
+      configFallbackReason: inferenceConfigSource.reason,
+      outputPath,
+      checkpointPath,
+      inputImagePath,
+      configSummary,
+      diagnostics,
+    },
+  });
+
+  return {
+    inferenceConfig: preparedInferenceConfig,
+    outputPath,
+    checkpointPath,
+    inputImagePath,
+    configOriginPath,
+    workflowId: overrides.workflowId ?? workflowId,
+  };
+}
+
+export async function launchInferenceFromContext(
+  appContext,
+  workflowId = null,
+  overrides = {},
+) {
+  const request = buildInferenceLaunchRequest(
+    appContext,
+    workflowId,
+    overrides,
+  );
+  return startModelInference(
+    request.inferenceConfig,
+    request.outputPath,
+    request.checkpointPath,
+    request.configOriginPath,
+    request.workflowId,
+    request.inputImagePath,
+  );
+}
diff --git a/client/src/runtime/modelLaunch.test.js b/client/src/runtime/modelLaunch.test.js
new file mode 100644
index 00000000..a1c78051
--- /dev/null
+++ b/client/src/runtime/modelLaunch.test.js
@@ -0,0 +1,153 @@
+import yaml from "js-yaml";
+
+import {
+  buildInferenceLaunchRequest,
+  buildTrainingLaunchRequest,
+} from "./modelLaunch";
+
+jest.mock("../api", () => ({
+  startModelInference: jest.fn(),
+  startModelTraining: jest.fn(),
+}));
+
+describe("modelLaunch helpers", () => {
+  it("builds a training launch request from app context state", () => {
+    const request = buildTrainingLaunchRequest(
+      {
+        trainingConfig: `
+DATASET:
+  INPUT_PATH: ""
+  IMAGE_NAME: ""
+  LABEL_NAME: ""
+  OUTPUT_PATH: ""
+`,
+        trainingState: {
+          inputImage: "/tmp/image.tif",
+          inputLabel: "/tmp/label.tif",
+          outputPath: "/tmp/train-out",
+          logPath: "",
+          configOriginPath: "/tmp/training.yaml",
+        },
+      },
+      7,
+    );
+
+    const parsed = yaml.load(request.trainingConfig);
+    expect(parsed.DATASET.OUTPUT_PATH).toBe("/tmp/train-out");
+    expect(request.logPath).toBe("/tmp/train-out");
+    expect(request.configOriginPath).toBe("/tmp/training.yaml");
+    expect(request.workflowId).toBe(7);
+  });
+
+  it("applies agent-selected training defaults from runtime overrides", () => {
+    const request = buildTrainingLaunchRequest(
+      {
+        trainingState: {},
+      },
+      7,
+      {
+        trainingConfig: `
+DATASET:
+  INPUT_PATH: ""
+  IMAGE_NAME: ""
+  LABEL_NAME: ""
+  OUTPUT_PATH: ""
+SOLVER: {}
+SYSTEM: {}
+`,
+        inputImagePath: "/tmp/image.h5",
+        inputLabelPath: "/tmp/corrected.tif",
+        outputPath: "/tmp/agent-training",
+        logPath: "/tmp/agent-training",
+        configOriginPath: "configs/MitoEM/Mito25-Local-BC.yaml",
+        autoParameters: true,
+      },
+    );
+
+    const parsed = yaml.load(request.trainingConfig);
+    expect(parsed.DATASET.IMAGE_NAME).toBe("/tmp/image.h5");
+    expect(parsed.DATASET.LABEL_NAME).toBe("/tmp/corrected.tif");
+    expect(parsed.DATASET.OUTPUT_PATH).toBe("/tmp/agent-training");
+    expect(parsed.SOLVER.SAMPLES_PER_BATCH).toBe(1);
+    expect(parsed.SOLVER.ITERATION_SAVE).toBe(80);
+    expect(parsed.SOLVER.ITERATION_TOTAL).toBe(80);
+    expect(parsed.SOLVER.ITERATION_VAL).toBe(80);
+    expect(parsed.SYSTEM.NUM_CPUS).toBe(2);
+    expect(parsed.SYSTEM.NUM_GPUS).toBe(1);
+    expect(parsed.MODEL.INPUT_SIZE).toEqual([65, 65, 65]);
+    expect(parsed.MODEL.OUTPUT_SIZE).toEqual([65, 65, 65]);
+    expect(parsed.MODEL.FILTERS).toEqual([8, 12, 16, 24, 32]);
+    expect(parsed.INFERENCE.STRIDE).toEqual([32, 32, 32]);
+    expect(request.autoParameters).toBe(true);
+    expect(request.configOriginPath).toBe(
+      "configs/MitoEM/Mito25-Local-BC.yaml",
+    );
+  });
+
+  it("uses runtime overrides when building an inference launch request", () => {
+    const request = buildInferenceLaunchRequest(
+      {
+        inferenceConfig: `
+INFERENCE:
+  OUTPUT_PATH: ""
+`,
+        inferenceState: {
+          inputImage: "/tmp/default-image.tif",
+          outputPath: "/tmp/default-out",
+          checkpointPath: "/tmp/default.ckpt",
+        },
+      },
+      9,
+      {
+        outputPath: "/tmp/runtime-out",
+        checkpointPath: "/tmp/runtime.ckpt",
+      },
+    );
+
+    expect(request.outputPath).toBe("/tmp/runtime-out");
+    expect(request.checkpointPath).toBe("/tmp/runtime.ckpt");
+    expect(request.workflowId).toBe(9);
+  });
+
+  it("rejects inference launches without a checkpoint", () => {
+    expect(() =>
+      buildInferenceLaunchRequest({
+        inferenceConfig: "INFERENCE: {}",
+        inferenceState: {},
+      }),
+    ).toThrow("Please set checkpoint path first.");
+  });
+
+  it("falls back to the training config when the persisted inference config is incompatible", () => {
+    const request = buildInferenceLaunchRequest({
+      trainingConfig: `
+DATASET:
+  INPUT_PATH: ""
+  IMAGE_NAME: ""
+INFERENCE:
+  OUTPUT_PATH: ""
+`,
+      inferenceConfig: `
+default:
+  inference:
+    batch_size: 1
+`,
+      trainingState: {
+        configOriginPath: "configs/MitoEM/Mito25-Local-BC.yaml",
+      },
+      inferenceState: {
+        configOriginPath: "tutorials/neuron_nisb_9nm_base.yaml",
+        inputImage: "/tmp/inference-image.h5",
+        outputPath: "/tmp/inference-out",
+        checkpointPath: "/tmp/model.ckpt",
+      },
+    });
+
+    const parsed = yaml.load(request.inferenceConfig);
+    expect(parsed.DATASET.IMAGE_NAME).toBe("/tmp/inference-image.h5");
+    expect(parsed.INFERENCE.IMAGE_NAME).toBe("/tmp/inference-image.h5");
+    expect(request.configOriginPath).toBe(
+      "configs/MitoEM/Mito25-Local-BC.yaml",
+    );
+  });
+});
diff --git a/client/src/utils/projectSuggestions.js b/client/src/utils/projectSuggestions.js
new file mode 100644
index 00000000..67da826f
--- /dev/null
+++ b/client/src/utils/projectSuggestions.js
@@ -0,0 +1,661 @@
+export const PROJECT_ROLE_LABELS = {
+  image: "image",
+  label: "label",
+  prediction: "prediction",
+  config: "config",
+  checkpoint: "checkpoint",
+  volume: "other volume",
+};
+
+export const joinProjectPath = (rootPath, relativePath) => {
+  if (!rootPath || !relativePath) return "";
+  return `${String(rootPath).replace(/\/+$/, "")}/${String(relativePath).replace(/^\/+/, "")}`;
+};
+
+const isAbsoluteOrUriPath = (path) =>
+  /^([a-z]+:)?\/\//i.test(String(path || "")) ||
+  String(path || "").startsWith("/");
+
+export const normalizeProjectRolePath = (rootPath, rolePath) => {
+  if (!rolePath) return "";
+  return isAbsoluteOrUriPath(rolePath)
+    ? String(rolePath)
+    : joinProjectPath(rootPath, rolePath);
+};
+
+const normalizeVoxelSizeNm = (value) => {
+  if (!value) return null;
+  const values = Array.isArray(value)
+    ? value
+    : String(value).match(/\d+(?:\.\d+)?/g);
+  if (!values || values.length < 3) return null;
+  const numeric = values.slice(0, 3).map((item) => Number(item));
+  return numeric.every((item) => Number.isFinite(item) && item > 0)
+    ? numeric
+    : null;
+};
+
+const scaleUnitMultiplier = (unitText) => {
+  const lower = String(unitText || "").toLowerCase();
+  return /(?:\u00b5m|um|micron|microns)/.test(lower) ? 1000 : 1;
+};
+
+const parseVoxelSizeNmFromText = (text) => {
+  const source = String(text || "");
+  if (!source.trim()) return null;
+
+  const threeAxisPattern =
+    /(?:voxel(?:\s+(?:size|spacing))?|resolution|spacing|pixel\s+size|scale)[^\d]{0,60}(\d+(?:\.\d+)?)\s*(?:x|by|,|;|\/|-|\s)\s*(\d+(?:\.\d+)?)\s*(?:x|by|,|;|\/|-|\s)\s*(\d+(?:\.\d+)?)(?:\s*(nm|nanometers?|um|\u00b5m|microns?))?/i;
+  const threeAxisMatch = source.match(threeAxisPattern);
+  if (threeAxisMatch) {
+    const multiplier = scaleUnitMultiplier(threeAxisMatch[4] || source);
+    return threeAxisMatch
+      .slice(1, 4)
+      .map((value) => Number(value) * multiplier);
+  }
+
+  const unitQualifiedTriple =
+    /(?:at|@)?\s*(\d+(?:\.\d+)?)\s*(?:x|by|,|;|\/|-)\s*(\d+(?:\.\d+)?)\s*(?:x|by|,|;|\/|-)\s*(\d+(?:\.\d+)?)\s*(nm|nanometers?|um|\u00b5m|microns?)/i;
+  const unitQualifiedMatch = source.match(unitQualifiedTriple);
+  if (unitQualifiedMatch) {
+    const multiplier = scaleUnitMultiplier(unitQualifiedMatch[4]);
+    return unitQualifiedMatch
+      .slice(1, 4)
+      .map((value) => Number(value) * multiplier);
+  }
+
+  const isotropicPattern =
+    /(?:isotropic|cubic|same\s+voxel|same\s+scale)[^\d]{0,60}(\d+(?:\.\d+)?)(?:\s*(nm|nanometers?|um|\u00b5m|microns?))?/i;
+  const isotropicMatch = source.match(isotropicPattern);
+  if (isotropicMatch) {
+    const value =
+      Number(isotropicMatch[1]) *
+      scaleUnitMultiplier(isotropicMatch[2] || source);
+    return [value, value, value];
+  }
+
+  return null;
+};
+
+const formatScaleNumber = (value) =>
+  Number.isInteger(Number(value))
+    ? String(Number(value))
+    : `${Number(value).toFixed(4)}`.replace(/0+$/, "").replace(/\.$/, "");
+
+export const formatVoxelSizeNm = (value) => {
+  const voxelSize = normalizeVoxelSizeNm(value);
+  if (!voxelSize) return "";
+  return `${voxelSize.map(formatScaleNumber).join(" x ")} nm`;
+};
+
+export const getProjectVolumeSetsFromSuggestion = (suggestion) => {
+  const profile = suggestion?.profile || {};
+  return profile.volume_sets || profile.schema?.volume_sets || [];
+};
+
+export const getProjectAuditFromSuggestion = (suggestion) => {
+  const profile = suggestion?.profile || {};
+  return profile.audit || profile.schema?.audit || null;
+};
+
+export const getProjectContextDefaultsFromSuggestion = (suggestion) => {
+  const profile = suggestion?.profile || {};
+  const contentHints = {
+    ...(profile.schema?.context_hints || {}),
+    ...(profile.context_hints || {}),
+    ...(suggestion?.context_hints || {}),
+  };
+  const counts = profile.counts || {};
+  const auditFacts =
+    getProjectAuditFromSuggestion(suggestion)?.context_facts || [];
+  const defaults = {};
+
+  [
+    "imaging_modality",
+    "target_structure",
+    "task_family",
+    "mask_status",
+    "image_only_strategy",
+    "training_policy",
+  ].forEach((key) => {
+    if (contentHints[key]) {
+      defaults[key] = contentHints[key];
+    }
+  });
+  const hintedVoxelSize = normalizeVoxelSizeNm(
+    contentHints.voxel_size_nm || contentHints.visualization_scales,
+  );
+  if (hintedVoxelSize) {
+    defaults.voxel_size_nm = hintedVoxelSize;
+    defaults.voxel_size_source =
+      contentHints.voxel_size_source || "project_profile";
+  }
+  const auditVoxelSizeFact = auditFacts.find(
+    (fact) => fact?.key === "voxel_size_nm" && fact.value,
+  );
+  const auditVoxelSize = normalizeVoxelSizeNm(auditVoxelSizeFact?.value);
+  if (auditVoxelSize) {
+    defaults.voxel_size_nm = auditVoxelSize;
+    defaults.voxel_size_source = auditVoxelSizeFact.source || "volume_metadata";
+  }
+
+  const modalityText = String(defaults.imaging_modality || "").toLowerCase();
+  const targetText = String(defaults.target_structure || "").toLowerCase();
+  const suggestionText = [
+    suggestion?.id,
+    suggestion?.name,
+    suggestion?.description,
+    suggestion?.directory_path,
+  ]
+    .filter(Boolean)
+    .join(" ")
+    .toLowerCase();
+  if (!defaults.task_family) {
+    if (/(xri|x-ray|xray)/.test(`${modalityText} ${suggestionText}`)) {
+      defaults.task_family = /fiber|fibre|cytotape/.test(
+        `${targetText} ${suggestionText}`,
+      )
+        ? "XRI fibre instance segmentation"
+        : "XRI volumetric segmentation";
+    } else if (/mitochond/.test(targetText)) {
+      defaults.task_family = "mitochondria instance segmentation";
+    } else if (/synap|cleft/.test(targetText)) {
+      defaults.task_family = "synapse segmentation";
+    } else if (/nuclei|nucleus/.test(targetText)) {
+      defaults.task_family = "nuclei instance segmentation";
+    }
+  }
+  const hasDomainContext = Boolean(
+    defaults.imaging_modality ||
+    defaults.target_structure ||
+    defaults.task_family ||
+    contentHints.task_goal,
+  );
+  if (hasDomainContext && !defaults.mask_status) {
+    if ((counts.image || 0) > 0 && (counts.label || 0) === 0) {
+      defaults.mask_status = "image-only; no masks found";
+    } else if (
+      (counts.image || 0) > (counts.label || 0) &&
+      (counts.label || 0) > 0
+    ) {
+      defaults.mask_status = "mixed: some masks, some image-only volumes";
+    } else if ((counts.label || 0) > 0) {
+      defaults.mask_status = "masks found; confirm ground truth vs draft";
+    }
+  }
+  if (
+    hasDomainContext &&
+    !defaults.image_only_strategy &&
+    (counts.image || 0) > (counts.label || 0)
+  ) {
+    defaults.image_only_strategy = "run inference on image-only volumes later";
+  }
+  if (
+    hasDomainContext &&
+    !defaults.training_policy &&
+    (counts.label || 0) > 0
+  ) {
+    defaults.training_policy = "train only on confirmed ground-truth masks";
+  }
+
+  return defaults;
+};
+
+export const inferProjectContextFromDescription = (description) => {
+  const text = String(description || "").trim();
+  if (!text) return null;
+
+  const lower = text.toLowerCase();
+  const normalizedLower = lower.replace(/[^a-z0-9+-]+/g, " ");
+  const paddedLower = ` ${normalizedLower} `;
+  const context = {
+    freeform_note: text.slice(0, 1000),
+  };
+
+  const modalityTerms = [
+    ["X-ray / XRI volumetric microscopy", ["xri", "x-ray", "xray"]],
+    ["electron microscopy", ["electron microscopy", "electron microscope"]],
+    ["EM", [" em ", "sem", "tem", "fib-sem", "fib sem"]],
+    ["confocal microscopy", ["confocal"]],
+    ["light-sheet microscopy", ["light sheet", "light-sheet"]],
+    ["fluorescence microscopy", ["fluorescence", "fluorescent"]],
+    ["brightfield microscopy", ["brightfield", "bright-field"]],
+    ["MRI", [" mri ", "mri"]],
+    ["CT", [" ct ", "micro-ct", "micro ct"]],
+  ];
+
+  const modality = modalityTerms.find(([, terms]) =>
+    terms.some((term) => paddedLower.includes(term)),
+  );
+  if (modality) {
+    context.imaging_modality = modality[0];
+  }
+
+  const targetTerms = [
+    ["fibres", ["fiber", "fibers", "fibre", "fibres", "cytotape"]],
+    ["mitochondria", ["mitochondria", "mitochondrion", "mito"]],
+    ["membranes", ["membrane", "membranes"]],
+    ["synapses", ["synapse", "synapses"]],
+    ["nuclei", ["nucleus", "nuclei"]],
+    ["cells", ["cell", "cells"]],
+    ["neurites", ["neurite", "neurites", "axon", "dendrite"]],
+    ["vasculature", ["vessel", "vasculature", "blood vessel"]],
+    ["organelle", ["organelle", "organelles"]],
+  ];
+
+  const target = targetTerms.find(([, terms]) =>
+    terms.some((term) => lower.includes(term)),
+  );
+  if (target) {
+    context.target_structure = target[0];
+  }
+
+  if (
+    /xri|x-ray|xray/.test(lower) &&
+    /fiber|fibers|fibre|fibres|cytotape/.test(lower)
+  ) {
+    context.task_family = "XRI fibre instance segmentation";
+  } else if (/mitochond/.test(lower)) {
+    context.task_family = "mitochondria instance segmentation";
+  } else if (/synap|cleft/.test(lower)) {
+    context.task_family = "synapse segmentation";
+  } else if (/nuclei|nucleus/.test(lower)) {
+    context.task_family = "nuclei instance segmentation";
+  }
+
+  if (/(fast|quick|smoke|prototype|rough|draft)/.test(lower)) {
+    context.optimization_priority = "speed";
+  } else if (/(accurate|accuracy|quality|best|careful|final)/.test(lower)) {
+    context.optimization_priority = "accuracy";
+  }
+
+  if (/(proofread|review|correct|fix|curat)/.test(lower)) {
+    context.task_goal = "proofreading";
+  } else if (/(segment|segmentation|infer|inference|predict)/.test(lower)) {
+    context.task_goal = "segmentation";
+  } else if (
+    /(retrain|fine.?tune|\btrain(?:ing)?\b(?!\s*\/\s*val))/.test(lower)
+  ) {
+    context.task_goal = "training";
+  } else if (/(compare|metric|evaluate|evaluation|before.*after)/.test(lower)) {
+    context.task_goal = "comparison";
+  }
+
+  if (
+    /(train|val|valid|test)\s*(\/|and|,|\+)\s*(val|valid|test|train)/.test(
+      lower,
+    )
+  ) {
+    context.data_unit = "train/validation/test folders";
+  } else if (
+    /(folder|directory|batch|multiple|several|many|set of|collection)/.test(
+      lower,
+    )
+  ) {
+    context.data_unit = "folder of volumes";
+  } else if (/(one|single)\s+(volume|image|stack|file)/.test(lower)) {
+    context.data_unit = "single volume";
+  } else if (/(tile|tiles|crop|crops|patch|patches)/.test(lower)) {
+    context.data_unit = "tiles or crops";
+  } else if (/(time.?series|timeseries|movie|frames)/.test(lower)) {
+    context.data_unit = "time series";
+  }
+
+  if (/(no labels|unlabeled|no mask|without labels|raw only)/.test(lower)) {
+    context.label_status = "no labels";
+  } else if (/(rough|weak|partial|imperfect).*(label|mask|seg)/.test(lower)) {
+    context.label_status = "rough labels";
+  } else if (
+    /(expert|manual|ground truth|ground-truth|gt).*(label|mask|seg)/.test(lower)
+  ) {
+    context.label_status = "expert labels";
+  } else if (
+    /(prediction|predictions|model output|baseline).*(mask|seg|available|exist)/.test(
+      lower,
+    )
+  ) {
+    context.label_status = "predictions available";
+  }
+
+  const voxelSizeNm = parseVoxelSizeNmFromText(text);
+  if (voxelSizeNm) {
+    context.voxel_size_nm = voxelSizeNm;
+    context.voxel_size_source = "project_description";
+  }
+
+  return context;
+};
+
+const PROJECT_CONTEXT_REQUIRED_FIELDS = [
+  {
+    key: "imaging_modality",
+    label: "imaging modality",
+    question:
+      "What imaging modality is this from, such as EM, fluorescence, or micro-CT?",
+  },
+  {
+    key: "target_structure",
+    label: "target structure",
+    question: "What structure should be segmented or proofread?",
+  },
+  {
+    key: "voxel_size_nm",
+    label: "imaging resolution",
+    question:
+      "What is the voxel size or imaging resolution in z, y, x nanometers?",
+  },
+];
+
+export const evaluateProjectContextCompleteness = (
+  description,
+  options = {},
+) => {
+  const context = {
+    ...(options.defaultContext && typeof options.defaultContext === "object"
+      ? options.defaultContext
+      : {}),
+    ...(inferProjectContextFromDescription(description) || {}),
+  };
+  if (options.useDefaults) {
+    return {
+      complete: true,
+      context: {
+        ...context,
+        use_defaults: true,
+      },
+      missing: [],
+      known: context,
+      next_question: "",
+    };
+  }
+
+  const missingFields = PROJECT_CONTEXT_REQUIRED_FIELDS.filter(
+    (field) => !context[field.key],
+  );
+  const nextQuestion = missingFields[0]?.question || "";
+  return {
+    complete: missingFields.length === 0,
+    context,
+    known: Object.fromEntries(
+      Object.entries(context).filter(([, value]) => Boolean(value)),
+    ),
+    missing: missingFields.map((field) => field.label),
+    next_question: nextQuestion,
+  };
+};
+
+export const describeProjectContextAssessment = (assessment) => {
+  if (!assessment) {
+    return "Describe the dataset so I can choose sensible workflow defaults.";
+  }
+  if (assessment.complete) {
+    return "I have enough project context to continue.";
+  }
+  return (
+    assessment.next_question || "Tell me one more detail about this dataset."
+  );
+};
+
+const preferDirectoryDefault = (profile, role) => {
+  const counts = profile.counts || {};
+  const primaryPaths = profile.schema?.primary_paths || {};
+  const volumeSets = profile.volume_sets || profile.schema?.volume_sets || [];
+
+  if (role === "image" && counts.image > 1 && volumeSets[0]?.image_root) {
+    return volumeSets[0].image_root;
+  }
+  if (
+    (role === "label" || role === "mask") &&
+    counts.label > 1 &&
+    volumeSets[0]?.label_root
+  ) {
+    return volumeSets[0].label_root;
+  }
+  if (counts[role] > 1 && primaryPaths[`${role}_root`]) {
+    return primaryPaths[`${role}_root`];
+  }
+  return "";
+};
+
+export const getProjectRoleDefaultsFromSuggestion = (suggestion) => {
+  const profile = suggestion?.profile || {};
+  const primaryPaths = profile.schema?.primary_paths || {};
+  const examples = profile.examples || {};
+  const paired = profile.paired_examples?.[0] || {};
+  const rootPath = suggestion?.directory_path;
+  const imageRelative =
+    preferDirectoryDefault(profile, "image") ||
+    primaryPaths.image ||
+    paired.image ||
+    examples.image?.[0] ||
+    examples.volume?.[0];
+  const labelRelative =
+    preferDirectoryDefault(profile, "label") ||
+    primaryPaths.label ||
+    primaryPaths.mask ||
+    paired.label ||
+    examples.label?.[0];
+  const predictionRelative =
+    preferDirectoryDefault(profile, "prediction") ||
+    primaryPaths.prediction ||
+    examples.prediction?.[0];
+  const checkpointRelative =
+    primaryPaths.checkpoint || examples.checkpoint?.[0];
+  const configRelative = primaryPaths.config || examples.config?.[0];
+
+  return {
+    image: normalizeProjectRolePath(rootPath, imageRelative),
+    label: normalizeProjectRolePath(rootPath, labelRelative),
+    prediction: normalizeProjectRolePath(rootPath, predictionRelative),
+    checkpoint: normalizeProjectRolePath(rootPath, checkpointRelative),
+    config: normalizeProjectRolePath(rootPath, configRelative),
+  };
+};
+
+export const buildWorkflowPatchFromConfirmedProjectRoles = ({
+  rootPath,
+  roles = {},
+  metadata = null,
+} = {}) => {
+  const labelOrMask = roles.label || roles.mask || "";
+  const patch = {
+    dataset_path: rootPath || null,
+    image_path: normalizeProjectRolePath(rootPath, roles.image) || null,
+    label_path: normalizeProjectRolePath(rootPath, labelOrMask) || null,
+    mask_path:
+      normalizeProjectRolePath(rootPath, roles.mask || labelOrMask) || null,
+    inference_output_path:
+      normalizeProjectRolePath(rootPath, roles.prediction) || null,
+    checkpoint_path:
+      normalizeProjectRolePath(rootPath, roles.checkpoint) || null,
+    config_path: normalizeProjectRolePath(rootPath, roles.config) || null,
+  };
+  if (metadata && typeof metadata === "object") {
+    const nextMetadata = { ...metadata };
+    const voxelSizeNm = normalizeVoxelSizeNm(
+      nextMetadata.project_context?.voxel_size_nm ||
+        nextMetadata.visualization_scales,
+    );
+    if (voxelSizeNm) {
+      nextMetadata.visualization_scales = voxelSizeNm;
+      nextMetadata.visualization_scales_source =
+        nextMetadata.project_context?.voxel_size_source ||
+        nextMetadata.visualization_scales_source ||
+        "project_setup_confirmation";
+    }
+    patch.metadata = nextMetadata;
+  }
+  return Object.fromEntries(
+    Object.entries(patch).filter(([, value]) => Boolean(value)),
+  );
+};
+
+export const buildWorkflowPatchFromProjectSuggestion = (suggestion) => {
+  const rootPath = suggestion?.directory_path;
+  return buildWorkflowPatchFromConfirmedProjectRoles({
+    rootPath,
+    roles: getProjectRoleDefaultsFromSuggestion(suggestion),
+  });
+};
+
+export const summarizeProjectSuggestionForWorkflow = (
+  suggestion,
+  overrides = {},
+) => {
+  const profile = suggestion?.profile || {};
+  const pairedExample = profile.paired_examples?.[0] || null;
+  return {
+    id: suggestion?.id || null,
+    name: suggestion?.name || null,
+    directory_path: suggestion?.directory_path || null,
+    already_mounted: Boolean(suggestion?.already_mounted),
+    mounted_root_id: suggestion?.mounted_root_id || null,
+    recommended: Boolean(suggestion?.recommended),
+    profile: {
+      ready_for_smoke: Boolean(profile.ready_for_smoke),
+      schema: profile.schema || null,
+      counts: profile.counts || {},
+      missing_roles: profile.missing_roles || [],
+      paired_example: pairedExample,
+      role_directories:
+        profile.role_directories || profile.schema?.role_directories || {},
+      volume_sets: getProjectVolumeSetsFromSuggestion(suggestion),
+    },
+    inferred_paths: buildWorkflowPatchFromProjectSuggestion(suggestion),
+    ...overrides,
+  };
+};
+
+const tokenizeGoal = (goal) =>
+  String(goal || "")
+    .toLowerCase()
+    .split(/[^a-z0-9_.-]+/)
+    .map((token) => token.trim())
+    .filter((token) => token.length >= 2);
+
+const flattenSuggestionText = (suggestion) => {
+  const profile = suggestion?.profile || {};
+  const examples = profile.examples || {};
+  const pairedExamples = profile.paired_examples || [];
+  return [
+    suggestion?.id,
+    suggestion?.name,
+    suggestion?.directory_path,
+    suggestion?.description,
+    ...Object.values(examples).flat(),
+    ...pairedExamples.flatMap((pair) => [pair?.image, pair?.label]),
+  ]
+    .filter(Boolean)
+    .join(" ")
+    .toLowerCase();
+};
+
+export const scoreProjectSuggestionForGoal = (suggestion, goal) => {
+  const tokens = tokenizeGoal(goal);
+  const profile = suggestion?.profile || {};
+  const counts = profile.counts || {};
+  const haystack = flattenSuggestionText(suggestion);
+
+  if (tokens.length === 0) {
+    return {
+      score: suggestion?.recommended ? 10 : 0,
+      reason: suggestion?.recommended ? "recommended" : "",
+    };
+  }
+
+  let score = 0;
+  const reasons = [];
+  tokens.forEach((token) => {
+    if (haystack.includes(token)) {
+      score += 8;
+      reasons.push(token);
+    }
+  });
+
+  const goalText = tokens.join(" ");
+  const hasImageLabel = counts.image > 0 && counts.label > 0;
+  const hasLoopArtifacts =
+    counts.image > 0 &&
+    counts.label > 0 &&
+    counts.prediction > 0 &&
+    counts.checkpoint > 0;
+
+  if (
+    /(proofread|review|correct|fix|mask|label)/.test(goalText) &&
+    hasImageLabel
+  ) {
+    score += 3;
+    reasons.push("image/mask pair");
+  }
+  if (
+    /(segment|segmentation|predict|prediction|infer|inference)/.test(goalText)
+  ) {
+    if (counts.prediction > 0) {
+      score += 3;
+      reasons.push("prediction artifacts");
+    } else if (counts.image > 0) {
+      score += 2;
+      reasons.push("image data");
+    }
+  }
+  if (/mitochond/.test(goalText) && haystack.includes("mito")) {
+    score += 7;
+    reasons.push("mitochondria");
+  }
+  if (
+    /(train|retrain|compare|metric|baseline|candidate|closed|loop)/.test(
+      goalText,
+    )
+  ) {
+    if (hasLoopArtifacts) {
+      score += 6;
+      reasons.push("loop artifacts");
+    } else if (hasImageLabel) {
+      score += 2;
+      reasons.push("trainable pair");
+    }
+  }
+  if (/(tif|tiff)/.test(goalText) && /\.(ome\.)?tiff?\b/.test(haystack)) {
+    score += 5;
+    reasons.push("TIFF data");
+  }
+  if (/(h5|hdf5)/.test(goalText) && /\.(h5|hdf5)\b/.test(haystack)) {
+    score += 5;
+    reasons.push("HDF5 data");
+  }
+  if (suggestion?.recommended && score > 0) {
+    score += 1;
+  }
+
+  return {
+    score,
+    reason: reasons.slice(0, 3).join(", "),
+  };
+};
+
+export const rankProjectSuggestionsForGoal = (suggestions, goal) =>
+  (suggestions || [])
+    .map((suggestion, originalIndex) => ({
+      ...suggestion,
+      match: scoreProjectSuggestionForGoal(suggestion, goal),
+      originalIndex,
+    }))
+    .sort((a, b) => {
+      if (b.match.score !== a.match.score) {
+        return b.match.score - a.match.score;
+      }
+      if (Boolean(b.recommended) !== Boolean(a.recommended)) {
+        return b.recommended ? 1 : -1;
+      }
+      return a.originalIndex - b.originalIndex;
+    });
+
+export const selectSuggestedProjectIdsForGoal = (suggestions, goal) => {
+  const ranked = rankProjectSuggestionsForGoal(suggestions, goal);
+  if (!ranked.length) return new Set();
+  if (tokenizeGoal(goal).length === 0) {
+    const recommended = ranked.find((suggestion) => suggestion.recommended);
+    return new Set([(recommended || ranked[0]).id]);
+  }
+  return ranked[0].match.score > 0 ? new Set([ranked[0].id]) : new Set();
+};
diff --git a/client/src/utils/projectSuggestions.test.js b/client/src/utils/projectSuggestions.test.js
new file mode 100644
index 00000000..430fdb05
--- /dev/null
+++ b/client/src/utils/projectSuggestions.test.js
@@ -0,0 +1,355 @@
+import {
+  buildWorkflowPatchFromConfirmedProjectRoles,
+  buildWorkflowPatchFromProjectSuggestion,
+  getProjectVolumeSetsFromSuggestion,
+  getProjectRoleDefaultsFromSuggestion,
+  getProjectContextDefaultsFromSuggestion,
+  evaluateProjectContextCompleteness,
+  formatVoxelSizeNm,
+  inferProjectContextFromDescription,
+} from "./projectSuggestions";
+
+const suggestion = {
+  directory_path: "/projects/demo",
+  profile: {
+    schema: {
+      primary_paths: {
+        image: "data/raw.h5",
+        label: "data/mask.h5",
+        prediction: "predictions/baseline.tif",
+        checkpoint: "checkpoints/model.pth.tar",
+        config: "configs/preset.yaml",
+      },
+    },
+  },
+};
+
+const batchSuggestion = {
+  directory_path: "/projects/batch-demo",
+  profile: {
+    counts: {
+      image: 4,
+      label: 4,
+      prediction: 2,
+      config: 1,
+      checkpoint: 1,
+    },
+    volume_sets: [
+      {
+        id: "set-1",
+        name: "train",
+        image_root: "data/Image/train",
+        label_root: "data/Label/train",
+        image_count: 4,
+        label_count: 4,
+        pair_count: 4,
+      },
+    ],
+    schema: {
+      primary_paths: {
+        image: "data/Image/train/img_000.h5",
+        image_root: "data/Image/train",
+        label: "data/Label/train/img_000.h5",
+        label_root: "data/Label/train",
+        prediction: "outputs/baseline.h5",
+        prediction_root: "outputs",
+        checkpoint: "checkpoints/model.pth.tar",
+        config: "configs/preset.yaml",
+      },
+    },
+  },
+};
+
+describe("project suggestion utilities", () => {
+  it("derives absolute default role paths from a profiled project", () => {
+    expect(getProjectRoleDefaultsFromSuggestion(suggestion)).toEqual({
+      image: "/projects/demo/data/raw.h5",
+      label: "/projects/demo/data/mask.h5",
+      prediction: "/projects/demo/predictions/baseline.tif",
+      checkpoint: "/projects/demo/checkpoints/model.pth.tar",
+      config: "/projects/demo/configs/preset.yaml",
+    });
+  });
+
+  it("converts confirmed roles into workflow patch fields", () => {
+    expect(
+      buildWorkflowPatchFromConfirmedProjectRoles({
+        rootPath: "/projects/demo",
+        roles: {
+          image: "/projects/demo/raw.h5",
+          label: "/projects/demo/labels.h5",
+          prediction: "",
+          checkpoint: "/models/model.pth.tar",
+          config: "/projects/demo/config.yaml",
+        },
+      }),
+    ).toEqual({
+      dataset_path: "/projects/demo",
+      image_path: "/projects/demo/raw.h5",
+      label_path: "/projects/demo/labels.h5",
+      mask_path: "/projects/demo/labels.h5",
+      checkpoint_path: "/models/model.pth.tar",
+      config_path: "/projects/demo/config.yaml",
+    });
+  });
+
+  it("copies confirmed imaging resolution into workflow metadata", () => {
+    expect(
+      buildWorkflowPatchFromConfirmedProjectRoles({
+        rootPath: "/projects/demo",
+        roles: {
+          image: "raw.h5",
+          label: "labels.h5",
+        },
+        metadata: {
+          project_context: {
+            voxel_size_nm: [30, 6, 6],
+            voxel_size_source: "project_description",
+          },
+        },
+      }),
+    ).toEqual(
+      expect.objectContaining({
+        metadata: expect.objectContaining({
+          visualization_scales: [30, 6, 6],
+          visualization_scales_source: "project_description",
+        }),
+      }),
+    );
+  });
+
+  it("keeps the legacy suggestion patch behavior backed by confirmed role defaults", () => {
+    expect(buildWorkflowPatchFromProjectSuggestion(suggestion)).toEqual({
+      dataset_path: "/projects/demo",
+      image_path: "/projects/demo/data/raw.h5",
+      label_path: "/projects/demo/data/mask.h5",
+      mask_path: "/projects/demo/data/mask.h5",
+      inference_output_path: "/projects/demo/predictions/baseline.tif",
+      checkpoint_path: "/projects/demo/checkpoints/model.pth.tar",
+      config_path: "/projects/demo/configs/preset.yaml",
+    });
+  });
+
+  it("prefers project folders when a profile contains multiple volume pairs", () => {
+    expect(getProjectRoleDefaultsFromSuggestion(batchSuggestion)).toEqual({
+      image: "/projects/batch-demo/data/Image/train",
+      label: "/projects/batch-demo/data/Label/train",
+      prediction: "/projects/batch-demo/outputs",
+      checkpoint: "/projects/batch-demo/checkpoints/model.pth.tar",
+      config: "/projects/batch-demo/configs/preset.yaml",
+    });
+    expect(getProjectVolumeSetsFromSuggestion(batchSuggestion)).toEqual([
+      expect.objectContaining({
+        image_root: "data/Image/train",
+        label_root: "data/Label/train",
+        pair_count: 4,
+      }),
+    ]);
+  });
+
+  it("extracts lightweight project context from a biologist description", () => {
+    expect(
+      inferProjectContextFromDescription(
+        "Mouse micro-CT nuclei dataset; segment nuclei at 4 x 4 x 40 nm and prioritize accuracy.",
+      ),
+    ).toEqual({
+      freeform_note:
+        "Mouse micro-CT nuclei dataset; segment nuclei at 4 x 4 x 40 nm and prioritize accuracy.",
+      imaging_modality: "CT",
+      target_structure: "nuclei",
+      task_family: "nuclei instance segmentation",
+      task_goal: "segmentation",
+      optimization_priority: "accuracy",
+      voxel_size_nm: [4, 4, 40],
+      voxel_size_source: "project_description",
+    });
+  });
+
+  it("derives guided defaults for the TapeReader XRI case study", () => {
+    expect(
+      getProjectContextDefaultsFromSuggestion({
+        id: "yixiao-tapereader-xri-case-study",
+        name: "yixiao_tapereader_xri_case_study",
+        directory_path:
+          "/home/weidf/demo_data/yixiao_tapereader_xri_case_study",
+        description: "Yixiao TapeReader XRI fibre segmentation case study.",
+        profile: {
+          counts: { image: 10, label: 8, config: 3 },
+          context_hints: {
+            imaging_modality: "X-ray / XRI volumetric microscopy",
+            target_structure: "CytoTape fibres",
+            voxel_size_nm: [40, 16.3, 16.3],
+          },
+        },
+      }),
+    ).toEqual(
+      expect.objectContaining({
+        imaging_modality: "X-ray / XRI volumetric microscopy",
+        target_structure: "CytoTape fibres",
+        task_family: "XRI fibre instance segmentation",
+        mask_status: "mixed: some masks, some image-only volumes",
+        image_only_strategy: "run inference on image-only volumes later",
+        training_policy: "train only on confirmed ground-truth masks",
+        voxel_size_nm: [40, 16.3, 16.3],
+      }),
+    );
+    expect(
+      inferProjectContextFromDescription(
+        "XRI CytoTape fibre masks at 40 x 16.3 x 16.3 nm.",
+      ),
+    ).toEqual(
+      expect.objectContaining({
+        imaging_modality: "X-ray / XRI volumetric microscopy",
+        target_structure: "fibres",
+        task_family: "XRI fibre instance segmentation",
+        voxel_size_nm: [40, 16.3, 16.3],
+      }),
+    );
+  });
+
+  it("parses and formats isotropic imaging resolution", () => {
+    const context = inferProjectContextFromDescription(
+      "EM mitochondria stack; segmentation from one volume; prioritize accuracy; isotropic 5 nm voxels.",
+    );
+    expect(context).toEqual(
+      expect.objectContaining({
+        voxel_size_nm: [5, 5, 5],
+      }),
+    );
+    expect(formatVoxelSizeNm(context.voxel_size_nm)).toBe("5 x 5 x 5 nm");
+  });
+
+  it("does not invent generic defaults from profiled folders", () => {
+    expect(getProjectContextDefaultsFromSuggestion(batchSuggestion)).toEqual(
+      {},
+    );
+    expect(
+      getProjectContextDefaultsFromSuggestion({
+        name: "prepilot_cremi_official",
+        directory_path: "/projects/prepilot_cremi_official",
+        profile: { counts: { image: 3, label: 3 } },
+      }),
+    ).toEqual({});
+  });
+
+  it("uses backend content hints instead of biological name guesses", () => {
+    expect(
+      getProjectContextDefaultsFromSuggestion({
+        name: "opaque-project-name",
+        directory_path: "/projects/opaque-project-name",
+        profile: {
+          counts: { image: 3, label: 3 },
+          context_hints: {
+            imaging_modality: "EM",
+            target_structure: "neurites",
+            task_goal: "proofreading",
+            optimization_priority: "accuracy",
+            voxel_size_nm: [40, 4, 4],
+          },
+        },
+      }),
+    ).toEqual(
+      expect.objectContaining({
+        imaging_modality: "EM",
+        target_structure: "neurites",
+        voxel_size_nm: [40, 4, 4],
+        voxel_size_source: "project_profile",
+      }),
+    );
+  });
+
+  it("uses high-confidence audit facts for voxel size defaults", () => {
+    expect(
+      getProjectContextDefaultsFromSuggestion({
+        name: "audit-project",
+        directory_path: "/projects/audit-project",
+        profile: {
+          counts: { image: 1, label: 1 },
+          context_hints: {
+            imaging_modality: "EM",
+            target_structure: "mitochondria",
+            voxel_size_nm: [30, 6, 6],
+          },
+          audit: {
+            context_facts: [
+              {
+                key: "voxel_size_nm",
+                value: [30, 8, 8],
+                source: "volume_metadata:data/image/sample.h5",
+                confidence: "high",
+              },
+            ],
+          },
+        },
+      }),
+    ).toEqual(
+      expect.objectContaining({
+        imaging_modality: "EM",
+        target_structure: "mitochondria",
+        voxel_size_nm: [30, 8, 8],
+        voxel_size_source: "volume_metadata:data/image/sample.h5",
+      }),
+    );
+  });
+
+  it("reports missing project context fields deterministically", () => {
+    expect(evaluateProjectContextCompleteness("EM!", {})).toEqual(
+      expect.objectContaining({
+        context: expect.objectContaining({
+          imaging_modality: "EM",
+        }),
+      }),
+    );
+    expect(evaluateProjectContextCompleteness("EM mitochondria", {})).toEqual(
+      expect.objectContaining({
+        complete: false,
+        missing: ["imaging resolution"],
+        next_question:
+          "What is the voxel size or imaging resolution in z, y, x nanometers?",
+      }),
+    );
+    expect(
+      evaluateProjectContextCompleteness(
+        "EM mitochondria segmentation from a single volume at 30 x 6 x 6 nm; prioritize accuracy.",
+      ),
+    ).toEqual(
+      expect.objectContaining({
+        complete: true,
+        context: expect.objectContaining({
+          imaging_modality: "EM",
+          target_structure: "mitochondria",
+          voxel_size_nm: [30, 6, 6],
+        }),
+      }),
+    );
+  });
+
+  it("uses project defaults to avoid blocking on inferable context", () => {
+    expect(
+      evaluateProjectContextCompleteness("EM!", {
+        defaultContext: getProjectContextDefaultsFromSuggestion({
+          name: "opaque-project-name",
+          directory_path: "/projects/opaque-project-name",
+          profile: {
+            counts: { image: 3, label: 3 },
+            context_hints: {
+              target_structure: "neurites",
+              voxel_size_nm: [8, 8, 8],
+            },
+          },
+        }),
+      }),
+    ).toEqual(
+      expect.objectContaining({
+        complete: true,
+        missing: [],
+        context: expect.objectContaining({
+          imaging_modality: "EM",
+          target_structure: "neurites",
+          voxel_size_nm: [8, 8, 8],
+          voxel_size_source: "project_profile",
+        }),
+      }),
+    );
+  });
+});
diff --git a/client/src/views/EHTool.js b/client/src/views/EHTool.js
index 3cb38e32..80f5d508 100644
--- a/client/src/views/EHTool.js
+++ b/client/src/views/EHTool.js
@@ -20,9 +20,11 @@ function EHTool({
 
   // Sync prop changes if they occur (e.g. from parent state update)
   useEffect(() => {
-    if (savedSessionId && savedSessionId !== sessionId) {
-      setSessionId(savedSessionId);
-    }
+    setSessionId((currentSessionId) =>
+      savedSessionId && savedSessionId !== currentSessionId
+        ? savedSessionId
+        : currentSessionId,
+    );
   }, [savedSessionId]);
 
   // Notify parent when session changes internally
diff --git a/client/src/views/FilesManager.js b/client/src/views/FilesManager.js
index 278f0e33..0daa2a64 100644
--- a/client/src/views/FilesManager.js
+++ b/client/src/views/FilesManager.js
@@ -27,15 +27,36 @@ import {
 } from "@ant-design/icons";
 import { apiClient } from "../api";
 import FileTreeSidebar from "../components/FileTreeSidebar";
-import { openLocalFile, revealInFinder } from "../electronApi";
+import FilePickerModal from "../components/FilePickerModal";
+import {
+  canOpenLocalFile,
+  openLocalFile,
+  revealInFinder,
+} from "../electronApi";
 import { AppContext } from "../contexts/GlobalContext";
+import { useWorkflow } from "../contexts/WorkflowContext";
+import { logClientEvent } from "../logging/appEventLog";
+import {
+  buildWorkflowPatchFromConfirmedProjectRoles,
+  describeProjectContextAssessment,
+  evaluateProjectContextCompleteness,
+  formatVoxelSizeNm,
+  getProjectAuditFromSuggestion,
+  getProjectContextDefaultsFromSuggestion,
+  getProjectVolumeSetsFromSuggestion,
+  getProjectRoleDefaultsFromSuggestion,
+} from "../utils/projectSuggestions";
 
 const HIDDEN_SYSTEM_FILES = new Set([
   "workflow_preference.json",
   ".pytc_proofreading.json",
+  ".pytc_instance_labels.tif",
   ".ds_store",
   "thumbs.db",
 ]);
+const DEFAULT_REMOTE_PROJECT_PATH =
+  process.env.REACT_APP_DEFAULT_PROJECT_PATH ||
+  "/home/weidf/demo_data/yixiao_tapereader_xri_case_study";
 const IMAGE_EXTENSIONS = new Set([
   ".png",
   ".jpg",
@@ -45,7 +66,614 @@ const IMAGE_EXTENSIONS = new Set([
   ".tif",
   ".tiff",
   ".webp",
+  ".h5",
+  ".hdf5",
+  ".npy",
+  ".npz",
+  ".zarr",
+  ".n5",
+  ".nii",
+  ".nii.gz",
+  ".mrc",
+  ".mrcs",
 ]);
+const PROJECT_CONFIRMATION_ROLES = [
+  {
+    key: "image",
+    label: "Image data",
+    required: true,
+    placeholder: "/path/to/image-folder-or-volume",
+  },
+  {
+    key: "label",
+    label: "Mask / label data",
+    required: false,
+    placeholder: "/path/to/mask-label-folder-or-file",
+  },
+  {
+    key: "prediction",
+    label: "Existing predictions",
+    required: false,
+    placeholder: "/path/to/prediction-folder-or-file",
+  },
+  {
+    key: "checkpoint",
+    label: "Checkpoint",
+    required: false,
+    placeholder: "/path/to/model-checkpoint",
+  },
+  {
+    key: "config",
+    label: "Config preset",
+    required: false,
+    placeholder: "/path/to/config.yaml",
+    provenanceOnly: true,
+  },
+];
+
+const getSelectedFilePath = (item) => {
+  if (!item) return "";
+  if (item.physical_path) return item.physical_path;
+  if (item.logical_path) return item.logical_path;
+  if (item.path && item.path !== "root" && item.name) {
+    return `${item.path}/${item.name}`;
+  }
+  return item.name || item.path || "";
+};
+
+const stripProjectRoot = (rootPath, path) => {
+  if (!rootPath || !path) return path || "";
+  const normalizedRoot = String(rootPath).replace(/\/+$/, "");
+  const normalizedPath = String(path);
+  return normalizedPath.startsWith(`${normalizedRoot}/`)
+    ? normalizedPath.slice(normalizedRoot.length + 1)
+    : normalizedPath;
+};
+
+const toProjectRelativeRoles = (rootPath, roles = {}) =>
+  Object.fromEntries(
+    Object.entries(roles).map(([key, value]) => [
+      key,
+      stripProjectRoot(rootPath, value),
+    ]),
+  );
+
+const basename = (path) => {
+  const parts = String(path || "")
+    .split(/[\\/]/)
+    .filter(Boolean);
+  return parts[parts.length - 1] || "";
+};
+
+const pluralize = (count, word) => `${count} ${word}${count === 1 ? "" : "s"}`;
+
+const cleanRoleOverridePath = (value) =>
+  String(value || "")
+    .trim()
+    .replace(/^["'`]+|["'`.,;]+$/g, "");
+
+const extractRoleOverridesFromFeedback = (feedback) => {
+  const rolePatterns = [
+    {
+      role: "label",
+      pattern:
+        /\b(?:label|labels|mask|masks|seg|segmentation)\b[^,;\n]*?\b(?:in|at|is|are|to|=)\s+([^,;\n]+)/i,
+    },
+    {
+      role: "image",
+      pattern:
+        /\b(?:image|images|raw|volume|volumes)\b[^,;\n]*?\b(?:in|at|is|are|to|=)\s+([^,;\n]+)/i,
+    },
+    {
+      role: "prediction",
+      pattern:
+        /\b(?:prediction|predictions|output|outputs)\b[^,;\n]*?\b(?:in|at|is|are|to|=)\s+([^,;\n]+)/i,
+    },
+    {
+      role: "checkpoint",
+      pattern:
+        /\b(?:checkpoint|model)\b[^,;\n]*?\b(?:in|at|is|are|to|=)\s+([^,;\n]+)/i,
+    },
+    {
+      role: "config",
+      pattern:
+        /\b(?:config|preset|yaml)\b[^,;\n]*?\b(?:in|at|is|are|to|=)\s+([^,;\n]+)/i,
+    },
+  ];
+
+  return rolePatterns.reduce((acc, { role, pattern }) => {
+    const match = String(feedback || "").match(pattern);
+    if (match?.[1]) {
+      acc[role] = cleanRoleOverridePath(match[1]);
+    }
+    return acc;
+  }, {});
+};
+
+const findVolumeSetForFeedback = (feedback, volumeSets) => {
+  const lower = String(feedback || "").toLowerCase();
+  const asksForSwitch =
+    /\b(use|switch|select|choose|prefer|start with|instead|not train|not val|not test)\b/.test(
+      lower,
+    );
+  if (!asksForSwitch) return null;
+
+  return (volumeSets || []).find((set) => {
+    const candidates = [
+      set.name,
+      basename(set.image_root),
+      basename(set.label_root),
+      set.image_root,
+      set.label_root,
+    ]
+      .filter(Boolean)
+      .map((item) => String(item).toLowerCase());
+    return candidates.some((candidate) => lower.includes(candidate));
+  });
+};
+
+const buildProjectSetupFeedbackResult = (setup) => {
+  const feedback = String(
+    setup?.mappingFeedback ?? setup?.projectContext ?? "",
+  ).trim();
+  const suggestion = setup?.suggestion || {};
+  const volumeSets = getProjectVolumeSetsFromSuggestion(suggestion);
+  const currentRoles = setup?.roles || {};
+  const nextRoles = { ...currentRoles };
+  const appliedChanges = {};
+
+  const selectedSet = findVolumeSetForFeedback(feedback, volumeSets);
+  if (selectedSet) {
+    if (selectedSet.image_root) {
+      nextRoles.image = selectedSet.image_root;
+      appliedChanges.image = selectedSet.image_root;
+    }
+    if (selectedSet.label_root) {
+      nextRoles.label = selectedSet.label_root;
+      appliedChanges.label = selectedSet.label_root;
+    }
+  }
+
+  const explicitOverrides = extractRoleOverridesFromFeedback(feedback);
+  Object.entries(explicitOverrides).forEach(([role, value]) => {
+    if (value) {
+      nextRoles[role] = value;
+      appliedChanges[role] = value;
+    }
+  });
+
+  const isQuestion =
+    /\?/.test(feedback) || /^(what|why|which|how)\b/i.test(feedback);
+  const chosenImage = basename(nextRoles.image);
+  const chosenLabel = basename(nextRoles.label);
+  let response = "";
+
+  if (Object.keys(appliedChanges).length > 0) {
+    response = `Updated the mapping. I will use ${chosenImage || "the selected image data"}${
+      chosenLabel ? ` with ${chosenLabel}` : ""
+    }. Check the fields below before starting.`;
+  } else if (
+    isQuestion &&
+    chosenImage &&
+    chosenLabel &&
+    chosenImage === chosenLabel
+  ) {
+    response = `${chosenImage} appears twice because the image and label folders use the same split name. I mapped image data to the image-side ${chosenImage} folder and masks to the label-side ${chosenLabel} folder.`;
+  } else if (isQuestion) {
+    response =
+      "I treated this as a question, so I did not change the mapping. To change it, say something like “use val split” or edit the fields below.";
+  } else {
+    response =
+      "I recorded that context. I did not see a path correction, so the mapping is unchanged.";
+  }
+
+  return {
+    feedback,
+    response,
+    nextRoles,
+    appliedChanges,
+  };
+};
+
+const PROJECT_CONTEXT_LABELS = {
+  imaging_modality: "Imaging modality",
+  target_structure: "Target structure",
+  voxel_size_nm: "Voxel size (z, y, x)",
+  task_family: "Task family",
+  training_policy: "Training policy",
+  volume_split: "Volume split",
+};
+
+const EDITABLE_PROJECT_CONTEXT_FIELDS = [
+  {
+    key: "imaging_modality",
+    label: "Imaging modality",
+    placeholder: "electron microscopy, fluorescence, micro-CT",
+  },
+  {
+    key: "target_structure",
+    label: "Target structure",
+    placeholder: "mitochondria, nuclei, membranes",
+  },
+  {
+    key: "voxel_size_nm",
+    label: "Voxel size (z, y, x nm)",
+    placeholder: "30, 6, 6",
+  },
+];
+
+const normalizeVolumeSplitCount = (value) => {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed >= 0 ? Math.trunc(parsed) : null;
+};
+
+const formatVolumeSplitText = (summary) => {
+  if (!summary) return "";
+  const groundTruth = normalizeVolumeSplitCount(summary.ground_truth);
+  const needsProofreading = normalizeVolumeSplitCount(
+    summary.needs_proofreading,
+  );
+  const missingSegmentation = normalizeVolumeSplitCount(
+    summary.missing_segmentation,
+  );
+  if (
+    groundTruth === null ||
+    needsProofreading === null ||
+    missingSegmentation === null
+  ) {
+    return "";
+  }
+  return `${groundTruth} ground-truth / ${needsProofreading} draft masks / ${missingSegmentation} image-only`;
+};
+
+const parseVolumeSplitFromMaskStatusText = (text) => {
+  const source = String(text || "").toLowerCase();
+  const groundTruth = source.match(
+    /(\d+)\s*(?:ground-truth|ground truth)\s*(?:mask|masks)?/,
+  );
+  const needsProofreading = source.match(
+    /(\d+)\s*(?:draft|proofread|needs proofreading|needs-proofreading)/,
+  );
+  const imageOnly = source.match(
+    /(\d+)\s*(?:image-only|no segmentation|missing segmentation)/,
+  );
+  if (!groundTruth && !needsProofreading && !imageOnly) {
+    return "";
+  }
+  const parsed = {
+    ground_truth: normalizeVolumeSplitCount(groundTruth?.[1]),
+    needs_proofreading: normalizeVolumeSplitCount(needsProofreading?.[1]),
+    missing_segmentation: normalizeVolumeSplitCount(imageOnly?.[1]),
+  };
+  return formatVolumeSplitText(parsed);
+};
+
+const getProjectVolumeSplitFromSuggestion = (suggestion) => {
+  const profile = suggestion?.profile || {};
+  const candidates = [
+    profile.schema?.manifest?.initial_progress_summary,
+    profile.manifest?.initial_progress_summary,
+  ].filter(Boolean);
+  const splitFromSummary = candidates.map(formatVolumeSplitText).find(Boolean);
+  if (splitFromSummary) {
+    return splitFromSummary;
+  }
+  const maskHints = [
+    profile.context_hints?.mask_status,
+    profile.schema?.context_hints?.mask_status,
+  ].filter(Boolean);
+  const splitFromMasks = maskHints
+    .map(parseVolumeSplitFromMaskStatusText)
+    .find(Boolean);
+  if (splitFromMasks) {
+    return splitFromMasks;
+  }
+  return "";
+};
+
+const parseEditableVoxelSizeNm = (value) => {
+  if (Array.isArray(value)) {
+    const numeric = value.slice(0, 3).map((item) => Number(item));
+    return numeric.length === 3 &&
+      numeric.every((item) => Number.isFinite(item) && item > 0)
+      ? numeric
+      : null;
+  }
+  const values = String(value || "").match(/\d+(?:\.\d+)?/g);
+  if (!values || values.length < 3) return null;
+  const numeric = values.slice(0, 3).map((item) => Number(item));
+  return numeric.every((item) => Number.isFinite(item) && item > 0)
+    ? numeric
+    : null;
+};
+
+const formatEditableVoxelSize = (value) => {
+  const parsed = parseEditableVoxelSizeNm(value);
+  return parsed ? parsed.join(", ") : String(value || "");
+};
+
+const cleanEditableProjectContext = (context, fallbackDescription = "") => {
+  const source = context && typeof context === "object" ? context : {};
+  const next = {};
+  const freeformNote = String(
+    source.freeform_note || fallbackDescription || "",
+  ).trim();
+  if (freeformNote) {
+    next.freeform_note = freeformNote.slice(0, 1000);
+  }
+  ["imaging_modality", "target_structure"].forEach((key) => {
+    const value = String(source[key] || "").trim();
+    if (value) next[key] = value;
+  });
+  [
+    "task_family",
+    "mask_status",
+    "image_only_strategy",
+    "training_policy",
+    "volume_split",
+  ].forEach((key) => {
+    const value = String(source[key] || "").trim();
+    if (value) next[key] = value;
+  });
+  const voxelSizeNm = parseEditableVoxelSizeNm(source.voxel_size_nm);
+  if (voxelSizeNm) {
+    next.voxel_size_nm = voxelSizeNm;
+    next.voxel_size_source =
+      source.voxel_size_source || "project_setup_confirmation";
+  }
+  if (source.use_defaults) {
+    next.use_defaults = true;
+  }
+  return next;
+};
+
+const editableProjectContextMissingFields = (context) => {
+  const missing = [];
+  if (!context?.imaging_modality) missing.push("imaging modality");
+  if (!context?.target_structure) missing.push("target structure");
+  if (!parseEditableVoxelSizeNm(context?.voxel_size_nm)) {
+    missing.push("imaging resolution");
+  }
+  return missing;
+};
+
+const buildProjectContextMetadata = (
+  description,
+  _existingMetadata = {},
+  options = {},
+) => {
+  void _existingMetadata;
+  const assessment = evaluateProjectContextCompleteness(description, options);
+  const contextSource =
+    options.projectContextDraft &&
+    typeof options.projectContextDraft === "object"
+      ? options.projectContextDraft
+      : assessment.context;
+  const projectContext = cleanEditableProjectContext(
+    contextSource,
+    description,
+  );
+  if (!projectContext || Object.keys(projectContext).length === 0) return null;
+  const missing = editableProjectContextMissingFields(projectContext);
+  return {
+    ...projectContext,
+    completeness: {
+      complete: missing.length === 0,
+      missing,
+    },
+    source: "project_setup_confirmation",
+    updated_at: new Date().toISOString(),
+  };
+};
+
+const getProjectContextDraftWithSharedFacts = (
+  setup,
+  descriptionOverride = "",
+  context = null,
+) => {
+  const baseContext = cleanEditableProjectContext(
+    context || {},
+    descriptionOverride,
+  );
+  const splitText = getProjectVolumeSplitFromSuggestion(setup?.suggestion);
+  if (splitText && !baseContext.volume_split) {
+    baseContext.volume_split = splitText;
+  }
+  return baseContext;
+};
+
+const compactProjectPath = (pathValue) => {
+  const text = String(pathValue || "").trim();
+  if (!text) return "";
+  const normalized = text.replace(/\\/g, "/");
+  const parts = normalized.split("/").filter(Boolean);
+  if (parts.length <= 3) return normalized;
+  return parts.slice(-3).join("/");
+};
+
+const formatAuditFactValue = (fact) => {
+  if (!fact) return "";
+  if (fact.key === "voxel_size_nm") {
+    return formatVoxelSizeNm(fact.value);
+  }
+  if (Array.isArray(fact.value)) {
+    return fact.value.join(", ");
+  }
+  return String(fact.value ?? "");
+};
+
+const compactAuditSource = (source) => {
+  const text = String(source || "").trim();
+  if (!text) return "";
+  return text
+    .replace(/^volume_metadata:/, "")
+    .replace(/^content_spot_check:/, "");
+};
+
+const auditFindingStyles = {
+  error: {
+    background: "#fff1f0",
+    border: "#ffccc7",
+    color: "#a8071a",
+  },
+  warning: {
+    background: "#fff7e6",
+    border: "#ffd591",
+    color: "#ad6800",
+  },
+  info: {
+    background: "#f6ffed",
+    border: "#b7eb8f",
+    color: "#237804",
+  },
+};
+
+const buildProjectBrief = ({ context, roles, suggestion, volumeSets }) => {
+  const projectContext = context || {};
+  const target = String(projectContext.target_structure || "").trim();
+  const modality = String(projectContext.imaging_modality || "").trim();
+  const resolution = formatVoxelSizeNm(projectContext.voxel_size_nm);
+  const imagePath = compactProjectPath(roles?.image);
+  const labelPath = compactProjectPath(roles?.label || roles?.mask);
+  const configPath = compactProjectPath(roles?.config);
+  const predictionPath = compactProjectPath(roles?.prediction);
+  const pairCounts = (volumeSets || []).map((set) =>
+    Number(set.pair_count || 0),
+  );
+  const pairCount = pairCounts.length > 0 ? Math.max(...pairCounts) : 0;
+  const subject = [modality, target].filter(Boolean).join(" ");
+  const summary = subject
+    ? `${subject} project${resolution ? ` at ${resolution}` : ""}.`
+    : `Project${resolution ? ` at ${resolution}` : ""}.`;
+  const nextMoves = [
+    imagePath ? `Use ${imagePath} as the active image data.` : "",
+    labelPath
+      ? `Use ${labelPath} for masks, proofreading seeds, and evaluation.`
+      : "Start image-only; ask before training or metric comparison.",
+    resolution
+      ? `Use ${resolution} as the z/y/x voxel size for visualization and model defaults.`
+      : "",
+    configPath ? `Start from ${configPath} as the config preset.` : "",
+    predictionPath ? `Treat ${predictionPath} as the existing prediction.` : "",
+    pairCount > 1
+      ? `Keep this as a multi-volume project with ${pairCount} detected image/mask pairs.`
+      : "",
+  ].filter(Boolean);
+  const uncertainties = [];
+  if (projectContext.completeness?.complete === false) {
+    uncertainties.push(
+      `Context still missing: ${projectContext.completeness.missing.join(", ")}.`,
+    );
+  }
+  if (!labelPath) {
+    uncertainties.push("No mask/label path is confirmed yet.");
+  }
+  if (!configPath) {
+    uncertainties.push("No config preset is confirmed yet.");
+  }
+  return {
+    project_name: suggestion?.name || "Mounted project",
+    summary,
+    fields: Object.entries(PROJECT_CONTEXT_LABELS)
+      .map(([key, label]) => ({
+        key,
+        label,
+        value:
+          key === "voxel_size_nm"
+            ? formatVoxelSizeNm(projectContext[key])
+            : projectContext[key],
+      }))
+      .filter((item) => Boolean(item.value)),
+    next_moves: nextMoves,
+    uncertainties,
+  };
+};
+
+const buildProjectMemoryProfile = ({
+  suggestion,
+  roles,
+  workflowPatch,
+  projectDescription,
+  projectContext,
+  projectBrief,
+  projectAudit,
+  semanticTurns,
+  mappingTurns,
+  source,
+  existingProfile,
+}) => {
+  const now = new Date().toISOString();
+  return {
+    ...(existingProfile && typeof existingProfile === "object"
+      ? existingProfile
+      : {}),
+    schema_version: "pytc-project-context/v1",
+    project_name: suggestion?.name || "Mounted project",
+    project_directory: suggestion?.directory_path || null,
+    semantic_context: projectContext || {
+      freeform_note: String(projectDescription || "").trim(),
+    },
+    project_brief: projectBrief || null,
+    project_audit: projectAudit || null,
+    context_facts: projectAudit?.context_facts || [],
+    mechanistic_mapping: roles || {},
+    workflow_memory: {
+      current_stage: "setup",
+      last_completed_step: "project_setup_confirmed",
+      known_blockers: [],
+      agent_recommendation: "Start from the confirmed project data.",
+      workflow_patch_keys: Object.keys(workflowPatch || {}),
+    },
+    setup_turns: {
+      semantic: semanticTurns || [],
+      mapping: mappingTurns || [],
+    },
+    source,
+    updated_at: now,
+  };
+};
+
+const GUIDED_PROJECT_CONTEXT_GROUPS = [
+  {
+    key: "task_family",
+    label: "What are we working over?",
+    helper:
+      "Example: XRI fibre instance segmentation, mitochondria segmentation, proofreading masks",
+    placeholder: "XRI fibre instance segmentation",
+  },
+  {
+    key: "mask_status",
+    label: "What mask data exists?",
+    helper:
+      "Example: 6 ground-truth masks, 2 draft masks, 2 image-only volumes",
+    placeholder:
+      "mixed: 6 ground-truth masks, 2 draft masks, 2 image-only targets",
+  },
+  {
+    key: "image_only_strategy",
+    label: "What should happen to image-only volumes?",
+    helper: "Tell the agent whether to infer, ignore, or ask first.",
+    placeholder: "run inference on image-only volumes later",
+  },
+  {
+    key: "training_policy",
+    label: "Which masks are safe for training?",
+    helper: "Example: train only on confirmed ground-truth masks",
+    placeholder: "train only on confirmed ground-truth masks",
+  },
+];
+
+const appendProjectContextAnswer = (existingText, nextAnswer) => {
+  const existing = String(existingText || "").trim();
+  const next = String(nextAnswer || "").trim();
+  if (!next) return existing;
+  if (!existing) return next;
+  const existingLower = existing.toLowerCase();
+  const nextLower = next.toLowerCase();
+  if (nextLower.includes(existingLower)) return next;
+  if (existingLower.includes(nextLower)) return existing;
+  return `${existing}\n${next}`;
+};
 
 const collectDescendantFolderIds = (folderList, rootIds) => {
   const removed = new Set();
@@ -70,7 +698,8 @@ const isFolderWithinSubtree = (folderList, rootId, targetId) => {
     return false;
   }
 
-  let current = folderList.find((folder) => folder.key === targetId);
+  const folderByKey = new Map(folderList.map((folder) => [folder.key, folder]));
+  let current = folderByKey.get(targetId);
   while (current) {
     if (current.key === rootId) {
       return true;
@@ -78,7 +707,7 @@ const isFolderWithinSubtree = (folderList, rootId, targetId) => {
     if (!current.parent || current.parent === "root") {
       break;
     }
-    current = folderList.find((folder) => folder.key === current.parent);
+    current = folderByKey.get(current.parent);
   }
   return false;
 };
@@ -118,11 +747,13 @@ const transformFiles = (fileList) => {
 
 function FilesManager() {
   const context = useContext(AppContext);
+  const workflowContext = useWorkflow();
   const [folders, setFolders] = useState([]);
   const [files, setFiles] = useState({});
   const foldersRef = useRef([]);
   const filesRef = useRef({});
   const [currentFolder, setCurrentFolder] = useState("root");
+  const currentFolderRef = useRef("root");
   const [loadedParents, setLoadedParents] = useState([]);
   const [loadingParents, setLoadingParents] = useState([]);
   const loadedParentsRef = useRef(new Set());
@@ -142,9 +773,24 @@ function FilesManager() {
   const [serverUnavailable, setServerUnavailable] = useState(false);
   const [hasShownServerWarning, setHasShownServerWarning] = useState(false);
   const [previewStatus, setPreviewStatus] = useState({});
+  const [projectSuggestions, setProjectSuggestions] = useState([]);
+  const [pendingProjectSetup, setPendingProjectSetup] = useState(null);
+  const [projectSetupSaving, setProjectSetupSaving] = useState(false);
+  const [projectSetupFeedbackSaving, setProjectSetupFeedbackSaving] =
+    useState(false);
+  const [rolePickerTarget, setRolePickerTarget] = useState(null);
+  const folderByKey = React.useMemo(
+    () => new Map(folders.map((folder) => [folder.key, folder])),
+    [folders],
+  );
+  const pendingProjectSetupRef = useRef(null);
+  const autoProjectSetupOpenedRef = useRef(false);
+  const handledChooseDataActionRef = useRef(null);
+  const chooseProjectDataRef = useRef(null);
   const containerRef = useRef(null);
   const itemRefs = useRef({});
   const isDragSelecting = useRef(false);
+  const keyHandlerStateRef = useRef({});
   const previewBaseUrl = apiClient.defaults.baseURL || "http://localhost:4242";
 
   // Sidebar Resize Logic
@@ -152,6 +798,10 @@ function FilesManager() {
   const [isResizing, setIsResizing] = useState(false);
   const [isSidebarVisible, setIsSidebarVisible] = useState(true);
 
+  useEffect(() => {
+    pendingProjectSetupRef.current = pendingProjectSetup;
+  }, [pendingProjectSetup]);
+
   const startResizing = React.useCallback(() => setIsResizing(true), []);
   const stopResizing = React.useCallback(() => setIsResizing(false), []);
   const resize = React.useCallback(
@@ -192,6 +842,10 @@ function FilesManager() {
     filesRef.current = files;
   }, [files]);
 
+  useEffect(() => {
+    currentFolderRef.current = currentFolder;
+  }, [currentFolder]);
+
   const syncLoadedParents = React.useCallback((nextParents) => {
     loadedParentsRef.current = new Set(nextParents);
     setLoadedParents(nextParents);
@@ -240,11 +894,14 @@ function FilesManager() {
       const normalizedParent = String(parentKey || "root");
       const previousFolders = foldersRef.current;
       const previousFiles = filesRef.current;
-      const { folders: nextFolders, files: nextFiles } = transformFiles(fileList);
+      const { folders: nextFolders, files: nextFiles } =
+        transformFiles(fileList);
       const existingDirectChildIds = previousFolders
         .filter((folder) => folder.parent === normalizedParent)
         .map((folder) => folder.key);
-      const nextDirectChildIds = new Set(nextFolders.map((folder) => folder.key));
+      const nextDirectChildIds = new Set(
+        nextFolders.map((folder) => folder.key),
+      );
       const removedFolderIds = collectDescendantFolderIds(
         previousFolders,
         existingDirectChildIds.filter((id) => !nextDirectChildIds.has(id)),
@@ -253,14 +910,19 @@ function FilesManager() {
       const mergedFolders = [
         ...previousFolders.filter(
           (folder) =>
-            folder.parent !== normalizedParent && !removedFolderIds.has(folder.key),
+            folder.parent !== normalizedParent &&
+            !removedFolderIds.has(folder.key),
         ),
         ...nextFolders,
       ].sort((left, right) => {
         if (left.parent === right.parent) {
-          return String(left.title || "").localeCompare(String(right.title || ""));
+          return String(left.title || "").localeCompare(
+            String(right.title || ""),
+          );
         }
-        return String(left.parent || "").localeCompare(String(right.parent || ""));
+        return String(left.parent || "").localeCompare(
+          String(right.parent || ""),
+        );
       });
 
       const mergedFiles = { ...previousFiles };
@@ -277,6 +939,31 @@ function FilesManager() {
       setFolders(mergedFolders);
       setFiles(mergedFiles);
       markParentLoaded(normalizedParent);
+
+      const activeFolder = currentFolderRef.current;
+      if (
+        activeFolder !== "root" &&
+        !mergedFolders.some((folder) => folder.key === activeFolder)
+      ) {
+        const fallbackFolder =
+          normalizedParent !== activeFolder &&
+          mergedFolders.some((folder) => folder.key === normalizedParent)
+            ? normalizedParent
+            : "root";
+        setCurrentFolder(fallbackFolder);
+        setSelectedItems([]);
+        setEditingItem(null);
+        setNewItemType(null);
+        logClientEvent("files_active_folder_reconciled", {
+          source: "files_manager",
+          message: "Active folder was removed by a fresh file index load.",
+          data: {
+            previousFolder: activeFolder,
+            fallbackFolder,
+            refreshedParent: normalizedParent,
+          },
+        });
+      }
     },
     [markParentLoaded],
   );
@@ -347,6 +1034,38 @@ function FilesManager() {
         return res.data;
       } catch (err) {
         const isNetworkError = !err.response;
+        const isMissingParent =
+          err.response?.status === 404 && normalizedParent !== "root";
+        if (isMissingParent) {
+          logClientEvent("files_parent_missing_refreshed", {
+            level: "WARN",
+            source: "files_manager",
+            message:
+              "File index parent was stale; refreshing the root project tree.",
+            data: {
+              parent: normalizedParent,
+              activeFolder: currentFolderRef.current,
+              detail: err.response?.data?.detail || err.message,
+            },
+          });
+          const activeFolderWasStale =
+            currentFolderRef.current === normalizedParent ||
+            isFolderWithinSubtree(
+              foldersRef.current,
+              normalizedParent,
+              currentFolderRef.current,
+            );
+          removeFolderSubtrees([normalizedParent]);
+          if (activeFolderWasStale) {
+            setCurrentFolder("root");
+            setSelectedItems([]);
+          }
+          await fetchFolderContents("root", {
+            force: true,
+            silentNetworkError: true,
+          });
+          return null;
+        }
         if (isNetworkError) {
           setServerUnavailable(true);
           if (!hasShownServerWarning && !silentNetworkError) {
@@ -365,6 +1084,7 @@ function FilesManager() {
     [
       hasShownServerWarning,
       replaceFolderChildren,
+      removeFolderSubtrees,
       setParentLoadingState,
     ],
   );
@@ -375,9 +1095,9 @@ function FilesManager() {
 
     const loadVisibleFolders = async () => {
       if (!isMounted) return;
-      await fetchFolderContents("root");
+      await fetchFolderContents("root", { force: true });
       if (currentFolder !== "root") {
-        await fetchFolderContents(currentFolder);
+        await fetchFolderContents(currentFolder, { force: true });
       }
     };
 
@@ -404,9 +1124,31 @@ function FilesManager() {
     };
   }, [currentFolder, fetchFolderContents, serverUnavailable]); // Retry when server unavailable
 
-  const getCurrentFolderObj = () =>
-    folders.find((f) => f.key === currentFolder);
-  // eslint-disable-next-line no-loop-func
+  useEffect(() => {
+    const refreshVisibleFolders = () => {
+      if (document.visibilityState === "hidden") return;
+      fetchFolderContents("root", {
+        force: true,
+        silentNetworkError: true,
+      });
+      const activeFolder = currentFolderRef.current;
+      if (activeFolder && activeFolder !== "root") {
+        fetchFolderContents(activeFolder, {
+          force: true,
+          silentNetworkError: true,
+        });
+      }
+    };
+
+    window.addEventListener("focus", refreshVisibleFolders);
+    document.addEventListener("visibilitychange", refreshVisibleFolders);
+    return () => {
+      window.removeEventListener("focus", refreshVisibleFolders);
+      document.removeEventListener("visibilitychange", refreshVisibleFolders);
+    };
+  }, [fetchFolderContents]);
+
+  const getCurrentFolderObj = () => folderByKey.get(currentFolder);
   const getBreadcrumbs = () => {
     const path = [{ key: "root", title: "Projects", parent: null }];
     if (currentFolder === "root") {
@@ -417,7 +1159,7 @@ function FilesManager() {
     while (curr) {
       chain.unshift(curr);
       if (!curr.parent || curr.parent === "root") break;
-      curr = folders.find((f) => f.key === curr.parent);
+      curr = folderByKey.get(curr.parent);
     }
     return path.concat(chain);
   };
@@ -435,13 +1177,32 @@ function FilesManager() {
     setNewItemType(null);
   };
 
+  const loadProjectSuggestions = React.useCallback(async () => {
+    try {
+      const response = await apiClient.get("/files/project-suggestions", {
+        withCredentials: true,
+      });
+      const suggestions = response.data || [];
+      setProjectSuggestions(suggestions);
+      return suggestions;
+    } catch (error) {
+      // Suggestions are convenience only; normal mounting must keep working.
+      console.warn("Could not load project suggestions", error);
+      setProjectSuggestions([]);
+      return [];
+    }
+  }, []);
+
+  useEffect(() => {
+    loadProjectSuggestions();
+  }, [loadProjectSuggestions]);
+
   const isImageFile = (file) => {
     if (!file || file.is_folder) return false;
     if (file.type && file.type.startsWith("image/")) return true;
-    const ext = `.${String(file.name || "")
-      .split(".")
-      .pop()}`.toLowerCase();
-    return IMAGE_EXTENSIONS.has(ext);
+    const name = String(file.name || "").toLowerCase();
+    const ext = `.${name.split(".").pop()}`;
+    return IMAGE_EXTENSIONS.has(ext) || name.endsWith(".nii.gz");
   };
 
   const getPreviewUrl = (fileKey) =>
@@ -769,7 +1530,7 @@ function FilesManager() {
 
             const childFiles = files[parentId] || [];
             descendantFileCount += childFiles.length;
-            childFiles.forEach((f) => {
+            for (const f of childFiles) {
               const sizeStr = String(f.size || "");
               const match = sizeStr.match(/([0-9.]+)\s*(KB|MB|GB|B)/i);
               if (match) {
@@ -780,7 +1541,7 @@ function FilesManager() {
                 if (unit === "MB") descendantSizeKb += value * 1024;
                 if (unit === "GB") descendantSizeKb += value * 1024 * 1024;
               }
-            });
+            }
           }
         }
 
@@ -1028,13 +1789,34 @@ function FilesManager() {
 
   const handleMouseUp = () => setSelectionBox(null);
 
+  useEffect(() => {
+    keyHandlerStateRef.current = {
+      clipboard,
+      currentFolder,
+      editingItem,
+      files,
+      finishCreateFolder,
+      finishRename,
+      folders,
+      handleCopy,
+      handleCut,
+      handleDelete,
+      handlePaste,
+      newItemType,
+      selectedItems,
+      tempName,
+    };
+  });
+
   // Keyboard shortcuts
-  // eslint-disable-next-line react-hooks/exhaustive-deps
   useEffect(() => {
     const handleKeyDown = (e) => {
-      if (editingItem) {
+      const state = keyHandlerStateRef.current;
+      if (state.editingItem) {
         if (e.key === "Enter")
-          newItemType ? finishCreateFolder() : finishRename();
+          state.newItemType
+            ? state.finishCreateFolder?.()
+            : state.finishRename?.();
         if (e.key === "Escape") {
           setEditingItem(null);
           setNewItemType(null);
@@ -1049,33 +1831,24 @@ function FilesManager() {
           target.isContentEditable)
       )
         return;
-      if (e.key === "Delete") handleDelete();
-      if (e.ctrlKey && e.key === "c") handleCopy();
-      if (e.ctrlKey && e.key === "x") handleCut();
-      if (e.ctrlKey && e.key === "v") handlePaste();
+      if (e.key === "Delete") state.handleDelete?.();
+      if (e.ctrlKey && e.key === "c") state.handleCopy?.();
+      if (e.ctrlKey && e.key === "x") state.handleCut?.();
+      if (e.ctrlKey && e.key === "v") state.handlePaste?.();
       if ((e.ctrlKey || e.metaKey) && e.key === "a") {
         e.preventDefault();
         const allKeys = [
-          ...folders
-            .filter((f) => f.parent === currentFolder)
+          ...(state.folders || [])
+            .filter((f) => f.parent === state.currentFolder)
             .map((f) => f.key),
-          ...(files[currentFolder] || []).map((f) => f.key),
+          ...((state.files || {})[state.currentFolder] || []).map((f) => f.key),
         ];
         setSelectedItems(allKeys);
       }
     };
     window.addEventListener("keydown", handleKeyDown);
     return () => window.removeEventListener("keydown", handleKeyDown);
-  }, [
-    selectedItems,
-    clipboard,
-    currentFolder,
-    folders,
-    files,
-    editingItem,
-    newItemType,
-    tempName,
-  ]);
+  }, []);
 
   // Context menu handling
   const handleContextMenu = (e, type, key) => {
@@ -1140,7 +1913,12 @@ function FilesManager() {
         )}
       </div>
     ) : type === "folder" ? (
-      <FolderFilled style={{ fontSize: iconSize, color: "#1890ff" }} />
+      <FolderFilled
+        style={{
+          fontSize: iconSize,
+          color: "var(--seg-accent-primary, #3f37c9)",
+        }}
+      />
     ) : (
       <FileOutlined style={{ fontSize: iconSize, color: "#555" }} />
     );
@@ -1179,8 +1957,12 @@ function FilesManager() {
           textAlign: viewMode === "grid" ? "center" : "left",
           cursor: "pointer",
           borderRadius: 4,
-          backgroundColor: isSelected ? "#e6f7ff" : "transparent",
-          border: isSelected ? "1px solid #1890ff" : "1px solid transparent",
+          backgroundColor: isSelected
+            ? "var(--seg-selection-fill, rgba(63, 55, 201, 0.12))"
+            : "transparent",
+          border: isSelected
+            ? "1px solid var(--seg-accent-primary, #3f37c9)"
+            : "1px solid transparent",
           display: viewMode === "list" ? "flex" : "block",
           alignItems: "center",
           userSelect: "none",
@@ -1229,9 +2011,10 @@ function FilesManager() {
                     padding: "2px 6px",
                     fontSize: 10,
                     borderRadius: 10,
-                    background: "#f0f5ff",
-                    color: "#2f54eb",
-                    border: "1px solid #adc6ff",
+                    background: "var(--seg-accent-primary-soft, #f0efff)",
+                    color: "var(--seg-accent-primary, #3f37c9)",
+                    border:
+                      "1px solid var(--seg-accent-primary-border, #c7c2ff)",
                   }}
                 >
                   Mounted
@@ -1253,7 +2036,7 @@ function FilesManager() {
           margin: viewMode === "grid" ? 8 : 0,
           textAlign: viewMode === "grid" ? "center" : "left",
           borderRadius: 4,
-          border: "1px solid #1890ff",
+          border: "1px solid var(--seg-accent-primary, #3f37c9)",
           display: viewMode === "list" ? "flex" : "block",
           alignItems: "center",
         }}
@@ -1270,7 +2053,7 @@ function FilesManager() {
           <FolderFilled
             style={{
               fontSize: viewMode === "grid" ? 48 : 24,
-              color: "#1890ff",
+              color: "var(--seg-accent-primary, #3f37c9)",
             }}
           />
         </div>
@@ -1298,88 +2081,1598 @@ function FilesManager() {
   const currentFolders = folders.filter((f) => f.parent === currentFolder);
   const currentFiles = files[currentFolder] || [];
 
-  const getContextMenuItems = () => {
-    if (contextMenu?.type === "container") {
-      return [
-        { key: "new_folder", label: "Create Folder", icon: <FolderFilled /> },
-        { key: "upload", label: "Upload File...", icon: <UploadOutlined /> },
-        {
-          key: "mount_project",
-          label: "Mount Project Directory...",
-          icon: <FolderOpenOutlined />,
+  const readStoredProjectMemory = async (directoryPath) => {
+    if (!directoryPath) return null;
+    try {
+      const response = await apiClient.get("/files/project-context", {
+        params: { directory_path: directoryPath },
+      });
+      return response?.data?.profile || null;
+    } catch (error) {
+      logClientEvent("project_context_profile_read_failed", {
+        level: "WARN",
+        source: "files_manager",
+        message: "Stored project context could not be read",
+        data: {
+          directoryPath,
+          error: error?.message || String(error),
         },
-      ];
-    }
-    const items = [];
-    const selectedKey = selectedItems.length === 1 ? selectedItems[0] : null;
-    const selectedFolder = selectedKey
-      ? folders.find((f) => f.key === selectedKey)
-      : null;
-    const isMountedProjectFolder = Boolean(
-      selectedFolder &&
-      selectedFolder.parent === "root" &&
-      selectedFolder.physical_path,
-    );
-    // Only show preview for files, not folders
-    if (selectedItems.length === 1) {
-      const isFolder = folders.some((f) => f.key === selectedKey);
-      if (!isFolder) {
-        items.push({ key: "preview", label: "Preview", icon: <EyeOutlined /> });
-      }
-    }
-    if (isMountedProjectFolder) {
-      items.push({
-        key: "unmount_project",
-        label: "Unmount Project",
-        danger: true,
-        icon: <FolderOpenOutlined />,
       });
+      return null;
     }
-    if (selectedItems.length === 1) {
-      const selectedFile = Object.values(files)
-        .flat()
-        .find((f) => f.key === selectedKey);
-      const selectedFolder = folders.find((f) => f.key === selectedKey);
-      const hasPhysicalPath =
-        (selectedFile &&
-          selectedFile.physical_path &&
-          selectedFile.physical_path.startsWith("/")) ||
-        (selectedFolder &&
-          selectedFolder.physical_path &&
-          selectedFolder.physical_path.startsWith("/"));
-      if (hasPhysicalPath) {
-        items.push({
-          key: "reveal_in_finder",
-          label: "Open in Finder",
-          icon: <FolderOpenOutlined />,
-        });
-      }
-    }
-    items.push(
-      {
-        key: "rename",
-        label: "Rename",
-        icon: <FileTextOutlined />,
-        disabled: selectedItems.length > 1,
-      },
+  };
+
+  const openProjectSetupConfirmation = async (suggestion, source) => {
+    const roles = toProjectRelativeRoles(
+      suggestion?.directory_path,
+      getProjectRoleDefaultsFromSuggestion(suggestion),
+    );
+    const volumeSets = getProjectVolumeSetsFromSuggestion(suggestion);
+    const projectAudit = getProjectAuditFromSuggestion(suggestion);
+    const storedProjectMemory = await readStoredProjectMemory(
+      suggestion?.directory_path,
+    );
+    const storedSemanticContext = storedProjectMemory?.semantic_context || {};
+    const storedDescription =
+      storedSemanticContext.freeform_note ||
+      storedProjectMemory?.project_description ||
+      "";
+    const projectContextDefaults =
+      getProjectContextDefaultsFromSuggestion(suggestion);
+    const initialProjectContextDraft = getProjectContextDraftWithSharedFacts(
       {
-        key: "copy",
-        label: `Copy${selectedItems.length > 1 ? ` (${selectedItems.length})` : ""}`,
-        icon: <FileOutlined />,
+        suggestion,
       },
+      storedDescription,
       {
-        key: "delete",
-        label: `Delete${selectedItems.length > 1 ? ` (${selectedItems.length})` : ""}`,
-        danger: true,
-        icon: <FileOutlined />,
+        ...projectContextDefaults,
+        ...storedSemanticContext,
       },
-      { type: "divider" },
-      { key: "properties", label: "Properties", icon: <FileTextOutlined /> },
     );
-    return items;
+    const missingInitialContextFields = editableProjectContextMissingFields(
+      initialProjectContextDraft,
+    );
+    const startsWithMapping =
+      missingInitialContextFields.length === 0 && Boolean(roles.image);
+    setPendingProjectSetup({
+      source,
+      suggestion,
+      roles,
+      setupStep: startsWithMapping ? "mapping" : "semantic",
+      projectDescription: storedDescription,
+      projectDescriptionDraft: storedDescription,
+      projectContextDraft: initialProjectContextDraft,
+      projectContextDefaults,
+      projectAudit,
+      useContextDefaults:
+        startsWithMapping || Boolean(storedSemanticContext.use_defaults),
+      semanticFeedbackTurns: [],
+      lastSemanticResponse: storedDescription
+        ? "I found saved project context. Review it before continuing."
+        : startsWithMapping
+          ? "I filled the project basics from the files I checked."
+          : "",
+      mappingFeedback: "",
+      feedbackTurns: [],
+      lastFeedbackResponse: "",
+      storedProjectMemory,
+    });
+    logClientEvent("project_role_confirmation_opened", {
+      source: "files_manager",
+      message: "Project role confirmation opened",
+      data: {
+        setupSource: source,
+        suggestionId: suggestion?.id || null,
+        projectName: suggestion?.name || null,
+        profileMode: suggestion?.profile?.schema?.mode || null,
+        volumeSetCount: volumeSets.length,
+        auditSummary: projectAudit?.summary || null,
+        projectContextDefaults,
+        missingInitialContextFields,
+        skippedSemanticSetup: startsWithMapping,
+        hasImage: Boolean(roles.image),
+        hasLabel: Boolean(roles.label),
+        hasPrediction: Boolean(roles.prediction),
+        hasCheckpoint: Boolean(roles.checkpoint),
+        hasStoredProjectMemory: Boolean(storedProjectMemory),
+      },
+    });
   };
 
-  const handleUploadClick = () => {
+  const setPendingProjectDescription = (nextValue) => {
+    setPendingProjectSetup((current) => {
+      if (!current) return current;
+      return {
+        ...current,
+        projectDescriptionDraft: nextValue,
+        useContextDefaults: false,
+      };
+    });
+  };
+
+  const setPendingMappingFeedback = (nextValue) => {
+    setPendingProjectSetup((current) => {
+      if (!current) return current;
+      return {
+        ...current,
+        mappingFeedback: nextValue,
+      };
+    });
+  };
+
+  const setPendingRoleValue = (roleKey, nextValue) => {
+    setPendingProjectSetup((current) => {
+      if (!current) return current;
+      return {
+        ...current,
+        roles: {
+          ...current.roles,
+          [roleKey]: nextValue,
+        },
+      };
+    });
+  };
+
+  const setPendingProjectContextValue = (contextKey, nextValue) => {
+    setPendingProjectSetup((current) => {
+      if (!current) return current;
+      const currentDraft = current.projectContextDraft || {};
+      return {
+        ...current,
+        projectContextDraft: {
+          ...currentDraft,
+          [contextKey]: nextValue,
+          ...(contextKey === "voxel_size_nm"
+            ? { voxel_size_source: "project_setup_confirmation" }
+            : {}),
+        },
+      };
+    });
+  };
+
+  const setPendingSetupStep = (setupStep) => {
+    setPendingProjectSetup((current) =>
+      current ? { ...current, setupStep } : current,
+    );
+  };
+
+  const getPendingProjectContextDefaults = (setup) =>
+    setup?.projectContextDefaults ||
+    getProjectContextDefaultsFromSuggestion(setup?.suggestion);
+
+  const handleProjectContextContinue = (options = {}) => {
+    const setupSnapshot = pendingProjectSetupRef.current || pendingProjectSetup;
+    if (!setupSnapshot) return;
+    const useDefaults = Boolean(options.useDefaults);
+    const currentAnswer = useDefaults
+      ? ""
+      : String(setupSnapshot.projectDescriptionDraft || "").trim();
+    const combinedProjectDescription = appendProjectContextAnswer(
+      setupSnapshot.projectDescription,
+      currentAnswer,
+    );
+    const hasProjectDescription = Boolean(combinedProjectDescription);
+    const defaultContext = getProjectContextDraftWithSharedFacts(
+      setupSnapshot,
+      combinedProjectDescription,
+      getPendingProjectContextDefaults(setupSnapshot),
+    );
+    const draftContext = getProjectContextDraftWithSharedFacts(
+      setupSnapshot,
+      combinedProjectDescription,
+      setupSnapshot.projectContextDraft,
+    );
+    const draftMissing = editableProjectContextMissingFields(draftContext);
+    const hasCompleteDraft = draftMissing.length === 0;
+    let assessment = evaluateProjectContextCompleteness(
+      combinedProjectDescription,
+      {
+        useDefaults: useDefaults || setupSnapshot.useContextDefaults,
+        defaultContext: hasCompleteDraft ? draftContext : defaultContext,
+      },
+    );
+    if (hasCompleteDraft) {
+      assessment = {
+        ...assessment,
+        complete: true,
+        context: {
+          ...assessment.context,
+          ...draftContext,
+          ...(useDefaults || setupSnapshot.useContextDefaults
+            ? { use_defaults: true }
+            : {}),
+        },
+        known: {
+          ...(assessment.known || {}),
+          ...draftContext,
+        },
+        missing: [],
+        next_question: "",
+      };
+    }
+    if (!useDefaults && !hasProjectDescription && !hasCompleteDraft) {
+      message.warning("Fill the project basics or add a note.");
+      return;
+    }
+    const response = describeProjectContextAssessment(assessment);
+    const shouldAdvance =
+      assessment.complete || useDefaults || setupSnapshot.useContextDefaults;
+    const turn = {
+      user: currentAnswer,
+      agent: response,
+      missing: assessment.missing,
+      complete: assessment.complete,
+      use_defaults: useDefaults || setupSnapshot.useContextDefaults,
+      accumulated_context: combinedProjectDescription,
+      timestamp: new Date().toISOString(),
+    };
+
+    logClientEvent("project_context_reviewed", {
+      source: "files_manager",
+      message: "Project context reviewed before mapping confirmation",
+      data: {
+        suggestionId: setupSnapshot.suggestion?.id || null,
+        projectName: setupSnapshot.suggestion?.name || null,
+        complete: assessment.complete,
+        missing: assessment.missing,
+        nextQuestion: assessment.next_question,
+        context: assessment.context,
+        accumulatedContextPreview: combinedProjectDescription.slice(0, 400),
+        useDefaults: useDefaults || setupSnapshot.useContextDefaults,
+      },
+    });
+
+    setPendingProjectSetup((current) => {
+      if (!current) return current;
+      return {
+        ...current,
+        projectDescription: combinedProjectDescription,
+        projectDescriptionDraft: "",
+        projectContextDraft: cleanEditableProjectContext(
+          assessment.context,
+          combinedProjectDescription,
+        ),
+        setupStep: shouldAdvance ? "mapping" : "semantic",
+        useContextDefaults: useDefaults || current.useContextDefaults,
+        semanticFeedbackTurns: [...(current.semanticFeedbackTurns || []), turn],
+        lastSemanticResponse: shouldAdvance ? "" : response,
+      };
+    });
+  };
+
+  const handleProjectSetupFeedbackSubmit = async () => {
+    const setupSnapshot = pendingProjectSetupRef.current || pendingProjectSetup;
+    if (!setupSnapshot) return;
+    const feedback = String(setupSnapshot.mappingFeedback || "").trim();
+    if (!feedback) return;
+
+    const result = buildProjectSetupFeedbackResult(setupSnapshot);
+    const turn = {
+      user: result.feedback,
+      agent: result.response,
+      applied_changes: result.appliedChanges,
+      timestamp: new Date().toISOString(),
+    };
+
+    setProjectSetupFeedbackSaving(true);
+    setPendingProjectSetup((current) => {
+      if (!current) return current;
+      return {
+        ...current,
+        roles: result.nextRoles,
+        mappingFeedback: "",
+        feedbackTurns: [...(current.feedbackTurns || []), turn],
+        lastFeedbackResponse: result.response,
+      };
+    });
+    pendingProjectSetupRef.current = {
+      ...setupSnapshot,
+      roles: result.nextRoles,
+      mappingFeedback: "",
+      feedbackTurns: [...(setupSnapshot.feedbackTurns || []), turn],
+      lastFeedbackResponse: result.response,
+    };
+
+    logClientEvent("project_role_confirmation_feedback_submitted", {
+      source: "files_manager",
+      message: "Project setup feedback submitted",
+      data: {
+        setupSource: setupSnapshot.source,
+        suggestionId: setupSnapshot.suggestion?.id || null,
+        projectName: setupSnapshot.suggestion?.name || null,
+        feedback: result.feedback,
+        response: result.response,
+        appliedChanges: result.appliedChanges,
+      },
+    });
+
+    Promise.resolve(
+      workflowContext.appendEvent?.({
+        actor: "user",
+        event_type: "dataset.setup_feedback",
+        stage: workflowContext.workflow?.stage || "setup",
+        summary: "Project setup feedback reviewed before confirmation.",
+        payload: {
+          source: "file_management_project_confirmation",
+          setup_source: setupSnapshot.source,
+          suggestion_id: setupSnapshot.suggestion?.id || null,
+          directory_path: setupSnapshot.suggestion?.directory_path || null,
+          feedback: result.feedback,
+          agent_response: result.response,
+          applied_changes: result.appliedChanges,
+          roles_after_feedback: result.nextRoles,
+        },
+      }),
+    ).finally(() => setProjectSetupFeedbackSaving(false));
+  };
+
+  const closeProjectSetupConfirmation = () => {
+    setPendingProjectSetup(null);
+    setRolePickerTarget(null);
+  };
+
+  const handleRolePickerSelect = (item) => {
+    if (!rolePickerTarget) return;
+    const rootPath = pendingProjectSetup?.suggestion?.directory_path || "";
+    setPendingRoleValue(
+      rolePickerTarget,
+      stripProjectRoot(rootPath, getSelectedFilePath(item)),
+    );
+    setRolePickerTarget(null);
+  };
+
+  const handleConfirmProjectSetup = async () => {
+    if (!pendingProjectSetup || projectSetupSaving) return;
+    const { suggestion, roles, source, projectDescription } =
+      pendingProjectSetup;
+    if (!String(roles.image || "").trim()) {
+      message.warning("Choose an image volume before starting the project.");
+      return;
+    }
+    if (!workflowContext?.updateWorkflow) {
+      message.warning("Workflow state is not ready yet.");
+      return;
+    }
+
+    const rootPath = suggestion?.directory_path || "";
+    const profile = suggestion?.profile || {};
+    const volumeSets = getProjectVolumeSetsFromSuggestion(suggestion);
+    const feedbackTurns = pendingProjectSetup.feedbackTurns || [];
+    const semanticFeedbackTurns =
+      pendingProjectSetup.semanticFeedbackTurns || [];
+    const projectDescriptionText = String(projectDescription || "").trim();
+    const existingMetadata = workflowContext.workflow?.metadata || {};
+    const projectContextMetadata = buildProjectContextMetadata(
+      projectDescriptionText,
+      existingMetadata,
+      {
+        useDefaults: pendingProjectSetup.useContextDefaults,
+        defaultContext: getPendingProjectContextDefaults(pendingProjectSetup),
+        projectContextDraft: pendingProjectSetup.projectContextDraft,
+      },
+    );
+    const contextAssessment = evaluateProjectContextCompleteness(
+      projectDescriptionText,
+      {
+        useDefaults: pendingProjectSetup.useContextDefaults,
+        defaultContext: getPendingProjectContextDefaults(pendingProjectSetup),
+      },
+    );
+    const projectBrief = buildProjectBrief({
+      context: projectContextMetadata,
+      roles,
+      suggestion,
+      volumeSets,
+    });
+    if (!contextAssessment.complete && !projectDescriptionText) {
+      setPendingProjectSetup((current) =>
+        current
+          ? {
+              ...current,
+              setupStep: "semantic",
+              lastSemanticResponse:
+                describeProjectContextAssessment(contextAssessment),
+            }
+          : current,
+      );
+      message.warning("Describe the project or use defaults.");
+      return;
+    }
+    const workflowPatch = buildWorkflowPatchFromConfirmedProjectRoles({
+      rootPath,
+      roles,
+      metadata: projectContextMetadata
+        ? {
+            ...existingMetadata,
+            project_context: projectContextMetadata,
+          }
+        : null,
+    });
+    const patch = workflowPatch;
+    if (!patch.image_path) {
+      message.warning("Choose an image volume before starting the project.");
+      return;
+    }
+
+    setProjectSetupSaving(true);
+    try {
+      await workflowContext.updateWorkflow(workflowPatch);
+      const projectMemoryProfile = buildProjectMemoryProfile({
+        suggestion,
+        roles,
+        workflowPatch,
+        projectDescription: projectDescriptionText,
+        projectContext: projectContextMetadata,
+        projectBrief,
+        projectAudit: pendingProjectSetup.projectAudit,
+        semanticTurns: semanticFeedbackTurns,
+        mappingTurns: feedbackTurns,
+        source,
+        existingProfile: pendingProjectSetup.storedProjectMemory,
+      });
+      try {
+        await apiClient.put("/files/project-context", {
+          directory_path: rootPath,
+          profile: projectMemoryProfile,
+        });
+      } catch (storageError) {
+        console.warn("Failed to persist project context profile", storageError);
+        logClientEvent("project_context_profile_write_failed", {
+          level: "WARN",
+          source: "files_manager",
+          message: "Project context profile could not be written",
+          data: {
+            suggestionId: suggestion?.id || null,
+            projectName: suggestion?.name || null,
+            directoryPath: rootPath,
+            error: storageError?.message || String(storageError),
+          },
+        });
+      }
+      await workflowContext.appendEvent?.({
+        actor: "user",
+        event_type: "dataset.loaded",
+        stage: workflowContext.workflow?.stage || "setup",
+        summary: `Confirmed project data for ${suggestion.name}.`,
+        payload: {
+          source: "file_management_project_confirmation",
+          setup_source: source,
+          suggestion_id: suggestion.id,
+          directory_path: rootPath,
+          mounted_root_id: suggestion.mounted_root_id || null,
+          profile_mode: suggestion.profile?.schema?.mode || null,
+          profile_schema_version:
+            suggestion.profile?.schema?.schema_version || null,
+          project_description: projectDescriptionText,
+          project_context: projectContextMetadata,
+          project_brief: projectBrief,
+          project_audit: pendingProjectSetup.projectAudit || null,
+          context_facts: pendingProjectSetup.projectAudit?.context_facts || [],
+          semantic_context_assessment: contextAssessment,
+          semantic_context_turns: semanticFeedbackTurns,
+          setup_feedback_turns: feedbackTurns,
+          detected_role_counts: profile.counts || {},
+          detected_role_directories:
+            profile.role_directories || profile.schema?.role_directories || {},
+          detected_volume_sets: volumeSets,
+          confirmed_roles: roles,
+          workflow_patch: workflowPatch,
+        },
+      });
+      await Promise.allSettled([
+        workflowContext.refreshPreflight?.(),
+        workflowContext.refreshAgentRecommendation?.(),
+      ]);
+      logClientEvent("project_role_confirmation_completed", {
+        source: "files_manager",
+        message: "Project roles confirmed and registered",
+        data: {
+          setupSource: source,
+          suggestionId: suggestion?.id || null,
+          projectName: suggestion?.name || null,
+          projectDescription: projectDescriptionText,
+          projectContext: projectContextMetadata,
+          projectBrief,
+          contextComplete: contextAssessment.complete,
+          workflowPatchKeys: Object.keys(workflowPatch),
+        },
+      });
+      message.success("Project data confirmed.");
+      closeProjectSetupConfirmation();
+    } catch (error) {
+      console.warn("Failed to register confirmed project roles", error);
+      logClientEvent("project_role_confirmation_failed", {
+        level: "ERROR",
+        source: "files_manager",
+        message: error.message || "Project role confirmation failed",
+        data: {
+          suggestionId: suggestion?.id || null,
+          projectName: suggestion?.name || null,
+        },
+      });
+      message.error("Failed to register project data.");
+    } finally {
+      setProjectSetupSaving(false);
+    }
+  };
+
+  const renderDetectedProjectStructure = () => {
+    if (!pendingProjectSetup) return null;
+    const suggestion = pendingProjectSetup.suggestion || {};
+    const profile = suggestion.profile || {};
+    const volumeSets = getProjectVolumeSetsFromSuggestion(suggestion);
+    const roleDirectories =
+      profile.role_directories || profile.schema?.role_directories || {};
+    const roleSummaries = ["image", "label", "prediction"]
+      .map((role) => {
+        const directory = roleDirectories[role]?.[0];
+        if (!directory) return null;
+        return {
+          role,
+          label:
+            role === "image"
+              ? "Images"
+              : role === "label"
+                ? "Labels"
+                : "Predictions",
+          ...directory,
+        };
+      })
+      .filter(Boolean);
+
+    const activeRoles = pendingProjectSetup.roles || {};
+    const chosenImage = activeRoles.image ? basename(activeRoles.image) : "";
+    const chosenLabel = activeRoles.label ? basename(activeRoles.label) : "";
+    let detectedSentence = "";
+
+    if (volumeSets.length > 0) {
+      const shownSets = volumeSets.slice(0, 3).map((set) => {
+        const setName = set.name || basename(set.image_root) || "batch";
+        const labelText = set.label_root
+          ? ` and ${pluralize(set.label_count || 0, "label")}`
+          : "";
+        const pairText = set.pair_count
+          ? `; ${pluralize(set.pair_count, "matched pair")}`
+          : "";
+        return `${setName} (${pluralize(set.image_count || 0, "image")}${labelText}${pairText})`;
+      });
+      detectedSentence = `I found ${pluralize(
+        volumeSets.length,
+        "candidate image set",
+      )}: ${shownSets.join(", ")}${
+        volumeSets.length > shownSets.length ? ", and more" : ""
+      }. I will start with ${
+        chosenImage || "the selected image data"
+      }${chosenLabel ? ` and ${chosenLabel}` : ""}. Is that correct?`;
+    } else if (roleSummaries.length > 0) {
+      const summaryText = roleSummaries
+        .map((item) => `${item.label.toLowerCase()} in ${basename(item.path)}`)
+        .join(", ");
+      detectedSentence = `I found ${summaryText}. I will use ${
+        chosenImage || "the selected image data"
+      }${chosenLabel ? ` with ${chosenLabel}` : ""}. Is that correct?`;
+    } else {
+      detectedSentence =
+        "I found a workable project, but I need you to confirm the image data before I use it. Is this mapping correct?";
+    }
+
+    return (
+      <div
+        style={{
+          marginBottom: 14,
+          padding: "12px",
+          borderRadius: 10,
+          border: "1px solid #ddd6fe",
+          background: "#fbfaff",
+        }}
+      >
+        <div style={{ fontWeight: 700, fontSize: 13, marginBottom: 4 }}>
+          What I found
+        </div>
+        <div style={{ fontSize: 13, color: "#4b5563", lineHeight: 1.45 }}>
+          {detectedSentence}
+        </div>
+      </div>
+    );
+  };
+
+  const renderProjectRoleFields = () => (
+    <div style={{ display: "grid", gap: 10 }}>
+      {PROJECT_CONFIRMATION_ROLES.map((role) => (
+        <div
+          key={role.key}
+          style={{
+            display: "grid",
+            gridTemplateColumns: "145px minmax(0, 1fr) auto auto",
+            gap: 8,
+            alignItems: "center",
+          }}
+        >
+          <div style={{ fontWeight: 700, fontSize: 13 }}>
+            {role.label}
+            {role.required ? (
+              <span style={{ color: "#d4380d" }}> *</span>
+            ) : null}
+            {role.provenanceOnly ? (
+              <span
+                style={{
+                  marginLeft: 6,
+                  color: "#8c8c8c",
+                  fontWeight: 500,
+                  fontSize: 11,
+                }}
+              >
+                optional
+              </span>
+            ) : null}
+          </div>
+          <Input
+            value={pendingProjectSetup.roles?.[role.key] || ""}
+            placeholder={role.placeholder}
+            onChange={(event) =>
+              setPendingRoleValue(role.key, event.target.value)
+            }
+          />
+          <Button
+            icon={<FolderOpenOutlined />}
+            onClick={() => setRolePickerTarget(role.key)}
+          >
+            Browse
+          </Button>
+          <Button
+            onClick={() => setPendingRoleValue(role.key, "")}
+            disabled={role.required && !pendingProjectSetup.roles?.[role.key]}
+          >
+            Clear
+          </Button>
+        </div>
+      ))}
+    </div>
+  );
+
+  const renderEditableProjectContextFields = (options = {}) => {
+    const {
+      title = "Editable project context",
+      description = "These are the concrete assumptions the agent absorbed. Edit or clear each one before starting.",
+      includeNotes = true,
+      marginBottom = 12,
+    } = options;
+    const draft = pendingProjectSetup.projectContextDraft || {};
+    return (
+      <div
+        style={{
+          padding: "10px 12px",
+          borderRadius: 10,
+          border: "1px solid #e5e7eb",
+          background: "#ffffff",
+          marginBottom,
+        }}
+      >
+        <div style={{ fontWeight: 700, fontSize: 13, marginBottom: 4 }}>
+          {title}
+        </div>
+        {description ? (
+          <div style={{ color: "#6b7280", fontSize: 12, marginBottom: 10 }}>
+            {description}
+          </div>
+        ) : null}
+        <div style={{ display: "grid", gap: 8 }}>
+          {EDITABLE_PROJECT_CONTEXT_FIELDS.map((field) => (
+            <div
+              key={field.key}
+              style={{
+                display: "grid",
+                gridTemplateColumns: "155px minmax(0, 1fr) auto",
+                gap: 8,
+                alignItems: "center",
+              }}
+            >
+              <div style={{ fontWeight: 700, fontSize: 13 }}>{field.label}</div>
+              <Input
+                value={
+                  field.key === "voxel_size_nm"
+                    ? formatEditableVoxelSize(draft[field.key])
+                    : draft[field.key] || ""
+                }
+                placeholder={field.placeholder}
+                onChange={(event) =>
+                  setPendingProjectContextValue(field.key, event.target.value)
+                }
+              />
+              <Button
+                onClick={() => setPendingProjectContextValue(field.key, "")}
+                disabled={!draft[field.key]}
+              >
+                Clear
+              </Button>
+            </div>
+          ))}
+          {includeNotes ? (
+            <div
+              style={{
+                display: "grid",
+                gridTemplateColumns: "155px minmax(0, 1fr)",
+                gap: 8,
+                alignItems: "start",
+              }}
+            >
+              <div style={{ fontWeight: 700, fontSize: 13 }}>Notes</div>
+              <Input.TextArea
+                rows={2}
+                value={draft.freeform_note || ""}
+                placeholder="Short project note for the agent memory."
+                onChange={(event) =>
+                  setPendingProjectContextValue(
+                    "freeform_note",
+                    event.target.value,
+                  )
+                }
+              />
+            </div>
+          ) : null}
+        </div>
+      </div>
+    );
+  };
+
+  const renderProjectAuditPanel = () => {
+    const audit = pendingProjectSetup?.projectAudit;
+    if (!audit) return null;
+    const summary = audit.summary || {};
+    const facts = (audit.context_facts || [])
+      .map((fact) => ({
+        ...fact,
+        displayValue: formatAuditFactValue(fact),
+      }))
+      .filter((fact) => fact.displayValue)
+      .slice(0, 4);
+    const findings = (audit.findings || []).slice(0, 5);
+    const checkedText = [
+      summary.audited_volumes
+        ? `${summary.audited_volumes} volume${summary.audited_volumes === 1 ? "" : "s"}`
+        : "",
+      summary.pair_checks
+        ? `${summary.pair_checks} image/mask pair${summary.pair_checks === 1 ? "" : "s"}`
+        : "",
+    ]
+      .filter(Boolean)
+      .join(" and ");
+
+    return (
+      <div
+        style={{
+          padding: "10px 12px",
+          borderRadius: 10,
+          border: "1px solid #bae6fd",
+          background: "#f0f9ff",
+          marginBottom: 12,
+        }}
+      >
+        <div style={{ fontWeight: 700, fontSize: 13, marginBottom: 4 }}>
+          What I checked automatically
+        </div>
+        <div style={{ color: "#374151", fontSize: 13, lineHeight: 1.45 }}>
+          {checkedText
+            ? `I inspected ${checkedText} directly from disk.`
+            : "I checked project files directly from disk."}{" "}
+          {summary.warnings || summary.errors
+            ? `${summary.warnings || 0} warning(s), ${summary.errors || 0} error(s).`
+            : "No blocking file issues were found in the sampled files."}
+        </div>
+        {facts.length > 0 && (
+          <div
+            style={{
+              display: "grid",
+              gridTemplateColumns: "repeat(auto-fit, minmax(160px, 1fr))",
+              gap: 8,
+              marginTop: 10,
+            }}
+          >
+            {facts.map((fact) => (
+              <div
+                key={`${fact.key}-${fact.source || fact.displayValue}`}
+                style={{
+                  background: "#fff",
+                  border: "1px solid #dbeafe",
+                  borderRadius: 8,
+                  padding: "7px 8px",
+                }}
+              >
+                <div
+                  style={{
+                    color: "#6b7280",
+                    fontSize: 11,
+                    textTransform: "uppercase",
+                    letterSpacing: 0,
+                  }}
+                >
+                  {fact.label || fact.key}
+                </div>
+                <div style={{ color: "#111827", fontSize: 13 }}>
+                  {fact.displayValue}
+                </div>
+                <div style={{ color: "#6b7280", fontSize: 11 }}>
+                  {compactProjectPath(compactAuditSource(fact.source)) ||
+                    fact.confidence ||
+                    "file metadata"}
+                </div>
+              </div>
+            ))}
+          </div>
+        )}
+        {findings.length > 0 && (
+          <div style={{ display: "grid", gap: 6, marginTop: 10 }}>
+            {findings.map((finding, index) => {
+              const tone =
+                auditFindingStyles[finding.level] || auditFindingStyles.info;
+              return (
+                <div
+                  key={`${finding.code || "finding"}-${finding.path || index}-${index}`}
+                  style={{
+                    display: "grid",
+                    gridTemplateColumns: "82px minmax(0, 1fr)",
+                    gap: 8,
+                    alignItems: "start",
+                    fontSize: 12,
+                    lineHeight: 1.4,
+                  }}
+                >
+                  <span
+                    style={{
+                      display: "inline-flex",
+                      justifyContent: "center",
+                      border: `1px solid ${tone.border}`,
+                      background: tone.background,
+                      color: tone.color,
+                      borderRadius: 999,
+                      padding: "1px 7px",
+                      fontWeight: 700,
+                      textTransform: "capitalize",
+                    }}
+                  >
+                    {finding.level || "info"}
+                  </span>
+                  <span style={{ color: "#374151" }}>
+                    {finding.message}
+                    {finding.path ? (
+                      <span style={{ color: "#6b7280" }}>
+                        {" "}
+                        {compactProjectPath(finding.path)}
+                      </span>
+                    ) : null}
+                  </span>
+                </div>
+              );
+            })}
+          </div>
+        )}
+      </div>
+    );
+  };
+
+  const renderProjectSharedFactsPanel = () => {
+    if (!pendingProjectSetup) return null;
+    const draft = pendingProjectSetup.projectContextDraft || {};
+    const volumeSplit =
+      draft.volume_split ||
+      getProjectVolumeSplitFromSuggestion(pendingProjectSetup.suggestion);
+    const factRows = [
+      {
+        key: "imaging_modality",
+        label: "Modality",
+        value: draft.imaging_modality || "Not set",
+      },
+      {
+        key: "target_structure",
+        label: "Target",
+        value: draft.target_structure || "Not set",
+      },
+      {
+        key: "voxel_size_nm",
+        label: "Voxel size",
+        value: formatEditableVoxelSize(draft.voxel_size_nm) || "Not set",
+      },
+      {
+        key: "volume_split",
+        label: "Volume split",
+        value: volumeSplit || "Not set",
+      },
+      {
+        key: "task_family",
+        label: "Task family",
+        value: draft.task_family || "Not set",
+      },
+      {
+        key: "training_policy",
+        label: "Training policy",
+        value: draft.training_policy || "Not set",
+      },
+    ];
+
+    return (
+      <div
+        style={{
+          padding: "10px 12px",
+          borderRadius: 10,
+          border: "1px solid #e5e7eb",
+          background: "#f8fafc",
+          marginBottom: 12,
+        }}
+      >
+        <div style={{ fontWeight: 700, fontSize: 13, marginBottom: 4 }}>
+          Shared project facts
+        </div>
+        <div style={{ color: "#6b7280", fontSize: 12, marginBottom: 10 }}>
+          These are the facts the agent will use to interpret this project. Edit
+          or confirm them in the controls below.
+        </div>
+        <div
+          style={{
+            display: "grid",
+            gridTemplateColumns: "repeat(auto-fit, minmax(120px, 1fr))",
+            gap: 8,
+          }}
+        >
+          {factRows.map((fact) => (
+            <div
+              key={fact.key}
+              style={{
+                border: "1px solid #eef2ff",
+                borderRadius: 8,
+                padding: "7px 8px",
+                background: "#fff",
+              }}
+            >
+              <div
+                style={{
+                  color: "#6b7280",
+                  fontSize: 11,
+                  textTransform: "uppercase",
+                  letterSpacing: "0.03em",
+                }}
+              >
+                {fact.label}
+              </div>
+              <div style={{ color: "#111827", fontSize: 13 }}>{fact.value}</div>
+            </div>
+          ))}
+        </div>
+      </div>
+    );
+  };
+
+  const renderDetectedDataSummary = () => {
+    const profile = pendingProjectSetup?.suggestion?.profile || {};
+    const counts = profile.counts || {};
+    const volumeSets = getProjectVolumeSetsFromSuggestion(
+      pendingProjectSetup?.suggestion,
+    );
+    const bestSet = volumeSets
+      .slice()
+      .sort((a, b) => Number(b.pair_count || 0) - Number(a.pair_count || 0))[0];
+    const items = [
+      ["Images", counts.image || counts.volume || 0],
+      ["Masks", counts.label || 0],
+      ["Predictions", counts.prediction || 0],
+      ["Configs", counts.config || 0],
+      ["Checkpoints", counts.checkpoint || 0],
+    ];
+    return (
+      <div
+        style={{
+          padding: "10px 12px",
+          borderRadius: 10,
+          border: "1px solid #e5e7eb",
+          background: "#ffffff",
+          marginBottom: 12,
+        }}
+      >
+        <div style={{ fontWeight: 700, fontSize: 13, marginBottom: 8 }}>
+          Detected data
+        </div>
+        <div
+          style={{
+            display: "grid",
+            gridTemplateColumns: "repeat(auto-fit, minmax(94px, 1fr))",
+            gap: 8,
+          }}
+        >
+          {items.map(([label, value]) => (
+            <div
+              key={label}
+              style={{
+                border: "1px solid #eef0f4",
+                borderRadius: 8,
+                padding: "7px 8px",
+                background: "#fafafa",
+              }}
+            >
+              <div style={{ color: "#6b7280", fontSize: 11 }}>{label}</div>
+              <div style={{ color: "#111827", fontWeight: 800, fontSize: 18 }}>
+                {value}
+              </div>
+            </div>
+          ))}
+        </div>
+        {bestSet ? (
+          <div style={{ color: "#6b7280", fontSize: 12, marginTop: 8 }}>
+            Best detected pairing: {bestSet.name || "image + mask"} with{" "}
+            {bestSet.pair_count || 0} pair
+            {Number(bestSet.pair_count || 0) === 1 ? "" : "s"}.
+          </div>
+        ) : null}
+      </div>
+    );
+  };
+
+  const renderGuidedContextConfirmations = () => {
+    const draft = pendingProjectSetup?.projectContextDraft || {};
+    return (
+      <div
+        style={{
+          padding: "10px 12px",
+          borderRadius: 10,
+          border: "1px solid #ddd6fe",
+          background: "#fbfaff",
+          marginBottom: 12,
+        }}
+      >
+        <div style={{ fontWeight: 700, fontSize: 13, marginBottom: 4 }}>
+          Workflow notes
+        </div>
+        <div style={{ color: "#6b7280", fontSize: 12, marginBottom: 10 }}>
+          I prefilled these from the mounted folder. Edit them in your own
+          words; they become durable agent context, not just UI labels.
+        </div>
+        <div style={{ display: "grid", gap: 12 }}>
+          {GUIDED_PROJECT_CONTEXT_GROUPS.map((group) => {
+            const selectedValue = String(draft[group.key] || "");
+            return (
+              <div key={group.key}>
+                <div
+                  style={{
+                    display: "flex",
+                    justifyContent: "space-between",
+                    gap: 8,
+                    alignItems: "baseline",
+                    marginBottom: 6,
+                  }}
+                >
+                  <span style={{ fontWeight: 700, fontSize: 13 }}>
+                    {group.label}
+                  </span>
+                  <span style={{ color: "#6b7280", fontSize: 11 }}>
+                    {group.helper}
+                  </span>
+                </div>
+                <div
+                  style={{
+                    display: "grid",
+                    gridTemplateColumns: "minmax(0, 1fr) auto",
+                    gap: 8,
+                    alignItems: "center",
+                  }}
+                >
+                  <Input
+                    value={selectedValue}
+                    placeholder={group.placeholder}
+                    onChange={(event) =>
+                      setPendingProjectContextValue(
+                        group.key,
+                        event.target.value,
+                      )
+                    }
+                  />
+                  <Button
+                    onClick={() => setPendingProjectContextValue(group.key, "")}
+                    disabled={!selectedValue}
+                  >
+                    Clear
+                  </Button>
+                </div>
+              </div>
+            );
+          })}
+        </div>
+      </div>
+    );
+  };
+
+  const renderProjectSetupSemanticStep = () => {
+    const draft = pendingProjectSetup.projectContextDraft || {};
+    const missingFields = editableProjectContextMissingFields(draft);
+    const missingText = missingFields.length
+      ? `Still needed: ${missingFields.join(", ")}.`
+      : "The basics are filled. You can continue or add an optional note.";
+    return (
+      <div>
+        <div style={{ marginBottom: 10, color: "#4b5563", fontSize: 13 }}>
+          I checked the folder first. Confirm what I found, then fill only the
+          basics I could not infer.
+        </div>
+        {renderDetectedDataSummary()}
+        {renderProjectAuditPanel()}
+        {renderProjectSharedFactsPanel()}
+        {renderGuidedContextConfirmations()}
+        {renderEditableProjectContextFields({
+          title: "Project basics",
+          description:
+            "These three fields give the agent enough context to choose sensible workflow defaults.",
+          includeNotes: false,
+        })}
+        {pendingProjectSetup.lastSemanticResponse && (
+          <div
+            style={{
+              padding: "8px 10px",
+              borderRadius: 8,
+              border: "1px solid #d9d6ff",
+              background: "#fff",
+              color: "#2b2f36",
+              fontSize: 13,
+              lineHeight: 1.45,
+              marginBottom: 8,
+            }}
+          >
+            {pendingProjectSetup.lastSemanticResponse}
+          </div>
+        )}
+        <div style={{ fontWeight: 700, fontSize: 13, marginBottom: 4 }}>
+          Anything else I should know?
+        </div>
+        <Input.TextArea
+          rows={3}
+          value={pendingProjectSetup.projectDescriptionDraft || ""}
+          placeholder={
+            pendingProjectSetup.lastSemanticResponse
+              ? "Add an answer here. Press Enter to continue; Shift+Enter for a new line."
+              : "Optional: tissue, species, acquisition quirks, what should count as good enough."
+          }
+          onChange={(event) => setPendingProjectDescription(event.target.value)}
+          onKeyDown={(event) => {
+            if (event.key === "Enter" && !event.shiftKey) {
+              event.preventDefault();
+              handleProjectContextContinue();
+            }
+          }}
+          style={{ marginBottom: 0 }}
+        />
+        <div style={{ color: "#6b7280", fontSize: 12, marginTop: 8 }}>
+          {missingText}
+        </div>
+      </div>
+    );
+  };
+
+  const renderProjectBriefCard = () => {
+    const projectContext = buildProjectContextMetadata(
+      pendingProjectSetup.projectDescription,
+      workflowContext.workflow?.metadata || {},
+      {
+        useDefaults: pendingProjectSetup.useContextDefaults,
+        defaultContext: getPendingProjectContextDefaults(pendingProjectSetup),
+        projectContextDraft: pendingProjectSetup.projectContextDraft,
+      },
+    );
+    const projectBrief = buildProjectBrief({
+      context: projectContext,
+      roles: pendingProjectSetup.roles,
+      suggestion: pendingProjectSetup.suggestion,
+      volumeSets: getProjectVolumeSetsFromSuggestion(
+        pendingProjectSetup.suggestion,
+      ),
+    });
+    return (
+      <div
+        style={{
+          padding: "10px 12px",
+          borderRadius: 10,
+          border: "1px solid #ddd6fe",
+          background: "#fbfaff",
+          marginBottom: 12,
+        }}
+      >
+        <div style={{ fontWeight: 700, fontSize: 13, marginBottom: 4 }}>
+          Project brief
+        </div>
+        <div style={{ color: "#111827", fontSize: 14, lineHeight: 1.45 }}>
+          {projectBrief.summary}
+        </div>
+        {projectBrief.fields.length > 0 && (
+          <div
+            style={{
+              display: "grid",
+              gridTemplateColumns: "repeat(auto-fit, minmax(120px, 1fr))",
+              gap: 8,
+              marginTop: 10,
+            }}
+          >
+            {projectBrief.fields.map((field) => (
+              <div
+                key={field.key}
+                style={{
+                  background: "#fff",
+                  border: "1px solid #ecebff",
+                  borderRadius: 8,
+                  padding: "7px 8px",
+                }}
+              >
+                <div
+                  style={{
+                    color: "#6b7280",
+                    fontSize: 11,
+                    textTransform: "uppercase",
+                    letterSpacing: "0.03em",
+                  }}
+                >
+                  {field.label}
+                </div>
+                <div style={{ color: "#111827", fontSize: 13 }}>
+                  {String(field.value)}
+                </div>
+              </div>
+            ))}
+          </div>
+        )}
+        {projectBrief.next_moves.length > 0 && (
+          <div style={{ marginTop: 12 }}>
+            <div
+              style={{
+                color: "#6b7280",
+                fontSize: 11,
+                textTransform: "uppercase",
+                letterSpacing: "0.03em",
+                marginBottom: 5,
+              }}
+            >
+              How the agent will use this
+            </div>
+            <ul
+              style={{
+                margin: 0,
+                paddingLeft: 18,
+                color: "#374151",
+                fontSize: 13,
+                lineHeight: 1.5,
+              }}
+            >
+              {projectBrief.next_moves.slice(0, 6).map((move) => (
+                <li key={move}>{move}</li>
+              ))}
+            </ul>
+          </div>
+        )}
+        {projectBrief.uncertainties.length > 0 && (
+          <div
+            style={{
+              marginTop: 10,
+              padding: "8px 10px",
+              borderRadius: 8,
+              background: "#fff7ed",
+              color: "#7c2d12",
+              fontSize: 12,
+              lineHeight: 1.45,
+            }}
+          >
+            {projectBrief.uncertainties[0]}
+          </div>
+        )}
+      </div>
+    );
+  };
+
+  const renderProjectSetupMappingStep = () => (
+    <div>
+      <div style={{ marginBottom: 10, color: "#4b5563", fontSize: 13 }}>
+        Confirm the project context and file mapping before starting.
+      </div>
+      {renderDetectedProjectStructure()}
+      {renderDetectedDataSummary()}
+      {renderProjectAuditPanel()}
+      {renderProjectSharedFactsPanel()}
+      {renderGuidedContextConfirmations()}
+      {renderEditableProjectContextFields()}
+      {renderProjectBriefCard()}
+      <div style={{ fontWeight: 700, fontSize: 13, marginBottom: 4 }}>
+        Correct my file mapping
+      </div>
+      <Input.TextArea
+        rows={3}
+        value={pendingProjectSetup.mappingFeedback || ""}
+        placeholder="Example correction: use the val split, not train; labels are in data/seg; predictions are in outputs/baseline."
+        onChange={(event) => setPendingMappingFeedback(event.target.value)}
+        onKeyDown={(event) => {
+          if (event.key === "Enter" && !event.shiftKey) {
+            event.preventDefault();
+            handleProjectSetupFeedbackSubmit();
+          }
+        }}
+        style={{ marginBottom: 8 }}
+      />
+      <div
+        style={{
+          display: "flex",
+          alignItems: "center",
+          justifyContent: "space-between",
+          gap: 12,
+          marginBottom: pendingProjectSetup.lastFeedbackResponse ? 8 : 12,
+        }}
+      >
+        <span style={{ color: "#8c8c8c", fontSize: 12 }}>
+          Press Enter to ask/apply a mapping correction. Shift+Enter adds a
+          line.
+        </span>
+        <Button
+          size="small"
+          onClick={handleProjectSetupFeedbackSubmit}
+          loading={projectSetupFeedbackSaving}
+          disabled={!String(pendingProjectSetup.mappingFeedback || "").trim()}
+        >
+          Ask/apply
+        </Button>
+      </div>
+      {pendingProjectSetup.lastFeedbackResponse && (
+        <div
+          style={{
+            marginBottom: 12,
+            padding: "8px 10px",
+            borderRadius: 8,
+            background: "#f6f6ff",
+            border: "1px solid #ddd6fe",
+            color: "#4b5563",
+            fontSize: 13,
+            lineHeight: 1.45,
+          }}
+        >
+          {pendingProjectSetup.lastFeedbackResponse}
+        </div>
+      )}
+      {renderProjectRoleFields()}
+    </div>
+  );
+
+  const renderProjectSetupBody = () => {
+    if (!pendingProjectSetup) return null;
+    if (pendingProjectSetup.setupStep === "mapping") {
+      return renderProjectSetupMappingStep();
+    }
+    return renderProjectSetupSemanticStep();
+  };
+
+  const renderProjectSetupFooter = () => {
+    if (!pendingProjectSetup) return null;
+    const step = pendingProjectSetup.setupStep || "semantic";
+    const footer = [
+      <Button
+        key="cancel"
+        onClick={closeProjectSetupConfirmation}
+        disabled={projectSetupSaving}
+      >
+        Cancel
+      </Button>,
+    ];
+    if (step !== "semantic") {
+      footer.push(
+        <Button
+          key="back"
+          onClick={() => setPendingSetupStep("semantic")}
+          disabled={projectSetupSaving}
+        >
+          Back
+        </Button>,
+      );
+    }
+    if (step === "semantic") {
+      const hasDraft = Boolean(
+        String(pendingProjectSetup.projectDescriptionDraft || "").trim(),
+      );
+      const hasReviewableContext = Boolean(
+        String(pendingProjectSetup.projectDescription || "").trim() &&
+        !pendingProjectSetup.lastSemanticResponse,
+      );
+      const hasCompleteDraft =
+        editableProjectContextMissingFields(
+          pendingProjectSetup.projectContextDraft || {},
+        ).length === 0;
+      footer.push(
+        <Button
+          key="defaults"
+          onClick={() => handleProjectContextContinue({ useDefaults: true })}
+          disabled={projectSetupSaving}
+        >
+          {hasCompleteDraft ? "Use detected context" : "Use safe defaults"}
+        </Button>,
+        <Button
+          key="continue"
+          type="primary"
+          onClick={() => handleProjectContextContinue()}
+          disabled={
+            projectSetupSaving ||
+            (!hasDraft && !hasReviewableContext && !hasCompleteDraft)
+          }
+        >
+          Continue
+        </Button>,
+      );
+      return footer;
+    }
+    if (step === "mapping") {
+      footer.push(
+        <Button
+          key="start"
+          type="primary"
+          onClick={handleConfirmProjectSetup}
+          loading={projectSetupSaving}
+          disabled={!pendingProjectSetup?.roles?.image || projectSetupSaving}
+        >
+          Start project
+        </Button>,
+      );
+      return footer;
+    }
+    footer.push(
+      <Button
+        key="start"
+        type="primary"
+        onClick={handleConfirmProjectSetup}
+        loading={projectSetupSaving}
+        disabled={!pendingProjectSetup?.roles?.image}
+      >
+        Start project
+      </Button>,
+    );
+    return footer;
+  };
+
+  const renderProjectInitializationEmptyState = () => {
+    if (currentFolder !== "root") return null;
+    if (currentFolders.length > 0 || currentFiles.length > 0 || newItemType) {
+      return null;
+    }
+    return (
+      <div
+        style={{
+          width: "100%",
+          minHeight: "70%",
+          display: "flex",
+          alignItems: "center",
+          justifyContent: "center",
+          pointerEvents: "auto",
+        }}
+      >
+        <div
+          style={{
+            width: "min(620px, 92%)",
+            padding: "28px",
+            borderRadius: 18,
+            background: "#fff",
+            boxShadow: "0 18px 48px rgba(17,24,39,0.08)",
+            border: "1px solid #e5e7eb",
+          }}
+        >
+          <div
+            style={{
+              fontSize: 24,
+              fontWeight: 800,
+              marginBottom: 8,
+              color: "#111827",
+            }}
+          >
+            Start a segmentation project
+          </div>
+          <div
+            style={{
+              color: "#6b7280",
+              fontSize: 14,
+              lineHeight: 1.5,
+              marginBottom: 20,
+            }}
+          >
+            Choose a project directory. I’ll ask what the dataset is, inspect
+            the folder, then ask you to confirm the image and mask mapping
+            before anything enters workflow state.
+          </div>
+          <div style={{ display: "flex", gap: 10, flexWrap: "wrap" }}>
+            <Button
+              type="primary"
+              icon={<FolderOpenOutlined />}
+              onClick={handleMountProjectDirectory}
+            >
+              Choose project directory
+            </Button>
+            <Button
+              onClick={handleSuggestedProject}
+              disabled={projectSuggestions.length === 0}
+            >
+              Use suggested project
+            </Button>
+          </div>
+        </div>
+      </div>
+    );
+  };
+
+  const getContextMenuItems = () => {
+    if (contextMenu?.type === "container") {
+      return [
+        { key: "new_folder", label: "Create Folder", icon: <FolderFilled /> },
+        { key: "upload", label: "Upload File...", icon: <UploadOutlined /> },
+        {
+          key: "mount_project",
+          label: "Mount Project Directory...",
+          icon: <FolderOpenOutlined />,
+        },
+      ];
+    }
+    const items = [];
+    const selectedKey = selectedItems.length === 1 ? selectedItems[0] : null;
+    const selectedFolder = selectedKey
+      ? folders.find((f) => f.key === selectedKey)
+      : null;
+    const isMountedProjectFolder = Boolean(
+      selectedFolder &&
+      selectedFolder.parent === "root" &&
+      selectedFolder.physical_path,
+    );
+    // Only show preview for files, not folders
+    if (selectedItems.length === 1) {
+      const isFolder = folders.some((f) => f.key === selectedKey);
+      if (!isFolder) {
+        items.push({ key: "preview", label: "Preview", icon: <EyeOutlined /> });
+      }
+    }
+    if (isMountedProjectFolder) {
+      items.push({
+        key: "unmount_project",
+        label: "Unmount Project",
+        danger: true,
+        icon: <FolderOpenOutlined />,
+      });
+    }
+    if (selectedItems.length === 1) {
+      const selectedFile = Object.values(files)
+        .flat()
+        .find((f) => f.key === selectedKey);
+      const selectedFolder = folders.find((f) => f.key === selectedKey);
+      const hasPhysicalPath =
+        (selectedFile &&
+          selectedFile.physical_path &&
+          selectedFile.physical_path.startsWith("/")) ||
+        (selectedFolder &&
+          selectedFolder.physical_path &&
+          selectedFolder.physical_path.startsWith("/"));
+      if (hasPhysicalPath) {
+        items.push({
+          key: "reveal_in_finder",
+          label: "Open in Finder",
+          icon: <FolderOpenOutlined />,
+        });
+      }
+    }
+    items.push(
+      {
+        key: "rename",
+        label: "Rename",
+        icon: <FileTextOutlined />,
+        disabled: selectedItems.length > 1,
+      },
+      {
+        key: "copy",
+        label: `Copy${selectedItems.length > 1 ? ` (${selectedItems.length})` : ""}`,
+        icon: <FileOutlined />,
+      },
+      {
+        key: "delete",
+        label: `Delete${selectedItems.length > 1 ? ` (${selectedItems.length})` : ""}`,
+        danger: true,
+        icon: <FileOutlined />,
+      },
+      { type: "divider" },
+      { key: "properties", label: "Properties", icon: <FileTextOutlined /> },
+    );
+    return items;
+  };
+
+  const handleUploadClick = () => {
     const input = document.createElement("input");
     input.type = "file";
     input.multiple = true;
@@ -1416,37 +3709,228 @@ function FilesManager() {
     input.click();
   };
 
+  const mountProjectPath = async (directoryPath, source = "manual_mount") => {
+    const mountPath = String(directoryPath || "").trim();
+    if (!mountPath) return;
+
+    const res = await apiClient.post(
+      "/files/mount",
+      {
+        directory_path: mountPath,
+        destination_path: "root",
+      },
+      { withCredentials: true },
+    );
+
+    await fetchFolderContents("root", { force: true });
+    await loadProjectSuggestions();
+    if (res?.data?.mounted_root_id) {
+      const mountedRootId = String(res.data.mounted_root_id);
+      await fetchFolderContents(mountedRootId, { force: true });
+      handleNavigate(mountedRootId);
+    }
+    await openProjectSetupConfirmation(
+      {
+        id: res?.data?.mounted_root_id
+          ? `mounted-${res.data.mounted_root_id}`
+          : "mounted-project",
+        name:
+          res?.data?.mount_name ||
+          mountPath.split(/[\\/]/).filter(Boolean).pop() ||
+          "Mounted project",
+        directory_path: res?.data?.directory_path || mountPath,
+        already_mounted: true,
+        mounted_root_id: res?.data?.mounted_root_id || null,
+        profile: res?.data?.profile || {},
+      },
+      source,
+    );
+    message.success(res?.data?.message || "Project mounted.");
+  };
+
   const handleMountProjectDirectory = async () => {
     try {
+      if (!canOpenLocalFile()) {
+        await mountProjectPath(
+          DEFAULT_REMOTE_PROJECT_PATH,
+          "remote_default_mount",
+        );
+        return;
+      }
       const selectedDirectory = await openLocalFile({
         properties: ["openDirectory"],
       });
       if (!selectedDirectory) return;
 
-      // Mount builds a stable project index now; later this same flow can point to
-      // cloud-backed project storage while keeping picker + workflow behavior unchanged.
+      await mountProjectPath(selectedDirectory, "manual_mount");
+    } catch (err) {
+      console.error("Mount directory error", err);
+      if (err?.message !== "Project path required") {
+        message.error("Failed to mount project");
+      }
+    }
+  };
+
+  const handleSuggestedProject = async (preferredSuggestion = null) => {
+    const explicitSuggestion =
+      preferredSuggestion &&
+      typeof preferredSuggestion === "object" &&
+      preferredSuggestion.directory_path
+        ? preferredSuggestion
+        : null;
+    const suggestion =
+      explicitSuggestion ||
+      projectSuggestions.find((item) => item.recommended) ||
+      projectSuggestions[0];
+    if (!suggestion) {
+      message.info("No suggested local project is available.");
+      return;
+    }
+    if (suggestion.already_mounted && suggestion.mounted_root_id) {
+      const mountedRootId = String(suggestion.mounted_root_id);
+      await fetchFolderContents(mountedRootId, { force: true });
+      handleNavigate(mountedRootId);
+      await openProjectSetupConfirmation(suggestion, "suggested_existing");
+      message.success(`${suggestion.name} is already mounted.`);
+      return;
+    }
+    try {
       const res = await apiClient.post(
         "/files/mount",
         {
-          directory_path: selectedDirectory,
+          directory_path: suggestion.directory_path,
           destination_path: "root",
+          mount_name: suggestion.name,
         },
         { withCredentials: true },
       );
-
       await fetchFolderContents("root", { force: true });
+      await loadProjectSuggestions();
       if (res?.data?.mounted_root_id) {
         const mountedRootId = String(res.data.mounted_root_id);
         await fetchFolderContents(mountedRootId, { force: true });
         handleNavigate(mountedRootId);
       }
-      message.success(res?.data?.message || "Project directory mounted.");
-    } catch (err) {
-      console.error("Mount directory error", err);
-      message.error("Failed to mount project directory");
+      await openProjectSetupConfirmation(
+        {
+          ...suggestion,
+          already_mounted: true,
+          mounted_root_id:
+            res?.data?.mounted_root_id || suggestion.mounted_root_id,
+          profile: res?.data?.profile || suggestion.profile || {},
+        },
+        "suggested_mount",
+      );
+      message.success(res?.data?.message || `${suggestion.name} mounted.`);
+    } catch (error) {
+      console.error("Suggested project mount error", error);
+      message.error(`Failed to mount ${suggestion.name}`);
+    }
+  };
+
+  chooseProjectDataRef.current = async (source = "assistant_choose_data") => {
+    const suggestions = await loadProjectSuggestions();
+    const suggestion =
+      suggestions.find((item) => item.recommended && item.already_mounted) ||
+      suggestions.find((item) => item.already_mounted) ||
+      suggestions.find((item) => item.recommended) ||
+      suggestions[0];
+
+    if (suggestion) {
+      await handleSuggestedProject(suggestion);
+      return;
+    }
+
+    await fetchFolderContents("root", { force: true });
+    const mountedRoot = foldersRef.current.find(
+      (folder) => folder.parent === "root" && folder.physical_path,
+    );
+    if (mountedRoot) {
+      await fetchFolderContents(mountedRoot.key, { force: true });
+      handleNavigate(mountedRoot.key);
+      await openProjectSetupConfirmation(
+        {
+          id: `mounted-${mountedRoot.key}`,
+          name: mountedRoot.title,
+          directory_path: mountedRoot.physical_path,
+          already_mounted: true,
+          mounted_root_id: Number(mountedRoot.key),
+          profile: {},
+        },
+        source,
+      );
+      return;
     }
+
+    message.info("Mount a project directory first.");
   };
 
+  const pendingRuntimeAction = workflowContext?.pendingRuntimeAction;
+  const consumeRuntimeAction = workflowContext?.consumeRuntimeAction;
+
+  useEffect(() => {
+    const action = pendingRuntimeAction;
+    if (!action || action.kind !== "choose_project_data") return;
+    if (handledChooseDataActionRef.current === action.id) return;
+    handledChooseDataActionRef.current = action.id;
+
+    const run = async () => {
+      logClientEvent("files_choose_project_data_started", {
+        source: "files_manager",
+        message: "Assistant requested project data selection.",
+        data: { actionId: action.id || null },
+      });
+      try {
+        await chooseProjectDataRef.current?.("assistant_choose_data");
+        logClientEvent("files_choose_project_data_completed", {
+          source: "files_manager",
+          message: "Assistant project data selection action was opened.",
+          data: { actionId: action.id || null },
+        });
+        consumeRuntimeAction?.(action.id);
+      } catch (error) {
+        logClientEvent("files_choose_project_data_failed", {
+          level: "ERROR",
+          source: "files_manager",
+          message: error?.message || "Could not open project data selection.",
+          data: { actionId: action.id || null },
+        });
+        message.error("Could not open project data selection.");
+        consumeRuntimeAction?.(action.id);
+      }
+    };
+
+    run();
+  }, [consumeRuntimeAction, pendingRuntimeAction]);
+
+  useEffect(() => {
+    const workflowMetadata = workflowContext.workflow?.metadata || {};
+    const hasProjectContext = Boolean(workflowMetadata.project_context);
+    const shouldCollectProjectContext =
+      workflowMetadata.needs_project_context || !hasProjectContext;
+    const suggestedProject =
+      projectSuggestions.find((item) => item.recommended) ||
+      projectSuggestions[0];
+    if (
+      autoProjectSetupOpenedRef.current ||
+      pendingProjectSetup ||
+      !shouldCollectProjectContext ||
+      !suggestedProject ||
+      !suggestedProject.already_mounted
+    ) {
+      return;
+    }
+    autoProjectSetupOpenedRef.current = true;
+    handleSuggestedProject();
+    // This should run once after the fixed demo project is mounted and the
+    // workflow has no project context yet.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [
+    pendingProjectSetup,
+    projectSuggestions,
+    workflowContext.workflow?.metadata,
+  ]);
+
   const handleResetWorkspace = () => {
     Modal.confirm({
       title: "Reset workspace?",
@@ -1766,6 +4250,19 @@ function FilesManager() {
           >
             Mount Project
           </Button>
+          <Button
+            onClick={handleSuggestedProject}
+            disabled={projectSuggestions.length === 0}
+            title={
+              projectSuggestions.length
+                ? projectSuggestions[0].description
+                : "No suggested local projects found"
+            }
+          >
+            {projectSuggestions.some((item) => item.already_mounted)
+              ? "Open suggested project"
+              : "Use suggested project"}
+          </Button>
           <Dropdown
             menu={{
               items: workspaceMenuItems,
@@ -1780,7 +4277,6 @@ function FilesManager() {
             <Button icon={<MoreOutlined />} title="More file actions" />
           </Dropdown>
         </div>
-
         {/* Content Area */}
         <div
           ref={containerRef}
@@ -1813,16 +4309,19 @@ function FilesManager() {
               <Spin size="large" />
             </div>
           )}
+          {!loadingParents.includes(currentFolder) &&
+            renderProjectInitializationEmptyState()}
           {!loadingParents.includes(currentFolder) &&
             currentFolders.length === 0 &&
             currentFiles.length === 0 &&
+            currentFolder !== "root" &&
             !newItemType && (
-            <div
-              style={{ width: "100%", marginTop: 64, pointerEvents: "none" }}
-            >
-              <Empty description="Empty Folder" />
-            </div>
-          )}
+              <div
+                style={{ width: "100%", marginTop: 64, pointerEvents: "none" }}
+              >
+                <Empty description="Empty Folder" />
+              </div>
+            )}
           {currentFolders.map((f) => renderItem(f, "folder"))}
           {renderNewFolderPlaceholder()}
           {currentFiles.map((f) => renderItem(f, "file"))}
@@ -1834,8 +4333,9 @@ function FilesManager() {
                 top: Math.min(selectionBox.startY, selectionBox.currentY),
                 width: Math.abs(selectionBox.currentX - selectionBox.startX),
                 height: Math.abs(selectionBox.currentY - selectionBox.startY),
-                backgroundColor: "rgba(24, 144, 255, 0.2)",
-                border: "1px solid #1890ff",
+                backgroundColor:
+                  "var(--seg-selection-fill, rgba(63, 55, 201, 0.12))",
+                border: "1px solid var(--seg-accent-primary, #3f37c9)",
                 pointerEvents: "none",
                 zIndex: 100,
               }}
@@ -1901,6 +4401,35 @@ function FilesManager() {
           </div>
         )}
 
+        {/* Project role confirmation */}
+        <Modal
+          title={
+            pendingProjectSetup?.setupStep === "mapping"
+              ? "Start project"
+              : pendingProjectSetup?.setupStep === "confirm"
+                ? "Start project"
+                : "Confirm project basics"
+          }
+          open={!!pendingProjectSetup}
+          onCancel={closeProjectSetupConfirmation}
+          width={780}
+          footer={renderProjectSetupFooter()}
+        >
+          {renderProjectSetupBody()}
+        </Modal>
+
+        <FilePickerModal
+          visible={!!rolePickerTarget}
+          onCancel={() => setRolePickerTarget(null)}
+          onSelect={handleRolePickerSelect}
+          title={`Select ${
+            PROJECT_CONFIRMATION_ROLES.find(
+              (role) => role.key === rolePickerTarget,
+            )?.label || "project file"
+          }`}
+          selectionType="fileOrDirectory"
+        />
+
         {/* Preview Modal */}
         <Modal
           title={previewFile?.name}
@@ -1971,7 +4500,12 @@ function FilesManager() {
                 }}
               >
                 {propertiesData.isFolder ? (
-                  <FolderFilled style={{ fontSize: 48, color: "#1890ff" }} />
+                  <FolderFilled
+                    style={{
+                      fontSize: 48,
+                      color: "var(--seg-accent-primary, #3f37c9)",
+                    }}
+                  />
                 ) : (
                   <FileOutlined style={{ fontSize: 48, color: "#555" }} />
                 )}
diff --git a/client/src/views/FilesManager.test.js b/client/src/views/FilesManager.test.js
index d52f54e3..457b5ae7 100644
--- a/client/src/views/FilesManager.test.js
+++ b/client/src/views/FilesManager.test.js
@@ -1,9 +1,10 @@
 import React from "react";
-import { render, waitFor } from "@testing-library/react";
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
 
 import FilesManager from "./FilesManager";
 import { AppContext } from "../contexts/GlobalContext";
 import { apiClient } from "../api";
+import { openLocalFile } from "../electronApi";
 
 jest.mock("../api", () => ({
   apiClient: {
@@ -16,11 +17,51 @@ jest.mock("../api", () => ({
 }));
 
 jest.mock("../electronApi", () => ({
+  canOpenLocalFile: jest.fn(() => true),
   openLocalFile: jest.fn(),
   revealInFinder: jest.fn(),
 }));
 
 jest.mock("../components/FileTreeSidebar", () => () => null);
+jest.mock(
+  "../components/FilePickerModal",
+  () =>
+    ({ visible, onSelect, title }) =>
+      visible ? (
+        <div>
+          <div>{title}</div>
+          <button
+            type="button"
+            onClick={() =>
+              onSelect({
+                name: "override-prediction.tif",
+                physical_path: "/tmp/override/override-prediction.tif",
+              })
+            }
+          >
+            Choose mocked file
+          </button>
+        </div>
+      ) : null,
+);
+
+jest.mock("../logging/appEventLog", () => ({
+  logClientEvent: jest.fn(),
+}));
+
+const mockWorkflowContext = {
+  workflow: { id: 1, stage: "setup" },
+  updateWorkflow: jest.fn(),
+  appendEvent: jest.fn(),
+  refreshPreflight: jest.fn(),
+  refreshAgentRecommendation: jest.fn(),
+  pendingRuntimeAction: null,
+  consumeRuntimeAction: jest.fn(),
+};
+
+jest.mock("../contexts/WorkflowContext", () => ({
+  useWorkflow: () => mockWorkflowContext,
+}));
 
 jest.mock("@ant-design/icons", () => {
   const Icon = () => <span />;
@@ -43,9 +84,19 @@ jest.mock("@ant-design/icons", () => {
 jest.mock("antd", () => {
   const React = require("react");
 
-  const Button = ({ children, ...props }) => <button {...props}>{children}</button>;
+  const Button = ({ children, icon, loading, type, ...props }) => (
+    <button type="button" {...props}>
+      {icon}
+      {children}
+    </button>
+  );
   const Dropdown = ({ children }) => <div>{children}</div>;
-  const Input = React.forwardRef((props, ref) => <input ref={ref} {...props} />);
+  const Input = React.forwardRef((props, ref) => (
+    <input ref={ref} {...props} />
+  ));
+  Input.TextArea = React.forwardRef((props, ref) => (
+    <textarea ref={ref} {...props} />
+  ));
   const Menu = ({ items = [], onClick }) => (
     <div>
       {items.map((item) =>
@@ -67,7 +118,14 @@ jest.mock("antd", () => {
       {children}
     </button>
   );
-  const Modal = ({ children, open }) => (open ? <div>{children}</div> : null);
+  const Modal = ({ children, open, title, footer }) =>
+    open ? (
+      <div role="dialog">
+        {title ? <div>{title}</div> : null}
+        {children}
+        {footer ? <div>{footer}</div> : null}
+      </div>
+    ) : null;
   Modal.confirm = jest.fn();
 
   return {
@@ -89,15 +147,330 @@ jest.mock("antd", () => {
   };
 });
 
+const smokeSuggestion = {
+  id: "mito25-paper-loop-smoke",
+  name: "mito25-paper-loop-smoke",
+  directory_path: "/tmp/mito25_paper_loop_smoke",
+  description: "Curated smoke project",
+  recommended: true,
+  already_mounted: false,
+  profile: {
+    ready_for_smoke: true,
+    counts: {
+      image: 1,
+      label: 1,
+      prediction: 2,
+      config: 1,
+      checkpoint: 1,
+    },
+    schema: {
+      schema_version: "pytc-project-profile/v1",
+      mode: "closed_loop_ready",
+      stages: {
+        visualization: true,
+        proofreading: true,
+        training: true,
+        evaluation: true,
+      },
+      primary_paths: {
+        image: "data/image/mito25_smoke_im.h5",
+        label: "data/seg/mito25_smoke_seg.h5",
+        prediction: "predictions/baseline.tif",
+        checkpoint: "checkpoints/checkpoint_00200.pth.tar",
+        config: "configs/MitoEM.yaml",
+      },
+    },
+    role_directories: {
+      image: [{ path: "data/image", count: 1 }],
+      label: [{ path: "data/seg", count: 1 }],
+      prediction: [{ path: "predictions", count: 2 }],
+    },
+    volume_sets: [
+      {
+        id: "set-1",
+        name: "image + seg",
+        image_root: "data/image",
+        label_root: "data/seg",
+        image_count: 1,
+        label_count: 1,
+        pair_count: 1,
+      },
+    ],
+    paired_examples: [
+      {
+        image: "data/image/mito25_smoke_im.h5",
+        label: "data/seg/mito25_smoke_seg.h5",
+      },
+    ],
+    audit: {
+      schema_version: "pytc-project-audit/v1",
+      summary: {
+        audited_volumes: 2,
+        readable_volumes: 2,
+        pair_checks: 1,
+        shape_match_count: 1,
+        shape_mismatch_count: 0,
+        warnings: 0,
+        errors: 0,
+      },
+      context_facts: [
+        {
+          key: "voxel_size_nm",
+          label: "Voxel size",
+          value: [30, 6, 6],
+          source: "volume_metadata:data/image/mito25_smoke_im.h5",
+          confidence: "high",
+        },
+      ],
+      findings: [
+        {
+          level: "info",
+          code: "pair_shape_match",
+          message: "Image and mask shapes match.",
+          path: "data/image/mito25_smoke_im.h5",
+          related_path: "data/seg/mito25_smoke_seg.h5",
+          source: "volume_metadata",
+        },
+      ],
+    },
+    examples: {
+      image: ["data/image/mito25_smoke_im.h5"],
+      label: ["data/seg/mito25_smoke_seg.h5"],
+      prediction: ["predictions/baseline.tif"],
+      checkpoint: ["checkpoints/checkpoint_00200.pth.tar"],
+      config: ["configs/MitoEM.yaml"],
+    },
+    missing_roles: [],
+  },
+};
+
+const completeSmokeSuggestion = {
+  ...smokeSuggestion,
+  profile: {
+    ...smokeSuggestion.profile,
+    context_hints: {
+      imaging_modality: "EM",
+      target_structure: "mitochondria",
+      voxel_size_nm: [30, 6, 6],
+      voxel_size_source: "volume_metadata:data/image/mito25_smoke_im.h5",
+    },
+    schema: {
+      ...smokeSuggestion.profile.schema,
+      context_hints: {
+        imaging_modality: "EM",
+        target_structure: "mitochondria",
+        voxel_size_nm: [30, 6, 6],
+        voxel_size_source: "volume_metadata:data/image/mito25_smoke_im.h5",
+      },
+    },
+  },
+};
+
+const yixiaoLikeSmokeSuggestion = {
+  ...completeSmokeSuggestion,
+  name: "Yixiao TapeReader XRI Case Study",
+  profile: {
+    ...completeSmokeSuggestion.profile,
+    context_hints: {
+      ...completeSmokeSuggestion.profile.context_hints,
+      task_family: "XRI fibre instance segmentation",
+      training_policy: "train only on confirmed ground-truth masks",
+      mask_status:
+        "mixed: 6 ground-truth masks, 2 draft masks, 2 image-only targets",
+    },
+    schema: {
+      ...completeSmokeSuggestion.profile.schema,
+      context_hints: {
+        ...(completeSmokeSuggestion.profile.schema &&
+        completeSmokeSuggestion.profile.schema.context_hints
+          ? completeSmokeSuggestion.profile.schema.context_hints
+          : {}),
+        task_family: "XRI fibre instance segmentation",
+        training_policy: "train only on confirmed ground-truth masks",
+        mask_status:
+          "mixed: 6 ground-truth masks, 2 draft masks, 2 image-only targets",
+      },
+      manifest: {
+        initial_progress_summary: {
+          ground_truth: 6,
+          needs_proofreading: 2,
+          missing_segmentation: 2,
+        },
+      },
+    },
+  },
+};
+
+const imageOnlySuggestion = {
+  id: "image-only-project",
+  name: "image-only-project",
+  directory_path: "/tmp/image_only_project",
+  description: "Detected image volume",
+  recommended: true,
+  already_mounted: false,
+  profile: {
+    counts: { image: 1 },
+    schema: {
+      workable: true,
+      mode: "image_only",
+      stages: { visualization: true, proofreading: false },
+      primary_paths: { image: "volume/raw_image.tif" },
+    },
+    examples: { image: ["volume/raw_image.tif"] },
+    missing_roles: ["label"],
+  },
+};
+
+const neutralSuggestion = {
+  id: "neutral-project",
+  name: "neutral-project",
+  directory_path: "/tmp/neutral_project",
+  description: "Generic image/mask project",
+  recommended: true,
+  already_mounted: false,
+  profile: {
+    counts: { image: 0, label: 0 },
+    schema: {
+      workable: true,
+      mode: "image_mask_pair",
+      primary_paths: {
+        image: "data/image.h5",
+        label: "data/label.h5",
+      },
+    },
+    examples: {
+      image: ["data/image.h5"],
+      label: ["data/label.h5"],
+    },
+    missing_roles: [],
+  },
+};
+
+const batchSuggestion = {
+  id: "nucmm-batch-project",
+  name: "nucmm-batch-project",
+  directory_path: "/tmp/nucmm_project",
+  description: "Detected image/label batch",
+  recommended: true,
+  already_mounted: false,
+  profile: {
+    ready_for_smoke: false,
+    counts: { image: 8, label: 8, checkpoint: 1, config: 1 },
+    role_directories: {
+      image: [{ path: "data/source/Image/train", count: 4 }],
+      label: [{ path: "data/source/Label/train", count: 4 }],
+    },
+    volume_sets: [
+      {
+        id: "set-1",
+        name: "train",
+        image_root: "data/source/Image/train",
+        label_root: "data/source/Label/train",
+        image_count: 4,
+        label_count: 4,
+        pair_count: 4,
+      },
+      {
+        id: "set-2",
+        name: "val",
+        image_root: "data/source/Image/val",
+        label_root: "data/source/Label/val",
+        image_count: 4,
+        label_count: 4,
+        pair_count: 4,
+      },
+    ],
+    schema: {
+      workable: true,
+      mode: "image_mask_pair",
+      stages: { visualization: true, proofreading: true, training: true },
+      primary_paths: {
+        image: "data/source/Image/train/img_000.h5",
+        image_root: "data/source/Image/train",
+        label: "data/source/Label/train/img_000.h5",
+        label_root: "data/source/Label/train",
+        checkpoint: "checkpoints/model.pth.tar",
+        config: "configs/preset.yaml",
+      },
+    },
+    examples: {
+      image: ["data/source/Image/train/img_000.h5"],
+      label: ["data/source/Label/train/img_000.h5"],
+      checkpoint: ["checkpoints/model.pth.tar"],
+      config: ["configs/preset.yaml"],
+    },
+    missing_roles: ["prediction"],
+  },
+};
+
+const renderFilesManager = () =>
+  render(
+    <AppContext.Provider value={{ resetFileState: jest.fn() }}>
+      <FilesManager />
+    </AppContext.Provider>,
+  );
+
+const mockProjectSuggestionResponses = (suggestions) => {
+  apiClient.get.mockImplementation((url) => {
+    if (url === "/files/project-suggestions") {
+      return Promise.resolve({ data: suggestions });
+    }
+    if (url === "/files/project-context") {
+      return Promise.resolve({ data: { exists: false, profile: null } });
+    }
+    return Promise.resolve({ data: [] });
+  });
+};
+
+const clickSuggestedProject = async () => {
+  const buttons = await screen.findAllByText("Use suggested project");
+  fireEvent.click(buttons[0]);
+};
+
+const continueWithProjectContext = async (
+  text = "EM mitochondria volumes from mouse tissue at 30 x 6 x 6 nm. Segment mitochondria from a single volume and prioritize accuracy.",
+) => {
+  await screen.findByText("Confirm project basics");
+  fireEvent.change(screen.getByPlaceholderText(/Optional:/i), {
+    target: { value: text },
+  });
+  fireEvent.click(screen.getByText("Continue"));
+  await waitFor(() => {
+    expect(screen.getAllByText("Start project").length).toBeGreaterThan(1);
+  });
+};
+
+const continueWithDefaults = async () => {
+  await screen.findByRole("dialog");
+  if (screen.queryAllByText("Start project").length > 1) return;
+  fireEvent.click(screen.getByText(/Use (safe defaults|detected context)/));
+  await waitFor(() => {
+    expect(screen.getAllByText("Start project").length).toBeGreaterThan(1);
+  });
+};
+
+const reviewAndStartProject = async () => {
+  const startButtons = screen
+    .getAllByText("Start project")
+    .filter((element) => element.tagName.toLowerCase() === "button");
+  fireEvent.click(startButtons[0]);
+};
+
 describe("FilesManager", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    mockWorkflowContext.updateWorkflow.mockResolvedValue({});
+    mockWorkflowContext.appendEvent.mockResolvedValue({});
+    mockWorkflowContext.refreshPreflight.mockResolvedValue({});
+    mockWorkflowContext.refreshAgentRecommendation.mockResolvedValue({});
+    mockWorkflowContext.pendingRuntimeAction = null;
+    mockWorkflowContext.consumeRuntimeAction.mockClear();
+  });
+
   it("loads root-level files with a parent-scoped request on initial render", async () => {
     apiClient.get.mockResolvedValue({ data: [] });
 
-    render(
-      <AppContext.Provider value={{ resetFileState: jest.fn() }}>
-        <FilesManager />
-      </AppContext.Provider>,
-    );
+    renderFilesManager();
 
     await waitFor(() => {
       expect(apiClient.get).toHaveBeenCalledWith("/files", {
@@ -107,4 +480,580 @@ describe("FilesManager", () => {
 
     expect(apiClient.get).not.toHaveBeenCalledWith("/files");
   });
+
+  it("opens a confirmation modal before registering a suggested smoke project", async () => {
+    mockProjectSuggestionResponses([smokeSuggestion]);
+    apiClient.post.mockResolvedValue({
+      data: { mounted_root_id: 7, message: "Mounted smoke project" },
+    });
+
+    renderFilesManager();
+
+    expect(
+      await screen.findByText("Start a segmentation project"),
+    ).toBeTruthy();
+    await clickSuggestedProject();
+
+    await waitFor(() => {
+      expect(apiClient.post).toHaveBeenCalledWith(
+        "/files/mount",
+        {
+          directory_path: "/tmp/mito25_paper_loop_smoke",
+          destination_path: "root",
+          mount_name: "mito25-paper-loop-smoke",
+        },
+        { withCredentials: true },
+      );
+    });
+    expect(apiClient.get).toHaveBeenCalledWith("/files", {
+      params: { parent: "7" },
+    });
+    await continueWithProjectContext();
+    await waitFor(() => {
+      expect(screen.getAllByText("Start project").length).toBeGreaterThan(1);
+    });
+    expect(
+      screen.getByDisplayValue("data/image/mito25_smoke_im.h5"),
+    ).toBeTruthy();
+    expect(mockWorkflowContext.updateWorkflow).not.toHaveBeenCalled();
+
+    await reviewAndStartProject();
+    expect(await screen.findByText("Project brief")).toBeTruthy();
+    expect(
+      screen.getByText("EM mitochondria project at 30 x 6 x 6 nm."),
+    ).toBeTruthy();
+    expect(screen.getByText("Editable project context")).toBeTruthy();
+    expect(screen.getByText("What I checked automatically")).toBeTruthy();
+    expect(
+      screen.getByText(/I inspected 2 volumes and 1 image\/mask pair/i),
+    ).toBeTruthy();
+    expect(screen.getByText(/Image and mask shapes match/i)).toBeTruthy();
+    expect(screen.queryByText(/^Priority$/)).toBeNull();
+    expect(screen.queryByText(/^Goal$/)).toBeNull();
+    expect(screen.queryByText(/^Labels$/)).toBeNull();
+    expect(screen.queryByText(/^Data$/)).toBeNull();
+    expect(screen.getByText("How the agent will use this")).toBeTruthy();
+
+    await waitFor(() => {
+      expect(mockWorkflowContext.updateWorkflow).toHaveBeenCalledWith({
+        dataset_path: "/tmp/mito25_paper_loop_smoke",
+        image_path:
+          "/tmp/mito25_paper_loop_smoke/data/image/mito25_smoke_im.h5",
+        label_path: "/tmp/mito25_paper_loop_smoke/data/seg/mito25_smoke_seg.h5",
+        mask_path: "/tmp/mito25_paper_loop_smoke/data/seg/mito25_smoke_seg.h5",
+        inference_output_path:
+          "/tmp/mito25_paper_loop_smoke/predictions/baseline.tif",
+        checkpoint_path:
+          "/tmp/mito25_paper_loop_smoke/checkpoints/checkpoint_00200.pth.tar",
+        config_path: "/tmp/mito25_paper_loop_smoke/configs/MitoEM.yaml",
+        metadata: {
+          visualization_scales: [30, 6, 6],
+          visualization_scales_source: "project_description",
+          project_context: expect.objectContaining({
+            freeform_note:
+              "EM mitochondria volumes from mouse tissue at 30 x 6 x 6 nm. Segment mitochondria from a single volume and prioritize accuracy.",
+            imaging_modality: "EM",
+            target_structure: "mitochondria",
+            voxel_size_nm: [30, 6, 6],
+            source: "project_setup_confirmation",
+          }),
+        },
+      });
+    });
+    expect(mockWorkflowContext.appendEvent).toHaveBeenCalledWith(
+      expect.objectContaining({
+        event_type: "dataset.loaded",
+        summary: "Confirmed project data for mito25-paper-loop-smoke.",
+        payload: expect.objectContaining({
+          source: "file_management_project_confirmation",
+          setup_source: "suggested_mount",
+          project_description:
+            "EM mitochondria volumes from mouse tissue at 30 x 6 x 6 nm. Segment mitochondria from a single volume and prioritize accuracy.",
+          project_context: expect.objectContaining({
+            imaging_modality: "EM",
+            target_structure: "mitochondria",
+            voxel_size_nm: [30, 6, 6],
+          }),
+          project_brief: expect.objectContaining({
+            summary: "EM mitochondria project at 30 x 6 x 6 nm.",
+            fields: expect.arrayContaining([
+              expect.objectContaining({
+                label: "Target structure",
+                value: "mitochondria",
+              }),
+              expect.objectContaining({
+                label: "Voxel size (z, y, x)",
+                value: "30 x 6 x 6 nm",
+              }),
+            ]),
+            next_moves: expect.arrayContaining([
+              "Use data/image/mito25_smoke_im.h5 as the active image data.",
+              "Use 30 x 6 x 6 nm as the z/y/x voxel size for visualization and model defaults.",
+            ]),
+          }),
+          detected_volume_sets: expect.arrayContaining([
+            expect.objectContaining({ pair_count: 1 }),
+          ]),
+          project_audit: expect.objectContaining({
+            schema_version: "pytc-project-audit/v1",
+          }),
+          context_facts: expect.arrayContaining([
+            expect.objectContaining({ key: "voxel_size_nm" }),
+          ]),
+          confirmed_roles: expect.objectContaining({
+            config: "configs/MitoEM.yaml",
+          }),
+        }),
+      }),
+    );
+    expect(apiClient.put).toHaveBeenCalledWith(
+      "/files/project-context",
+      expect.objectContaining({
+        directory_path: "/tmp/mito25_paper_loop_smoke",
+        profile: expect.objectContaining({
+          schema_version: "pytc-project-context/v1",
+          semantic_context: expect.objectContaining({
+            target_structure: "mitochondria",
+          }),
+          project_brief: expect.objectContaining({
+            summary: "EM mitochondria project at 30 x 6 x 6 nm.",
+          }),
+          project_audit: expect.objectContaining({
+            schema_version: "pytc-project-audit/v1",
+          }),
+          mechanistic_mapping: expect.objectContaining({
+            image: "data/image/mito25_smoke_im.h5",
+          }),
+        }),
+      }),
+    );
+  });
+
+  it("skips the blank description prompt when project basics are already detected", async () => {
+    mockProjectSuggestionResponses([completeSmokeSuggestion]);
+    apiClient.post.mockResolvedValue({
+      data: { mounted_root_id: 7, message: "Mounted smoke project" },
+    });
+
+    renderFilesManager();
+
+    await clickSuggestedProject();
+
+    await waitFor(() => {
+      expect(screen.getAllByText("Start project").length).toBeGreaterThan(1);
+    });
+    expect(screen.queryByText("Confirm project basics")).toBeNull();
+    expect(screen.queryByText("Anything else I should know?")).toBeNull();
+    expect(screen.getByDisplayValue("EM")).toBeTruthy();
+    expect(screen.getByDisplayValue("mitochondria")).toBeTruthy();
+    expect(screen.getByDisplayValue("30, 6, 6")).toBeTruthy();
+    expect(screen.getByText("What I checked automatically")).toBeTruthy();
+  });
+
+  it("shows compact shared facts including task/training policy and volume split", async () => {
+    mockProjectSuggestionResponses([yixiaoLikeSmokeSuggestion]);
+    apiClient.post.mockResolvedValue({
+      data: { mounted_root_id: 7, message: "Mounted yixiao project" },
+    });
+
+    renderFilesManager();
+
+    await clickSuggestedProject();
+    await screen.findByText("Shared project facts");
+    expect(screen.getAllByText("Shared project facts").length).toBeGreaterThan(
+      0,
+    );
+    expect(screen.getAllByText("Modality").length).toBeGreaterThan(0);
+    expect(screen.getAllByText("Target").length).toBeGreaterThan(0);
+    expect(screen.getAllByText("Voxel size").length).toBeGreaterThan(0);
+    expect(screen.getAllByText("Volume split").length).toBeGreaterThan(0);
+    expect(
+      screen.getAllByText("XRI fibre instance segmentation").length,
+    ).toBeGreaterThan(0);
+    expect(
+      screen.getAllByText("train only on confirmed ground-truth masks").length,
+    ).toBeGreaterThan(0);
+    expect(
+      screen.getAllByText("6 ground-truth / 2 draft masks / 2 image-only")
+        .length,
+    ).toBeGreaterThan(0);
+
+    await continueWithDefaults();
+    expect(screen.getByText("Shared project facts")).toBeTruthy();
+    await reviewAndStartProject();
+
+    await waitFor(() => {
+      expect(mockWorkflowContext.updateWorkflow).toHaveBeenCalledWith(
+        expect.objectContaining({
+          metadata: expect.objectContaining({
+            project_context: expect.objectContaining({
+              task_family: "XRI fibre instance segmentation",
+              training_policy: "train only on confirmed ground-truth masks",
+              volume_split: "6 ground-truth / 2 draft masks / 2 image-only",
+            }),
+          }),
+        }),
+      );
+    });
+  });
+
+  it("asks semantic follow-up questions for context the app cannot infer", async () => {
+    mockProjectSuggestionResponses([neutralSuggestion]);
+    apiClient.post.mockResolvedValue({
+      data: { mounted_root_id: 7, message: "Mounted neutral project" },
+    });
+
+    renderFilesManager();
+
+    await clickSuggestedProject();
+    await screen.findByText("Confirm project basics");
+    const descriptionBox = screen.getByPlaceholderText(/Optional:/i);
+    fireEvent.change(descriptionBox, {
+      target: { value: "EM mitochondria from mouse brain tissue." },
+    });
+    fireEvent.click(screen.getByText("Continue"));
+    expect(
+      await screen.findByText(
+        "What is the voxel size or imaging resolution in z, y, x nanometers?",
+      ),
+    ).toBeTruthy();
+    expect(screen.queryAllByText("Start project")).toHaveLength(0);
+    expect(descriptionBox.value).toBe("");
+
+    fireEvent.change(descriptionBox, {
+      target: {
+        value: "30 x 6 x 6 nm",
+      },
+    });
+    fireEvent.click(screen.getByText("Continue"));
+    await waitFor(() => {
+      expect(screen.getAllByText("Start project").length).toBeGreaterThan(1);
+    });
+
+    await reviewAndStartProject();
+
+    await waitFor(() => {
+      expect(mockWorkflowContext.updateWorkflow).toHaveBeenCalledWith(
+        expect.objectContaining({
+          metadata: expect.objectContaining({
+            project_context: expect.objectContaining({
+              freeform_note:
+                "EM mitochondria from mouse brain tissue.\n30 x 6 x 6 nm",
+              imaging_modality: "EM",
+              target_structure: "mitochondria",
+              voxel_size_nm: [30, 6, 6],
+              completeness: expect.objectContaining({
+                complete: true,
+                missing: [],
+              }),
+            }),
+          }),
+        }),
+      );
+    });
+  });
+
+  it("lets users edit absorbed project context fields before confirming", async () => {
+    mockProjectSuggestionResponses([smokeSuggestion]);
+    apiClient.post.mockResolvedValue({
+      data: { mounted_root_id: 7, message: "Mounted smoke project" },
+    });
+
+    renderFilesManager();
+
+    await clickSuggestedProject();
+    await continueWithProjectContext();
+
+    fireEvent.change(screen.getByDisplayValue("EM"), {
+      target: { value: "serial block-face EM" },
+    });
+    fireEvent.change(screen.getByDisplayValue("mitochondria"), {
+      target: { value: "synapses" },
+    });
+    fireEvent.change(screen.getByDisplayValue("30, 6, 6"), {
+      target: { value: "4, 4, 40" },
+    });
+
+    expect(
+      screen.getByText(
+        "serial block-face EM synapses project at 4 x 4 x 40 nm.",
+      ),
+    ).toBeTruthy();
+
+    await reviewAndStartProject();
+
+    await waitFor(() => {
+      expect(mockWorkflowContext.updateWorkflow).toHaveBeenCalledWith(
+        expect.objectContaining({
+          metadata: expect.objectContaining({
+            visualization_scales: [4, 4, 40],
+            visualization_scales_source: "project_setup_confirmation",
+            project_context: expect.objectContaining({
+              imaging_modality: "serial block-face EM",
+              target_structure: "synapses",
+              voxel_size_nm: [4, 4, 40],
+            }),
+          }),
+        }),
+      );
+    });
+    const projectContext =
+      mockWorkflowContext.updateWorkflow.mock.calls[0][0].metadata
+        .project_context;
+    expect(projectContext).not.toHaveProperty("task_goal");
+    expect(projectContext).not.toHaveProperty("data_unit");
+    expect(projectContext).not.toHaveProperty("optimization_priority");
+    expect(projectContext).not.toHaveProperty("label_status");
+  });
+
+  it("uses edited and cleared role paths when confirming project setup", async () => {
+    mockProjectSuggestionResponses([smokeSuggestion]);
+    apiClient.post.mockResolvedValue({
+      data: { mounted_root_id: 7, message: "Mounted smoke project" },
+    });
+
+    renderFilesManager();
+
+    await clickSuggestedProject();
+    await continueWithDefaults();
+
+    fireEvent.change(screen.getByDisplayValue("predictions/baseline.tif"), {
+      target: { value: "" },
+    });
+    fireEvent.change(
+      screen.getByDisplayValue("checkpoints/checkpoint_00200.pth.tar"),
+      { target: { value: "/tmp/custom/checkpoint.pth.tar" } },
+    );
+    await reviewAndStartProject();
+
+    await waitFor(() => {
+      expect(mockWorkflowContext.updateWorkflow).toHaveBeenCalledWith(
+        expect.objectContaining({
+          dataset_path: "/tmp/mito25_paper_loop_smoke",
+          image_path:
+            "/tmp/mito25_paper_loop_smoke/data/image/mito25_smoke_im.h5",
+          label_path:
+            "/tmp/mito25_paper_loop_smoke/data/seg/mito25_smoke_seg.h5",
+          mask_path:
+            "/tmp/mito25_paper_loop_smoke/data/seg/mito25_smoke_seg.h5",
+          checkpoint_path: "/tmp/custom/checkpoint.pth.tar",
+          config_path: "/tmp/mito25_paper_loop_smoke/configs/MitoEM.yaml",
+        }),
+      );
+    });
+    expect(
+      mockWorkflowContext.updateWorkflow.mock.calls[0][0].inference_output_path,
+    ).toBeUndefined();
+  });
+
+  it("lets a user browse to override a detected role before confirmation", async () => {
+    mockProjectSuggestionResponses([smokeSuggestion]);
+    apiClient.post.mockResolvedValue({
+      data: { mounted_root_id: 7, message: "Mounted smoke project" },
+    });
+
+    renderFilesManager();
+
+    await clickSuggestedProject();
+    await continueWithDefaults();
+    fireEvent.click(screen.getAllByText("Browse")[2]);
+    fireEvent.click(await screen.findByText("Choose mocked file"));
+    await reviewAndStartProject();
+
+    await waitFor(() => {
+      expect(mockWorkflowContext.updateWorkflow).toHaveBeenCalledWith(
+        expect.objectContaining({
+          inference_output_path: "/tmp/override/override-prediction.tif",
+        }),
+      );
+    });
+    expect(apiClient.put).toHaveBeenCalledWith(
+      "/files/project-context",
+      expect.objectContaining({
+        directory_path: "/tmp/mito25_paper_loop_smoke",
+        profile: expect.objectContaining({
+          schema_version: "pytc-project-context/v1",
+          semantic_context: expect.objectContaining({
+            use_defaults: true,
+          }),
+          mechanistic_mapping: expect.objectContaining({
+            prediction: "/tmp/override/override-prediction.tif",
+          }),
+        }),
+      }),
+    );
+  });
+
+  it("defaults multi-volume projects to confirmed folders instead of one file", async () => {
+    mockProjectSuggestionResponses([batchSuggestion]);
+    apiClient.post.mockResolvedValue({
+      data: { mounted_root_id: 21, message: "Mounted batch project" },
+    });
+
+    renderFilesManager();
+
+    await clickSuggestedProject();
+    await continueWithProjectContext(
+      "Mouse micro-CT nuclei dataset with train/val folders at 8 x 8 x 8 nm. Segment nuclei and prioritize accuracy.",
+    );
+    expect(screen.getByDisplayValue("data/source/Image/train")).toBeTruthy();
+    expect(screen.getByDisplayValue("data/source/Label/train")).toBeTruthy();
+    expect(screen.getByText(/4 matched pairs/)).toBeTruthy();
+
+    await reviewAndStartProject();
+
+    await waitFor(() => {
+      expect(mockWorkflowContext.updateWorkflow).toHaveBeenCalledWith(
+        expect.objectContaining({
+          dataset_path: "/tmp/nucmm_project",
+          image_path: "/tmp/nucmm_project/data/source/Image/train",
+          label_path: "/tmp/nucmm_project/data/source/Label/train",
+          mask_path: "/tmp/nucmm_project/data/source/Label/train",
+          checkpoint_path: "/tmp/nucmm_project/checkpoints/model.pth.tar",
+          config_path: "/tmp/nucmm_project/configs/preset.yaml",
+        }),
+      );
+    });
+    expect(mockWorkflowContext.appendEvent).toHaveBeenCalledWith(
+      expect.objectContaining({
+        payload: expect.objectContaining({
+          detected_role_counts: expect.objectContaining({ image: 8, label: 8 }),
+          detected_volume_sets: expect.arrayContaining([
+            expect.objectContaining({ pair_count: 4 }),
+          ]),
+        }),
+      }),
+    );
+  });
+
+  it("submits repeated setup feedback with Enter and applies each correction", async () => {
+    mockProjectSuggestionResponses([batchSuggestion]);
+    apiClient.post.mockResolvedValue({
+      data: { mounted_root_id: 21, message: "Mounted batch project" },
+    });
+
+    renderFilesManager();
+
+    await clickSuggestedProject();
+    await continueWithDefaults();
+
+    const feedbackBox = screen.getByPlaceholderText(/Example correction/i);
+    fireEvent.change(feedbackBox, { target: { value: "use val split" } });
+    fireEvent.keyDown(feedbackBox, { key: "Enter", shiftKey: false });
+
+    expect(await screen.findByText(/Updated the mapping/)).toBeTruthy();
+    expect(screen.getByDisplayValue("data/source/Image/val")).toBeTruthy();
+    expect(screen.getByDisplayValue("data/source/Label/val")).toBeTruthy();
+    await waitFor(() => {
+      expect(mockWorkflowContext.appendEvent).toHaveBeenCalledWith(
+        expect.objectContaining({
+          event_type: "dataset.setup_feedback",
+          payload: expect.objectContaining({
+            feedback: "use val split",
+            applied_changes: expect.objectContaining({
+              image: "data/source/Image/val",
+              label: "data/source/Label/val",
+            }),
+          }),
+        }),
+      );
+    });
+
+    fireEvent.change(feedbackBox, { target: { value: "use train split" } });
+    fireEvent.keyDown(feedbackBox, { key: "Enter", shiftKey: false });
+
+    expect(screen.getByDisplayValue("data/source/Image/train")).toBeTruthy();
+    expect(screen.getByDisplayValue("data/source/Label/train")).toBeTruthy();
+    await waitFor(() => {
+      expect(mockWorkflowContext.appendEvent).toHaveBeenCalledWith(
+        expect.objectContaining({
+          event_type: "dataset.setup_feedback",
+          payload: expect.objectContaining({
+            feedback: "use train split",
+            applied_changes: expect.objectContaining({
+              image: "data/source/Image/train",
+              label: "data/source/Label/train",
+            }),
+          }),
+        }),
+      );
+    });
+  });
+
+  it("allows image-only projects to start without mask or checkpoint roles", async () => {
+    mockProjectSuggestionResponses([imageOnlySuggestion]);
+    apiClient.post.mockResolvedValue({
+      data: { mounted_root_id: 12, message: "Mounted image-only project" },
+    });
+
+    renderFilesManager();
+
+    await clickSuggestedProject();
+    await continueWithDefaults();
+    await reviewAndStartProject();
+
+    await waitFor(() => {
+      expect(mockWorkflowContext.updateWorkflow).toHaveBeenCalledWith(
+        expect.objectContaining({
+          dataset_path: "/tmp/image_only_project",
+          image_path: "/tmp/image_only_project/volume/raw_image.tif",
+        }),
+      );
+    });
+  });
+
+  it("opens confirmation after a manual project mount and leaves workflow unchanged when canceled", async () => {
+    apiClient.get.mockResolvedValue({ data: [] });
+    openLocalFile.mockResolvedValue("/tmp/manual_project");
+    apiClient.post.mockResolvedValue({
+      data: {
+        mounted_root_id: 15,
+        mount_name: "manual_project",
+        message: "Mounted manual project",
+        profile: {
+          schema: {
+            mode: "image_only",
+            primary_paths: { image: "raw/manual.h5" },
+          },
+          examples: { image: ["raw/manual.h5"] },
+          counts: { image: 1 },
+        },
+      },
+    });
+
+    renderFilesManager();
+
+    fireEvent.click(await screen.findByText("Mount Project"));
+    await screen.findByText("Confirm project basics");
+    expect(screen.getByPlaceholderText(/Optional:/i)).toBeTruthy();
+    fireEvent.click(screen.getByText("Cancel"));
+
+    expect(mockWorkflowContext.updateWorkflow).not.toHaveBeenCalled();
+  });
+
+  it("opens project data confirmation for assistant choose-data actions", async () => {
+    mockWorkflowContext.pendingRuntimeAction = {
+      id: "choose-data-action",
+      kind: "choose_project_data",
+    };
+    mockProjectSuggestionResponses([
+      {
+        ...smokeSuggestion,
+        already_mounted: true,
+        mounted_root_id: 7,
+      },
+    ]);
+
+    renderFilesManager();
+
+    await screen.findByText("Confirm project basics");
+    await waitFor(() => {
+      expect(apiClient.get).toHaveBeenCalledWith("/files", {
+        params: { parent: "7" },
+      });
+      expect(mockWorkflowContext.consumeRuntimeAction).toHaveBeenCalledWith(
+        "choose-data-action",
+      );
+    });
+  });
 });
diff --git a/client/src/views/ModelInference.js b/client/src/views/ModelInference.js
index bd3384d0..5bffc17f 100644
--- a/client/src/views/ModelInference.js
+++ b/client/src/views/ModelInference.js
@@ -1,43 +1,45 @@
-import React, { useContext, useEffect, useRef, useState } from "react";
+import React, {
+  useCallback,
+  useContext,
+  useEffect,
+  useRef,
+  useState,
+} from "react";
 import { Button, Space } from "antd";
-import yaml from "js-yaml";
 import {
   getInferenceLogs,
   getInferenceStatus,
-  startModelInference,
+  syncWorkflowInferenceRuntime,
   stopModelInference,
 } from "../api";
 import Configurator from "../components/Configurator";
-import { applyInputPaths } from "../configSchema";
 import RuntimeLogPanel from "../components/RuntimeLogPanel";
+import StageHeader from "../components/workflow/StageHeader";
 import { AppContext } from "../contexts/GlobalContext";
 import { useWorkflow } from "../contexts/WorkflowContext";
+import {
+  getPathValue,
+  launchInferenceFromContext,
+} from "../runtime/modelLaunch";
 
 function ModelInference({ isInferring, setIsInferring }) {
   const context = useContext(AppContext);
   const workflowContext = useWorkflow();
   const appendWorkflowEvent = workflowContext?.appendEvent;
   const workflowId = workflowContext?.workflow?.id;
+  const workflowStage = workflowContext?.workflow?.stage || "inference";
+  const pendingRuntimeAction = workflowContext?.pendingRuntimeAction;
+  const consumeRuntimeAction = workflowContext?.consumeRuntimeAction;
+  const refreshWorkflow = workflowContext?.refreshWorkflow;
+  const refreshWorkflowEvents = workflowContext?.refreshEvents;
+  const refreshWorkflowInsights = workflowContext?.refreshInsights;
+  const refreshWorkflowEvidence = workflowContext?.refreshEvidence;
   const inference = context.inferenceState;
   const [inferenceStatus, setInferenceStatus] = useState("");
   const [inferenceRuntime, setInferenceRuntime] = useState(null);
   const pollingIntervalRef = useRef(null);
   const terminalLoggedRef = useRef(false);
 
-  const getPath = (val) => {
-    if (!val) return "";
-    if (typeof val === "string") return val;
-    return val.path || val.originFileObj?.path || "";
-  };
-
-  const getConfigOriginPath = () => {
-    return (
-      inference.configOriginPath ||
-      inference.selectedYamlPreset ||
-      getPath(inference.uploadedYamlFile)
-    );
-  };
-
   const refreshInferenceLogs = async () => {
     try {
       const runtime = await getInferenceLogs();
@@ -49,27 +51,6 @@ function ModelInference({ isInferring, setIsInferring }) {
     }
   };
 
-  const getPreparedInferenceConfig = (inferenceConfig) => {
-    try {
-      const yamlData = yaml.load(inferenceConfig);
-      if (!yamlData || typeof yamlData !== "object") {
-        return inferenceConfig;
-      }
-
-      applyInputPaths(yamlData, {
-        mode: "inference",
-        inputImagePath: getPath(inference.inputImage),
-        inputLabelPath: "",
-        inputPath: "",
-        outputPath: getPath(inference.outputPath),
-      });
-      return yaml.dump(yamlData, { indent: 2 }).replace(/^\s*\n/gm, "");
-    } catch (error) {
-      console.warn("Failed to prepare inference config from current inputs:", error);
-      return inferenceConfig;
-    }
-  };
-
   useEffect(() => {
     refreshInferenceLogs();
   }, []);
@@ -85,41 +66,82 @@ function ModelInference({ isInferring, setIsInferring }) {
           setInferenceRuntime(runtime);
 
           if (!status.isRunning) {
+            if (pollingIntervalRef.current) {
+              clearInterval(pollingIntervalRef.current);
+              pollingIntervalRef.current = null;
+            }
             setIsInferring(false);
+            const succeeded = status.exitCode === 0;
+            let syncResult = null;
+            let syncError = null;
+            if (workflowId) {
+              try {
+                syncResult = await syncWorkflowInferenceRuntime(workflowId);
+                if (syncResult?.synced) {
+                  await Promise.all([
+                    refreshWorkflow?.(),
+                    refreshWorkflowEvents?.(),
+                    refreshWorkflowInsights?.(),
+                    refreshWorkflowEvidence?.(),
+                  ]);
+                }
+              } catch (error) {
+                syncError = error;
+                console.warn("Model run artifact sync failed:", error);
+              }
+            }
             if (!terminalLoggedRef.current && appendWorkflowEvent) {
               terminalLoggedRef.current = true;
-              const succeeded = status.exitCode === 0;
-              await appendWorkflowEvent({
-                actor: "system",
-                event_type: succeeded
-                  ? "inference.completed"
-                  : "inference.failed",
-                stage: "inference",
-                summary: succeeded
-                  ? "Inference completed successfully."
-                  : "Inference finished without a successful exit.",
-                payload: {
-                  exitCode: status.exitCode,
-                  phase: status.phase,
-                  lastError: status.lastError,
-                  outputPath: getPath(inference.outputPath),
-                },
-              });
+              if (!syncResult?.synced) {
+                await appendWorkflowEvent({
+                  actor: "system",
+                  event_type: succeeded
+                    ? "inference.completed"
+                    : "inference.failed",
+                  stage: "inference",
+                  summary: succeeded
+                    ? "Model run completed, but runtime artifact sync did not complete."
+                    : "Model run finished without a successful exit.",
+                  payload: {
+                    exitCode: status.exitCode,
+                    phase: status.phase,
+                    lastError: status.lastError,
+                    outputPath: getPathValue(inference.outputPath),
+                    syncReason: syncResult?.reason || null,
+                    syncError: syncError?.message || null,
+                  },
+                });
+              }
             }
             if (status.exitCode === 0) {
-              setInferenceStatus("Inference completed successfully! ✓");
-            } else if (status.exitCode !== null && status.exitCode !== undefined) {
+              console.log("Model run completed successfully.", status);
               setInferenceStatus(
-                `Inference finished with exit code: ${status.exitCode}`,
+                syncResult?.synced
+                  ? `Model run completed and workflow synced: ${syncResult.outputPath || "prediction artifact captured"} ✓`
+                  : "Model run completed successfully; workflow sync is pending. ✓",
+              );
+            } else if (
+              status.exitCode !== null &&
+              status.exitCode !== undefined
+            ) {
+              console.error("Model run failed.", status);
+              setInferenceStatus(
+                `Model run finished with exit code: ${status.exitCode}`,
               );
             } else if (status.phase === "failed" && status.lastError) {
-              setInferenceStatus(`Inference failed: ${status.lastError}`);
+              console.error("Model run failed.", status);
+              setInferenceStatus(`Model run failed: ${status.lastError}`);
             } else {
-              setInferenceStatus("Inference stopped.");
+              console.warn("Model run stopped.", status);
+              setInferenceStatus("Model run stopped.");
             }
           }
         } catch (error) {
           console.error("Error polling inference status:", error);
+          if (pollingIntervalRef.current) {
+            clearInterval(pollingIntervalRef.current);
+            pollingIntervalRef.current = null;
+          }
           setIsInferring(false);
           if (!terminalLoggedRef.current && appendWorkflowEvent) {
             terminalLoggedRef.current = true;
@@ -127,15 +149,15 @@ function ModelInference({ isInferring, setIsInferring }) {
               actor: "system",
               event_type: "inference.failed",
               stage: "inference",
-              summary: "Inference status polling failed.",
+              summary: "Model run status polling failed.",
               payload: {
                 error: error.message || "unknown error",
-                outputPath: getPath(inference.outputPath),
+                outputPath: getPathValue(inference.outputPath),
               },
             });
           }
           setInferenceStatus(
-            `Inference status polling failed: ${error.message || "unknown error"}`,
+            `Model run status polling failed: ${error.message || "unknown error"}`,
           );
         }
       }, 2000);
@@ -147,73 +169,108 @@ function ModelInference({ isInferring, setIsInferring }) {
         pollingIntervalRef.current = null;
       }
     };
-  }, [isInferring, setIsInferring, appendWorkflowEvent, inference.outputPath]);
+  }, [
+    appendWorkflowEvent,
+    inference.outputPath,
+    isInferring,
+    refreshWorkflow,
+    refreshWorkflowEvidence,
+    refreshWorkflowEvents,
+    refreshWorkflowInsights,
+    setIsInferring,
+    workflowId,
+  ]);
 
-  const handleStartButton = async () => {
-    let checkpointPath = "";
-    try {
-      const inferenceConfig = context.inferenceConfig;
-      if (!inferenceConfig) {
-        setInferenceStatus(
-          "Error: Please load or upload an inference configuration first.",
-        );
+  const startInferenceRun = useCallback(
+    async (runtimeAction = null) => {
+      let checkpointPath = "";
+      if (isInferring) {
+        setInferenceStatus("A model run is already running.");
         return;
       }
+      try {
+        setIsInferring(true);
+        setInferenceStatus("Starting model run...");
+        terminalLoggedRef.current = false;
 
-      checkpointPath = getPath(inference.checkpointPath);
-      if (!checkpointPath) {
-        setInferenceStatus("Error: Please set checkpoint path first.");
-        return;
-      }
+        checkpointPath = getPathValue(
+          runtimeAction?.overrides?.checkpointPath ?? inference.checkpointPath,
+        );
 
-      setIsInferring(true);
-      setInferenceStatus("Starting inference...");
-      terminalLoggedRef.current = false;
+        const res = await launchInferenceFromContext(
+          context,
+          workflowId,
+          runtimeAction?.overrides || {},
+        );
+        console.log(res);
+        await refreshInferenceLogs();
+        setInferenceStatus("Model run started. Monitoring process...");
+      } catch (e) {
+        console.log(e);
+        setIsInferring(false);
+        if (runtimeAction && appendWorkflowEvent) {
+          await appendWorkflowEvent({
+            actor: "system",
+            event_type: "assistant.command_failed",
+            stage: workflowStage,
+            summary: "Assistant could not start the model run.",
+            payload: {
+              error: e.message || "unknown error",
+              runtime_action: runtimeAction.kind,
+            },
+          });
+        }
+        if (!terminalLoggedRef.current && appendWorkflowEvent) {
+          terminalLoggedRef.current = true;
+          await appendWorkflowEvent({
+            actor: "system",
+            event_type: "inference.failed",
+            stage: workflowStage,
+            summary: "Model run failed to start.",
+            payload: {
+              error: e.message || "unknown error",
+              outputPath: getPathValue(inference.outputPath),
+              checkpointPath,
+            },
+          });
+        }
+        await refreshInferenceLogs();
+        setInferenceStatus(
+          `Model run error: ${e.message || "Please check console for details."}`,
+        );
+      }
+    },
+    [
+      appendWorkflowEvent,
+      context,
+      inference.checkpointPath,
+      inference.outputPath,
+      isInferring,
+      setIsInferring,
+      workflowId,
+      workflowStage,
+    ],
+  );
 
-      const preparedInferenceConfig = getPreparedInferenceConfig(inferenceConfig);
+  useEffect(() => {
+    if (pendingRuntimeAction?.kind !== "start_inference") return;
+    const action = pendingRuntimeAction;
+    consumeRuntimeAction?.(action.id);
+    startInferenceRun(action);
+  }, [consumeRuntimeAction, pendingRuntimeAction, startInferenceRun]);
 
-      const res = await startModelInference(
-        preparedInferenceConfig,
-        getPath(inference.outputPath),
-        checkpointPath,
-        getConfigOriginPath(),
-        workflowId,
-      );
-      console.log(res);
-      await refreshInferenceLogs();
-      setInferenceStatus("Inference started. Monitoring process...");
-    } catch (e) {
-      console.log(e);
-      setIsInferring(false);
-      if (!terminalLoggedRef.current && appendWorkflowEvent) {
-        terminalLoggedRef.current = true;
-        await appendWorkflowEvent({
-          actor: "system",
-          event_type: "inference.failed",
-          stage: "inference",
-          summary: "Inference failed to start.",
-          payload: {
-            error: e.message || "unknown error",
-            outputPath: getPath(inference.outputPath),
-            checkpointPath,
-          },
-        });
-      }
-      await refreshInferenceLogs();
-      setInferenceStatus(
-        `Inference error: ${e.message || "Please check console for details."}`,
-      );
-    }
+  const handleStartButton = async () => {
+    await startInferenceRun();
   };
 
   const handleStopButton = async () => {
     try {
-      setInferenceStatus("Stopping inference...");
+      setInferenceStatus("Stopping model run...");
       await stopModelInference();
     } catch (e) {
       console.log(e);
       setInferenceStatus(
-        `Error stopping inference: ${e.message || "Please check console for details."}`,
+        `Error stopping model run: ${e.message || "Please check console for details."}`,
       );
     } finally {
       setIsInferring(false);
@@ -226,6 +283,13 @@ function ModelInference({ isInferring, setIsInferring }) {
   return (
     <>
       <div>
+        <div style={{ marginBottom: 12 }}>
+          <StageHeader
+            stage="inference"
+            title="Run Model"
+            subtitle="Run prediction, register output artifacts, and route failures into proofreading."
+          />
+        </div>
         <Configurator fileList={context.files} type="inference" />
         <Space wrap style={{ marginTop: 12 }} size={componentSize}>
           <Button
@@ -233,18 +297,18 @@ function ModelInference({ isInferring, setIsInferring }) {
             disabled={isInferring} // Disables the button when inference is running
             style={{ marginRight: "8px" }}
           >
-            Start Inference
+            Run Model
           </Button>
           <Button
             onClick={handleStopButton}
             disabled={!isInferring} // Disables the button when inference is not running
           >
-            Stop Inference
+            Stop Run
           </Button>
         </Space>
         <p style={{ marginTop: 4 }}>{inferenceStatus}</p>
         <RuntimeLogPanel
-          title="Inference Runtime Log"
+          title="Run Model Runtime"
           runtime={inferenceRuntime}
           onRefresh={refreshInferenceLogs}
         />
diff --git a/client/src/views/ModelInference.test.js b/client/src/views/ModelInference.test.js
new file mode 100644
index 00000000..8585140d
--- /dev/null
+++ b/client/src/views/ModelInference.test.js
@@ -0,0 +1,138 @@
+import React from "react";
+import { act, cleanup, render, screen, waitFor } from "@testing-library/react";
+
+import ModelInference from "./ModelInference";
+import { AppContext } from "../contexts/GlobalContext";
+import {
+  getInferenceLogs,
+  getInferenceStatus,
+  syncWorkflowInferenceRuntime,
+} from "../api";
+
+const mockAppendWorkflowEvent = jest.fn();
+const mockRefreshWorkflow = jest.fn();
+const mockRefreshEvents = jest.fn();
+const mockRefreshInsights = jest.fn();
+const mockRefreshEvidence = jest.fn();
+
+jest.mock("../api", () => ({
+  getInferenceLogs: jest.fn(),
+  getInferenceStatus: jest.fn(),
+  syncWorkflowInferenceRuntime: jest.fn(),
+  stopModelInference: jest.fn(),
+}));
+
+jest.mock("../runtime/modelLaunch", () => ({
+  getPathValue: (value) => value,
+  launchInferenceFromContext: jest.fn(),
+}));
+
+jest.mock("../contexts/WorkflowContext", () => ({
+  useWorkflow: () => ({
+    workflow: { id: 42, stage: "inference" },
+    appendEvent: mockAppendWorkflowEvent,
+    refreshWorkflow: mockRefreshWorkflow,
+    refreshEvents: mockRefreshEvents,
+    refreshInsights: mockRefreshInsights,
+    refreshEvidence: mockRefreshEvidence,
+    pendingRuntimeAction: null,
+    consumeRuntimeAction: jest.fn(),
+  }),
+}));
+
+jest.mock("../components/Configurator", () => () => <div>Configurator</div>);
+jest.mock("../components/RuntimeLogPanel", () => () => <div>Runtime Log</div>);
+jest.mock("../components/workflow/StageHeader", () => ({ title }) => (
+  <h1>{title}</h1>
+));
+
+function renderInference(props = {}) {
+  const setIsInferring = props.setIsInferring || jest.fn();
+  render(
+    <AppContext.Provider
+      value={{
+        inferenceState: {
+          outputPath: "/tmp/inference-out",
+          checkpointPath: "/tmp/checkpoint.pth.tar",
+        },
+      }}
+    >
+      <ModelInference
+        isInferring={props.isInferring ?? true}
+        setIsInferring={setIsInferring}
+      />
+    </AppContext.Provider>,
+  );
+  return { setIsInferring };
+}
+
+describe("ModelInference", () => {
+  beforeEach(() => {
+    jest.useFakeTimers();
+    jest.clearAllMocks();
+    getInferenceLogs.mockResolvedValue({ phase: "finished", metadata: {} });
+    getInferenceStatus.mockResolvedValue({
+      isRunning: false,
+      exitCode: 0,
+      phase: "finished",
+      lastError: null,
+    });
+    syncWorkflowInferenceRuntime.mockResolvedValue({
+      synced: true,
+      outputPath: "/tmp/inference-out/result_xy.h5",
+    });
+  });
+
+  afterEach(() => {
+    cleanup();
+    jest.clearAllTimers();
+    jest.useRealTimers();
+  });
+
+  it("syncs completed inference runtime instead of appending a duplicate event", async () => {
+    const { setIsInferring } = renderInference();
+
+    await act(async () => {
+      jest.advanceTimersByTime(2000);
+    });
+
+    await waitFor(() => {
+      expect(syncWorkflowInferenceRuntime).toHaveBeenCalledWith(42);
+    });
+    expect(setIsInferring).toHaveBeenCalledWith(false);
+    expect(mockRefreshWorkflow).toHaveBeenCalled();
+    expect(mockRefreshEvents).toHaveBeenCalled();
+    expect(mockRefreshInsights).toHaveBeenCalled();
+    expect(mockRefreshEvidence).toHaveBeenCalled();
+    expect(mockAppendWorkflowEvent).not.toHaveBeenCalled();
+    expect(
+      await screen.findByText(
+        /Model run completed and workflow synced: \/tmp\/inference-out\/result_xy.h5/,
+      ),
+    ).toBeTruthy();
+  });
+
+  it("falls back to workflow event append when runtime sync does not capture an artifact", async () => {
+    syncWorkflowInferenceRuntime.mockResolvedValueOnce({
+      synced: false,
+      reason: "prediction_artifact_not_found",
+    });
+
+    renderInference();
+
+    await act(async () => {
+      jest.advanceTimersByTime(2000);
+    });
+
+    await waitFor(() => {
+      expect(mockAppendWorkflowEvent).toHaveBeenCalledWith(
+        expect.objectContaining({
+          event_type: "inference.completed",
+          payload: expect.objectContaining({
+            syncReason: "prediction_artifact_not_found",
+          }),
+        }),
+      );
+    });
+  });
+});
diff --git a/client/src/views/ModelTraining.js b/client/src/views/ModelTraining.js
index 220062da..f5f7633b 100644
--- a/client/src/views/ModelTraining.js
+++ b/client/src/views/ModelTraining.js
@@ -1,43 +1,138 @@
-//  global localStorage
-import React, { useContext, useState, useEffect, useRef } from "react";
-import { Button, Space } from "antd";
-import yaml from "js-yaml";
+import React, {
+  useCallback,
+  useContext,
+  useState,
+  useEffect,
+  useRef,
+} from "react";
+import { Button, Space, Tag, Typography, message } from "antd";
 import {
   getTrainingLogs,
-  startModelTraining,
   stopModelTraining,
   getTrainingStatus,
+  startTensorboard,
 } from "../api";
 import Configurator from "../components/Configurator";
-import { applyInputPaths } from "../configSchema";
 import RuntimeLogPanel from "../components/RuntimeLogPanel";
+import StageHeader from "../components/workflow/StageHeader";
 import { AppContext } from "../contexts/GlobalContext";
 import { useWorkflow } from "../contexts/WorkflowContext";
+import { revealInFinder } from "../electronApi";
+import {
+  getPathValue,
+  launchTrainingFromContext,
+} from "../runtime/modelLaunch";
+
+const { Text } = Typography;
+
+function getBaseName(pathValue) {
+  if (!pathValue) return "";
+  const normalized = String(pathValue).replace(/\\/g, "/");
+  const parts = normalized.split("/");
+  return parts[parts.length - 1] || "";
+}
+
+function firstPath(...values) {
+  for (const value of values) {
+    const path = getPathValue(value);
+    if (path) return path;
+  }
+  return "";
+}
 
 function ModelTraining() {
   const context = useContext(AppContext);
   const workflowContext = useWorkflow();
+  const appendWorkflowEvent = workflowContext?.appendEvent;
+  const updateWorkflow = workflowContext?.updateWorkflow;
+  const runClientEffects = workflowContext?.runClientEffects;
+  const workflowId = workflowContext?.workflow?.id;
+  const workflowStage = workflowContext?.workflow?.stage || "retraining_staged";
+  const pendingRuntimeAction = workflowContext?.pendingRuntimeAction;
+  const consumeRuntimeAction = workflowContext?.consumeRuntimeAction;
   const training = context.trainingState;
+  const setTrainingInputImage = training.setInputImage;
+  const setTrainingInputLabel = training.setInputLabel;
+  const setTrainingOutputPath = training.setOutputPath;
+  const setTrainingLogPath = training.setLogPath;
+  const setInferenceConfig = context?.setInferenceConfig;
+  const setInferenceCheckpointPath = context?.inferenceState?.setCheckpointPath;
+  const setInferenceConfigOriginPath =
+    context?.inferenceState?.setConfigOriginPath;
+  const setInferenceSelectedYamlPreset =
+    context?.inferenceState?.setSelectedYamlPreset;
+  const setInferenceUploadedYamlFile =
+    context?.inferenceState?.setUploadedYamlFile;
   const [isTraining, setIsTraining] = useState(false);
   const [trainingStatus, setTrainingStatus] = useState("");
   const [trainingRuntime, setTrainingRuntime] = useState(null);
   const pollingIntervalRef = useRef(null);
+  const terminalLoggedRef = useRef(false);
+  const latestCheckpointPath = getPathValue(
+    trainingRuntime?.metadata?.latestCheckpointPath ||
+      trainingRuntime?.metadata?.checkpointPath,
+  );
+  const latestCheckpointName = getBaseName(latestCheckpointPath);
+  const resolvedTrainingOutputPath = getPathValue(
+    trainingRuntime?.metadata?.outputPath || training.outputPath,
+  );
 
-  const getPath = (val) => {
-    if (!val) return "";
-    if (typeof val === "string") return val;
-    return val.path || val.originFileObj?.path || "";
-  };
+  const applyTrainingRunPaths = useCallback(
+    (source = {}) => {
+      const overrides = source.overrides || {};
+      const effects = source.clientEffects || source.client_effects || {};
+      const metadata = source.metadata || {};
+      const inputImagePath = firstPath(
+        overrides.inputImagePath,
+        effects.set_training_image_path,
+        metadata.inputImagePath,
+        metadata.input_image_path,
+      );
+      const inputLabelPath = firstPath(
+        overrides.inputLabelPath,
+        effects.set_training_label_path,
+        metadata.inputLabelPath,
+        metadata.input_label_path,
+      );
+      const outputPath = firstPath(
+        overrides.outputPath,
+        effects.set_training_output_path,
+        metadata.outputPath,
+        metadata.output_path,
+      );
+      const logPath = firstPath(
+        overrides.logPath,
+        effects.set_training_log_path,
+        metadata.logPath,
+        metadata.log_path,
+        outputPath,
+      );
 
-  const getConfigOriginPath = () => {
-    return (
-      training.configOriginPath ||
-      training.selectedYamlPreset ||
-      getPath(training.uploadedYamlFile)
-    );
-  };
+      if (inputImagePath) setTrainingInputImage?.(inputImagePath);
+      if (inputLabelPath) setTrainingInputLabel?.(inputLabelPath);
+      if (outputPath) setTrainingOutputPath?.(outputPath);
+      if (logPath) setTrainingLogPath?.(logPath);
+    },
+    [
+      setTrainingInputImage,
+      setTrainingInputLabel,
+      setTrainingLogPath,
+      setTrainingOutputPath,
+    ],
+  );
+
+  useEffect(() => {
+    const metadata = trainingRuntime?.metadata || {};
+    const phase = trainingRuntime?.phase || "idle";
+    if (
+      !["starting", "running", "finished", "failed", "stopped"].includes(phase)
+    ) {
+      return;
+    }
+    applyTrainingRunPaths({ metadata });
+  }, [applyTrainingRunPaths, trainingRuntime]);
 
-  const refreshTrainingLogs = async () => {
+  const refreshTrainingLogs = useCallback(async () => {
     try {
       const runtime = await getTrainingLogs();
       setTrainingRuntime(runtime);
@@ -46,9 +141,9 @@ function ModelTraining() {
       console.error("Error loading training logs:", error);
       return null;
     }
-  };
+  }, []);
 
-  const refreshTrainingRuntime = async () => {
+  const refreshTrainingRuntime = useCallback(async () => {
     const [status, runtime] = await Promise.all([
       getTrainingStatus(),
       getTrainingLogs(),
@@ -57,16 +152,93 @@ function ModelTraining() {
     console.log("Training status:", status);
 
     if (!status.isRunning) {
-      console.log("Training completed!");
       setIsTraining(false);
+      const runtimeMetadata = runtime?.metadata || {};
+      const nextOutputPath = getPathValue(
+        runtimeMetadata.outputPath || training.outputPath,
+      );
+      const nextCheckpointPath = getPathValue(
+        runtimeMetadata.latestCheckpointPath || runtimeMetadata.checkpointPath,
+      );
+      const nextCheckpointName = getBaseName(nextCheckpointPath);
+      let nextStage = workflowStage;
 
       if (status.exitCode === 0) {
-        setTrainingStatus("Training completed successfully! ✓");
+        if (nextCheckpointPath) {
+          setInferenceCheckpointPath?.(nextCheckpointPath);
+        }
+        if (context?.trainingConfig) {
+          setInferenceConfig?.(context.trainingConfig);
+          setInferenceConfigOriginPath?.(
+            training.configOriginPath ||
+              training.selectedYamlPreset ||
+              getPathValue(training.uploadedYamlFile) ||
+              "",
+          );
+          setInferenceSelectedYamlPreset?.(training.selectedYamlPreset || "");
+          setInferenceUploadedYamlFile?.("");
+        }
+        if (updateWorkflow) {
+          try {
+            const patch = { stage: "evaluation" };
+            if (nextOutputPath) {
+              patch.training_output_path = nextOutputPath;
+            }
+            if (nextCheckpointPath) {
+              patch.checkpoint_path = nextCheckpointPath;
+            }
+            const nextWorkflow = await updateWorkflow(patch);
+            nextStage = nextWorkflow?.stage || "evaluation";
+          } catch (error) {
+            console.error(
+              "Error updating workflow after training success:",
+              error,
+            );
+            nextStage = "evaluation";
+          }
+        } else {
+          nextStage = "evaluation";
+        }
+      }
+
+      if (!terminalLoggedRef.current && appendWorkflowEvent) {
+        terminalLoggedRef.current = true;
+        const succeeded = status.exitCode === 0;
+        await appendWorkflowEvent({
+          actor: "system",
+          event_type: succeeded ? "training.completed" : "training.failed",
+          stage: succeeded ? nextStage : workflowStage,
+          summary: succeeded
+            ? "Training completed successfully."
+            : "Training finished without a successful exit.",
+          payload: {
+            exitCode: status.exitCode,
+            phase: status.phase,
+            lastError: status.lastError,
+            outputPath: nextOutputPath,
+            checkpointPath: nextCheckpointPath || null,
+            checkpointName: nextCheckpointName || null,
+          },
+        });
+      }
+
+      if (status.exitCode === 0) {
+        console.log("Training completed successfully.", status);
+        setTrainingStatus(
+          nextCheckpointName
+            ? `Model ready: ${nextCheckpointName}`
+            : "Training completed successfully! ✓",
+        );
       } else if (status.exitCode !== null) {
-        setTrainingStatus(`Training finished with exit code: ${status.exitCode}`);
+        console.error("Training failed.", status);
+        setTrainingStatus(
+          `Training finished with exit code: ${status.exitCode}`,
+        );
       } else if (status.phase === "failed" && status.lastError) {
+        console.error("Training failed.", status);
         setTrainingStatus(`Training failed: ${status.lastError}`);
       } else {
+        console.warn("Training stopped.", status);
         setTrainingStatus("Training stopped.");
       }
 
@@ -75,32 +247,44 @@ function ModelTraining() {
         pollingIntervalRef.current = null;
       }
     }
-  };
+  }, [
+    appendWorkflowEvent,
+    context?.trainingConfig,
+    setInferenceConfig,
+    setInferenceConfigOriginPath,
+    setInferenceCheckpointPath,
+    setInferenceSelectedYamlPreset,
+    setInferenceUploadedYamlFile,
+    training.configOriginPath,
+    training.outputPath,
+    training.selectedYamlPreset,
+    training.uploadedYamlFile,
+    updateWorkflow,
+    workflowStage,
+  ]);
 
-  const getPreparedTrainingConfig = (trainingConfig) => {
-    try {
-      const yamlData = yaml.load(trainingConfig);
-      if (!yamlData || typeof yamlData !== "object") {
-        return trainingConfig;
+  const recordTrainingPollingFailure = useCallback(
+    async (error) => {
+      if (!terminalLoggedRef.current && appendWorkflowEvent) {
+        terminalLoggedRef.current = true;
+        await appendWorkflowEvent({
+          actor: "system",
+          event_type: "training.failed",
+          stage: workflowStage,
+          summary: "Training status polling failed.",
+          payload: {
+            error: error.message || "unknown error",
+            outputPath: getPathValue(training.outputPath),
+          },
+        });
       }
-
-      applyInputPaths(yamlData, {
-        mode: "training",
-        inputImagePath: getPath(training.inputImage),
-        inputLabelPath: getPath(training.inputLabel),
-        inputPath: "",
-        outputPath: getPath(training.outputPath),
-      });
-      return yaml.dump(yamlData, { indent: 2 }).replace(/^\s*\n/gm, "");
-    } catch (error) {
-      console.warn("Failed to prepare training config from current inputs:", error);
-      return trainingConfig;
-    }
-  };
+    },
+    [appendWorkflowEvent, training.outputPath, workflowStage],
+  );
 
   useEffect(() => {
     refreshTrainingLogs();
-  }, []);
+  }, [refreshTrainingLogs]);
 
   // Poll training status when training is active
   useEffect(() => {
@@ -112,6 +296,7 @@ function ModelTraining() {
         } catch (error) {
           console.error("Error polling training status:", error);
           setIsTraining(false);
+          await recordTrainingPollingFailure(error);
           setTrainingStatus(
             `Training status polling failed: ${error.message || "unknown error"}`,
           );
@@ -127,59 +312,102 @@ function ModelTraining() {
         pollingIntervalRef.current = null;
       }
     };
-  }, [isTraining]);
+  }, [isTraining, recordTrainingPollingFailure, refreshTrainingRuntime]);
 
-  const handleStartButton = async () => {
-    try {
-      const trainingConfig = context.trainingConfig;
-
-      // Accept either uploaded YAML or preset-backed config text.
-      if (!trainingConfig) {
-        setTrainingStatus(
-          "Error: Please load a preset or upload a YAML configuration first.",
-        );
+  const startTrainingRun = useCallback(
+    async (runtimeAction = null) => {
+      if (isTraining) {
+        setTrainingStatus("Training is already running.");
         return;
       }
+      try {
+        setIsTraining(true);
+        setTrainingStatus(
+          "Starting training... Please wait, this may take a while.",
+        );
+        terminalLoggedRef.current = false;
 
-      if (!training.outputPath) {
-        setTrainingStatus("Error: Please set output path first in Step 1.");
-        return;
+        const res = await launchTrainingFromContext(
+          context,
+          workflowId,
+          runtimeAction?.overrides || {},
+        );
+        console.log(res);
+        await refreshTrainingLogs();
+
+        setTrainingStatus(
+          "Training started successfully. Monitoring progress...",
+        );
+      } catch (e) {
+        console.error("Training start error:", e);
+        if (runtimeAction && appendWorkflowEvent) {
+          await appendWorkflowEvent({
+            actor: "system",
+            event_type: "assistant.command_failed",
+            stage: workflowStage,
+            summary: "Assistant could not start training.",
+            payload: {
+              error: e.message || "unknown error",
+              runtime_action: runtimeAction.kind,
+            },
+          });
+        }
+        await refreshTrainingLogs();
+        setTrainingStatus(
+          `Training error: ${e.message || "Please check console for details."}`,
+        );
+        setIsTraining(false);
       }
+    },
+    [
+      appendWorkflowEvent,
+      context,
+      isTraining,
+      refreshTrainingLogs,
+      workflowId,
+      workflowStage,
+    ],
+  );
 
-      console.log(training.uploadedYamlFile);
-      console.log(trainingConfig);
+  useEffect(() => {
+    if (pendingRuntimeAction?.kind !== "start_training") return;
+    const action = pendingRuntimeAction;
+    applyTrainingRunPaths(action);
+    consumeRuntimeAction?.(action.id);
+    startTrainingRun(action);
+  }, [
+    applyTrainingRunPaths,
+    consumeRuntimeAction,
+    pendingRuntimeAction,
+    startTrainingRun,
+  ]);
 
-      setIsTraining(true);
+  useEffect(() => {
+    if (pendingRuntimeAction?.kind !== "monitor_training") return;
+    const action = pendingRuntimeAction;
+    applyTrainingRunPaths(action);
+    consumeRuntimeAction?.(action.id);
+    terminalLoggedRef.current = false;
+    setIsTraining(true);
+    setTrainingStatus("Training started. Monitoring progress...");
+    refreshTrainingRuntime().catch(async (error) => {
+      console.error("Error monitoring approved training run:", error);
+      setIsTraining(false);
+      await recordTrainingPollingFailure(error);
       setTrainingStatus(
-        "Starting training... Please wait, this may take a while.",
+        `Training status polling failed: ${error.message || "unknown error"}`,
       );
+    });
+  }, [
+    consumeRuntimeAction,
+    applyTrainingRunPaths,
+    pendingRuntimeAction,
+    recordTrainingPollingFailure,
+    refreshTrainingRuntime,
+  ]);
 
-      const preparedTrainingConfig = getPreparedTrainingConfig(trainingConfig);
-
-      // TODO: The API call should be non-blocking and return immediately
-      // Real training status should be polled separately
-      const res = await startModelTraining(
-        preparedTrainingConfig,
-        getPath(training.logPath) || getPath(training.outputPath),
-        getPath(training.outputPath),
-        getConfigOriginPath(),
-        workflowContext?.workflow?.id,
-      );
-      console.log(res);
-      await refreshTrainingLogs();
-
-      // TODO: Don't set training complete here - implement proper status polling
-      setTrainingStatus(
-        "Training started successfully. Monitoring progress...",
-      );
-    } catch (e) {
-      console.error("Training start error:", e);
-      await refreshTrainingLogs();
-      setTrainingStatus(
-        `Training error: ${e.message || "Please check console for details."}`,
-      );
-      setIsTraining(false);
-    }
+  const handleStartButton = async () => {
+    await startTrainingRun();
   };
 
   const handleStopButton = async () => {
@@ -198,6 +426,52 @@ function ModelTraining() {
     }
   };
 
+  const handleOpenInference = useCallback(async () => {
+    const effects = { navigate_to: "inference" };
+    if (latestCheckpointPath) {
+      setInferenceCheckpointPath?.(latestCheckpointPath);
+      effects.set_inference_checkpoint_path = latestCheckpointPath;
+    }
+    await runClientEffects?.(effects);
+  }, [latestCheckpointPath, runClientEffects, setInferenceCheckpointPath]);
+
+  const handleOpenTensorboard = useCallback(async () => {
+    try {
+      const response = await startTensorboard(resolvedTrainingOutputPath);
+      const url = response?.url || response?.tensorboard_url || response;
+      if (url && typeof url === "string") {
+        context?.setTensorBoardURL?.(url);
+        if (
+          typeof window !== "undefined" &&
+          typeof window.open === "function"
+        ) {
+          window.open(url, "_blank", "noopener,noreferrer");
+        }
+        message.success("TensorBoard opened for this training run.");
+      } else {
+        message.success("TensorBoard is starting for this training run.");
+      }
+      await refreshTrainingLogs();
+      await runClientEffects?.({ navigate_to: "training" });
+    } catch (error) {
+      message.error(error.message || "Failed to start TensorBoard.");
+    }
+  }, [
+    context,
+    refreshTrainingLogs,
+    resolvedTrainingOutputPath,
+    runClientEffects,
+  ]);
+
+  const handleRevealOutput = useCallback(async () => {
+    if (!resolvedTrainingOutputPath) return;
+    try {
+      await revealInFinder(resolvedTrainingOutputPath);
+    } catch (error) {
+      console.error("Error revealing training output:", error);
+    }
+  }, [resolvedTrainingOutputPath]);
+
   // const handleTensorboardButton = async () => {
   //   try {
   //     const res = await startTensorboard();
@@ -216,6 +490,13 @@ function ModelTraining() {
     <>
       <div>
         {/* {"ModelTraining"} */}
+        <div style={{ marginBottom: 12 }}>
+          <StageHeader
+            stage={workflowStage}
+            title="Train Model"
+            subtitle="Train a candidate model from staged corrections and register the resulting checkpoint."
+          />
+        </div>
         <Configurator fileList={context.files} type="training" />
         <Space wrap style={{ marginTop: 12 }}>
           <Button onClick={handleStartButton} disabled={isTraining}>
@@ -226,8 +507,56 @@ function ModelTraining() {
           </Button>
         </Space>
         <p style={{ marginTop: 4 }}>{trainingStatus}</p>
+        {trainingRuntime?.phase === "finished" && (
+          <div
+            style={{
+              marginTop: 12,
+              padding: "12px 14px",
+              borderRadius: 8,
+              border: "1px solid #d9f7be",
+              background: "#f6ffed",
+            }}
+          >
+            <Space direction="vertical" size={6} style={{ display: "flex" }}>
+              <Space size={8} wrap>
+                <Text strong>
+                  {latestCheckpointName ? "Model Ready" : "Training Complete"}
+                </Text>
+                {latestCheckpointName && (
+                  <Tag color="success" style={{ margin: 0 }}>
+                    {latestCheckpointName}
+                  </Tag>
+                )}
+              </Space>
+              {resolvedTrainingOutputPath && (
+                <Text type="secondary" style={{ fontSize: 12 }}>
+                  {`Output: ${getBaseName(resolvedTrainingOutputPath) || resolvedTrainingOutputPath}`}
+                </Text>
+              )}
+              <Space wrap size={8}>
+                <Button
+                  size="small"
+                  type="primary"
+                  onClick={handleOpenInference}
+                >
+                  Open Run Model
+                </Button>
+                <Button size="small" onClick={handleOpenTensorboard}>
+                  TensorBoard
+                </Button>
+                <Button
+                  size="small"
+                  onClick={handleRevealOutput}
+                  disabled={!resolvedTrainingOutputPath}
+                >
+                  Show Output
+                </Button>
+              </Space>
+            </Space>
+          </div>
+        )}
         <RuntimeLogPanel
-          title="Training Runtime Log"
+          title="Train Model Runtime"
           runtime={trainingRuntime}
           onRefresh={refreshTrainingLogs}
         />
diff --git a/client/src/views/Monitoring.js b/client/src/views/Monitoring.js
index 35d0daca..28ef149f 100644
--- a/client/src/views/Monitoring.js
+++ b/client/src/views/Monitoring.js
@@ -1,38 +1,240 @@
-import React, { useState, useEffect } from "react";
-import { getTensorboardURL } from "../api";
+import React, { useCallback, useEffect, useMemo, useState } from "react";
+import {
+  Alert,
+  Button,
+  Card,
+  Space,
+  Spin,
+  Tag,
+  Typography,
+  message,
+} from "antd";
+import { getTensorboardStatus, startTensorboard } from "../api";
+import WorkflowEvidencePanel from "../components/workflow/WorkflowEvidencePanel";
+
+const phaseColors = {
+  idle: "default",
+  starting: "processing",
+  running: "success",
+  finished: "default",
+  failed: "error",
+  stopped: "warning",
+};
+
+function formatValue(value) {
+  if (value === null || value === undefined || value === "") {
+    return "—";
+  }
+  return String(value);
+}
 
 function Monitoring() {
-  const [tensorboardURL, setTensorboardURL] = useState(null);
+  const [tensorboardStatus, setTensorboardStatus] = useState(null);
+  const [loading, setLoading] = useState(true);
+  const [starting, setStarting] = useState(false);
 
-  const callGetTensorboardURL = async () => {
+  const loadTensorboardStatus = useCallback(async ({ silent = false } = {}) => {
+    if (!silent) {
+      setLoading(true);
+    }
     try {
-      const res = await getTensorboardURL();
-      console.log(res);
-      setTensorboardURL(res);
-    } catch (e) {
-      console.log(e);
+      const status = await getTensorboardStatus();
+      setTensorboardStatus(status);
+    } catch (error) {
+      console.error("Error loading TensorBoard status:", error);
+      if (!silent) {
+        message.error(
+          error.message || "Failed to load TensorBoard monitoring status.",
+        );
+      }
+    } finally {
+      if (!silent) {
+        setLoading(false);
+      }
     }
-  };
+  }, []);
 
   useEffect(() => {
-    if (!tensorboardURL) {
-      callGetTensorboardURL();
+    loadTensorboardStatus();
+    const intervalId = setInterval(() => {
+      loadTensorboardStatus({ silent: true });
+    }, 3000);
+    return () => clearInterval(intervalId);
+  }, [loadTensorboardStatus]);
+
+  const handleStartTensorboard = async () => {
+    try {
+      setStarting(true);
+      const response = await startTensorboard();
+      message.success(
+        response?.tensorboard?.isRunning
+          ? "TensorBoard is ready."
+          : "TensorBoard is starting.",
+      );
+      await loadTensorboardStatus();
+    } catch (error) {
+      console.error("Error starting TensorBoard:", error);
+      message.error(error.message || "Failed to start TensorBoard.");
+    } finally {
+      setStarting(false);
     }
-  }, [tensorboardURL]);
+  };
+
+  const sourceEntries = useMemo(
+    () => Object.entries(tensorboardStatus?.sources || {}),
+    [tensorboardStatus],
+  );
+
+  const phase = tensorboardStatus?.phase || "idle";
+  const isRunning = Boolean(tensorboardStatus?.isRunning);
+  const hasSources = sourceEntries.length > 0;
 
   return (
-    <>
-      {tensorboardURL && (
-        <iframe
-          title="Tensorboard Display"
-          width="100%"
-          height="800"
-          frameBorder="0"
-          scrolling="no"
-          src={tensorboardURL}
-        />
-      )}
-    </>
+    <div style={{ display: "flex", flexDirection: "column", gap: 16 }}>
+      <WorkflowEvidencePanel />
+
+      <Card>
+        <div
+          style={{
+            display: "flex",
+            justifyContent: "space-between",
+            gap: 16,
+            flexWrap: "wrap",
+            alignItems: "flex-start",
+          }}
+        >
+          <Space direction="vertical" size={4}>
+            <Space wrap size={8}>
+              <Typography.Text strong>TensorBoard</Typography.Text>
+              <Tag color={phaseColors[phase] || "default"}>{phase}</Tag>
+              <Typography.Text type="secondary">
+                PID {formatValue(tensorboardStatus?.pid)}
+              </Typography.Text>
+              <Typography.Text type="secondary">
+                Port {formatValue(tensorboardStatus?.port)}
+              </Typography.Text>
+            </Space>
+            {tensorboardStatus?.url && (
+              <Typography.Link
+                href={tensorboardStatus.url}
+                target="_blank"
+                rel="noreferrer"
+              >
+                {tensorboardStatus.url}
+              </Typography.Link>
+            )}
+          </Space>
+          <Space wrap>
+            <Button onClick={() => loadTensorboardStatus()} disabled={loading}>
+              Refresh
+            </Button>
+            <Button
+              type="primary"
+              onClick={handleStartTensorboard}
+              disabled={!hasSources}
+              loading={starting}
+            >
+              {isRunning ? "Refresh TensorBoard" : "Start TensorBoard"}
+            </Button>
+          </Space>
+        </div>
+
+        {tensorboardStatus?.lastError && (
+          <Alert
+            style={{ marginTop: 16 }}
+            type="error"
+            showIcon
+            message={tensorboardStatus.lastError}
+          />
+        )}
+
+        <div
+          style={{
+            marginTop: 16,
+            display: "grid",
+            gridTemplateColumns: "repeat(auto-fit, minmax(240px, 1fr))",
+            gap: 12,
+          }}
+        >
+          <Card size="small" title="Process">
+            <div>Started: {formatValue(tensorboardStatus?.startedAt)}</div>
+            <div>Ended: {formatValue(tensorboardStatus?.endedAt)}</div>
+            <div>Updated: {formatValue(tensorboardStatus?.lastUpdatedAt)}</div>
+            <div>Command: {formatValue(tensorboardStatus?.command)}</div>
+          </Card>
+          <Card size="small" title="Watched Sources">
+            {hasSources ? (
+              <Space direction="vertical" size={8} style={{ width: "100%" }}>
+                {sourceEntries.map(([key, source]) => (
+                  <div
+                    key={key}
+                    style={{
+                      padding: "8px 10px",
+                      border: "1px solid #f0f0f0",
+                      borderRadius: 8,
+                      background: "#fafafa",
+                    }}
+                  >
+                    <div style={{ fontWeight: 600 }}>{source.name}</div>
+                    <div style={{ wordBreak: "break-word", color: "#595959" }}>
+                      {source.path}
+                    </div>
+                    <div
+                      style={{ color: source.exists ? "#389e0d" : "#d46b08" }}
+                    >
+                      {source.exists ? "Directory ready" : "Directory missing"}
+                    </div>
+                  </div>
+                ))}
+              </Space>
+            ) : (
+              <Typography.Text type="secondary">
+                No training or inference output directories have been registered
+                yet.
+              </Typography.Text>
+            )}
+          </Card>
+        </div>
+      </Card>
+
+      <Card bodyStyle={{ padding: 12 }}>
+        {loading && !tensorboardStatus ? (
+          <div
+            style={{
+              minHeight: 640,
+              display: "flex",
+              alignItems: "center",
+              justifyContent: "center",
+            }}
+          >
+            <Spin tip="Loading TensorBoard status..." />
+          </div>
+        ) : isRunning && tensorboardStatus?.url ? (
+          <iframe
+            title="TensorBoard Display"
+            width="100%"
+            height="800"
+            frameBorder="0"
+            src={tensorboardStatus.url}
+            style={{
+              border: "1px solid #f0f0f0",
+              borderRadius: 10,
+              minHeight: 800,
+              background: "#fff",
+            }}
+          />
+        ) : (
+          <Alert
+            type={hasSources ? "warning" : "info"}
+            showIcon
+            message={
+              hasSources ? "TensorBoard is stopped." : "No log directory yet."
+            }
+          />
+        )}
+      </Card>
+    </div>
   );
 }
+
 export default Monitoring;
diff --git a/client/src/views/ProjectProgress.js b/client/src/views/ProjectProgress.js
new file mode 100644
index 00000000..1a4eca99
--- /dev/null
+++ b/client/src/views/ProjectProgress.js
@@ -0,0 +1,456 @@
+import React, { useEffect, useMemo, useState } from "react";
+import {
+  Button,
+  Card,
+  Empty,
+  Progress,
+  Select,
+  Space,
+  Table,
+  Tag,
+  Typography,
+} from "antd";
+import {
+  CheckCircleOutlined,
+  ClockCircleOutlined,
+  DatabaseOutlined,
+  ReloadOutlined,
+  WarningOutlined,
+} from "@ant-design/icons";
+import { useWorkflow } from "../contexts/WorkflowContext";
+import { logClientEvent } from "../logging/appEventLog";
+
+const { Text, Title } = Typography;
+
+const STATUS_OPTIONS = [
+  { value: "ground_truth", label: "Fully good" },
+  { value: "needs_proofreading", label: "Needs proofreading" },
+  { value: "missing_segmentation", label: "No segmentation" },
+  { value: "ignored", label: "Ignored" },
+];
+
+const STATUS_META = {
+  ground_truth: { color: "green", icon: <CheckCircleOutlined /> },
+  needs_proofreading: { color: "gold", icon: <ClockCircleOutlined /> },
+  missing_segmentation: { color: "red", icon: <WarningOutlined /> },
+  ignored: { color: "default", icon: <DatabaseOutlined /> },
+};
+
+const METRIC_TONE_COLORS = {
+  default: "#111827",
+  good: "#047857",
+  warn: "#b45309",
+  bad: "#b91c1c",
+};
+
+function shortPath(path) {
+  if (!path) return "Not found";
+  const parts = String(path)
+    .split(/[\\/]+/)
+    .filter(Boolean);
+  if (parts.length <= 3) return parts.join("/");
+  return parts.slice(-3).join("/");
+}
+
+function statusTag(status, label) {
+  const meta = STATUS_META[status] || STATUS_META.ignored;
+  return (
+    <Tag color={meta.color} icon={meta.icon} style={{ margin: 0 }}>
+      {label || status}
+    </Tag>
+  );
+}
+
+function MetricCard({ title, value, detail, tone = "default" }) {
+  const color = METRIC_TONE_COLORS[tone] || METRIC_TONE_COLORS.default;
+  return (
+    <Card size="small" styles={{ body: { padding: 14 } }}>
+      <Text type="secondary" style={{ fontSize: 12 }}>
+        {title}
+      </Text>
+      <div style={{ color, fontSize: 28, fontWeight: 700, lineHeight: 1.15 }}>
+        {value}
+      </div>
+      {detail && (
+        <Text type="secondary" style={{ fontSize: 12 }}>
+          {detail}
+        </Text>
+      )}
+    </Card>
+  );
+}
+
+function ProjectProgress() {
+  const workflowContext = useWorkflow();
+  const {
+    workflow,
+    workflowOverview,
+    projectProgress,
+    refreshProjectProgress,
+    updateProjectProgressVolume,
+    runClientEffects,
+  } = workflowContext || {};
+  const [loading, setLoading] = useState(false);
+  const [filter, setFilter] = useState("all");
+
+  const loadProgress = async ({ source = "project_progress_view" } = {}) => {
+    if (!workflow?.id || !refreshProjectProgress) return null;
+    setLoading(true);
+    try {
+      const progress = await refreshProjectProgress();
+      logClientEvent("project_progress_refreshed", {
+        source,
+        message: "Project progress view refreshed",
+        data: {
+          workflowId: workflow.id,
+          total: progress?.summary?.total || 0,
+        },
+      });
+      return progress;
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  useEffect(() => {
+    loadProgress({ source: "project_progress_mount" });
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [workflow?.id]);
+
+  const summary = projectProgress?.summary || {};
+  const stages = workflowOverview?.stages || [];
+  const blockers = workflowOverview?.blockers || [];
+  const actions = workflowOverview?.recommended_next_actions || [];
+  const filteredVolumes = useMemo(() => {
+    const volumes = projectProgress?.volumes || [];
+    if (filter === "all") return volumes;
+    return volumes.filter((volume) => volume.status === filter);
+  }, [filter, projectProgress?.volumes]);
+
+  const handleOverviewAction = async (action) => {
+    if (!action) return;
+    const effects = action.client_effects?.navigate_to
+      ? action.client_effects
+      : { navigate_to: action.target_view || "project-progress" };
+    await runClientEffects?.(effects);
+  };
+
+  const handleStatusChange = async (volumeId, status) => {
+    if (!workflow?.id || !updateProjectProgressVolume) return;
+    setLoading(true);
+    try {
+      await updateProjectProgressVolume({ volume_id: volumeId, status });
+      logClientEvent("project_progress_volume_status_changed", {
+        source: "project_progress_view",
+        message: "Project progress volume status changed",
+        data: { workflowId: workflow.id, volumeId, status },
+      });
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  const columns = [
+    {
+      title: "Volume",
+      dataIndex: "name",
+      key: "name",
+      render: (_, volume) => (
+        <Space direction="vertical" size={0}>
+          <Text strong>{volume.name}</Text>
+          <Text type="secondary" style={{ fontSize: 12 }}>
+            {shortPath(volume.image_path)}
+          </Text>
+        </Space>
+      ),
+    },
+    {
+      title: "Status",
+      dataIndex: "status",
+      key: "status",
+      width: 210,
+      render: (_, volume) => (
+        <Space direction="vertical" size={6}>
+          {statusTag(volume.status, volume.status_label)}
+          <Select
+            size="small"
+            value={volume.status}
+            options={STATUS_OPTIONS}
+            style={{ width: 170 }}
+            onChange={(status) => handleStatusChange(volume.id, status)}
+          />
+        </Space>
+      ),
+    },
+    {
+      title: "Segmentation",
+      dataIndex: "segmentation_path",
+      key: "segmentation_path",
+      render: (_, volume) => (
+        <Space direction="vertical" size={0}>
+          <Text>{shortPath(volume.segmentation_path)}</Text>
+          <Text type="secondary" style={{ fontSize: 12 }}>
+            {volume.segmentation_kind || "none"}
+            {volume.status_source ? ` · ${volume.status_source}` : ""}
+          </Text>
+        </Space>
+      ),
+    },
+    {
+      title: "Set",
+      dataIndex: "volume_set_name",
+      key: "volume_set_name",
+      width: 180,
+      render: (value) => value || "Current workflow",
+    },
+  ];
+
+  if (!workflow?.id) {
+    return <Empty description="Start or mount a workflow to track progress." />;
+  }
+
+  return (
+    <div style={{ maxWidth: 1280, margin: "0 auto", paddingBottom: 24 }}>
+      <div
+        style={{
+          alignItems: "flex-start",
+          display: "flex",
+          justifyContent: "space-between",
+          gap: 16,
+          marginBottom: 16,
+        }}
+      >
+        <Space direction="vertical" size={4}>
+          <Title level={3} style={{ margin: 0 }}>
+            Workflow Overview
+          </Title>
+          <Text type="secondary">
+            Shared workflow map for the user, agent, volume statuses, blockers,
+            and next actions.
+          </Text>
+        </Space>
+        <Button
+          icon={<ReloadOutlined />}
+          onClick={() => loadProgress()}
+          loading={loading}
+        >
+          Refresh
+        </Button>
+      </div>
+
+      <Card size="small" style={{ marginBottom: 16 }}>
+        <Space direction="vertical" size={12} style={{ width: "100%" }}>
+          <Space
+            align="center"
+            style={{ width: "100%", justifyContent: "space-between" }}
+          >
+            <Space direction="vertical" size={2}>
+              <Text strong>
+                Current phase:{" "}
+                {workflowOverview?.phase_label || workflow?.stage || "Setup"}
+              </Text>
+              <Text type="secondary">
+                {workflowOverview?.phase_reason ||
+                  "The workflow is waiting for project state."}
+              </Text>
+            </Space>
+            <Text type="secondary">
+              {workflowOverview?.active_runs?.length
+                ? `${workflowOverview.active_runs.length} active run(s)`
+                : "No active run"}
+            </Text>
+          </Space>
+          {stages.length > 0 && (
+            <div
+              style={{
+                display: "grid",
+                gap: 8,
+                gridTemplateColumns: "repeat(auto-fit, minmax(110px, 1fr))",
+              }}
+            >
+              {stages.map((stage) => (
+                <button
+                  key={stage.id}
+                  type="button"
+                  onClick={() =>
+                    runClientEffects?.({ navigate_to: stage.target_view })
+                  }
+                  style={{
+                    border: stage.current
+                      ? "1px solid #4338ca"
+                      : "1px solid #e5e7eb",
+                    borderRadius: 8,
+                    background: stage.current
+                      ? "#eef2ff"
+                      : stage.complete
+                        ? "#f0fdf4"
+                        : "#fff",
+                    color: stage.blocked ? "#b91c1c" : "#111827",
+                    cursor: "pointer",
+                    padding: "8px 10px",
+                    textAlign: "left",
+                    minHeight: 58,
+                  }}
+                >
+                  <div style={{ fontWeight: 650 }}>{stage.label}</div>
+                  <div style={{ color: "#6b7280", fontSize: 12 }}>
+                    {stage.current
+                      ? "Current"
+                      : stage.complete
+                        ? "Done"
+                        : stage.blocked
+                          ? "Needs attention"
+                          : "Upcoming"}
+                  </div>
+                </button>
+              ))}
+            </div>
+          )}
+        </Space>
+      </Card>
+
+      <div
+        style={{
+          display: "grid",
+          gap: 12,
+          gridTemplateColumns: "repeat(auto-fit, minmax(180px, 1fr))",
+          marginBottom: 16,
+        }}
+      >
+        <MetricCard
+          title="Tracked volumes"
+          value={summary.tracked_total ?? summary.total ?? 0}
+          detail={`${summary.completion_pct ?? 0}% fully good`}
+        />
+        <MetricCard
+          title="Fully good"
+          value={summary.ground_truth ?? 0}
+          detail="proofread ground truth"
+          tone="good"
+        />
+        <MetricCard
+          title="Needs proofreading"
+          value={summary.needs_proofreading ?? 0}
+          detail="segmentation exists"
+          tone="warn"
+        />
+        <MetricCard
+          title="No segmentation"
+          value={summary.missing_segmentation ?? 0}
+          detail="image only"
+          tone="bad"
+        />
+      </div>
+
+      <Card size="small" style={{ marginBottom: 16 }}>
+        <Space direction="vertical" size={8} style={{ width: "100%" }}>
+          <Space
+            align="center"
+            style={{ width: "100%", justifyContent: "space-between" }}
+          >
+            <Text strong>Completion</Text>
+            <Text type="secondary">{summary.remaining ?? 0} remaining</Text>
+          </Space>
+          <Progress
+            percent={summary.completion_pct || 0}
+            success={{ percent: summary.completion_pct || 0 }}
+          />
+          <Text type="secondary">
+            Segmentation coverage: {summary.segmentation_coverage_pct || 0}%
+            have some mask or segmentation.
+          </Text>
+        </Space>
+      </Card>
+
+      {(blockers.length > 0 || actions.length > 0) && (
+        <div
+          style={{
+            display: "grid",
+            gap: 12,
+            gridTemplateColumns: "repeat(auto-fit, minmax(280px, 1fr))",
+            marginBottom: 16,
+          }}
+        >
+          <Card size="small" title="What needs attention">
+            {blockers.length ? (
+              <Space direction="vertical" size={10} style={{ width: "100%" }}>
+                {blockers.map((blocker) => (
+                  <Space
+                    key={blocker.id}
+                    direction="vertical"
+                    size={2}
+                    style={{ width: "100%" }}
+                  >
+                    <Text strong>{blocker.label}</Text>
+                    <Text type="secondary">{blocker.detail}</Text>
+                  </Space>
+                ))}
+              </Space>
+            ) : (
+              <Text type="secondary">No blockers are currently detected.</Text>
+            )}
+          </Card>
+          <Card size="small" title="Recommended next moves">
+            {actions.length ? (
+              <Space direction="vertical" size={10} style={{ width: "100%" }}>
+                {actions.map((action) => (
+                  <div
+                    key={action.id}
+                    style={{
+                      display: "flex",
+                      gap: 12,
+                      justifyContent: "space-between",
+                      alignItems: "flex-start",
+                    }}
+                  >
+                    <Space direction="vertical" size={2}>
+                      <Text strong>{action.label}</Text>
+                      <Text type="secondary">{action.detail}</Text>
+                    </Space>
+                    <Button
+                      size="small"
+                      onClick={() => handleOverviewAction(action)}
+                    >
+                      Open
+                    </Button>
+                  </div>
+                ))}
+              </Space>
+            ) : (
+              <Text type="secondary">No next move is suggested yet.</Text>
+            )}
+          </Card>
+        </div>
+      )}
+
+      <Space wrap style={{ marginBottom: 12 }}>
+        <Select
+          value={filter}
+          style={{ width: 220 }}
+          onChange={setFilter}
+          options={[{ value: "all", label: "All volumes" }, ...STATUS_OPTIONS]}
+        />
+        {STATUS_OPTIONS.map((option) => (
+          <Tag
+            key={option.value}
+            color={STATUS_META[option.value]?.color || "default"}
+            title={projectProgress?.status_definitions?.[option.value]}
+          >
+            {option.label}
+          </Tag>
+        ))}
+      </Space>
+
+      <Table
+        rowKey="id"
+        loading={loading}
+        columns={columns}
+        dataSource={filteredVolumes}
+        pagination={{ pageSize: 25, hideOnSinglePage: true }}
+        locale={{ emptyText: "No tracked volumes found yet." }}
+      />
+    </div>
+  );
+}
+
+export default ProjectProgress;
diff --git a/client/src/views/ProjectProgress.test.js b/client/src/views/ProjectProgress.test.js
new file mode 100644
index 00000000..0e38957a
--- /dev/null
+++ b/client/src/views/ProjectProgress.test.js
@@ -0,0 +1,140 @@
+import React from "react";
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
+
+import ProjectProgress from "./ProjectProgress";
+
+let mockWorkflowContext;
+
+jest.mock("../contexts/WorkflowContext", () => ({
+  useWorkflow: () => mockWorkflowContext,
+}));
+
+jest.mock("../logging/appEventLog", () => ({
+  logClientEvent: jest.fn(),
+}));
+
+describe("ProjectProgress", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    window.matchMedia = jest.fn().mockImplementation((query) => ({
+      matches: false,
+      media: query,
+      onchange: null,
+      addListener: jest.fn(),
+      removeListener: jest.fn(),
+      addEventListener: jest.fn(),
+      removeEventListener: jest.fn(),
+      dispatchEvent: jest.fn(),
+    }));
+    mockWorkflowContext = {
+      workflow: { id: 1 },
+      workflowOverview: {
+        phase: "proofread",
+        phase_label: "Proofread",
+        phase_reason: "One draft mask still needs review.",
+        stages: [
+          {
+            id: "setup",
+            label: "Setup",
+            target_view: "files",
+            complete: true,
+            current: false,
+          },
+          {
+            id: "proofread",
+            label: "Proofread",
+            target_view: "mask-proofreading",
+            complete: false,
+            current: true,
+          },
+        ],
+        blockers: [
+          {
+            id: "draft_masks_need_review",
+            label: "Draft masks need review",
+            detail: "1 volume has a mask that is not marked ground truth.",
+            target_view: "mask-proofreading",
+          },
+        ],
+        recommended_next_actions: [
+          {
+            id: "proofread-draft-masks",
+            label: "Proofread draft masks",
+            detail: "Review the draft mask before treating it as ground truth.",
+            target_view: "mask-proofreading",
+            client_effects: { navigate_to: "mask-proofreading" },
+          },
+        ],
+        active_runs: [],
+      },
+      projectProgress: {
+        summary: {
+          total: 3,
+          tracked_total: 3,
+          ground_truth: 1,
+          needs_proofreading: 1,
+          missing_segmentation: 1,
+          remaining: 2,
+          completion_pct: 33.3,
+          segmentation_coverage_pct: 66.7,
+        },
+        status_definitions: {},
+        volumes: [
+          {
+            id: "data/image/vol_a_im.h5",
+            name: "vol_a_im.h5",
+            status: "ground_truth",
+            status_label: "Fully good",
+            status_source: "path_marker",
+            image_path: "/tmp/project/data/image/vol_a_im.h5",
+            segmentation_path: "/tmp/project/data/seg/vol_a_gt.h5",
+            segmentation_kind: "label",
+            volume_set_name: "image + seg",
+          },
+        ],
+      },
+      refreshProjectProgress: jest.fn().mockResolvedValue({
+        summary: { total: 3 },
+      }),
+      updateProjectProgressVolume: jest.fn().mockResolvedValue({}),
+      runClientEffects: jest.fn().mockResolvedValue(),
+    };
+  });
+
+  it("renders the workflow project progress summary", async () => {
+    render(<ProjectProgress />);
+
+    expect(await screen.findByText("Workflow Overview")).toBeTruthy();
+    expect(screen.getByText("Current phase: Proofread")).toBeTruthy();
+    expect(screen.getByText("Recommended next moves")).toBeTruthy();
+    expect(screen.getByText("Tracked volumes")).toBeTruthy();
+    expect(screen.getAllByText("Fully good").length).toBeGreaterThan(0);
+    expect(screen.getAllByText("Needs proofreading").length).toBeGreaterThan(0);
+    expect(screen.getAllByText("No segmentation").length).toBeGreaterThan(0);
+    expect(screen.getByText("vol_a_im.h5")).toBeTruthy();
+    await waitFor(() => {
+      expect(mockWorkflowContext.refreshProjectProgress).toHaveBeenCalled();
+    });
+  });
+
+  it("refreshes on demand", async () => {
+    render(<ProjectProgress />);
+
+    await waitFor(() => {
+      expect(mockWorkflowContext.refreshProjectProgress).toHaveBeenCalledTimes(
+        1,
+      );
+    });
+    const refreshButton = screen.getByRole("button", { name: /Refresh/ });
+    await waitFor(() => {
+      expect(refreshButton.className).not.toContain("ant-btn-loading");
+    });
+    fireEvent.click(refreshButton);
+
+    await waitFor(() => {
+      expect(mockWorkflowContext.refreshProjectProgress).toHaveBeenCalledTimes(
+        2,
+      );
+    });
+  });
+});
diff --git a/client/src/views/Views.js b/client/src/views/Views.js
index 82282ce6..8cd60b5c 100644
--- a/client/src/views/Views.js
+++ b/client/src/views/Views.js
@@ -1,11 +1,10 @@
 import React, { useState, useEffect, useRef, useCallback } from "react";
-import { Layout, Menu, Button, Drawer } from "antd";
+import { Layout, Menu, Button, Drawer, message } from "antd";
 import {
   FolderOpenOutlined,
   EyeOutlined,
   ExperimentOutlined,
   ThunderboltOutlined,
-  DashboardOutlined,
   BugOutlined,
   MessageOutlined,
   ProjectOutlined,
@@ -14,26 +13,31 @@ import FilesManager from "./FilesManager";
 import Visualization from "./Visualization";
 import ModelTraining from "./ModelTraining";
 import ModelInference from "./ModelInference";
-import Monitoring from "./Monitoring";
 import MaskProofreading from "./MaskProofreading";
 import ProjectManager from "./project-manager/ProjectManager";
+import ProjectProgress from "./ProjectProgress";
 import Chatbot from "../components/Chatbot";
 import { useWorkflow } from "../contexts/WorkflowContext";
+import { logClientEvent } from "../logging/appEventLog";
 
 const { Content } = Layout;
 
 const MODULE_ITEMS = [
-  { label: "File Management", key: "files", icon: <FolderOpenOutlined /> },
-  { label: "Visualization", key: "visualization", icon: <EyeOutlined /> },
-  { label: "Model Training", key: "training", icon: <ExperimentOutlined /> },
+  { label: "Files", key: "files", icon: <FolderOpenOutlined /> },
+  { label: "Visualize", key: "visualization", icon: <EyeOutlined /> },
+  { label: "Train Model", key: "training", icon: <ExperimentOutlined /> },
   {
-    label: "Model Inference",
+    label: "Run Model",
     key: "inference",
     icon: <ThunderboltOutlined />,
   },
-  { label: "Tensorboard", key: "monitoring", icon: <DashboardOutlined /> },
   {
-    label: "Mask Proofreading",
+    label: "Workflow",
+    key: "project-progress",
+    icon: <ProjectOutlined />,
+  },
+  {
+    label: "Proofread",
     key: "mask-proofreading",
     icon: <BugOutlined />,
   },
@@ -44,15 +48,136 @@ const MODULE_ITEMS = [
   },
 ];
 
+const formatCount = (value, label) => `${Number(value || 0)} ${label}`;
+
+const workflowPhaseTone = {
+  setup: "#6b7280",
+  inspect: "#2563eb",
+  proofread: "#b45309",
+  train: "#4338ca",
+  infer: "#047857",
+  evaluate: "#7c3aed",
+};
+
+function WorkflowOverviewStrip({ overview, workflow, onNavigate }) {
+  const summary = overview?.volume_summary || {};
+  const phase = overview?.phase || workflow?.stage || "setup";
+  const phaseLabel =
+    overview?.phase_label || String(phase || "Setup").replace(/_/g, " ");
+  const projectName =
+    overview?.project_name || workflow?.title || "Segmentation workflow";
+  const blocker = overview?.blockers?.[0] || null;
+  const activeRun = overview?.active_runs?.[0] || null;
+  const action = overview?.recommended_next_actions?.[0] || null;
+  const tone = workflowPhaseTone[phase] || "#4338ca";
+  const counts = [
+    formatCount(summary.ground_truth, "GT"),
+    formatCount(summary.needs_proofreading, "draft"),
+    formatCount(summary.missing_segmentation, "missing"),
+  ];
+
+  return (
+    <div
+      aria-label="Workflow overview"
+      style={{
+        display: "flex",
+        alignItems: "center",
+        gap: 12,
+        padding: "8px 14px",
+        borderBottom: "1px solid #eceef3",
+        background: "#fbfbfd",
+        minHeight: 42,
+        overflowX: "auto",
+        whiteSpace: "nowrap",
+      }}
+    >
+      <button
+        type="button"
+        onClick={() => onNavigate("project-progress")}
+        style={{
+          border: "none",
+          background: "transparent",
+          padding: 0,
+          color: "#111827",
+          fontWeight: 650,
+          cursor: "pointer",
+        }}
+      >
+        {projectName}
+      </button>
+      <span
+        style={{
+          color: tone,
+          border: `1px solid ${tone}`,
+          borderRadius: 999,
+          padding: "2px 9px",
+          fontSize: 12,
+          fontWeight: 650,
+          textTransform: "capitalize",
+        }}
+      >
+        {phaseLabel}
+      </span>
+      <button
+        type="button"
+        onClick={() => onNavigate("project-progress")}
+        style={{
+          border: "none",
+          background: "transparent",
+          color: "#4b5563",
+          cursor: "pointer",
+          padding: 0,
+        }}
+      >
+        {counts.join(" · ")}
+      </button>
+      {activeRun ? (
+        <span style={{ color: "#4338ca", fontWeight: 600 }}>
+          {activeRun.run_type} {activeRun.status}
+        </span>
+      ) : blocker ? (
+        <button
+          type="button"
+          onClick={() => onNavigate(blocker.target_view || "project-progress")}
+          style={{
+            border: "none",
+            background: "transparent",
+            color: blocker.severity === "blocking" ? "#b91c1c" : "#92400e",
+            cursor: "pointer",
+            padding: 0,
+          }}
+          title={blocker.detail}
+        >
+          {blocker.label}
+        </button>
+      ) : (
+        <span style={{ color: "#047857", fontWeight: 600 }}>No blockers</span>
+      )}
+      {action && (
+        <Button
+          size="small"
+          onClick={() => onNavigate(action.target_view)}
+          style={{ marginLeft: "auto" }}
+        >
+          {action.label}
+        </Button>
+      )}
+    </div>
+  );
+}
+
 function Views() {
   const [current, setCurrent] = useState("files");
   const [visitedTabs, setVisitedTabs] = useState(new Set(["files"]));
   const workflowContext = useWorkflow();
   const lastClientEffects = workflowContext?.lastClientEffects;
   const consumeClientEffects = workflowContext?.consumeClientEffects;
+  const refreshProjectProgress = workflowContext?.refreshProjectProgress;
   const [isChatOpen, setIsChatOpen] = useState(false);
-  const [chatWidth, setChatWidth] = useState(560);
+  const [quickAgentRequest, setQuickAgentRequest] = useState(null);
+  const [chatWidth, setChatWidth] = useState(460);
   const isResizing = useRef(false);
+  const quickAgentRequestId = useRef(0);
 
   const [viewers, setViewers] = useState([]);
   const [isInferring, setIsInferring] = useState(false);
@@ -89,6 +214,14 @@ function Views() {
     setVisitedTabs((prev) => new Set(prev).add(e.key));
   };
 
+  const navigateTo = useCallback((key) => {
+    if (!key) return;
+    const targetKey =
+      key === "monitoring" || key === "model-training" ? "training" : key;
+    setCurrent(targetKey);
+    setVisitedTabs((prev) => new Set(prev).add(targetKey));
+  }, []);
+
   const startResizing = useCallback((e) => {
     isResizing.current = true;
     e.preventDefault();
@@ -117,13 +250,94 @@ function Views() {
   }, [resize, stopResizing]);
 
   useEffect(() => {
-    const target = lastClientEffects?.navigate_to;
-    if (!target) return;
-    const targetKey = target === "model-training" ? "training" : target;
-    setCurrent(targetKey);
-    setVisitedTabs((prev) => new Set(prev).add(targetKey));
+    if (!lastClientEffects) return;
+    const target = lastClientEffects.navigate_to;
+    if (target) {
+      navigateTo(target);
+    }
+    if (lastClientEffects.open_assistant) {
+      setIsChatOpen(true);
+    }
+    if (lastClientEffects.show_workflow_context) {
+      navigateTo("project-progress");
+    }
+    if (lastClientEffects.refresh_project_progress) {
+      refreshProjectProgress?.();
+    }
     consumeClientEffects?.();
-  }, [lastClientEffects, consumeClientEffects]);
+  }, [
+    lastClientEffects,
+    consumeClientEffects,
+    refreshProjectProgress,
+    navigateTo,
+  ]);
+
+  useEffect(() => {
+    logClientEvent("view_changed", {
+      level: "INFO",
+      message: `Switched to ${current}`,
+      source: "views",
+      data: { view: current },
+    });
+  }, [current]);
+
+  useEffect(() => {
+    logClientEvent(isChatOpen ? "chat_opened" : "chat_closed", {
+      level: "INFO",
+      message: isChatOpen
+        ? "Assistant drawer opened"
+        : "Assistant drawer closed",
+      source: "views",
+      data: { width: chatWidth },
+    });
+  }, [chatWidth, isChatOpen]);
+
+  const handleStartNewProject = async () => {
+    const confirmed =
+      typeof window === "undefined" ||
+      window.confirm(
+        "Start a new workflow? Existing workflow evidence stays saved, but this app session will start from setup.",
+      );
+    if (!confirmed) return;
+
+    try {
+      await workflowContext?.startNewWorkflow?.({
+        metadata: { created_from: "new_project_button" },
+      });
+      setCurrent("files");
+      setVisitedTabs(new Set(["files"]));
+      message.success("Started a fresh workflow.");
+    } catch (error) {
+      console.error("Could not start a new workflow", error);
+      message.error("Could not start a fresh workflow.");
+    }
+  };
+
+  const handleAskWhatNext = () => {
+    if (!workflowContext?.workflow?.id) {
+      message.warning("Start or load a workflow first.");
+      return;
+    }
+    quickAgentRequestId.current += 1;
+    const request = {
+      id: quickAgentRequestId.current,
+      query: "What should I do next?",
+      displayText: "What should I do next?",
+      source: "quick_next",
+    };
+    setQuickAgentRequest(request);
+    setIsChatOpen(true);
+    logClientEvent("workflow_agent_quick_next_requested", {
+      level: "INFO",
+      source: "views",
+      message: "Quick next-step assistant request",
+      data: {
+        workflowId: workflowContext.workflow.id,
+        stage: workflowContext.workflow.stage,
+        view: current,
+      },
+    });
+  };
 
   const renderTabContent = (key, component) => {
     if (!visitedTabs.has(key)) return null;
@@ -136,14 +350,33 @@ function Views() {
     );
   };
 
+  if (workflowContext?.loading && !workflowContext?.workflow) {
+    return (
+      <Layout style={{ minHeight: "100vh", background: "#f6f7fb" }}>
+        <Content
+          style={{
+            minHeight: "100vh",
+            display: "flex",
+            alignItems: "center",
+            justifyContent: "center",
+            color: "#6b7280",
+          }}
+        >
+          Loading workspace...
+        </Content>
+      </Layout>
+    );
+  }
+
   return (
-    <Layout style={{ minHeight: "100vh" }}>
+    <Layout style={{ minHeight: "100vh", height: "100vh" }}>
       <div
+        className="pytc-top-nav"
         style={{
           display: "flex",
           alignItems: "center",
           background: "#fff",
-          paddingRight: 16,
+          paddingRight: 12,
           borderBottom: "1px solid #f0f0f0",
         }}
       >
@@ -152,24 +385,42 @@ function Views() {
           selectedKeys={[current]}
           mode="horizontal"
           items={MODULE_ITEMS}
+          className="pytc-top-menu"
           style={{
-            lineHeight: "64px",
-            paddingLeft: "16px",
+            lineHeight: "48px",
+            paddingLeft: "12px",
             flex: 1,
             borderBottom: "none",
           }}
         />
+        <Button
+          onClick={handleAskWhatNext}
+          title="Ask the assistant for the best next workflow step"
+          disabled={!workflowContext?.workflow?.id}
+        >
+          What next?
+        </Button>
+        <Button onClick={handleStartNewProject} title="Start a fresh workflow">
+          New project
+        </Button>
         <Button
           type="primary"
           shape="circle"
           icon={<MessageOutlined />}
           onClick={() => setIsChatOpen(true)}
+          style={{ marginLeft: 8 }}
         />
       </div>
+      <WorkflowOverviewStrip
+        overview={workflowContext?.workflowOverview}
+        workflow={workflowContext?.workflow}
+        onNavigate={navigateTo}
+      />
       <Content
         style={{
-          padding: "24px",
-          height: "calc(100vh - 64px)",
+          padding: "16px",
+          flex: 1,
+          minHeight: 0,
           overflow: "auto",
         }}
       >
@@ -179,7 +430,7 @@ function Views() {
           <Visualization viewers={viewers} setViewers={setViewers} />,
         )}
         {renderTabContent("training", <ModelTraining />)}
-        {renderTabContent("monitoring", <Monitoring />)}
+        {renderTabContent("project-progress", <ProjectProgress />)}
         {renderTabContent(
           "inference",
           <ModelInference
@@ -215,14 +466,23 @@ function Views() {
             zIndex: 10,
           }}
           onMouseEnter={(e) =>
-            (e.currentTarget.style.backgroundColor = "#1890ff")
+            (e.currentTarget.style.backgroundColor =
+              "var(--seg-accent-primary, #3f37c9)")
           }
           onMouseLeave={(e) =>
             !isResizing.current &&
             (e.currentTarget.style.backgroundColor = "transparent")
           }
         />
-        <Chatbot onClose={() => setIsChatOpen(false)} />
+        <Chatbot
+          onClose={() => setIsChatOpen(false)}
+          queuedWorkflowQuery={quickAgentRequest}
+          onQueuedWorkflowQueryConsumed={(id) => {
+            setQuickAgentRequest((currentRequest) =>
+              currentRequest?.id === id ? null : currentRequest,
+            );
+          }}
+        />
       </Drawer>
     </Layout>
   );
diff --git a/client/src/views/Views.test.js b/client/src/views/Views.test.js
index 54edff84..4d0bdc01 100644
--- a/client/src/views/Views.test.js
+++ b/client/src/views/Views.test.js
@@ -1,10 +1,16 @@
 import React from "react";
-import { fireEvent, render, screen } from "@testing-library/react";
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
 
 import Views from "./Views";
 
+let mockWorkflowContext;
+
 jest.mock("../contexts/WorkflowContext", () => ({
-  useWorkflow: () => null,
+  useWorkflow: () => mockWorkflowContext,
+}));
+
+jest.mock("../logging/appEventLog", () => ({
+  logClientEvent: jest.fn(),
 }));
 
 jest.mock("antd", () => {
@@ -30,8 +36,15 @@ jest.mock("antd", () => {
   return {
     Layout,
     Menu,
-    Button: ({ children, ...props }) => <button {...props}>{children}</button>,
+    Button: ({ children, icon: _icon, ...props }) => (
+      <button {...props}>{children}</button>
+    ),
     Drawer: ({ children, open }) => (open ? <div>{children}</div> : null),
+    message: {
+      error: jest.fn(),
+      success: jest.fn(),
+      warning: jest.fn(),
+    },
   };
 });
 
@@ -42,8 +55,8 @@ jest.mock("@ant-design/icons", () => {
     EyeOutlined: Icon,
     ExperimentOutlined: Icon,
     ThunderboltOutlined: Icon,
-    DashboardOutlined: Icon,
     BugOutlined: Icon,
+    ProjectOutlined: Icon,
     MessageOutlined: Icon,
   };
 });
@@ -52,25 +65,66 @@ jest.mock("./FilesManager", () => () => <div>Files Manager Content</div>);
 jest.mock("./Visualization", () => () => <div>Visualization Content</div>);
 jest.mock("./ModelTraining", () => () => <div>Training Content</div>);
 jest.mock("./ModelInference", () => () => <div>Inference Content</div>);
-jest.mock("./Monitoring", () => () => <div>Monitoring Content</div>);
+jest.mock("./ProjectProgress", () => () => <div>Project Progress Content</div>);
+jest.mock("./project-manager/ProjectManager", () => () => (
+  <div>Project Manager Content</div>
+));
 jest.mock("./MaskProofreading", () => () => (
   <div>Mask Proofreading Content</div>
 ));
-jest.mock("../components/Chatbot", () => () => <div>Chatbot</div>);
+jest.mock("../components/Chatbot", () => (props) => (
+  <div>
+    <div>Chatbot</div>
+    {props.queuedWorkflowQuery?.displayText && (
+      <div>{props.queuedWorkflowQuery.displayText}</div>
+    )}
+  </div>
+));
 
 describe("Views", () => {
-  it("shows all active modules without the workflow selector", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    mockWorkflowContext = {
+      workflow: {
+        id: 1,
+        stage: "setup",
+        title: "Demo Workflow",
+        metadata: {},
+      },
+      workflowOverview: {
+        project_name: "Demo Workflow",
+        phase: "setup",
+        phase_label: "Setup",
+        volume_summary: {
+          ground_truth: 0,
+          needs_proofreading: 0,
+          missing_segmentation: 0,
+        },
+        blockers: [{ label: "No project mounted", detail: "Mount data." }],
+        recommended_next_actions: [],
+        active_runs: [],
+      },
+      loading: false,
+      startNewWorkflow: jest.fn().mockResolvedValue({}),
+      consumeClientEffects: jest.fn(),
+    };
+  });
+
+  it("shows all active modules without a startup splash screen", () => {
     render(<Views />);
 
-    expect(screen.getByText("File Management")).toBeTruthy();
-    expect(screen.getByText("Visualization")).toBeTruthy();
-    expect(screen.getByText("Model Training")).toBeTruthy();
-    expect(screen.getByText("Model Inference")).toBeTruthy();
-    expect(screen.getByText("Tensorboard")).toBeTruthy();
-    expect(screen.getByText("Mask Proofreading")).toBeTruthy();
-    expect(screen.queryByText("SynAnno")).toBeNull();
-    expect(screen.queryByText("Change Views")).toBeNull();
-    expect(screen.queryByText("Launch Selected")).toBeNull();
+    expect(screen.getByText("Files")).toBeTruthy();
+    expect(screen.getByText("Visualize")).toBeTruthy();
+    expect(screen.getByText("Train Model")).toBeTruthy();
+    expect(screen.getByText("Run Model")).toBeTruthy();
+    expect(screen.queryByText("Monitor")).toBeNull();
+    expect(screen.getByText("Workflow")).toBeTruthy();
+    expect(screen.getByText("Demo Workflow")).toBeTruthy();
+    expect(screen.getByText("Setup")).toBeTruthy();
+    expect(screen.getByText("Proofread")).toBeTruthy();
+    expect(screen.getByText("Project Manager")).toBeTruthy();
+    expect(screen.queryByText("What are you trying to do?")).toBeNull();
+    expect(screen.queryByText("Confirm project folders")).toBeNull();
     expect(screen.getByText("Files Manager Content")).toBeTruthy();
   });
 
@@ -79,8 +133,59 @@ describe("Views", () => {
 
     expect(screen.queryByText("Visualization Content")).toBeNull();
 
-    fireEvent.click(screen.getByText("Visualization"));
+    fireEvent.click(screen.getByText("Visualize"));
 
     expect(screen.getByText("Visualization Content")).toBeTruthy();
   });
+
+  it("opens the project progress tracker tab", () => {
+    render(<Views />);
+
+    fireEvent.click(screen.getByText("Workflow"));
+
+    expect(screen.getByText("Project Progress Content")).toBeTruthy();
+  });
+
+  it("opens the generalist project manager tab", () => {
+    render(<Views />);
+
+    fireEvent.click(screen.getByText("Project Manager"));
+
+    expect(screen.getByText("Project Manager Content")).toBeTruthy();
+  });
+
+  it("routes legacy monitoring navigation to Train Model", async () => {
+    mockWorkflowContext.lastClientEffects = { navigate_to: "monitoring" };
+
+    render(<Views />);
+
+    await waitFor(() => {
+      expect(screen.getByText("Training Content")).toBeTruthy();
+    });
+    expect(mockWorkflowContext.consumeClientEffects).toHaveBeenCalled();
+  });
+
+  it("starts a fresh workflow from the app shell", async () => {
+    const confirmSpy = jest.spyOn(window, "confirm").mockReturnValue(true);
+
+    render(<Views />);
+    fireEvent.click(screen.getByText("New project"));
+
+    await waitFor(() => {
+      expect(mockWorkflowContext.startNewWorkflow).toHaveBeenCalledWith({
+        metadata: { created_from: "new_project_button" },
+      });
+    });
+    expect(confirmSpy).toHaveBeenCalled();
+    confirmSpy.mockRestore();
+  });
+
+  it("opens the assistant with a quick next-step request", async () => {
+    render(<Views />);
+
+    fireEvent.click(screen.getByText("What next?"));
+
+    expect(screen.getByText("Chatbot")).toBeTruthy();
+    expect(screen.getByText("What should I do next?")).toBeTruthy();
+  });
 });
diff --git a/client/src/views/Visualization.js b/client/src/views/Visualization.js
index 4c2de865..b740f63b 100644
--- a/client/src/views/Visualization.js
+++ b/client/src/views/Visualization.js
@@ -1,119 +1,466 @@
-import React, { useState } from "react";
-import { Button, Tabs, Input, Space, Typography, message } from "antd";
+import React, {
+  useCallback,
+  useContext,
+  useEffect,
+  useRef,
+  useState,
+} from "react";
+import {
+  Button,
+  Tabs,
+  Input,
+  Space,
+  Typography,
+  message,
+  notification,
+} from "antd";
 import {
   ArrowRightOutlined,
   InboxOutlined,
   ReloadOutlined,
 } from "@ant-design/icons";
-import { getNeuroglancerViewer } from "../api";
+import { apiClient, getNeuroglancerViewer } from "../api";
 import UnifiedFileInput from "../components/UnifiedFileInput";
+import StageHeader from "../components/workflow/StageHeader";
+import { AppContext } from "../contexts/GlobalContext";
 import { useWorkflow } from "../contexts/WorkflowContext";
+import { logClientEvent } from "../logging/appEventLog";
 
 const { Title } = Typography;
 
+const formatScales = (value) => {
+  if (!value) return "";
+  if (Array.isArray(value)) return value.join(",");
+  return String(value);
+};
+
+const getPath = (val) => {
+  if (!val) return "";
+  if (typeof val === "string") return val;
+  return val.path || "";
+};
+
+const getDisplay = (val) => {
+  if (!val) return "";
+  if (typeof val === "string") return val;
+  return val.display || val.path || "";
+};
+
+const getViewerTitle = (imageValue, labelValue) => {
+  const getImageName = (val) => {
+    const display = getDisplay(val);
+    if (!display) return "";
+    const parts = display.split(/[/\\]/);
+    return parts[parts.length - 1];
+  };
+
+  return (
+    getImageName(imageValue) +
+    (labelValue ? " & " + getImageName(labelValue) : "")
+  );
+};
+
+const waitForViewerLayout = () =>
+  new Promise((resolve) => {
+    window.requestAnimationFrame(() => {
+      window.requestAnimationFrame(() => {
+        window.setTimeout(resolve, 250);
+      });
+    });
+  });
+
+const appendRefreshParam = (url) => {
+  if (!url) return url;
+  const hashIndex = url.indexOf("#");
+  const base = hashIndex >= 0 ? url.slice(0, hashIndex) : url;
+  const hash = hashIndex >= 0 ? url.slice(hashIndex) : "";
+  const separator = base.includes("?") ? "&" : "?";
+  return `${base}${separator}refresh=${Date.now()}${hash}`;
+};
+
+const isMixedContentUrl = (url) => {
+  if (typeof window === "undefined" || window.location.protocol !== "https:") {
+    return false;
+  }
+  try {
+    return new URL(url, window.location.href).protocol === "http:";
+  } catch {
+    return false;
+  }
+};
+
 function Visualization(props) {
   const { viewers, setViewers } = props;
   const workflowContext = useWorkflow();
+  const appContext = useContext(AppContext);
+  const globalImage = appContext?.currentImage || null;
+  const globalLabel = appContext?.currentLabel || null;
+  const globalScales = appContext?.visualizationScales || "";
+  const workflowScales =
+    workflowContext?.workflow?.metadata?.visualization_scales ||
+    workflowContext?.workflow?.metadata?.project_context?.voxel_size_nm ||
+    null;
+  const handledRuntimeActionRef = useRef(null);
+  const viewerRefreshTimersRef = useRef([]);
   const [activeKey, setActiveKey] = useState(
     viewers.length > 0 ? viewers[0].key : null,
   );
 
   // Input states
-  const [currentImage, setCurrentImage] = useState(null);
-  const [currentLabel, setCurrentLabel] = useState(null);
-  const [scales, setScales] = useState("30,6,6");
+  const [currentImage, setCurrentImage] = useState(globalImage);
+  const [currentLabel, setCurrentLabel] = useState(globalLabel);
+  const [scales, setScales] = useState(
+    formatScales(globalScales) || formatScales(workflowScales) || "",
+  );
   const [isLoading, setIsLoading] = useState(false);
 
+  useEffect(() => {
+    return () => {
+      viewerRefreshTimersRef.current.forEach((timerId) => {
+        window.clearTimeout(timerId);
+      });
+      viewerRefreshTimersRef.current = [];
+    };
+  }, []);
+
   const handleImageChange = (value) => {
-    console.log(`selected image:`, value);
     setCurrentImage(value);
+    appContext?.setCurrentImage?.(value);
   };
 
   const handleLabelChange = (value) => {
-    console.log(`selected label:`, value);
     setCurrentLabel(value);
+    appContext?.setCurrentLabel?.(value);
   };
 
+  useEffect(() => {
+    if (globalImage !== currentImage) {
+      setCurrentImage(globalImage);
+    }
+  }, [globalImage, currentImage]);
+
+  useEffect(() => {
+    if (globalLabel !== currentLabel) {
+      setCurrentLabel(globalLabel);
+    }
+  }, [globalLabel, currentLabel]);
+
+  useEffect(() => {
+    const nextScales = formatScales(globalScales || workflowScales);
+    if (nextScales !== scales) {
+      setScales(nextScales);
+    }
+  }, [globalScales, workflowScales, scales]);
+
   const handleInputScales = (event) => {
-    setScales(event.target.value);
+    const nextScales = event.target.value;
+    setScales(nextScales);
+    appContext?.setVisualizationScales?.(nextScales);
   };
 
-  // Helper to get path string from potential object
-  const getPath = (val) => {
-    if (!val) return "";
-    if (typeof val === "string") return val;
-    return val.path || "";
-  };
+  const parseScalesInput = useCallback((value) => {
+    const parts = (String(value || "").match(/-?\d+(?:\.\d+)?/g) || []).map(
+      Number,
+    );
+    if (
+      parts.length < 3 ||
+      parts.slice(0, 3).some((part) => !Number.isFinite(part) || part <= 0)
+    ) {
+      return null;
+    }
+    return parts.slice(0, 3);
+  }, []);
 
-  // Helper to get display string from potential object
-  const getDisplay = (val) => {
-    if (!val) return "";
-    if (typeof val === "string") return val;
-    return val.display || val.path || "";
-  };
+  const validateManagedUploadSelection = useCallback(async (value, role) => {
+    const selectedPath = getPath(value);
+    if (!selectedPath || !selectedPath.startsWith("uploads/")) {
+      return true;
+    }
 
-  const fetchNeuroglancerViewer = async () => {
-    const imagePath = getPath(currentImage);
-    const labelPath = getPath(currentLabel);
+    const response = await apiClient.get("/files");
+    const exists = (response.data || []).some(
+      (item) => !item.is_folder && item.physical_path === selectedPath,
+    );
+    if (exists) {
+      return true;
+    }
 
-    if (!imagePath) {
-      message.error("Please select an image");
-      return;
+    if (role === "image") {
+      setCurrentImage(null);
+    } else {
+      setCurrentLabel(null);
     }
+    message.error(
+      `The selected ${role} file is no longer present in app uploads. Please re-select or re-upload it.`,
+    );
+    return false;
+  }, []);
+
+  const loadViewer = useCallback(
+    async (imageValue, labelValue, scalesValue, options = {}) => {
+      const imagePath = getPath(imageValue);
+      const labelPath = getPath(labelValue);
+
+      if (!imagePath) {
+        message.error("Please select an image");
+        return;
+      }
+
+      setIsLoading(true);
+      try {
+        const imageSelectionOk = await validateManagedUploadSelection(
+          imageValue,
+          "image",
+        );
+        if (!imageSelectionOk) {
+          return;
+        }
+        const labelSelectionOk = await validateManagedUploadSelection(
+          labelValue,
+          "label",
+        );
+        if (!labelSelectionOk) {
+          return;
+        }
+
+        const scalesArray = parseScalesInput(scalesValue);
+        if (!scalesArray) {
+          message.error(
+            "Enter voxel scales as z,y,x nanometers before opening the viewer.",
+          );
+          return;
+        }
+        const viewerId =
+          imagePath + (labelPath || "") + JSON.stringify(scalesArray);
+
+        let updatedViewers = viewers;
+        const exists = viewers.find((viewer) => viewer.key === viewerId);
 
-    setIsLoading(true);
-    try {
-      const scalesArray = scales.split(",").map(Number);
-      // Use path string for ID generation
-      const viewerId =
-        imagePath + (labelPath || "") + JSON.stringify(scalesArray);
+        if (exists) {
+          updatedViewers = viewers.filter((viewer) => viewer.key !== viewerId);
+        }
 
-      let updatedViewers = viewers;
-      const exists = viewers.find((viewer) => viewer.key === viewerId);
+        const viewerResult = await getNeuroglancerViewer(
+          imagePath,
+          labelPath,
+          scalesArray,
+          workflowContext?.workflow?.id,
+        );
+        const viewerUrl =
+          typeof viewerResult === "string"
+            ? viewerResult
+            : viewerResult?.url || viewerResult?.neuroglancer_url || "";
 
-      if (exists) {
-        updatedViewers = viewers.filter((viewer) => viewer.key !== viewerId);
+        if (!viewerUrl) {
+          throw new Error("Viewer did not return a Neuroglancer URL.");
+        }
+        logClientEvent("visualization_viewer_url_received", {
+          level: "INFO",
+          message: "Received Neuroglancer viewer URL",
+          source: "visualization",
+          data: {
+            viewerUrl,
+            imagePath,
+            labelPath,
+            scales: scalesArray,
+            workflowId: workflowContext?.workflow?.id || null,
+            requestedImagePath: viewerResult?.requested_image_path || imagePath,
+            requestedLabelPath: viewerResult?.requested_label_path || labelPath,
+            resolvedImagePath: viewerResult?.image_path || null,
+            resolvedLabelPath: viewerResult?.label_path || null,
+          },
+        });
+        if (isMixedContentUrl(viewerUrl)) {
+          logClientEvent("visualization_viewer_mixed_content_blocked", {
+            level: "ERROR",
+            message: "Blocked insecure Neuroglancer viewer URL on HTTPS page",
+            source: "visualization",
+            data: {
+              viewerUrl,
+              pageUrl: window.location.href,
+              imagePath,
+              labelPath,
+              scales: scalesArray,
+              workflowId: workflowContext?.workflow?.id || null,
+            },
+          });
+          throw new Error(
+            "Viewer URL is insecure for this HTTPS page. The server must expose Neuroglancer through HTTPS.",
+          );
+        }
+
+        const resolvedImagePath = viewerResult?.image_path;
+        const resolvedLabelPath = viewerResult?.label_path;
+        const pairQuestion = viewerResult?.pair_question;
+        if (resolvedImagePath && resolvedImagePath !== imagePath) {
+          setCurrentImage(resolvedImagePath);
+          appContext?.setCurrentImage?.(resolvedImagePath);
+        }
+        if (resolvedLabelPath && resolvedLabelPath !== labelPath) {
+          setCurrentLabel(resolvedLabelPath);
+          appContext?.setCurrentLabel?.(resolvedLabelPath);
+        }
+        if (pairQuestion) {
+          const pairCount = viewerResult?.pair_discovery?.pair_count || 0;
+          const notificationKey = `volume-pairs-${viewerId}`;
+          notification.info({
+            key: notificationKey,
+            message: `Found ${pairCount} image/segmentation pairs`,
+            description:
+              "I opened the first pair. You can use the progress tracker to review which volumes are proofread, draft, or missing masks.",
+            duration: 12,
+            btn: (
+              <Space size={8}>
+                <Button
+                  size="small"
+                  type="primary"
+                  onClick={() => {
+                    notification.close(notificationKey);
+                    workflowContext?.runClientEffects?.({
+                      navigate_to: "project-progress",
+                      refresh_project_progress: true,
+                    });
+                  }}
+                >
+                  Open Progress
+                </Button>
+                <Button
+                  size="small"
+                  onClick={() => {
+                    notification.close(notificationKey);
+                    workflowContext?.runClientEffects?.({
+                      navigate_to: "files",
+                    });
+                  }}
+                >
+                  Show Files
+                </Button>
+              </Space>
+            ),
+          });
+        }
+
+        const newViewers = [
+          ...updatedViewers,
+          {
+            key: viewerId,
+            title: getViewerTitle(
+              resolvedImagePath || imageValue,
+              resolvedLabelPath || labelValue,
+            ),
+            viewer: viewerUrl,
+          },
+        ];
+
+        setViewers(newViewers);
+        setActiveKey(viewerId);
+        logClientEvent("visualization_viewer_mounted", {
+          level: "INFO",
+          message: "Mounted Neuroglancer iframe",
+          source: "visualization",
+          data: {
+            viewerId,
+            viewerUrl,
+            title: getViewerTitle(
+              resolvedImagePath || imageValue,
+              resolvedLabelPath || labelValue,
+            ),
+            imagePath: resolvedImagePath || imagePath,
+            labelPath: resolvedLabelPath || labelPath,
+            scales: scalesArray,
+            workflowId: workflowContext?.workflow?.id || null,
+          },
+        });
+        if (options.refreshAfterMount) {
+          const timerId = window.setTimeout(() => {
+            setViewers((currentViewers) =>
+              currentViewers.map((viewer) =>
+                viewer.key === viewerId
+                  ? { ...viewer, viewer: appendRefreshParam(viewer.viewer) }
+                  : viewer,
+              ),
+            );
+          }, options.refreshAfterMount);
+          viewerRefreshTimersRef.current.push(timerId);
+        }
+      } catch (error) {
+        console.error("Failed to load Neuroglancer viewer", error);
+        logClientEvent("visualization_viewer_load_failed", {
+          level: "ERROR",
+          message: error?.message || "Failed to load Neuroglancer viewer",
+          source: "visualization",
+          data: {
+            imagePath,
+            labelPath,
+            scalesValue,
+            workflowId: workflowContext?.workflow?.id || null,
+            error,
+          },
+        });
+        message.error(error?.message || "Failed to load viewer");
+      } finally {
+        setIsLoading(false);
       }
+    },
+    [
+      appContext,
+      parseScalesInput,
+      setViewers,
+      validateManagedUploadSelection,
+      viewers,
+      workflowContext,
+    ],
+  );
 
-      const res = await getNeuroglancerViewer(
-        imagePath,
-        labelPath,
-        scalesArray,
-        workflowContext?.workflow?.id,
-      );
-
-      console.log("Current Viewer at ", res);
-
-      // Extract name from path for title
-      const getImageName = (val) => {
-        const display = getDisplay(val);
-        if (!display) return "";
-        const parts = display.split(/[/\\]/);
-        return parts[parts.length - 1];
-      };
-
-      const newViewers = [
-        ...updatedViewers,
-        {
-          key: viewerId,
-          title:
-            getImageName(currentImage) +
-            (currentLabel ? " & " + getImageName(currentLabel) : ""),
-          viewer: res,
-        },
-      ];
-
-      setViewers(newViewers);
-      setActiveKey(viewerId);
-
-      setIsLoading(false);
-    } catch (e) {
-      console.log(e);
-      setIsLoading(false);
-      message.error("Failed to load viewer");
-    }
+  const fetchNeuroglancerViewer = async () => {
+    await loadViewer(currentImage, currentLabel, scales);
   };
 
+  useEffect(() => {
+    const action = workflowContext?.pendingRuntimeAction;
+    if (!action || action.kind !== "load_visualization") return;
+    if (handledRuntimeActionRef.current === action.id) return;
+    handledRuntimeActionRef.current = action.id;
+
+    const overrideScales = formatScales(action.overrides?.visualizationScales);
+    const imageValue =
+      action.overrides?.visualizationImagePath || currentImage || globalImage;
+    const labelValue =
+      action.overrides?.visualizationLabelPath || currentLabel || globalLabel;
+    const scalesValue = overrideScales || scales;
+    if (overrideScales) {
+      setScales(overrideScales);
+      appContext?.setVisualizationScales?.(overrideScales);
+    }
+    if (imageValue) {
+      setCurrentImage(imageValue);
+      appContext?.setCurrentImage?.(imageValue);
+    }
+    if (labelValue) {
+      setCurrentLabel(labelValue);
+      appContext?.setCurrentLabel?.(labelValue);
+    }
+
+    waitForViewerLayout()
+      .then(() => {
+        return loadViewer(imageValue, labelValue, scalesValue, {
+          refreshAfterMount: 800,
+        });
+      })
+      .finally(() => {
+        workflowContext?.consumeRuntimeAction?.(action.id);
+      });
+  }, [
+    appContext,
+    currentImage,
+    currentLabel,
+    globalImage,
+    globalLabel,
+    loadViewer,
+    scales,
+    workflowContext,
+  ]);
+
   const handleEdit = (targetKey, action) => {
     if (action === "remove") {
       remove(targetKey);
@@ -149,7 +496,7 @@ function Visualization(props) {
       if (viewer.key === key) {
         return {
           ...viewer,
-          viewer: viewer.viewer + "?refresh=" + new Date().getTime(),
+          viewer: appendRefreshParam(viewer.viewer),
         };
       }
       return viewer;
@@ -159,6 +506,13 @@ function Visualization(props) {
 
   return (
     <div style={{ height: "100%", display: "flex", flexDirection: "column" }}>
+      <div style={{ marginBottom: 12 }}>
+        <StageHeader
+          stage="visualization"
+          title="Visualization"
+          subtitle="Inspect image and label volumes before routing failures into inference or proofreading."
+        />
+      </div>
       {/* Input Section */}
       <div
         style={{
@@ -198,7 +552,7 @@ function Visualization(props) {
               Scales (z,y,x)
             </Title>
             <Input
-              placeholder="30,6,6"
+              placeholder="z,y,x nm"
               value={scales}
               onChange={handleInputScales}
               style={{ width: "150px" }}
@@ -219,41 +573,91 @@ function Visualization(props) {
       {/* Viewers Section */}
       <div style={{ flex: 1, minHeight: 0 }}>
         {viewers.length > 0 ? (
-          <Tabs
-            closeIcon
-            type="editable-card"
-            hideAdd
-            onEdit={handleEdit}
-            activeKey={activeKey}
-            onChange={handleChange}
-            items={viewers.map((viewer) => ({
-              label: (
-                <span>
-                  {viewer.title}
-                  <Button
-                    type="link"
-                    icon={<ReloadOutlined />}
-                    onClick={(e) => {
-                      e.stopPropagation();
-                      refreshViewer(viewer.key);
+          <div style={{ height: "calc(100vh - 250px)" }}>
+            <Tabs
+              className="visualization-viewer-tabs"
+              closeIcon
+              type="editable-card"
+              tabPosition="bottom"
+              hideAdd
+              onEdit={handleEdit}
+              activeKey={activeKey}
+              onChange={handleChange}
+              style={{ height: "100%" }}
+              items={viewers.map((viewer) => ({
+                label: (
+                  <span
+                    style={{
+                      display: "inline-flex",
+                      alignItems: "center",
+                      gap: 4,
                     }}
-                  />
-                </span>
-              ),
-              key: viewer.key,
-              children: (
-                <iframe
-                  title="Viewer Display"
-                  width="100%"
-                  height="800"
-                  frameBorder="0"
-                  scrolling="no"
-                  src={viewer.viewer}
-                  style={{ height: "calc(100vh - 250px)" }}
-                />
-              ),
-            }))}
-          />
+                  >
+                    <span>{viewer.title}</span>
+                    <Button
+                      type="link"
+                      icon={<ReloadOutlined />}
+                      onClick={(e) => {
+                        e.stopPropagation();
+                        refreshViewer(viewer.key);
+                      }}
+                      style={{ paddingInline: 4 }}
+                    />
+                  </span>
+                ),
+                key: viewer.key,
+                children: (
+                  <div
+                    style={{
+                      height: "100%",
+                      overflow: "hidden",
+                      borderRadius: 8,
+                      background: "#000",
+                    }}
+                  >
+                    <iframe
+                      title="Viewer Display"
+                      width="100%"
+                      height="800"
+                      frameBorder="0"
+                      scrolling="no"
+                      src={viewer.viewer}
+                      onLoad={() =>
+                        logClientEvent("visualization_iframe_loaded", {
+                          level: "INFO",
+                          message: "Neuroglancer iframe load event",
+                          source: "visualization",
+                          data: {
+                            viewerKey: viewer.key,
+                            viewerUrl: viewer.viewer,
+                            activeKey,
+                          },
+                        })
+                      }
+                      onError={(event) =>
+                        logClientEvent("visualization_iframe_error", {
+                          level: "ERROR",
+                          message: "Neuroglancer iframe error event",
+                          source: "visualization",
+                          data: {
+                            viewerKey: viewer.key,
+                            viewerUrl: viewer.viewer,
+                            activeKey,
+                            eventType: event?.type,
+                          },
+                        })
+                      }
+                      style={{
+                        width: "100%",
+                        height: "100%",
+                        display: "block",
+                      }}
+                    />
+                  </div>
+                ),
+              }))}
+            />
+          </div>
         ) : (
           <div style={{ textAlign: "center", padding: "40px", color: "#999" }}>
             <InboxOutlined style={{ fontSize: "48px", marginBottom: "16px" }} />
diff --git a/client/src/views/ehtool/DatasetLoader.js b/client/src/views/ehtool/DatasetLoader.js
index dd9957d8..92e96316 100644
--- a/client/src/views/ehtool/DatasetLoader.js
+++ b/client/src/views/ehtool/DatasetLoader.js
@@ -1,7 +1,13 @@
-import React from "react";
-import { Card, Form, Input, Button, Modal, Space, Typography } from "antd";
+import React, { useMemo } from "react";
+import { Card, Form, Input, Button, Modal, Space, Typography, Tag } from "antd";
 import { FolderOpenOutlined, UploadOutlined } from "@ant-design/icons";
 import UnifiedFileInput from "../../components/UnifiedFileInput";
+import {
+  basename,
+  getProofreadingImagePath,
+  getProofreadingMaskPath,
+  getProofreadingProjectName,
+} from "./proofreadingPaths";
 
 const { Title, Text } = Typography;
 
@@ -9,7 +15,7 @@ const { Title, Text } = Typography;
  * Dataset Loader Component
  * Interface for loading image datasets
  */
-function DatasetLoader({ onLoad, loading }) {
+function DatasetLoader({ onLoad, loading, workflow }) {
   const [form] = Form.useForm();
 
   const resolvePath = (value) => {
@@ -65,9 +71,61 @@ function DatasetLoader({ onLoad, loading }) {
     }
   };
 
+  const currentPair = useMemo(() => {
+    if (!workflow) return null;
+    const imagePath = getProofreadingImagePath(workflow);
+    const maskPath = getProofreadingMaskPath(workflow);
+
+    if (!imagePath) return null;
+    return {
+      imagePath,
+      maskPath,
+      projectName: getProofreadingProjectName(workflow),
+    };
+  }, [workflow]);
+
+  const fillCurrentPair = () => {
+    if (!currentPair) return;
+    form.setFieldsValue({
+      projectName: currentPair.projectName,
+      datasetPath: {
+        path: currentPair.imagePath,
+        display: basename(currentPair.imagePath),
+      },
+      maskPath: currentPair.maskPath
+        ? {
+            path: currentPair.maskPath,
+            display: basename(currentPair.maskPath),
+          }
+        : undefined,
+    });
+  };
+
+  const startCurrentPair = () => {
+    if (!currentPair || loading) return;
+    form.setFieldsValue({
+      projectName: currentPair.projectName,
+      datasetPath: {
+        path: currentPair.imagePath,
+        display: basename(currentPair.imagePath),
+      },
+      maskPath: currentPair.maskPath
+        ? {
+            path: currentPair.maskPath,
+            display: basename(currentPair.maskPath),
+          }
+        : undefined,
+    });
+    onLoad(
+      currentPair.imagePath,
+      currentPair.maskPath,
+      currentPair.projectName,
+    );
+  };
+
   return (
     <Card
-      bordered={false}
+      variant="borderless"
       style={{
         maxWidth: "720px",
         margin: "0 auto",
@@ -77,19 +135,60 @@ function DatasetLoader({ onLoad, loading }) {
     >
       <Space direction="vertical" size={4} style={{ width: "100%" }}>
         <Space align="center">
-          <FolderOpenOutlined style={{ color: "#1677ff", fontSize: 18 }} />
+          <FolderOpenOutlined
+            style={{
+              color: "var(--seg-accent-primary, #3f37c9)",
+              fontSize: 18,
+            }}
+          />
           <Title level={4} style={{ margin: 0 }}>
-            Start a Mask Proofreading Session
+            What should I proofread?
           </Title>
         </Space>
-        <Text type="secondary">
-          Load a volume (single file, folder, or glob). Add a mask if you have
-          one.
-        </Text>
       </Space>
 
       <div style={{ height: 16 }} />
 
+      {currentPair && (
+        <div
+          style={{
+            border: "1px solid #dedbfd",
+            background: "#fafaff",
+            borderRadius: 12,
+            padding: 12,
+            marginBottom: 16,
+            display: "grid",
+            gap: 8,
+          }}
+        >
+          <Space size="small" wrap>
+            <Tag color="blue" style={{ margin: 0 }}>
+              current project
+            </Tag>
+            <Text strong>{currentPair.projectName}</Text>
+            <Text type="secondary">
+              {basename(currentPair.imagePath)}
+              {currentPair.maskPath
+                ? ` + ${basename(currentPair.maskPath)}`
+                : ""}
+            </Text>
+          </Space>
+          <Space size="small" wrap>
+            <Button
+              size="small"
+              type="primary"
+              onClick={startCurrentPair}
+              loading={loading}
+            >
+              Start with current data
+            </Button>
+            <Button size="small" onClick={fillCurrentPair}>
+              Fill form
+            </Button>
+          </Space>
+        </div>
+      )}
+
       <Form
         form={form}
         layout="vertical"
@@ -99,23 +198,29 @@ function DatasetLoader({ onLoad, loading }) {
         }}
       >
         <Form.Item
-          label="Project Name"
+          label="Review name"
           name="projectName"
-          rules={[{ required: true, message: "Please enter a project name" }]}
+          rules={[{ required: true, message: "Name this review" }]}
         >
           <Input placeholder="My EM volume" />
         </Form.Item>
 
         <Form.Item
-          label="Dataset Path"
+          label="Image to proofread"
           name="datasetPath"
-          rules={[{ required: true, message: "Please enter dataset path" }]}
+          rules={[{ required: true, message: "Choose the image volume" }]}
         >
-          <UnifiedFileInput placeholder="/path/to/dataset" />
+          <UnifiedFileInput
+            placeholder="/path/to/image"
+            selectionType="fileOrDirectory"
+          />
         </Form.Item>
 
-        <Form.Item label="Mask Path (Optional)" name="maskPath">
-          <UnifiedFileInput placeholder="/path/to/masks" />
+        <Form.Item label="Mask to edit (optional)" name="maskPath">
+          <UnifiedFileInput
+            placeholder="/path/to/mask"
+            selectionType="fileOrDirectory"
+          />
         </Form.Item>
 
         <Form.Item style={{ marginBottom: 0 }}>
@@ -127,7 +232,7 @@ function DatasetLoader({ onLoad, loading }) {
             block
             size="large"
           >
-            Load Dataset
+            Start proofreading
           </Button>
         </Form.Item>
       </Form>
diff --git a/client/src/views/ehtool/DatasetLoader.test.js b/client/src/views/ehtool/DatasetLoader.test.js
new file mode 100644
index 00000000..985b104a
--- /dev/null
+++ b/client/src/views/ehtool/DatasetLoader.test.js
@@ -0,0 +1,133 @@
+import React from "react";
+import { fireEvent, render, screen } from "@testing-library/react";
+
+import DatasetLoader from "./DatasetLoader";
+
+beforeEach(() => {
+  Object.defineProperty(window, "matchMedia", {
+    writable: true,
+    value: (query) => ({
+      matches: false,
+      media: query,
+      onchange: null,
+      addListener: jest.fn((listener) => listener({ matches: false })),
+      removeListener: jest.fn(),
+      addEventListener: jest.fn((event, listener) => {
+        if (event === "change") listener({ matches: false });
+      }),
+      removeEventListener: jest.fn(),
+      dispatchEvent: jest.fn(),
+    }),
+  });
+});
+
+jest.mock("../../components/UnifiedFileInput", () => {
+  return function MockUnifiedFileInput({ placeholder, value, onChange }) {
+    return (
+      <input
+        aria-label={placeholder}
+        value={value?.path || value || ""}
+        onChange={(event) => onChange?.({ path: event.target.value })}
+      />
+    );
+  };
+});
+
+describe("DatasetLoader", () => {
+  it("does not show global project suggestions when no workflow data exists", () => {
+    render(<DatasetLoader onLoad={jest.fn()} loading={false} />);
+
+    expect(screen.getByText("What should I proofread?")).toBeTruthy();
+    expect(screen.queryByText("mito25-paper-loop-smoke")).toBeNull();
+    expect(screen.queryByText("Start proofreading this pair")).toBeNull();
+    expect(screen.queryByText("current project")).toBeNull();
+  });
+
+  it("offers only the current workflow pair when workflow data exists", () => {
+    const onLoad = jest.fn();
+    render(
+      <DatasetLoader
+        onLoad={onLoad}
+        loading={false}
+        workflow={{
+          title: "prepilot_nucmm_mouse",
+          image_path: "/projects/prepilot/data/image/train",
+          label_path: "/projects/prepilot/data/label/train",
+        }}
+      />,
+    );
+
+    expect(screen.getByText("current project")).toBeTruthy();
+    expect(screen.getByText("prepilot_nucmm_mouse")).toBeTruthy();
+    expect(screen.getByText("train + train")).toBeTruthy();
+    expect(screen.queryByText("mito25-paper-loop-smoke")).toBeNull();
+
+    fireEvent.click(
+      screen.getByRole("button", { name: "Start with current data" }),
+    );
+
+    expect(onLoad).toHaveBeenCalledWith(
+      "/projects/prepilot/data/image/train",
+      "/projects/prepilot/data/label/train",
+      "prepilot_nucmm_mouse",
+    );
+  });
+
+  it("prefers corrected masks and predictions over original labels for current project proofreading", () => {
+    const onLoad = jest.fn();
+    render(
+      <DatasetLoader
+        onLoad={onLoad}
+        loading={false}
+        workflow={{
+          title: "mito review",
+          image_path: "/projects/mito/data/image/raw.h5",
+          mask_path: "/projects/mito/data/masks/original.h5",
+          inference_output_path: "/projects/mito/outputs/prediction.h5",
+          corrected_mask_path: "/projects/mito/outputs/corrected.tif",
+          label_path: "/projects/mito/data/labels/label.h5",
+        }}
+      />,
+    );
+
+    expect(screen.getByText("raw.h5 + corrected.tif")).toBeTruthy();
+
+    fireEvent.click(
+      screen.getByRole("button", { name: "Start with current data" }),
+    );
+
+    expect(onLoad).toHaveBeenCalledWith(
+      "/projects/mito/data/image/raw.h5",
+      "/projects/mito/outputs/corrected.tif",
+      "mito review",
+    );
+  });
+
+  it("uses inference outputs as editable masks when no corrected mask exists", () => {
+    const onLoad = jest.fn();
+    render(
+      <DatasetLoader
+        onLoad={onLoad}
+        loading={false}
+        workflow={{
+          title: "prediction review",
+          dataset_path: "/projects/mito/data/image/raw.h5",
+          inference_output_path: "/projects/mito/outputs/prediction.h5",
+          mask_path: "/projects/mito/data/masks/original.h5",
+        }}
+      />,
+    );
+
+    expect(screen.getByText("raw.h5 + prediction.h5")).toBeTruthy();
+
+    fireEvent.click(
+      screen.getByRole("button", { name: "Start with current data" }),
+    );
+
+    expect(onLoad).toHaveBeenCalledWith(
+      "/projects/mito/data/image/raw.h5",
+      "/projects/mito/outputs/prediction.h5",
+      "prediction review",
+    );
+  });
+});
diff --git a/client/src/views/ehtool/DetectionWorkflow.js b/client/src/views/ehtool/DetectionWorkflow.js
index 48ee921c..f9eb8e41 100644
--- a/client/src/views/ehtool/DetectionWorkflow.js
+++ b/client/src/views/ehtool/DetectionWorkflow.js
@@ -1,27 +1,44 @@
-import React, { useContext, useState, useEffect, useMemo, useRef } from "react";
+import React, { useContext, useState, useEffect, useRef } from "react";
 import {
+  Card,
+  Divider,
   Layout,
   message,
   Space,
   Typography,
   Button,
-  Slider,
-  Drawer,
-  Collapse,
   Modal,
-  Input,
-  Dropdown,
+  Slider,
+  InputNumber,
+  Popover,
   Tag,
+  Spin,
+  Tooltip,
 } from "antd";
-import { MoreOutlined } from "@ant-design/icons";
+import {
+  ClearOutlined,
+  DragOutlined,
+  EditOutlined,
+  EyeInvisibleOutlined,
+  EyeOutlined,
+  SaveOutlined,
+  ZoomInOutlined,
+  ZoomOutOutlined,
+} from "@ant-design/icons";
 import DatasetLoader from "./DatasetLoader";
-import ProgressTracker from "./ProgressTracker";
 import InstanceNavigator from "./InstanceNavigator";
 import ProofreadingEditor from "./ProofreadingEditor";
+import Instance3DPreview from "./Instance3DPreview";
 import SliceScheduler from "./SliceScheduler";
-import { apiClient } from "../../api";
+import { apiClient, getInstanceMeshPreview } from "../../api";
 import { AppContext } from "../../contexts/GlobalContext";
 import { useWorkflow } from "../../contexts/WorkflowContext";
+import { logClientEvent } from "../../logging/appEventLog";
+import {
+  getProofreadingImagePath,
+  getProofreadingMaskPath,
+  getTrainingReadyCorrectedMask,
+} from "./proofreadingPaths";
 
 const { Sider, Content } = Layout;
 const { Title, Text } = Typography;
@@ -56,6 +73,210 @@ const SCRUB_IDLE_MS = parsePositiveInt(
   process.env.REACT_APP_EH_SCRUB_IDLE_MS,
   120,
 );
+const WHEEL_SLICE_DELTA_PX = 72;
+const WHEEL_SLICE_IDLE_MS = 140;
+const DEFAULT_OVERLAY_ALL_ALPHA = 0.24;
+const DEFAULT_OVERLAY_ACTIVE_ALPHA = 0.8;
+
+const supportsAllInstanceOverlay = (mode) =>
+  mode === "instance" || mode === "semantic";
+
+const AXIS_LABELS = {
+  xy: "XY",
+  zy: "YZ",
+  zx: "XZ",
+};
+
+const ORTHO_PANES = [
+  { axis: "xy", label: "XY" },
+  { axis: "zy", label: "YZ" },
+  { axis: "zx", label: "XZ" },
+];
+
+const formatAxisLabel = (axis) =>
+  AXIS_LABELS[axis] || String(axis).toUpperCase();
+
+function OrthoviewPane({
+  axis,
+  label,
+  payload,
+  loading,
+  active,
+  editable,
+  onActivate,
+  onSliceWheel,
+  children,
+}) {
+  const rootRef = useRef(null);
+  const wheelHandlerRef = useRef(onSliceWheel);
+
+  useEffect(() => {
+    wheelHandlerRef.current = onSliceWheel;
+  }, [onSliceWheel]);
+
+  useEffect(() => {
+    const node = rootRef.current;
+    if (!node) return undefined;
+    const handleWheel = (event) => {
+      if (!wheelHandlerRef.current || event.ctrlKey || event.metaKey) return;
+      event.preventDefault();
+      event.stopPropagation();
+      wheelHandlerRef.current({
+        deltaY: event.deltaY,
+        deltaMode: event.deltaMode,
+      });
+    };
+    node.addEventListener("wheel", handleWheel, {
+      capture: true,
+      passive: false,
+    });
+    return () => {
+      node.removeEventListener("wheel", handleWheel, { capture: true });
+    };
+  }, []);
+
+  return (
+    <section
+      ref={rootRef}
+      onMouseDownCapture={() => {
+        if (!active) onActivate?.();
+      }}
+      style={{
+        minHeight: 0,
+        position: "relative",
+        display: "block",
+        border: active ? "1px solid #64748b" : "1px solid #1f2937",
+        borderRadius: 6,
+        background: "#0f172a",
+        overflow: "hidden",
+        overscrollBehavior: "contain",
+        touchAction: "none",
+        boxShadow: "none",
+      }}
+    >
+      <button
+        type="button"
+        onClick={onActivate}
+        style={{
+          position: "absolute",
+          top: 8,
+          left: 8,
+          zIndex: 6,
+          border: 0,
+          borderRadius: 6,
+          background: active
+            ? "rgba(226, 232, 240, 0.94)"
+            : "rgba(15, 23, 42, 0.66)",
+          color: "#f8fafc",
+          display: "inline-flex",
+          alignItems: "center",
+          minHeight: 24,
+          padding: "3px 9px",
+          cursor: active ? "default" : "pointer",
+          textAlign: "left",
+          boxShadow: active
+            ? "0 0 0 1px rgba(148, 163, 184, 0.65), 0 6px 18px rgba(2, 6, 23, 0.22)"
+            : "0 6px 18px rgba(2, 6, 23, 0.18)",
+        }}
+      >
+        <span
+          style={{
+            fontWeight: 700,
+            fontSize: 12,
+            color: active ? "#0f172a" : "#f8fafc",
+          }}
+        >
+          {label}
+        </span>
+      </button>
+      <div style={{ position: "absolute", inset: 0, minHeight: 0 }}>
+        {editable ? (
+          children
+        ) : payload?.imageBase64 ? (
+          <div
+            style={{
+              position: "absolute",
+              inset: 0,
+              display: "flex",
+              alignItems: "center",
+              justifyContent: "center",
+              overflow: "hidden",
+              background: "#0f172a",
+            }}
+          >
+            <img
+              src={payload.imageBase64}
+              alt={`${label} slice`}
+              draggable={false}
+              style={{
+                position: "absolute",
+                maxWidth: "100%",
+                maxHeight: "100%",
+                imageRendering: "pixelated",
+              }}
+            />
+            {payload.maskAllBase64 && (
+              <img
+                src={payload.maskAllBase64}
+                alt=""
+                draggable={false}
+                style={{
+                  position: "absolute",
+                  maxWidth: "100%",
+                  maxHeight: "100%",
+                  imageRendering: "pixelated",
+                  pointerEvents: "none",
+                }}
+              />
+            )}
+            {payload.maskActiveBase64 && (
+              <img
+                src={payload.maskActiveBase64}
+                alt=""
+                draggable={false}
+                style={{
+                  position: "absolute",
+                  maxWidth: "100%",
+                  maxHeight: "100%",
+                  imageRendering: "pixelated",
+                  pointerEvents: "none",
+                }}
+              />
+            )}
+          </div>
+        ) : (
+          <div
+            style={{
+              position: "absolute",
+              inset: 0,
+              display: "flex",
+              alignItems: "center",
+              justifyContent: "center",
+              color: "#cbd5e1",
+              background: "#0f172a",
+            }}
+          >
+            {loading ? <Spin /> : <span>{formatAxisLabel(axis)} preview</span>}
+          </div>
+        )}
+        {!editable && loading && payload?.imageBase64 && (
+          <div
+            style={{
+              position: "absolute",
+              right: 10,
+              bottom: 10,
+              background: "rgba(15, 23, 42, 0.72)",
+              borderRadius: 8,
+              padding: 6,
+            }}
+          >
+            <Spin size="small" />
+          </div>
+        )}
+      </div>
+    </section>
+  );
+}
 
 function DetectionWorkflow({
   sessionId,
@@ -65,6 +286,9 @@ function DetectionWorkflow({
 }) {
   const appContext = useContext(AppContext);
   const workflowContext = useWorkflow();
+  const pendingRuntimeAction = workflowContext?.pendingRuntimeAction;
+  const consumeRuntimeAction = workflowContext?.consumeRuntimeAction;
+  const activeWorkflow = workflowContext?.workflow;
   const [projectName, setProjectName] = useState("");
   const [totalLayers, setTotalLayers] = useState(0);
   const [instances, setInstances] = useState([]);
@@ -74,6 +298,20 @@ function DetectionWorkflow({
   const [filterText, setFilterText] = useState("");
   const [loadingInstances, setLoadingInstances] = useState(false);
   const [loadingView, setLoadingView] = useState(false);
+  const [volumePreview, setVolumePreview] = useState(null);
+  const [loadingVolumePreview, setLoadingVolumePreview] = useState(false);
+  const [meshRevision, setMeshRevision] = useState(0);
+  const [liveMaskDraft, setLiveMaskDraft] = useState(null);
+  const [orthoviewPayloads, setOrthoviewPayloads] = useState({});
+  const [loadingOrthoviews, setLoadingOrthoviews] = useState(false);
+  const [activeToolState, setActiveToolState] = useState({
+    tool: "paint",
+    showMask: true,
+    hasUnsavedEdits: false,
+    zoom: 1,
+    canEdit: true,
+    activeBrushSize: 10,
+  });
   const [viewAxis, setViewAxis] = useState("xy");
   const [axisTotal, setAxisTotal] = useState(0);
   const [viewState, setViewState] = useState({
@@ -84,6 +322,7 @@ function DetectionWorkflow({
     zIndex: 0,
     axis: "xy",
     total: 0,
+    instanceId: null,
   });
   const [sliderZ, setSliderZ] = useState(0);
   const [committedZ, setCommittedZ] = useState(0);
@@ -101,28 +340,25 @@ function DetectionWorkflow({
   const isScrubbingRef = useRef(false);
   const scrubTrackRef = useRef({ zIndex: 0, at: 0 });
   const isFastScrubRef = useRef(false);
-  const [overlayAllAlpha, setOverlayAllAlpha] = useState(0.08);
-  const [overlayActiveAlpha, setOverlayActiveAlpha] = useState(0.8);
+  const [overlayAllAlpha, setOverlayAllAlpha] = useState(
+    DEFAULT_OVERLAY_ALL_ALPHA,
+  );
+  const [overlayActiveAlpha, setOverlayActiveAlpha] = useState(
+    DEFAULT_OVERLAY_ACTIVE_ALPHA,
+  );
   const [savingMask, setSavingMask] = useState(false);
-  const [classificationPending, setClassificationPending] = useState(false);
   const [windowWidth, setWindowWidth] = useState(
     typeof window !== "undefined" ? window.innerWidth : 1440,
   );
-  const [showInstanceBrowser, setShowInstanceBrowser] = useState(false);
-  const [showInspector, setShowInspector] = useState(true);
-  const [inspectorSections, setInspectorSections] = useState([
-    "review",
-    "instances",
-  ]);
+  const [showQueue, setShowQueue] = useState(true);
   const [persistence, setPersistence] = useState(null);
-  const [showExportModal, setShowExportModal] = useState(false);
-  const [exportPath, setExportPath] = useState("");
-  const [lastExportPath, setLastExportPath] = useState("");
-  const [exportingMasks, setExportingMasks] = useState(false);
-  const [overwritingSource, setOverwritingSource] = useState(false);
   const lastPersistenceErrorRef = useRef(null);
   const lastFullRequestKeyRef = useRef(null);
   const fullRequestInFlightRef = useRef(null);
+  const lastProofreadingLogRef = useRef({});
+  const orthoviewPayloadsRef = useRef({});
+  const editorRefs = useRef({});
+  const sliceWheelRef = useRef({});
 
   const schedulerRef = useRef(
     new SliceScheduler({
@@ -134,6 +370,7 @@ function DetectionWorkflow({
   const viewCache = useRef(new Map());
   const viewCacheOrder = useRef([]);
   const viewCacheLimit = 80;
+  const handledRuntimeActionIdsRef = useRef(new Set());
 
   const ensurePerfState = () => {
     if (typeof window === "undefined") return null;
@@ -192,14 +429,35 @@ function DetectionWorkflow({
     window.__proofreadPerf = perfState;
   };
 
-  const axisOptions = useMemo(
-    () => [
-      { label: "XY", value: "xy" },
-      { label: "ZX", value: "zx" },
-      { label: "ZY", value: "zy" },
-    ],
-    [],
-  );
+  const logProofreadingEvent = (event, data = {}, options = {}) => {
+    const now =
+      typeof performance !== "undefined" ? performance.now() : Date.now();
+    const throttleMs = Number.isFinite(options.throttleMs)
+      ? options.throttleMs
+      : 0;
+    const throttleKey = options.throttleKey || event;
+    if (
+      throttleMs > 0 &&
+      lastProofreadingLogRef.current[throttleKey] &&
+      now - lastProofreadingLogRef.current[throttleKey] < throttleMs
+    ) {
+      return;
+    }
+    lastProofreadingLogRef.current[throttleKey] = now;
+    logClientEvent(event, {
+      level: options.level || "INFO",
+      message: options.message || event,
+      source: "proofreading",
+      data: {
+        sessionId,
+        activeInstanceId,
+        axis: viewAxis,
+        sliderZ,
+        committedZ,
+        ...data,
+      },
+    });
+  };
 
   const getErrorMessage = (error, fallback) => {
     const detail = error?.response?.data?.detail;
@@ -234,6 +492,33 @@ function DetectionWorkflow({
     }
   }, [sessionId, refreshTrigger]);
 
+  useEffect(() => {
+    if (!sessionId || !activeInstanceId) {
+      setVolumePreview(null);
+      setLiveMaskDraft(null);
+      return undefined;
+    }
+    let cancelled = false;
+    setLoadingVolumePreview(true);
+    setLiveMaskDraft(null);
+    getInstanceMeshPreview(sessionId, activeInstanceId, 60000)
+      .then((preview) => {
+        if (!cancelled) setVolumePreview(preview || null);
+      })
+      .catch((error) => {
+        if (!cancelled) {
+          console.warn("Failed to load 3D instance preview:", error);
+          setVolumePreview(null);
+        }
+      })
+      .finally(() => {
+        if (!cancelled) setLoadingVolumePreview(false);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [activeInstanceId, meshRevision, sessionId]);
+
   useEffect(() => {
     const persistenceError = persistence?.last_error;
     if (!persistenceError) return;
@@ -247,41 +532,10 @@ function DetectionWorkflow({
   }, [persistence?.last_error]);
 
   useEffect(() => {
-    const storedAll = Number(
-      localStorage.getItem("mask-proofreading-overlay-all"),
-    );
-    const storedActive = Number(
-      localStorage.getItem("mask-proofreading-overlay-active"),
-    );
-    const storedAxis = localStorage.getItem("mask-proofreading-axis");
-    if (!Number.isNaN(storedAll)) {
-      setOverlayAllAlpha(Math.min(Math.max(storedAll, 0), 1));
-    }
-    if (!Number.isNaN(storedActive)) {
-      setOverlayActiveAlpha(Math.min(Math.max(storedActive, 0), 1));
-    }
-    if (storedAxis && ["xy", "zx", "zy"].includes(storedAxis)) {
-      setViewAxis(storedAxis);
-    }
-  }, []);
-
-  useEffect(() => {
-    localStorage.setItem(
-      "mask-proofreading-overlay-all",
-      overlayAllAlpha.toString(),
-    );
-  }, [overlayAllAlpha]);
-
-  useEffect(() => {
-    localStorage.setItem(
-      "mask-proofreading-overlay-active",
-      overlayActiveAlpha.toString(),
-    );
-  }, [overlayActiveAlpha]);
-
-  useEffect(() => {
+    const scheduler = schedulerRef.current;
     return () => {
-      schedulerRef.current.clear();
+      scheduler.clear();
+      clearSliceWheelTimers();
       if (previewDebounceRef.current) {
         clearTimeout(previewDebounceRef.current);
       }
@@ -292,7 +546,29 @@ function DetectionWorkflow({
   }, []);
 
   useEffect(() => {
-    if (!sessionId || !activeInstanceId || instanceMode !== "instance") return;
+    if (typeof document === "undefined") return undefined;
+    const lockViewerWheel = (event) => {
+      if (!event.target?.closest?.("[data-proofreader-wheel-lock='true']")) {
+        return;
+      }
+      event.preventDefault();
+    };
+    document.addEventListener("wheel", lockViewerWheel, {
+      capture: true,
+      passive: false,
+    });
+    return () => {
+      document.removeEventListener("wheel", lockViewerWheel, { capture: true });
+    };
+  }, []);
+
+  useEffect(() => {
+    if (
+      !sessionId ||
+      !activeInstanceId ||
+      !supportsAllInstanceOverlay(instanceMode)
+    )
+      return;
     if (isScrubbingRef.current) return;
     const includeAll = overlayAllAlpha > 0.001;
     const includeActive = overlayActiveAlpha > 0.001;
@@ -342,7 +618,8 @@ function DetectionWorkflow({
   useEffect(() => {
     if (!sessionId || !activeInstanceId) return;
     if (isScrubbingRef.current) return;
-    const includeAll = instanceMode === "instance" && overlayAllAlpha > 0.001;
+    const includeAll =
+      supportsAllInstanceOverlay(instanceMode) && overlayAllAlpha > 0.001;
     const includeActive = overlayActiveAlpha > 0.001;
     const requestIdentity = [
       activeInstanceId,
@@ -396,19 +673,10 @@ function DetectionWorkflow({
           handleAxisChange("xy");
           break;
         case "2":
-          handleAxisChange("zx");
-          break;
-        case "3":
           handleAxisChange("zy");
           break;
-        case "c":
-          handleInstanceClassify("correct");
-          break;
-        case "x":
-          handleInstanceClassify("incorrect");
-          break;
-        case "u":
-          handleInstanceClassify("unsure");
+        case "3":
+          handleAxisChange("zx");
           break;
         case "arrowright":
           goToNextInstance();
@@ -425,35 +693,14 @@ function DetectionWorkflow({
     return () => window.removeEventListener("keydown", handleKeyPress);
   }, [sessionId, activeInstanceId, instances]);
 
-  const stats = useMemo(() => {
-    const total = instances.length;
-    const correct = instances.filter(
-      (i) => i.classification === "correct",
-    ).length;
-    const incorrect = instances.filter(
-      (i) => i.classification === "incorrect",
-    ).length;
-    const unsure = instances.filter(
-      (i) => i.classification === "unsure",
-    ).length;
-    const error = instances.filter((i) => i.classification === "error").length;
-    const reviewed = total - error;
-    const progress_percent = total > 0 ? (reviewed / total) * 100 : 0;
-
-    return {
-      correct,
-      incorrect,
-      unsure,
-      error,
-      total,
-      reviewed,
-      progress_percent: Math.round(progress_percent * 100) / 100,
-    };
-  }, [instances]);
-
   const handleDatasetLoad = async (datasetPath, maskPath, projectName) => {
     setLoadingInstances(true);
     try {
+      logProofreadingEvent("proofreading_dataset_load_started", {
+        datasetPath,
+        maskPath,
+        projectName,
+      });
       const response = await apiClient.post("/eh/detection/load", {
         dataset_path: datasetPath,
         mask_path: maskPath || null,
@@ -464,12 +711,22 @@ function DetectionWorkflow({
       setSessionId(response.data.session_id);
       setProjectName(response.data.project_name);
       setTotalLayers(response.data.total_layers);
+      logProofreadingEvent("proofreading_dataset_load_completed", {
+        nextSessionId: response.data.session_id,
+        totalLayers: response.data.total_layers,
+        projectName: response.data.project_name,
+      });
       message.success(
         `Loaded ${response.data.total_layers} slices successfully`,
       );
       await loadInstances(response.data.session_id, true);
     } catch (error) {
       console.error("Failed to load dataset:", error);
+      logProofreadingEvent(
+        "proofreading_dataset_load_failed",
+        { error: getErrorMessage(error, "Failed to load dataset") },
+        { level: "ERROR" },
+      );
       Modal.error({
         title: "Dataset load failed",
         content: getErrorMessage(
@@ -483,6 +740,47 @@ function DetectionWorkflow({
     }
   };
 
+  useEffect(() => {
+    if (pendingRuntimeAction?.kind !== "start_proofreading") return;
+    const action = pendingRuntimeAction;
+    const actionKey =
+      action.id ||
+      `${action.kind}:${action.created_at || action.createdAt || JSON.stringify(action.overrides || {})}`;
+    if (handledRuntimeActionIdsRef.current.has(actionKey)) return;
+    handledRuntimeActionIdsRef.current.add(actionKey);
+    consumeRuntimeAction?.(action.id);
+    if (sessionId) return;
+
+    const overrides = action.overrides || {};
+    const datasetPath =
+      overrides.datasetPath || getProofreadingImagePath(activeWorkflow);
+    const maskPath =
+      overrides.maskPath || getProofreadingMaskPath(activeWorkflow);
+    const nextProjectName =
+      overrides.projectName || activeWorkflow?.title || "Proofreading review";
+
+    if (!datasetPath) {
+      message.warning("Choose image data before proofreading.");
+      return;
+    }
+
+    handleDatasetLoad(datasetPath, maskPath, nextProjectName);
+    // Runtime actions are one-shot messages consumed above; handleDatasetLoad is
+    // intentionally not a dependency because it is defined in this large legacy component.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [
+    activeWorkflow?.corrected_mask_path,
+    activeWorkflow?.dataset_path,
+    activeWorkflow?.image_path,
+    activeWorkflow?.inference_output_path,
+    activeWorkflow?.label_path,
+    activeWorkflow?.mask_path,
+    activeWorkflow?.title,
+    consumeRuntimeAction,
+    pendingRuntimeAction,
+    sessionId,
+  ]);
+
   const isAbortError = (error) => {
     if (!error) return false;
     return (
@@ -526,11 +824,20 @@ function DetectionWorkflow({
     previewCacheOrder.current = [];
     filmstripBatchCacheOrder.current = [];
     filmstripFrameCacheOrder.current = [];
+    logProofreadingEvent(
+      "proofreading_frame_caches_cleared",
+      {},
+      { throttleMs: 1000 },
+    );
   };
 
   useEffect(() => {
     return () => {
       clearFrameCaches();
+      Object.values(orthoviewPayloadsRef.current).forEach((payload) =>
+        revokePayloadUrls(payload),
+      );
+      orthoviewPayloadsRef.current = {};
     };
   }, []);
 
@@ -663,10 +970,17 @@ function DetectionWorkflow({
       // blank between preview frames.
       maskAllBase64: payload.maskAllBase64 ?? prev.maskAllBase64,
       maskActiveBase64: payload.maskActiveBase64 ?? prev.maskActiveBase64,
-      maskRawBase64: payload.maskRawBase64 ?? prev.maskRawBase64,
+      maskRawBase64:
+        payload.maskRawBase64 ??
+        (payload.zIndex === prev.zIndex &&
+        payload.axis === prev.axis &&
+        payload.instanceId === prev.instanceId
+          ? prev.maskRawBase64
+          : null),
       zIndex: payload.zIndex,
       axis: payload.axis,
       total: payload.total,
+      instanceId: payload.instanceId ?? prev.instanceId,
     }));
     setAxisTotal(payload.total);
   };
@@ -848,6 +1162,7 @@ function DetectionWorkflow({
       zIndex: resolvedIndex,
       axis: resolvedAxis,
       total,
+      instanceId,
       batchStart: resolvedIndex,
       batchCount: 1,
       quality,
@@ -964,6 +1279,7 @@ function DetectionWorkflow({
       zIndex: resolvedStart + frameOffset,
       axis: resolvedAxis,
       total,
+      instanceId,
       batchStart: resolvedStart,
       batchCount: resolvedCount,
       quality,
@@ -1002,7 +1318,7 @@ function DetectionWorkflow({
     preferFilmstrip = ENABLE_FILMSTRIP_PREVIEW,
     signal,
   }) => {
-    const kinds = ["image"];
+    const kinds = ["image", "mask_active_binary"];
     if (!imageOnly) {
       if (includeActive) kinds.push("mask_active");
       if (includeAll) kinds.push("mask_all");
@@ -1070,17 +1386,46 @@ function DetectionWorkflow({
       setAxisTotal(nextTotalLayers);
       setPersistence(persistenceStatus);
 
-      if (uiState && shouldRestore) {
-        setOverlayAllAlpha(
-          clampAlpha(uiState.overlay_all_alpha, overlayAllAlpha),
-        );
-        setOverlayActiveAlpha(
-          clampAlpha(uiState.overlay_active_alpha, overlayActiveAlpha),
-        );
+      let nextOverlayAllAlpha =
+        uiState && shouldRestore
+          ? clampAlpha(uiState.overlay_all_alpha, overlayAllAlpha)
+          : overlayAllAlpha;
+      let nextOverlayActiveAlpha =
+        uiState && shouldRestore
+          ? clampAlpha(uiState.overlay_active_alpha, overlayActiveAlpha)
+          : overlayActiveAlpha;
+      let overlayVisibilityChanged = false;
+
+      if (shouldRestore && nextInstanceMode !== "none") {
+        if (nextOverlayAllAlpha <= 0.001 && nextOverlayActiveAlpha <= 0.001) {
+          nextOverlayAllAlpha = DEFAULT_OVERLAY_ALL_ALPHA;
+          nextOverlayActiveAlpha = DEFAULT_OVERLAY_ACTIVE_ALPHA;
+          overlayVisibilityChanged = true;
+        } else {
+          if (
+            supportsAllInstanceOverlay(nextInstanceMode) &&
+            nextOverlayAllAlpha > 0.001 &&
+            nextOverlayAllAlpha < DEFAULT_OVERLAY_ALL_ALPHA
+          ) {
+            nextOverlayAllAlpha = DEFAULT_OVERLAY_ALL_ALPHA;
+            overlayVisibilityChanged = true;
+          }
+          if (
+            nextOverlayActiveAlpha > 0.001 &&
+            nextOverlayActiveAlpha < DEFAULT_OVERLAY_ACTIVE_ALPHA
+          ) {
+            nextOverlayActiveAlpha = DEFAULT_OVERLAY_ACTIVE_ALPHA;
+            overlayVisibilityChanged = true;
+          }
+        }
+      }
+
+      if (shouldRestore || overlayVisibilityChanged) {
+        setOverlayAllAlpha(nextOverlayAllAlpha);
+        setOverlayActiveAlpha(nextOverlayActiveAlpha);
       }
 
       setViewAxis(axisToUse);
-      localStorage.setItem("mask-proofreading-axis", axisToUse);
 
       const firstUnreviewed = instanceList.find(
         (inst) => inst.classification === "error",
@@ -1107,6 +1452,11 @@ function DetectionWorkflow({
           zIndex: resolvedIndex,
           axis: axisToUse,
           total: nextTotalLayers,
+          instanceId: initialInstance.id,
+          imageBase64: null,
+          maskAllBase64: null,
+          maskActiveBase64: null,
+          maskRawBase64: null,
         }));
         setSliderZ(resolvedIndex);
         setCommittedZ(resolvedIndex);
@@ -1153,7 +1503,7 @@ function DetectionWorkflow({
         Math.min(zIndex + 1, totalForAxis - 1),
       ]),
     );
-    const kinds = ["image"];
+    const kinds = ["image", "mask_active_binary"];
     if (includeActive) kinds.push("mask_active");
     if (includeAll) kinds.push("mask_all");
     if (includeRaw) kinds.push("mask_active_binary");
@@ -1267,6 +1617,7 @@ function DetectionWorkflow({
     const maxDim = parsePositiveInt(options.maxDim, PREVIEW_MAX_DIM);
     const qualityLabel = options.qualityLabel || `preview-${maxDim}`;
     const imageOnly = options.imageOnly === true;
+    const includeAllContext = options.includeAllContext !== false;
     const shouldPrefetch =
       options.prefetchNeighbors !== false && !isFastScrubRef.current;
     const prefetchDistance =
@@ -1274,7 +1625,10 @@ function DetectionWorkflow({
       (isFastScrubRef.current ? 0 : PREVIEW_PREFETCH_RADIUS);
     const priority = Number.isFinite(options.priority) ? options.priority : 120;
     const includeAll =
-      !imageOnly && instanceMode === "instance" && overlayAllAlpha > 0.001;
+      !imageOnly &&
+      includeAllContext &&
+      supportsAllInstanceOverlay(instanceMode) &&
+      overlayAllAlpha > 0.001;
     const includeActive = !imageOnly && overlayActiveAlpha > 0.001;
     const cacheKey = buildCacheKey({
       instanceId,
@@ -1287,6 +1641,17 @@ function DetectionWorkflow({
     const cached = previewCache.current.get(cacheKey);
     if (cached) {
       perfCount("preview-cache-hit");
+      logProofreadingEvent(
+        "proofreading_slice_preview_cache_hit",
+        {
+          instanceId,
+          zIndex,
+          axis: axisToUse,
+          quality: qualityLabel,
+          imageOnly,
+        },
+        { throttleMs: 500 },
+      );
       setPreviewView(cached);
       setSliderZ(cached.zIndex ?? zIndex);
       setAxisTotal(cached.total ?? axisTotal);
@@ -1298,6 +1663,18 @@ function DetectionWorkflow({
     const startedAt = performance.now();
     try {
       perfCount("request_start");
+      logProofreadingEvent(
+        "proofreading_slice_preview_requested",
+        {
+          instanceId,
+          zIndex,
+          axis: axisToUse,
+          quality: qualityLabel,
+          imageOnly,
+          maxDim,
+        },
+        { throttleMs: 250 },
+      );
       const previewPayload = await schedulerRef.current.run({
         key: requestKey,
         lane: "interactive",
@@ -1322,6 +1699,18 @@ function DetectionWorkflow({
       setSliderZ(previewPayload.zIndex);
       setAxisTotal(previewPayload.total);
       perfLog("first_preview_paint", startedAt);
+      logProofreadingEvent(
+        "proofreading_slice_preview_loaded",
+        {
+          instanceId,
+          zIndex: previewPayload.zIndex,
+          axis: axisToUse,
+          quality: qualityLabel,
+          imageOnly,
+          elapsedMs: Number((performance.now() - startedAt).toFixed(1)),
+        },
+        { throttleMs: 250 },
+      );
       if (shouldPrefetch && prefetchDistance > 0) {
         prefetchPreviewNeighbors(
           instanceId,
@@ -1356,7 +1745,8 @@ function DetectionWorkflow({
     if (!sessionToUse || !instanceId) return;
     const axisToUse = axisOverride ?? viewAxis;
     const includeAll =
-      (modeOverride ?? instanceMode) === "instance" && overlayAllAlpha > 0.001;
+      supportsAllInstanceOverlay(modeOverride ?? instanceMode) &&
+      overlayAllAlpha > 0.001;
     const includeActive = overlayActiveAlpha > 0.001;
     const requestIdentity = [
       instanceId,
@@ -1380,6 +1770,12 @@ function DetectionWorkflow({
     const cached = viewCache.current.get(cacheKey);
     if (cached && (!includeRaw || cached.maskRawBase64)) {
       perfCount("full-cache-hit");
+      logProofreadingEvent("proofreading_slice_full_cache_hit", {
+        instanceId,
+        zIndex,
+        axis: axisToUse,
+        includeRaw,
+      });
       lastFullRequestKeyRef.current = requestIdentity;
       setViewState(cached);
       setAxisTotal(cached.total ?? axisTotal);
@@ -1421,6 +1817,14 @@ function DetectionWorkflow({
     const startedAt = performance.now();
     try {
       perfCount("request_start");
+      logProofreadingEvent("proofreading_slice_full_requested", {
+        instanceId,
+        zIndex,
+        axis: axisToUse,
+        includeRaw,
+        includeAll,
+        includeActive,
+      });
       const fullPayload = await schedulerRef.current.run({
         key: requestKey,
         lane: "interactive",
@@ -1451,6 +1855,13 @@ function DetectionWorkflow({
       setAxisTotal(fullPayload.total);
       setSliderZ(fullPayload.zIndex);
       perfLog("full_paint", startedAt);
+      logProofreadingEvent("proofreading_slice_full_loaded", {
+        instanceId,
+        zIndex: fullPayload.zIndex,
+        axis: axisToUse,
+        includeRaw,
+        elapsedMs: Number((performance.now() - startedAt).toFixed(1)),
+      });
       prefetchAdjacent(
         instanceId,
         fullPayload.zIndex,
@@ -1466,6 +1877,16 @@ function DetectionWorkflow({
         perfCount("dropped_request");
       } else {
         console.error("Failed to load instance view:", error);
+        logProofreadingEvent(
+          "proofreading_slice_full_failed",
+          {
+            instanceId,
+            zIndex,
+            axis: axisToUse,
+            error: getErrorMessage(error, "Failed to load instance view"),
+          },
+          { level: "ERROR" },
+        );
         message.error(getErrorMessage(error, "Failed to load instance view"));
       }
     } finally {
@@ -1487,8 +1908,18 @@ function DetectionWorkflow({
     }
   };
 
+  const clearSliceWheelTimers = () => {
+    Object.values(sliceWheelRef.current || {}).forEach((state) => {
+      if (state?.commitTimer) {
+        clearTimeout(state.commitTimer);
+      }
+    });
+    sliceWheelRef.current = {};
+  };
+
   const selectInstance = (instance) => {
     clearScrubTimers();
+    clearSliceWheelTimers();
     isScrubbingRef.current = false;
     isFastScrubRef.current = false;
     const axisIndex = clampSliceIndex(
@@ -1497,24 +1928,19 @@ function DetectionWorkflow({
     );
     setActiveInstanceId(instance.id);
     setActiveInstance(instance);
-    setViewState((prev) => ({ ...prev, zIndex: axisIndex }));
+    setViewState((prev) => ({
+      ...prev,
+      zIndex: axisIndex,
+      instanceId: instance.id,
+      imageBase64: null,
+      maskAllBase64: null,
+      maskActiveBase64: null,
+      maskRawBase64: null,
+    }));
     setSliderZ(axisIndex);
     setCommittedZ(axisIndex);
   };
 
-  const goToNextUnreviewed = () => {
-    if (instances.length === 0) return;
-    const pool = instances.filter((inst) => inst.classification === "error");
-    if (pool.length === 0) return;
-    if (!activeInstanceId) {
-      selectInstance(pool[0]);
-      return;
-    }
-    const currentIdx = pool.findIndex((inst) => inst.id === activeInstanceId);
-    const next = pool[(currentIdx + 1 + pool.length) % pool.length];
-    if (next) selectInstance(next);
-  };
-
   const goToNextInstance = () => {
     if (!activeInstanceId || instances.length === 0) return;
     const index = instances.findIndex((inst) => inst.id === activeInstanceId);
@@ -1529,58 +1955,6 @@ function DetectionWorkflow({
     if (prev) selectInstance(prev);
   };
 
-  const handleInstanceClassify = async (classification) => {
-    if (!activeInstanceId) return;
-    if (classificationPending) return;
-
-    const instanceId = activeInstanceId;
-    const previousClassification =
-      activeInstance?.classification ||
-      instances.find((inst) => inst.id === instanceId)?.classification ||
-      "error";
-
-    const applyLocalClassification = (instanceToUpdate, nextClassification) => {
-      setInstances((prev) =>
-        prev.map((inst) =>
-          inst.id === instanceToUpdate
-            ? { ...inst, classification: nextClassification }
-            : inst,
-        ),
-      );
-      setActiveInstance((prev) =>
-        prev && prev.id === instanceToUpdate
-          ? { ...prev, classification: nextClassification }
-          : prev,
-      );
-    };
-
-    // Optimistic update to keep the interaction snappy.
-    applyLocalClassification(instanceId, classification);
-    setClassificationPending(true);
-
-    try {
-      await apiClient.post("/eh/detection/instance-classify", {
-        session_id: sessionId,
-        instance_ids: [instanceId],
-        classification,
-        ui_state: {
-          axis: viewAxis,
-          overlay_all_alpha: overlayAllAlpha,
-          overlay_active_alpha: overlayActiveAlpha,
-          last_instance_id: instanceId,
-          last_slice_index: viewState.zIndex,
-        },
-      });
-    } catch (error) {
-      console.error("Failed to classify instance:", error);
-      // Roll back local optimistic state if save fails.
-      applyLocalClassification(instanceId, previousClassification);
-      message.error(getErrorMessage(error, "Failed to classify instance"));
-    } finally {
-      setClassificationPending(false);
-    }
-  };
-
   const handleSliceChange = (value) => {
     const nextIndex = clampSliceIndex(value, axisTotal || totalLayers);
     const now =
@@ -1598,7 +1972,7 @@ function DetectionWorkflow({
 
     const axisToUse = viewAxis;
     const fullIncludeAll =
-      instanceMode === "instance" && overlayAllAlpha > 0.001;
+      supportsAllInstanceOverlay(instanceMode) && overlayAllAlpha > 0.001;
     const fullIncludeActive = overlayActiveAlpha > 0.001;
     const includeAll = false;
     const includeActive = false;
@@ -1681,6 +2055,7 @@ function DetectionWorkflow({
         prefetchNeighbors: !isFastScrubRef.current,
         prefetchDistance: isFastScrubRef.current ? 0 : 1,
         imageOnly: false,
+        includeAllContext: false,
         priority: 110,
       });
     }, SCRUB_IDLE_MS);
@@ -1698,147 +2073,197 @@ function DetectionWorkflow({
       zIndex: nextIndex,
       at: typeof performance !== "undefined" ? performance.now() : Date.now(),
     };
+    logProofreadingEvent("proofreading_slice_committed", {
+      zIndex: nextIndex,
+      axis: viewAxis,
+    });
+    loadInstanceView(activeInstanceId, nextIndex, true, undefined, viewAxis);
   };
 
   const handleAxisChange = (nextAxis) => {
     clearScrubTimers();
+    clearSliceWheelTimers();
     const axisValue = nextAxis || "xy";
     isScrubbingRef.current = false;
     isFastScrubRef.current = false;
-    localStorage.setItem("mask-proofreading-axis", axisValue);
     setViewAxis(axisValue);
-    const axisIndex = clampSliceIndex(
-      getAxisIndexForInstance(activeInstance, axisValue),
-      axisTotal || totalLayers,
-    );
-    setViewState((prev) => ({ ...prev, zIndex: axisIndex, axis: axisValue }));
+    const cachedPlane = orthoviewPayloadsRef.current?.[axisValue];
+    const cachedTotal = Number(cachedPlane?.total) || 0;
+    const axisIndex = Number.isFinite(Number(cachedPlane?.zIndex))
+      ? Number(cachedPlane.zIndex)
+      : Math.max(
+          0,
+          Math.round(
+            Number(getAxisIndexForInstance(activeInstance, axisValue)) || 0,
+          ),
+        );
+    if (cachedTotal) {
+      setAxisTotal(cachedTotal);
+    }
+    setViewState((prev) => ({
+      ...prev,
+      ...(cachedPlane || {}),
+      zIndex: axisIndex,
+      axis: axisValue,
+      imageBase64: cachedPlane?.imageBase64 || null,
+      maskAllBase64: cachedPlane?.maskAllBase64 || null,
+      maskActiveBase64: cachedPlane?.maskActiveBase64 || null,
+      maskRawBase64: cachedPlane?.maskRawBase64 || null,
+      total: cachedTotal || prev.total,
+      instanceId: activeInstanceId,
+    }));
     setSliderZ(axisIndex);
     setCommittedZ(axisIndex);
   };
 
-  const handleSaveMask = async (maskBase64) => {
+  const reloadOrthoviewAxis = async (axis, zIndex) => {
+    if (!sessionId || !activeInstanceId || axis === viewAxis) return;
+    const includeAll =
+      supportsAllInstanceOverlay(instanceMode) && overlayAllAlpha > 0.001;
+    const includeActive = overlayActiveAlpha > 0.001;
+    const kinds = ["image", "mask_active_binary"];
+    if (includeActive) kinds.push("mask_active");
+    if (includeAll) kinds.push("mask_all");
+    setLoadingOrthoviews(true);
+    try {
+      const payload = await fetchInstanceBundle({
+        sessionId,
+        instanceId: activeInstanceId,
+        axis,
+        zIndex,
+        kinds,
+        maxDim: null,
+        quality: "full",
+      });
+      setOrthoviewPayloads((prev) => {
+        if (prev[axis]) revokePayloadUrls(prev[axis]);
+        const next = { ...prev, [axis]: payload };
+        orthoviewPayloadsRef.current = next;
+        return next;
+      });
+    } catch (error) {
+      if (!isAbortError(error)) {
+        console.warn("Failed to reload orthogonal editable plane:", error);
+      }
+    } finally {
+      setLoadingOrthoviews(false);
+    }
+  };
+
+  const handleSaveMaskForAxis = async (
+    axis,
+    zIndex,
+    planeState,
+    maskBase64,
+  ) => {
     if (!sessionId || !activeInstanceId) return;
+    const targetIndex = clampSliceIndex(zIndex, axisTotal || totalLayers);
+    const rawMaskMatchesCurrentSlice =
+      planeState?.axis === axis &&
+      planeState?.zIndex === targetIndex &&
+      planeState?.instanceId === activeInstanceId &&
+      Boolean(planeState?.maskRawBase64);
+    if (!rawMaskMatchesCurrentSlice) {
+      logProofreadingEvent(
+        "proofreading_mask_save_blocked_stale_mask",
+        {
+          targetIndex,
+          viewStateIndex: planeState?.zIndex,
+          viewStateAxis: planeState?.axis,
+          viewStateInstanceId: planeState?.instanceId,
+          hasRawMask: Boolean(planeState?.maskRawBase64),
+        },
+        { level: "WARNING" },
+      );
+      message.warning("Wait for the editable mask for this slice to load.");
+      if (axis === viewAxis) {
+        loadInstanceView(
+          activeInstanceId,
+          targetIndex,
+          true,
+          undefined,
+          viewAxis,
+        );
+      } else {
+        reloadOrthoviewAxis(axis, targetIndex);
+      }
+      throw new Error("Editable mask is not loaded for the current slice");
+    }
     setSavingMask(true);
     try {
-      await apiClient.post("/eh/detection/instance-mask", {
+      logProofreadingEvent("proofreading_mask_save_started", {
+        instanceId: activeInstanceId,
+        axis,
+        zIndex: targetIndex,
+      });
+      const response = await apiClient.post("/eh/detection/instance-mask", {
         session_id: sessionId,
         instance_id: activeInstanceId,
-        axis: viewAxis,
-        z_index: viewState.zIndex,
+        axis,
+        z_index: targetIndex,
         mask_base64: maskBase64,
         ui_state: {
-          axis: viewAxis,
+          axis,
           overlay_all_alpha: overlayAllAlpha,
           overlay_active_alpha: overlayActiveAlpha,
           last_instance_id: activeInstanceId,
-          last_slice_index: sliderZ ?? viewState.zIndex,
+          last_slice_index: targetIndex,
         },
       });
+      clearFrameCaches();
+      if (response.data?.persistence) {
+        setPersistence(response.data.persistence);
+      }
+      setMeshRevision((revision) => revision + 1);
       message.success("Instance mask updated");
+      logProofreadingEvent("proofreading_mask_save_completed", {
+        instanceId: activeInstanceId,
+        axis,
+        zIndex: targetIndex,
+        pixelsChanged: response.data?.edit?.pixels_changed,
+        artifactPath: response.data?.persistence?.artifact_path,
+        artifactExists: response.data?.persistence?.artifact_exists,
+      });
       refreshPersistenceStatus();
-      loadInstanceView(
-        activeInstanceId,
-        viewState.zIndex,
-        true,
-        undefined,
-        viewAxis,
-      );
+      if (axis === viewAxis) {
+        loadInstanceView(
+          activeInstanceId,
+          targetIndex,
+          true,
+          undefined,
+          viewAxis,
+        );
+      } else {
+        reloadOrthoviewAxis(axis, targetIndex);
+      }
     } catch (error) {
       console.error("Failed to save mask:", error);
+      logProofreadingEvent(
+        "proofreading_mask_save_failed",
+        {
+          instanceId: activeInstanceId,
+          axis,
+          zIndex: targetIndex,
+          error: getErrorMessage(error, "Failed to save mask"),
+        },
+        { level: "ERROR" },
+      );
       message.error(getErrorMessage(error, "Failed to save mask"));
+      throw error;
     } finally {
       setSavingMask(false);
     }
   };
 
-  const openExportModal = () => {
-    const artifactPath = persistence?.artifact_path;
-    if (artifactPath && artifactPath.endsWith(".tif")) {
-      setExportPath(artifactPath.replace(".tif", ".exported.tif"));
-    } else if (artifactPath && artifactPath.endsWith(".tiff")) {
-      setExportPath(artifactPath.replace(".tiff", ".exported.tif"));
-    } else {
-      setExportPath("");
-    }
-    setShowExportModal(true);
-  };
-
-  const handleExportMasks = async () => {
-    const output = exportPath?.trim();
-    if (!output) {
-      message.warning("Enter an output path to export edited masks.");
-      return;
-    }
-    setExportingMasks(true);
-    try {
-      const response = await apiClient.post("/eh/detection/export-masks", {
-        session_id: sessionId,
-        mode: "new_file",
-        output_path: output,
-        create_backup: true,
-      });
-      setShowExportModal(false);
-      setLastExportPath(response.data.written_path);
-      message.success(`Exported masks to ${response.data.written_path}`);
-      if (response.data.backup_path) {
-        message.info(`Backup created at ${response.data.backup_path}`);
-      }
-      refreshPersistenceStatus();
-    } catch (error) {
-      Modal.error({
-        title: "Export failed",
-        content: getErrorMessage(error, "Unable to export edited masks."),
-        okText: "OK",
-      });
-    } finally {
-      setExportingMasks(false);
-    }
-  };
-
-  const handleOverwriteSource = () => {
-    Modal.confirm({
-      title: "Overwrite source masks?",
-      content:
-        "This writes your edited masks back to the original source and always creates a timestamped backup first.",
-      okText: "Overwrite with backup",
-      okButtonProps: { danger: true, loading: overwritingSource },
-      cancelText: "Cancel",
-      onOk: async () => {
-        setOverwritingSource(true);
-        try {
-          const response = await apiClient.post("/eh/detection/export-masks", {
-            session_id: sessionId,
-            mode: "overwrite_source",
-            create_backup: true,
-          });
-          message.success(
-            `Source masks updated at ${response.data.written_path}`,
-          );
-          if (response.data.backup_path) {
-            message.info(`Backup created at ${response.data.backup_path}`);
-          }
-          setLastExportPath(response.data.written_path);
-          refreshPersistenceStatus();
-        } catch (error) {
-          Modal.error({
-            title: "Overwrite failed",
-            content: getErrorMessage(
-              error,
-              "Unable to overwrite source masks safely.",
-            ),
-            okText: "OK",
-          });
-        } finally {
-          setOverwritingSource(false);
-        }
-      },
-    });
-  };
-
   const handleStageForRetraining = async () => {
-    const correctedMaskPath = lastExportPath || persistence?.last_export_path;
+    const { path: correctedMaskPath, source } = getTrainingReadyCorrectedMask({
+      persistence,
+      workflow: activeWorkflow,
+    });
     if (!correctedMaskPath) {
-      message.warning("Export corrected masks before staging retraining.");
+      message.warning(
+        "Save an edit or export corrected masks before staging for training.",
+      );
       return;
     }
     if (!workflowContext?.workflow?.id) {
@@ -1859,7 +2284,7 @@ function DetectionWorkflow({
         payload: {
           corrected_mask_path: correctedMaskPath,
           ehtool_session_id: sessionId,
-          source: "proofreading_export",
+          source,
         },
       });
       if (appContext?.trainingState?.setInputLabel) {
@@ -1868,193 +2293,711 @@ function DetectionWorkflow({
       message.success("Corrected masks staged for retraining.");
     } catch (error) {
       message.error(
-        getErrorMessage(error, "Failed to stage corrected masks for retraining"),
+        getErrorMessage(
+          error,
+          "Failed to stage corrected masks for retraining",
+        ),
       );
     }
   };
 
+  const resetProofreadingSession = () => {
+    clearFrameCaches();
+    setSessionId(null);
+    setActiveInstanceId(null);
+    setActiveInstance(null);
+    setInstances([]);
+    setPersistence(null);
+    setVolumePreview(null);
+    setLiveMaskDraft(null);
+    setOrthoviewPayloads((prev) => {
+      Object.values(prev).forEach((payload) => revokePayloadUrls(payload));
+      orthoviewPayloadsRef.current = {};
+      return {};
+    });
+  };
+
+  const formatCount = (value) => {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed.toLocaleString() : value || 0;
+  };
+
+  const currentAxisTotal = axisTotal || totalLayers;
+  const currentSliceIndex = clampSliceIndex(
+    sliderZ ?? viewState.zIndex,
+    currentAxisTotal,
+  );
+  const isEditableMaskReady =
+    Boolean(viewState.maskRawBase64) &&
+    viewState.axis === viewAxis &&
+    viewState.zIndex === currentSliceIndex &&
+    viewState.instanceId === activeInstanceId;
+
+  useEffect(() => {
+    if (
+      !sessionId ||
+      !activeInstanceId ||
+      !activeInstance ||
+      instanceMode === "none"
+    ) {
+      setLoadingOrthoviews(false);
+      setOrthoviewPayloads((prev) => {
+        Object.values(prev).forEach((payload) => revokePayloadUrls(payload));
+        orthoviewPayloadsRef.current = {};
+        return {};
+      });
+      return undefined;
+    }
+
+    let cancelled = false;
+    const controller = new AbortController();
+    const axesToLoad = ORTHO_PANES.filter((pane) => pane.axis !== viewAxis);
+    const includeAll =
+      supportsAllInstanceOverlay(instanceMode) && overlayAllAlpha > 0.001;
+    const includeActive = overlayActiveAlpha > 0.001;
+    const kinds = ["image", "mask_active_binary"];
+    if (includeActive) kinds.push("mask_active");
+    if (includeAll) kinds.push("mask_all");
+
+    setLoadingOrthoviews(true);
+    Promise.allSettled(
+      axesToLoad.map(async (pane) => {
+        const zIndex = Math.max(
+          0,
+          Math.round(
+            Number(getAxisIndexForInstance(activeInstance, pane.axis)) || 0,
+          ),
+        );
+        const payload = await fetchInstanceBundle({
+          sessionId,
+          instanceId: activeInstanceId,
+          axis: pane.axis,
+          zIndex,
+          kinds,
+          maxDim: null,
+          quality: "full",
+          signal: controller.signal,
+        });
+        return { axis: pane.axis, payload };
+      }),
+    )
+      .then((results) => {
+        const next = {};
+        results.forEach((result) => {
+          if (result.status !== "fulfilled") return;
+          next[result.value.axis] = result.value.payload;
+        });
+        if (cancelled) {
+          Object.values(next).forEach((payload) => revokePayloadUrls(payload));
+          return;
+        }
+        setOrthoviewPayloads((prev) => {
+          Object.values(prev).forEach((payload) => revokePayloadUrls(payload));
+          orthoviewPayloadsRef.current = next;
+          return next;
+        });
+      })
+      .catch((error) => {
+        if (!isAbortError(error)) {
+          console.warn("Failed to load orthogonal previews:", error);
+        }
+      })
+      .finally(() => {
+        if (!cancelled) setLoadingOrthoviews(false);
+      });
+
+    return () => {
+      cancelled = true;
+      controller.abort();
+    };
+    // fetchInstanceBundle is recreated each render; the request is keyed by the
+    // explicit session, instance, axis, and overlay state above.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [
+    activeInstance,
+    activeInstanceId,
+    currentAxisTotal,
+    instanceMode,
+    meshRevision,
+    overlayActiveAlpha,
+    overlayAllAlpha,
+    sessionId,
+    totalLayers,
+    viewAxis,
+  ]);
+
   if (!sessionId) {
     return (
       <div style={{ padding: "24px 0" }}>
-        <DatasetLoader onLoad={handleDatasetLoad} loading={loadingInstances} />
+        <DatasetLoader
+          onLoad={handleDatasetLoad}
+          loading={loadingInstances}
+          workflow={activeWorkflow}
+        />
       </div>
     );
   }
 
-  const currentSliceIndex = clampSliceIndex(
-    sliderZ ?? viewState.zIndex,
-    axisTotal || totalLayers,
-  );
-  const exportedMaskPath = lastExportPath || persistence?.last_export_path || "";
-
-  const reviewControls =
+  const compactWorkbench = windowWidth < 980;
+  const queuePanelVisible = showQueue && !compactWorkbench;
+  const compactQueueVisible = showQueue && compactWorkbench;
+  const persistenceColor = persistence?.last_error
+    ? "red"
+    : persistence?.artifact_exists
+      ? "green"
+      : persistence?.enabled
+        ? "blue"
+        : "default";
+  const persistenceLabel = persistence?.last_error
+    ? "Save issue"
+    : persistence?.artifact_exists
+      ? "Edits saved"
+      : persistence?.enabled
+        ? "Ready to save"
+        : "No persistence";
+
+  const activeInstanceMeta =
     activeInstance && instanceMode !== "none" ? (
-      <div style={{ display: "grid", gap: 8 }}>
-        <Text style={{ fontSize: 13, fontWeight: 600 }}>
-          Instance #{activeInstance.id}
-        </Text>
-        <Space size="small" wrap>
-          <Button
-            size="small"
-            type="primary"
-            loading={classificationPending}
-            disabled={classificationPending}
-            onClick={() => handleInstanceClassify("correct")}
-          >
-            Looks good
-          </Button>
-          <Button
-            size="small"
-            danger
-            loading={classificationPending}
-            disabled={classificationPending}
-            onClick={() => handleInstanceClassify("incorrect")}
-          >
-            Needs fix
-          </Button>
-          <Button
-            size="small"
-            style={{ background: "#f59e0b", color: "#fff" }}
-            loading={classificationPending}
-            disabled={classificationPending}
-            onClick={() => handleInstanceClassify("unsure")}
-          >
-            Unsure
-          </Button>
-        </Space>
-      </div>
+      <Tag color="cyan" style={{ margin: 0 }}>
+        Instance #{activeInstance.id}
+      </Tag>
     ) : (
       <Text type="secondary" style={{ fontSize: 12 }}>
-        Select an instance to review.
+        Select an instance.
       </Text>
     );
 
-  const viewControls = (
-    <div style={{ display: "grid", gap: 6 }}>
+  const progressPanel = (
+    <div style={{ display: "grid", gap: 4 }}>
+      <Text strong style={{ fontSize: 13 }}>
+        {instances.length} instances
+      </Text>
       <Text type="secondary" style={{ fontSize: 12 }}>
-        Opacity controls
+        {activeInstance
+          ? `Selected #${activeInstance.id}`
+          : "Select an instance to inspect."}
       </Text>
-      <Space
-        size="small"
-        style={{ width: "100%", justifyContent: "space-between" }}
-      >
-        <Text style={{ fontSize: 12 }}>Other instances</Text>
-        <Text type="secondary" style={{ fontSize: 12 }}>
-          {Math.round(overlayAllAlpha * 100)}%
-        </Text>
-      </Space>
-      <Slider
-        min={0}
-        max={100}
-        value={Math.round(overlayAllAlpha * 100)}
-        onChange={(value) => setOverlayAllAlpha(value / 100)}
+    </div>
+  );
+
+  const queuePanel = (
+    <Card
+      size="small"
+      title="Review queue"
+      extra={
+        <Tag color="blue" style={{ margin: 0 }}>
+          {instances.length} total
+        </Tag>
+      }
+      bodyStyle={{ display: "grid", gap: 12 }}
+      style={{ height: "100%", borderRadius: 14 }}
+    >
+      {progressPanel}
+      <Divider style={{ margin: "4px 0" }} />
+      <InstanceNavigator
+        instances={instances}
+        activeInstanceId={activeInstanceId}
+        onSelect={selectInstance}
+        filterText={filterText}
+        onFilterText={setFilterText}
+        showClassification={false}
       />
-      <Space
-        size="small"
-        style={{ width: "100%", justifyContent: "space-between" }}
-      >
-        <Text style={{ fontSize: 12 }}>Selected instance</Text>
-        <Text type="secondary" style={{ fontSize: 12 }}>
-          {Math.round(overlayActiveAlpha * 100)}%
+    </Card>
+  );
+
+  const activeInstanceCoordinates = activeInstance
+    ? `XYZ ${formatCount(activeInstance.com_x)}, ${formatCount(
+        activeInstance.com_y,
+      )}, ${formatCount(activeInstance.com_z)}`
+    : "XYZ --";
+
+  const viewerToolbar = (
+    <div
+      style={{
+        display: "flex",
+        alignItems: "center",
+        justifyContent: "space-between",
+        gap: 12,
+        flexWrap: "wrap",
+        padding: "12px 16px",
+        borderBottom: "1px solid #e5e7eb",
+        background: "#ffffff",
+      }}
+    >
+      <Space size="small" wrap>
+        <Text strong style={{ fontSize: 13 }}>
+          {formatAxisLabel(viewAxis)} {currentSliceIndex + 1} /{" "}
+          {Math.max(currentAxisTotal, 1)}
         </Text>
+        <div style={{ width: 220, maxWidth: "42vw" }}>
+          <Slider
+            min={0}
+            max={Math.max(currentAxisTotal - 1, 0)}
+            value={currentSliceIndex}
+            disabled={currentAxisTotal <= 1}
+            tooltip={{ formatter: (value) => `Slice ${Number(value) + 1}` }}
+            onChange={handleSliceChange}
+            onChangeComplete={handleSliceCommit}
+          />
+        </div>
+        <Tag color="default" style={{ margin: 0 }}>
+          {activeInstanceCoordinates}
+        </Tag>
+        {activeInstanceMeta}
+        {!isEditableMaskReady && (
+          <Tag color="blue" style={{ margin: 0 }}>
+            loading mask
+          </Tag>
+        )}
+        {savingMask && (
+          <Tag color="processing" style={{ margin: 0 }}>
+            saving
+          </Tag>
+        )}
       </Space>
-      <Slider
-        min={0}
-        max={100}
-        value={Math.round(overlayActiveAlpha * 100)}
-        onChange={(value) => setOverlayActiveAlpha(value / 100)}
-      />
+      <Space size="small" wrap>
+        <Button size="small" onClick={goToNextInstance}>
+          Next instance
+        </Button>
+        <Button size="small" type="primary" onClick={handleStageForRetraining}>
+          Use edits for training
+        </Button>
+      </Space>
+    </div>
+  );
+
+  const getActiveEditor = () => editorRefs.current[viewAxis] || null;
+  const setActiveTool = (nextTool) => {
+    getActiveEditor()?.setTool?.(nextTool);
+    setActiveToolState((prev) => ({ ...prev, tool: nextTool }));
+  };
+  const setActiveBrushSize = (value) => {
+    const numeric = Number(value);
+    if (!Number.isFinite(numeric)) return;
+    const nextSize = Math.max(1, Math.min(50, Math.round(numeric)));
+    getActiveEditor()?.setBrushSize?.(nextSize);
+    setActiveToolState((prev) => ({ ...prev, activeBrushSize: nextSize }));
+  };
+  const brushSizeControl = (
+    <div style={{ width: 220, padding: "2px 4px" }}>
+      <Text strong style={{ display: "block", marginBottom: 8 }}>
+        Brush size
+      </Text>
+      <div
+        style={{
+          display: "grid",
+          gridTemplateColumns: "1fr 64px",
+          gap: 10,
+          alignItems: "center",
+        }}
+      >
+        <Slider
+          min={1}
+          max={50}
+          value={activeToolState.activeBrushSize || 10}
+          onChange={setActiveBrushSize}
+          tooltip={{ formatter: (value) => `${value}px` }}
+        />
+        <InputNumber
+          min={1}
+          max={50}
+          size="small"
+          value={activeToolState.activeBrushSize || 10}
+          onChange={setActiveBrushSize}
+        />
+      </div>
     </div>
   );
+  const normalizeWheelDelta = (wheel) => {
+    const deltaY = Number(wheel?.deltaY ?? wheel ?? 0);
+    const deltaMode = Number(wheel?.deltaMode ?? 0);
+    if (deltaMode === 1) return deltaY * 32;
+    if (deltaMode === 2) return deltaY * 240;
+    return deltaY;
+  };
 
-  const instanceControls =
-    instanceMode !== "none" && instances.length > 0 ? (
-      <div style={{ display: "grid", gap: 8 }}>
-        <Space size="small" wrap>
+  const stepAxisSlice = (
+    axis,
+    currentIndex,
+    delta,
+    totalOverride,
+    options = {},
+  ) => {
+    const totalForPlane =
+      Number(totalOverride) ||
+      (axis === viewAxis ? currentAxisTotal : 0) ||
+      currentAxisTotal ||
+      totalLayers;
+    const nextIndex = clampSliceIndex(currentIndex + delta, totalForPlane);
+    if (nextIndex === currentIndex) return nextIndex;
+    if (axis === viewAxis) {
+      if (options.previewOnly) {
+        handleSliceChange(nextIndex);
+      } else {
+        handleSliceCommit(nextIndex);
+      }
+    } else {
+      reloadOrthoviewAxis(axis, nextIndex);
+    }
+    return nextIndex;
+  };
+  const handlePaneSliceWheel = (axis, currentIndex, wheel, totalOverride) => {
+    const deltaPixels = normalizeWheelDelta(wheel);
+    if (Math.abs(deltaPixels) < 1) return;
+    const now =
+      typeof performance !== "undefined" ? performance.now() : Date.now();
+    const state = sliceWheelRef.current[axis] || {};
+    const baseIndex =
+      now - (state.at || 0) > 320
+        ? currentIndex
+        : Number.isFinite(state.index)
+          ? state.index
+          : currentIndex;
+    const nextRemainder =
+      (now - (state.at || 0) > 320 ? 0 : state.remainder || 0) + deltaPixels;
+    let steps = Math.trunc(nextRemainder / WHEEL_SLICE_DELTA_PX);
+    if (!steps) {
+      sliceWheelRef.current[axis] = {
+        ...state,
+        index: baseIndex,
+        remainder: nextRemainder,
+        at: now,
+      };
+      return;
+    }
+    steps = Math.max(-4, Math.min(4, steps));
+    const usedDelta = steps * WHEEL_SLICE_DELTA_PX;
+    const nextIndex = stepAxisSlice(axis, baseIndex, steps, totalOverride, {
+      previewOnly: axis === viewAxis,
+    });
+    if (state.commitTimer) {
+      clearTimeout(state.commitTimer);
+    }
+    const nextState = {
+      index: nextIndex,
+      remainder: nextRemainder - usedDelta,
+      at: now,
+      commitTimer: null,
+    };
+    if (axis === viewAxis) {
+      nextState.commitTimer = setTimeout(() => {
+        handleSliceCommit(nextIndex);
+        if (sliceWheelRef.current[axis]) {
+          sliceWheelRef.current[axis].remainder = 0;
+          sliceWheelRef.current[axis].commitTimer = null;
+        }
+      }, WHEEL_SLICE_IDLE_MS);
+    }
+    sliceWheelRef.current[axis] = nextState;
+  };
+  const toolButtonStyle = {
+    width: 36,
+    height: 36,
+    display: "inline-flex",
+    alignItems: "center",
+    justifyContent: "center",
+  };
+  const sharedToolRail = (
+    <aside
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        alignItems: "center",
+        gap: 8,
+        padding: "8px 6px",
+        borderRight: "1px solid #1f2937",
+        background: "#0b1220",
+      }}
+    >
+      <Tag color="blue" style={{ margin: 0, fontSize: 10 }}>
+        {formatAxisLabel(viewAxis)}
+      </Tag>
+      <div
+        style={{
+          width: 28,
+          height: 1,
+          background: "rgba(148, 163, 184, 0.28)",
+          margin: "2px 0",
+        }}
+      />
+      <Tooltip title="Paint">
+        <Button
+          size="small"
+          type={activeToolState.tool === "paint" ? "primary" : "default"}
+          icon={<EditOutlined />}
+          disabled={!activeToolState.canEdit}
+          onClick={() => setActiveTool("paint")}
+          style={toolButtonStyle}
+        />
+      </Tooltip>
+      <Tooltip title="Erase">
+        <Button
+          size="small"
+          type={activeToolState.tool === "erase" ? "primary" : "default"}
+          icon={<ClearOutlined />}
+          disabled={!activeToolState.canEdit}
+          onClick={() => setActiveTool("erase")}
+          style={toolButtonStyle}
+        />
+      </Tooltip>
+      <Popover
+        content={brushSizeControl}
+        trigger="click"
+        placement="right"
+        overlayStyle={{ width: 252 }}
+      >
+        <Tooltip title="Brush size">
           <Button
             size="small"
-            type="primary"
-            onClick={() => setShowInstanceBrowser(true)}
-          >
-            Browse...
-          </Button>
-          <Button size="small" onClick={goToNextUnreviewed}>
-            Next unreviewed
-          </Button>
-          {exportedMaskPath && (
-            <Button
-              size="small"
-              type="primary"
-              onClick={handleStageForRetraining}
-            >
-              Stage for retraining
-            </Button>
-          )}
-          <Dropdown
-            trigger={["click"]}
-            menu={{
-              items: [
-                {
-                  key: "export",
-                  label: "Export edited masks...",
-                  onClick: openExportModal,
-                },
-                {
-                  key: "overwrite",
-                  label: "Overwrite source masks...",
-                  danger: true,
-                  onClick: handleOverwriteSource,
-                },
-              ],
+            disabled={!activeToolState.canEdit}
+            style={{
+              ...toolButtonStyle,
+              fontSize: 11,
+              fontWeight: 700,
+              padding: 0,
             }}
           >
-            <Button size="small" icon={<MoreOutlined />} />
-          </Dropdown>
-        </Space>
-        <Space size="small" align="center">
-          <Text type="secondary" style={{ fontSize: 12 }}>
-            Instances
+            {activeToolState.activeBrushSize || 10}
+          </Button>
+        </Tooltip>
+      </Popover>
+      <Tooltip title="Pan">
+        <Button
+          size="small"
+          type={activeToolState.tool === "hand" ? "primary" : "default"}
+          icon={<DragOutlined />}
+          onClick={() => setActiveTool("hand")}
+          style={toolButtonStyle}
+        />
+      </Tooltip>
+      <Tooltip title={activeToolState.showMask ? "Hide mask" : "Show mask"}>
+        <Button
+          size="small"
+          icon={
+            activeToolState.showMask ? (
+              <EyeInvisibleOutlined />
+            ) : (
+              <EyeOutlined />
+            )
+          }
+          onClick={() => getActiveEditor()?.toggleMask?.()}
+          style={toolButtonStyle}
+        />
+      </Tooltip>
+      <Tooltip title="Save active plane">
+        <Button
+          size="small"
+          type={activeToolState.hasUnsavedEdits ? "primary" : "default"}
+          icon={<SaveOutlined />}
+          disabled={!activeToolState.canEdit}
+          onClick={() => getActiveEditor()?.save?.()}
+          style={toolButtonStyle}
+        />
+      </Tooltip>
+      <div
+        style={{
+          width: 28,
+          height: 1,
+          background: "rgba(148, 163, 184, 0.28)",
+          margin: "2px 0",
+        }}
+      />
+      <Tooltip title="Zoom in">
+        <Button
+          size="small"
+          icon={<ZoomInOutlined />}
+          onClick={() => getActiveEditor()?.zoomIn?.()}
+          style={toolButtonStyle}
+        />
+      </Tooltip>
+      <Tooltip title="Zoom out">
+        <Button
+          size="small"
+          icon={<ZoomOutOutlined />}
+          onClick={() => getActiveEditor()?.zoomOut?.()}
+          style={toolButtonStyle}
+        />
+      </Tooltip>
+    </aside>
+  );
+
+  const editorSurface =
+    loadingInstances && instances.length === 0 ? (
+      <Card style={{ minHeight: 420, borderRadius: 14 }}>
+        <div style={{ padding: 32, textAlign: "center" }}>
+          <Title level={4}>Preparing instances...</Title>
+          <Text type="secondary">
+            Building the review queue and loading the first editable slice.
           </Text>
-          <Tag style={{ margin: 0 }}>{instances.length}</Tag>
-        </Space>
-      </div>
+        </div>
+      </Card>
+    ) : instanceMode === "none" ? (
+      <Card style={{ minHeight: 420, borderRadius: 14 }}>
+        <div style={{ padding: 32, textAlign: "center" }}>
+          <Title level={4}>Mask required</Title>
+          <Text type="secondary">
+            Load a dataset with a mask to enable instance proofreading.
+          </Text>
+        </div>
+      </Card>
     ) : (
-      <Text type="secondary" style={{ fontSize: 12 }}>
-        No instances available.
-      </Text>
-    );
-
-  const inspectorItems = [
-    { key: "review", label: "Review", children: reviewControls },
-    { key: "instances", label: "Instances", children: instanceControls },
-    { key: "view", label: "Overlay", children: viewControls },
-    {
-      key: "progress",
-      label: "Progress",
-      children: (
-        <ProgressTracker
-          stats={stats}
-          projectName={projectName}
-          totalLayers={instances.length}
-          unitLabel="instances"
-          compact
-          onNewSession={() => {
-            setSessionId(null);
-            setActiveInstanceId(null);
-            setInstances([]);
-            setPersistence(null);
+      <section
+        data-proofreader-wheel-lock="true"
+        style={{
+          display: "grid",
+          overflow: "hidden",
+          borderRadius: 18,
+          border: "1px solid #d8e1dc",
+          background: "#ffffff",
+          boxShadow: "0 18px 45px rgba(15, 23, 42, 0.08)",
+        }}
+      >
+        {viewerToolbar}
+        <div
+          style={{
+            display: "grid",
+            gridTemplateColumns: "50px minmax(0, 1fr)",
+            background: "#111827",
+            minHeight: 0,
+            overscrollBehavior: "contain",
           }}
-          onJumpToNext={goToNextUnreviewed}
-        />
-      ),
-    },
-  ];
+        >
+          {sharedToolRail}
+          <div
+            style={{
+              display: "grid",
+              gridTemplateColumns:
+                windowWidth < 1180
+                  ? "minmax(0, 1fr)"
+                  : "minmax(0, 1fr) minmax(0, 1fr)",
+              gridAutoRows: windowWidth < 1180 ? "360px" : "minmax(260px, 1fr)",
+              height:
+                windowWidth < 1180
+                  ? "auto"
+                  : "clamp(560px, calc(100vh - 270px), 860px)",
+              gap: 2,
+              padding: 2,
+              minWidth: 0,
+              minHeight: 0,
+              background: "#111827",
+              overscrollBehavior: "contain",
+            }}
+          >
+            {ORTHO_PANES.map((pane) => {
+              const activePane = pane.axis === viewAxis;
+              const payload = activePane
+                ? viewState
+                : orthoviewPayloads[pane.axis];
+              const planeReady = Boolean(payload?.imageBase64);
+              const planeIndex = clampSliceIndex(
+                payload?.zIndex ??
+                  getAxisIndexForInstance(activeInstance, pane.axis),
+                payload?.total ||
+                  (activePane ? currentAxisTotal : 0) ||
+                  currentAxisTotal,
+              );
+              const planeTotal =
+                Number(payload?.total) ||
+                (activePane ? currentAxisTotal : 0) ||
+                currentAxisTotal ||
+                totalLayers;
+              const planeCanEdit =
+                Boolean(payload?.maskRawBase64) &&
+                payload?.axis === pane.axis &&
+                payload?.instanceId === activeInstanceId;
+              return (
+                <OrthoviewPane
+                  key={pane.axis}
+                  axis={pane.axis}
+                  label={pane.label}
+                  payload={payload}
+                  loading={
+                    activePane
+                      ? loadingView || loadingInstances
+                      : loadingOrthoviews
+                  }
+                  active={activePane}
+                  editable={planeReady}
+                  onActivate={() => {
+                    if (!activePane) handleAxisChange(pane.axis);
+                  }}
+                  onSliceWheel={(wheel) =>
+                    handlePaneSliceWheel(
+                      pane.axis,
+                      planeIndex,
+                      wheel,
+                      planeTotal,
+                    )
+                  }
+                >
+                  {planeReady && (
+                    <ProofreadingEditor
+                      ref={(node) => {
+                        if (node) editorRefs.current[pane.axis] = node;
+                        else delete editorRefs.current[pane.axis];
+                      }}
+                      imageBase64={payload.imageBase64}
+                      maskBase64={payload.maskRawBase64}
+                      overlayAllBase64={payload.maskAllBase64}
+                      overlayActiveBase64={payload.maskActiveBase64}
+                      overlayAllAlpha={overlayAllAlpha}
+                      overlayActiveAlpha={overlayActiveAlpha}
+                      loading={
+                        activePane
+                          ? loadingView || loadingInstances
+                          : loadingOrthoviews
+                      }
+                      axis={pane.axis}
+                      activeInstanceId={activeInstanceId}
+                      onSave={(maskBase64) =>
+                        handleSaveMaskForAxis(
+                          pane.axis,
+                          planeIndex,
+                          payload,
+                          maskBase64,
+                        )
+                      }
+                      onMaskDraftChange={setLiveMaskDraft}
+                      currentLayer={planeIndex}
+                      totalLayers={planeTotal}
+                      layerName={`${pane.label} ${planeIndex + 1}`}
+                      canEdit={planeCanEdit}
+                      saveDisabledReason="Editable mask for this slice is still loading."
+                      minimalChrome
+                      hideLayerToolbar
+                      editorHeightOverride="100%"
+                      keyboardEnabled={activePane}
+                      hideToolPanel
+                      onToolStateChange={
+                        activePane ? setActiveToolState : undefined
+                      }
+                    />
+                  )}
+                </OrthoviewPane>
+              );
+            })}
+            <Instance3DPreview
+              preview={volumePreview}
+              liveSlice={liveMaskDraft}
+              axis={liveMaskDraft?.axis || viewAxis}
+              layerIndex={liveMaskDraft?.layerIndex ?? currentSliceIndex}
+              activeInstanceId={activeInstanceId}
+              loading={loadingVolumePreview}
+              fill
+            />
+          </div>
+        </div>
+      </section>
+    );
 
   return (
     <Layout
       style={{
-        minHeight: "calc(100vh - 210px)",
-        background: "transparent",
+        minHeight: "calc(100vh - 180px)",
+        background:
+          "linear-gradient(135deg, rgba(240,247,244,0.95), rgba(245,241,232,0.95))",
+        borderRadius: 18,
+        padding: 12,
       }}
     >
       <Content style={{ padding: 0 }}>
@@ -2063,186 +3006,68 @@ function DetectionWorkflow({
             display: "flex",
             justifyContent: "space-between",
             alignItems: "center",
-            marginBottom: 10,
+            gap: 12,
+            flexWrap: "wrap",
+            padding: "4px 2px 14px",
           }}
         >
-          <Title level={5} style={{ margin: 0 }}>
-            Instance proofreading
-          </Title>
-          <Space size="small">
+          <Space size="small" wrap>
+            <Title level={4} style={{ margin: 0 }}>
+              Mask proofreading
+            </Title>
+            <Tag color="geekblue" style={{ margin: 0 }}>
+              {projectName || "Untitled project"}
+            </Tag>
+            <Tag color={persistenceColor} style={{ margin: 0 }}>
+              {persistenceLabel}
+            </Tag>
+          </Space>
+          <Space size="small" wrap>
+            <Button size="small" onClick={resetProofreadingSession}>
+              Change data
+            </Button>
             <Button
               size="small"
-              type={showInspector ? "default" : "primary"}
-              onClick={() => setShowInspector((prev) => !prev)}
+              type={queuePanelVisible ? "default" : "primary"}
+              onClick={() => setShowQueue((prev) => !prev)}
             >
-              {showInspector ? "Focus canvas" : "Show sidebar"}
+              {queuePanelVisible ? "Focus view" : "Show queue"}
             </Button>
           </Space>
         </div>
 
-        <Layout style={{ background: "transparent", position: "relative" }}>
-          <Content style={{ padding: showInspector ? "0 14px 0 0" : 0 }}>
-            {loadingInstances && instances.length === 0 ? (
-              <div style={{ padding: 32, textAlign: "center" }}>
-                <Title level={4}>Preparing instances…</Title>
-                <Text type="secondary">
-                  Building the instance list and loading the first view.
-                </Text>
-              </div>
-            ) : instanceMode === "none" ? (
-              <div style={{ padding: 32, textAlign: "center" }}>
-                <Title level={4}>Mask required</Title>
-                <Text type="secondary">
-                  Load a dataset with a mask to enable instance proofreading.
-                </Text>
-              </div>
-            ) : (
-              <>
-                <ProofreadingEditor
-                  imageBase64={viewState.imageBase64}
-                  maskBase64={viewState.maskRawBase64}
-                  overlayAllBase64={viewState.maskAllBase64}
-                  overlayActiveBase64={viewState.maskActiveBase64}
-                  overlayAllAlpha={overlayAllAlpha}
-                  overlayActiveAlpha={overlayActiveAlpha}
-                  loading={loadingView || loadingInstances}
-                  axis={viewAxis}
-                  axisOptions={axisOptions}
-                  onAxisChange={handleAxisChange}
-                  activeInstanceId={activeInstanceId}
-                  onSave={handleSaveMask}
-                  onNext={() =>
-                    handleSliceCommit(
-                      Math.min(
-                        currentSliceIndex + 1,
-                        (axisTotal || totalLayers) - 1,
-                      ),
-                    )
-                  }
-                  onPrevious={() =>
-                    handleSliceCommit(Math.max(currentSliceIndex - 1, 0))
-                  }
-                  currentLayer={currentSliceIndex}
-                  totalLayers={axisTotal || totalLayers}
-                  layerName={`${viewAxis.toUpperCase()} ${currentSliceIndex + 1}`}
-                  minimalChrome
-                />
-                <div style={{ marginTop: 16 }}>
-                  <Slider
-                    min={0}
-                    max={Math.max((axisTotal || totalLayers) - 1, 0)}
-                    value={currentSliceIndex}
-                    onChange={handleSliceChange}
-                    onAfterChange={handleSliceCommit}
-                    tooltip={{
-                      formatter: (value) =>
-                        `${viewAxis.toUpperCase()} ${value + 1}`,
-                    }}
-                  />
-                </div>
-                {savingMask && (
-                  <div style={{ marginTop: 8 }}>
-                    <Text type="secondary">Saving mask…</Text>
-                  </div>
-                )}
-              </>
-            )}
-          </Content>
-
-          {showInspector && (
+        <Layout
+          style={{
+            background: "transparent",
+            display: "flex",
+            gap: 12,
+          }}
+        >
+          {queuePanelVisible && (
             <Sider
-              width={Math.max(260, Math.min(360, windowWidth * 0.3))}
+              width={280}
               theme="light"
-              style={{
-                borderLeft: "1px solid #eef2f7",
-                background: "transparent",
-              }}
+              style={{ background: "transparent" }}
             >
-              <div style={{ padding: "12px 12px", display: "grid", gap: 12 }}>
-                <div
-                  style={{
-                    display: "flex",
-                    alignItems: "center",
-                    justifyContent: "space-between",
-                    padding: "0 2px 2px",
-                    borderBottom: "1px solid #eef2f7",
-                  }}
-                >
-                  <Space size={8} align="center">
-                    <Text
-                      type="secondary"
-                      style={{
-                        fontSize: 11,
-                        letterSpacing: 0.6,
-                        textTransform: "uppercase",
-                      }}
-                    >
-                      {viewAxis.toUpperCase()}
-                    </Text>
-                    <Text style={{ fontSize: 14, fontWeight: 500 }}>
-                      Slice {currentSliceIndex + 1}
-                    </Text>
-                  </Space>
-                  <Text type="secondary" style={{ fontSize: 12 }}>
-                    {axisTotal || totalLayers} slices
-                  </Text>
-                </div>
-                <Collapse
-                  bordered={false}
-                  size="small"
-                  activeKey={inspectorSections}
-                  onChange={(keys) =>
-                    setInspectorSections(Array.isArray(keys) ? keys : [keys])
-                  }
-                  items={inspectorItems}
-                />
-              </div>
+              {queuePanel}
             </Sider>
           )}
+          <Content style={{ minWidth: 0 }}>{editorSurface}</Content>
         </Layout>
-      </Content>
 
-      {/* Editor is now inline to keep context */}
-      <Drawer
-        title="Browse instances"
-        open={showInstanceBrowser}
-        onClose={() => setShowInstanceBrowser(false)}
-        width={380}
-      >
-        <InstanceNavigator
-          instances={instances}
-          activeInstanceId={activeInstanceId}
-          onSelect={(inst) => {
-            selectInstance(inst);
-            setShowInstanceBrowser(false);
-          }}
-          onPrev={goToPreviousInstance}
-          onNext={goToNextInstance}
-          filterText={filterText}
-          onFilterText={setFilterText}
-          instanceMode={instanceMode}
-        />
-      </Drawer>
-      <Modal
-        title="Export edited masks"
-        open={showExportModal}
-        onCancel={() => setShowExportModal(false)}
-        onOk={handleExportMasks}
-        confirmLoading={exportingMasks}
-        okText="Export"
-      >
-        <div style={{ display: "grid", gap: 8 }}>
-          <Text type="secondary" style={{ fontSize: 12 }}>
-            Choose where to write a TIFF containing the current edited instance
-            volume.
-          </Text>
-          <Input
-            value={exportPath}
-            onChange={(event) => setExportPath(event.target.value)}
-            placeholder="/path/to/edited_masks.tif"
-          />
-        </div>
-      </Modal>
+        {compactQueueVisible && (
+          <div
+            style={{
+              display: "grid",
+              gridTemplateColumns: "repeat(auto-fit, minmax(320px, 1fr))",
+              gap: 12,
+              marginTop: 12,
+            }}
+          >
+            {queuePanel}
+          </div>
+        )}
+      </Content>
     </Layout>
   );
 }
diff --git a/client/src/views/ehtool/Instance3DPreview.js b/client/src/views/ehtool/Instance3DPreview.js
new file mode 100644
index 00000000..1abf0182
--- /dev/null
+++ b/client/src/views/ehtool/Instance3DPreview.js
@@ -0,0 +1,475 @@
+import React, { useEffect, useMemo, useRef, useState } from "react";
+import { Spin, Typography } from "antd";
+import * as THREE from "three";
+import { OrbitControls } from "three/examples/jsm/controls/OrbitControls";
+
+const { Text } = Typography;
+
+const hsvToRgb = (h, s, v) => {
+  const i = Math.floor(h * 6);
+  const f = h * 6 - i;
+  const p = v * (1 - s);
+  const q = v * (1 - f * s);
+  const t = v * (1 - (1 - f) * s);
+  let r;
+  let g;
+  let b;
+  switch (i % 6) {
+    case 0:
+      r = v;
+      g = t;
+      b = p;
+      break;
+    case 1:
+      r = q;
+      g = v;
+      b = p;
+      break;
+    case 2:
+      r = p;
+      g = v;
+      b = t;
+      break;
+    case 3:
+      r = p;
+      g = q;
+      b = v;
+      break;
+    case 4:
+      r = t;
+      g = p;
+      b = v;
+      break;
+    default:
+      r = v;
+      g = p;
+      b = q;
+      break;
+  }
+  return [Math.round(r * 255), Math.round(g * 255), Math.round(b * 255)];
+};
+
+const glasbeyColor = (labelId) => {
+  const numeric = Number(labelId) || 0;
+  const idx = Math.abs(Math.floor(numeric)) % 256;
+  const golden = 0.61803398875;
+  const h = ((idx + 1) * golden) % 1.0;
+  const s = 0.65 + 0.3 * ((idx % 3) / 2.0);
+  const v = 0.9;
+  return hsvToRgb(h, s, v);
+};
+
+const slicePointToZyx = (point, axis, layerIndex) => {
+  const x = point[0];
+  const y = point[1];
+  if (axis === "zx") return [y, layerIndex, x];
+  if (axis === "zy") return [y, x, layerIndex];
+  return [layerIndex, y, x];
+};
+
+const makeTransform = (preview) => {
+  const bbox = preview?.bbox_zyx || {};
+  const min = bbox.min || [0, 0, 0];
+  const max = bbox.max || preview?.shape_zyx || [1, 1, 1];
+  const center = [
+    (min[0] + max[0]) / 2,
+    (min[1] + max[1]) / 2,
+    (min[2] + max[2]) / 2,
+  ];
+  const span = [
+    Math.max(1, max[0] - min[0] + 1),
+    Math.max(1, max[1] - min[1] + 1),
+    Math.max(1, max[2] - min[2] + 1),
+  ];
+  const scale = 3.6 / Math.max(span[1], span[2], span[0] * 2.2);
+  const zStretch = Math.min(
+    5,
+    Math.max(1.6, Math.max(span[1], span[2]) / span[0] / 2.2),
+  );
+  const toScene = (point) => [
+    (point[2] - center[2]) * scale,
+    -(point[1] - center[1]) * scale,
+    (point[0] - center[0]) * scale * zStretch,
+  ];
+  return { toScene };
+};
+
+const isFinitePoint = (point) =>
+  Array.isArray(point) &&
+  point.length >= 3 &&
+  point.every((value) => Number.isFinite(Number(value)));
+
+const buildMeshPayload = (preview) => {
+  if (!preview?.vertices_zyx?.length || !preview?.faces?.length) return null;
+  const { toScene } = makeTransform(preview);
+  const sourceVertices = preview.vertices_zyx;
+  const positions = [];
+  const vertexMap = new Map();
+
+  const mapVertex = (sourceIndex) => {
+    if (!Number.isInteger(sourceIndex)) return null;
+    if (sourceIndex < 0 || sourceIndex >= sourceVertices.length) return null;
+    if (vertexMap.has(sourceIndex)) return vertexMap.get(sourceIndex);
+
+    const sourcePoint = sourceVertices[sourceIndex];
+    if (!isFinitePoint(sourcePoint)) return null;
+    const scenePoint = toScene(sourcePoint);
+    if (!scenePoint.every((value) => Number.isFinite(value))) return null;
+
+    const mappedIndex = positions.length / 3;
+    positions.push(scenePoint[0], scenePoint[1], scenePoint[2]);
+    vertexMap.set(sourceIndex, mappedIndex);
+    return mappedIndex;
+  };
+
+  const indices = [];
+  preview.faces.forEach((face) => {
+    if (!Array.isArray(face) || face.length < 3) return;
+    const a = mapVertex(Number(face[0]));
+    const b = mapVertex(Number(face[1]));
+    const c = mapVertex(Number(face[2]));
+    if (a == null || b == null || c == null) return;
+    if (a === b || b === c || a === c) return;
+    indices.push(a, b, c);
+  });
+
+  if (!positions.length || !indices.length) return null;
+  const vertexCount = positions.length / 3;
+  const IndexArray = vertexCount > 65535 ? Uint32Array : Uint16Array;
+  return {
+    positions: new Float32Array(positions),
+    indices: new IndexArray(indices),
+    vertexCount,
+    faceCount: indices.length / 3,
+    droppedFaceCount: preview.faces.length - indices.length / 3,
+  };
+};
+
+function Instance3DPreview({
+  preview,
+  liveSlice,
+  axis = "xy",
+  layerIndex = 0,
+  activeInstanceId,
+  loading = false,
+  fill = false,
+  showLiveSlice = false,
+}) {
+  const containerRef = useRef(null);
+  const rendererRef = useRef(null);
+  const sceneRef = useRef(null);
+  const cameraRef = useRef(null);
+  const controlsRef = useRef(null);
+  const meshGroupRef = useRef(null);
+  const liveRef = useRef(null);
+  const frameRef = useRef(null);
+  const [renderError, setRenderError] = useState("");
+  const segmentColor = useMemo(
+    () => glasbeyColor(activeInstanceId),
+    [activeInstanceId],
+  );
+
+  const disposeObject = (object) => {
+    if (!object) return;
+    object.traverse?.((child) => {
+      child.geometry?.dispose?.();
+      if (Array.isArray(child.material)) {
+        child.material.forEach((material) => material?.dispose?.());
+      } else {
+        child.material?.dispose?.();
+      }
+    });
+  };
+
+  const meshPayload = useMemo(() => {
+    return buildMeshPayload(preview);
+  }, [preview]);
+
+  const livePayload = useMemo(() => {
+    if (
+      !showLiveSlice ||
+      !preview ||
+      !liveSlice?.points?.length ||
+      liveSlice.axis !== axis ||
+      liveSlice.layerIndex !== layerIndex
+    ) {
+      return null;
+    }
+    const { toScene } = makeTransform(preview);
+    const positions = new Float32Array(liveSlice.points.length * 3);
+    liveSlice.points.forEach((point, index) => {
+      const scenePoint = toScene(slicePointToZyx(point, axis, layerIndex));
+      positions[index * 3] = scenePoint[0];
+      positions[index * 3 + 1] = scenePoint[1];
+      positions[index * 3 + 2] = scenePoint[2];
+    });
+    return {
+      positions,
+      pointCount: liveSlice.points.length,
+      positiveCount: liveSlice.positiveCount,
+    };
+  }, [axis, layerIndex, liveSlice, preview, showLiveSlice]);
+
+  useEffect(() => {
+    const container = containerRef.current;
+    if (!container) return undefined;
+
+    const scene = new THREE.Scene();
+    scene.background = new THREE.Color(0x0f172a);
+    const camera = new THREE.PerspectiveCamera(45, 1, 0.01, 100);
+    camera.position.set(3.4, -3.2, 2.8);
+
+    const canvas = document.createElement("canvas");
+    const context =
+      canvas.getContext("webgl2", { antialias: true }) ||
+      canvas.getContext("webgl", { antialias: true });
+    if (!context) {
+      setRenderError("3D preview needs WebGL.");
+      return undefined;
+    }
+
+    let renderer;
+    try {
+      renderer = new THREE.WebGLRenderer({
+        antialias: true,
+        canvas,
+        context,
+      });
+    } catch (error) {
+      setRenderError("3D preview needs WebGL.");
+      return undefined;
+    }
+    setRenderError("");
+    renderer.setPixelRatio(Math.min(window.devicePixelRatio || 1, 2));
+    renderer.setClearColor(0x0f172a, 1);
+    renderer.domElement.style.width = "100%";
+    renderer.domElement.style.height = "100%";
+    renderer.domElement.style.display = "block";
+    renderer.setSize(
+      container.clientWidth || 360,
+      container.clientHeight || 480,
+      false,
+    );
+    container.appendChild(renderer.domElement);
+
+    const controls = new OrbitControls(camera, renderer.domElement);
+    controls.enableDamping = true;
+    controls.dampingFactor = 0.08;
+    controls.autoRotate = false;
+    controls.target.set(0, 0, 0);
+    controls.update();
+
+    scene.add(new THREE.HemisphereLight(0xf8fafc, 0x1e293b, 2.4));
+    const keyLight = new THREE.DirectionalLight(0xffffff, 2.2);
+    keyLight.position.set(3, -4, 5);
+    scene.add(keyLight);
+    const fillLight = new THREE.DirectionalLight(0x93c5fd, 0.9);
+    fillLight.position.set(-4, 2, 2);
+    scene.add(fillLight);
+
+    rendererRef.current = renderer;
+    sceneRef.current = scene;
+    cameraRef.current = camera;
+    controlsRef.current = controls;
+
+    let lastWidth = 0;
+    let lastHeight = 0;
+    const resize = () => {
+      const rect = container.getBoundingClientRect();
+      const width = Math.max(container.clientWidth || rect.width || 360, 240);
+      const height = Math.max(
+        container.clientHeight || rect.height || 480,
+        320,
+      );
+      if (width === lastWidth && height === lastHeight) return;
+      lastWidth = width;
+      lastHeight = height;
+      camera.aspect = width / height;
+      camera.updateProjectionMatrix();
+      renderer.setSize(width, height, false);
+    };
+    resize();
+
+    const animate = () => {
+      resize();
+      controls.update();
+      renderer.render(scene, camera);
+      frameRef.current = requestAnimationFrame(animate);
+    };
+    animate();
+
+    return () => {
+      if (frameRef.current) cancelAnimationFrame(frameRef.current);
+      controls.dispose();
+      [meshGroupRef.current, liveRef.current].forEach((object) => {
+        if (!object) return;
+        scene.remove(object);
+        disposeObject(object);
+      });
+      renderer.dispose();
+      if (renderer.domElement.parentNode === container) {
+        container.removeChild(renderer.domElement);
+      }
+    };
+  }, []);
+
+  useEffect(() => {
+    const scene = sceneRef.current;
+    if (!scene) return;
+    if (meshGroupRef.current) {
+      scene.remove(meshGroupRef.current);
+      disposeObject(meshGroupRef.current);
+      meshGroupRef.current = null;
+    }
+    if (!meshPayload) return;
+
+    const geometry = new THREE.BufferGeometry();
+    geometry.setAttribute(
+      "position",
+      new THREE.BufferAttribute(meshPayload.positions, 3),
+    );
+    geometry.setIndex(new THREE.BufferAttribute(meshPayload.indices, 1));
+    geometry.computeVertexNormals();
+    geometry.computeBoundingSphere();
+
+    const baseColor = new THREE.Color(
+      segmentColor[0] / 255,
+      segmentColor[1] / 255,
+      segmentColor[2] / 255,
+    );
+    const material = new THREE.MeshStandardMaterial({
+      color: baseColor,
+      emissive: baseColor.clone().multiplyScalar(0.2),
+      roughness: 0.72,
+      metalness: 0,
+      transparent: false,
+      opacity: 1,
+      side: THREE.FrontSide,
+    });
+    const mesh = new THREE.Mesh(geometry, material);
+    const group = new THREE.Group();
+    group.add(mesh);
+
+    const sphere = geometry.boundingSphere;
+    if (sphere && cameraRef.current && controlsRef.current) {
+      const radius = Math.max(sphere.radius, 1);
+      const camera = cameraRef.current;
+      const controls = controlsRef.current;
+      const fov = THREE.MathUtils.degToRad(camera.fov);
+      const fitDistance = Math.max(radius * 2.8, radius / Math.sin(fov / 2));
+      controls.target.copy(sphere.center);
+      controls.minDistance = Math.max(radius * 0.35, 0.1);
+      controls.maxDistance = Math.max(radius * 8, fitDistance * 3);
+      controls.autoRotate = false;
+      controlsRef.current.target.copy(sphere.center);
+      camera.position.set(
+        sphere.center.x + fitDistance * 0.72,
+        sphere.center.y - fitDistance * 0.78,
+        sphere.center.z + fitDistance * 0.52,
+      );
+      camera.near = Math.max(fitDistance / 100, 0.01);
+      camera.far = Math.max(fitDistance * 8, 100);
+      camera.lookAt(sphere.center);
+      camera.updateProjectionMatrix();
+      controls.update();
+      controls.saveState?.();
+    }
+    meshGroupRef.current = group;
+    scene.add(group);
+  }, [meshPayload, segmentColor]);
+
+  useEffect(() => {
+    const scene = sceneRef.current;
+    if (!scene) return;
+    if (liveRef.current) {
+      scene.remove(liveRef.current);
+      disposeObject(liveRef.current);
+      liveRef.current = null;
+    }
+    if (!livePayload) return;
+
+    const geometry = new THREE.BufferGeometry();
+    geometry.setAttribute(
+      "position",
+      new THREE.BufferAttribute(livePayload.positions, 3),
+    );
+    const material = new THREE.PointsMaterial({
+      color: new THREE.Color(
+        segmentColor[0] / 255,
+        segmentColor[1] / 255,
+        segmentColor[2] / 255,
+      ).lerp(new THREE.Color(0xffffff), 0.2),
+      size: 0.035,
+      transparent: true,
+      opacity: 0.95,
+      depthWrite: false,
+    });
+    const points = new THREE.Points(geometry, material);
+    liveRef.current = points;
+    scene.add(points);
+  }, [livePayload, segmentColor]);
+
+  const showOverlay = renderError || loading || !meshPayload;
+  return (
+    <section
+      style={{
+        minWidth: fill ? 0 : 320,
+        flex: fill ? undefined : "0 0 clamp(320px, 32%, 520px)",
+        width: fill ? "100%" : undefined,
+        height: fill ? "100%" : undefined,
+        position: "relative",
+        display: "block",
+        borderLeft: fill ? 0 : "1px solid #e5e7eb",
+        border: fill ? "1px solid #1f2937" : undefined,
+        borderRadius: fill ? 8 : undefined,
+        overflow: "hidden",
+        background: fill ? "#0f172a" : "#ffffff",
+        alignSelf: "stretch",
+      }}
+    >
+      <div
+        style={{
+          position: "relative",
+          minHeight: fill ? 0 : 480,
+          height: "100%",
+          background: "#0f172a",
+        }}
+      >
+        <div
+          ref={containerRef}
+          style={{
+            width: "100%",
+            height: "100%",
+            minHeight: fill ? 0 : 480,
+          }}
+        />
+        {showOverlay && (
+          <div
+            style={{
+              position: "absolute",
+              inset: 0,
+              display: "flex",
+              alignItems: "center",
+              justifyContent: "center",
+              background: "rgba(15, 23, 42, 0.72)",
+              padding: 16,
+              textAlign: "center",
+            }}
+          >
+            {renderError ? (
+              <Text style={{ color: "#e5e7eb" }}>{renderError}</Text>
+            ) : loading ? (
+              <Spin />
+            ) : (
+              <Text style={{ color: "#e5e7eb" }}>
+                Extracting surface mesh...
+              </Text>
+            )}
+          </div>
+        )}
+      </div>
+    </section>
+  );
+}
+
+export default Instance3DPreview;
diff --git a/client/src/views/ehtool/InstanceNavigator.js b/client/src/views/ehtool/InstanceNavigator.js
index f3a6ea4f..f884ef79 100644
--- a/client/src/views/ehtool/InstanceNavigator.js
+++ b/client/src/views/ehtool/InstanceNavigator.js
@@ -1,6 +1,5 @@
 import React, { useMemo, useRef, useState, useEffect } from "react";
-import { Input, Tag, Space, Typography, Button } from "antd";
-import { LeftOutlined, RightOutlined } from "@ant-design/icons";
+import { Input, Space, Tag, Typography } from "antd";
 
 const { Text } = Typography;
 
@@ -22,17 +21,15 @@ function InstanceNavigator({
   instances,
   activeInstanceId,
   onSelect,
-  onPrev,
-  onNext,
   filterText,
   onFilterText,
-  instanceMode,
   showSummary = true,
+  showClassification = false,
 }) {
   const listRef = useRef(null);
   const [scrollTop, setScrollTop] = useState(0);
   const [containerHeight, setContainerHeight] = useState(360);
-  const rowHeight = 76;
+  const rowHeight = 88;
   const overscan = 6;
 
   useEffect(() => {
@@ -71,21 +68,9 @@ function InstanceNavigator({
 
   return (
     <div style={{ padding: "0" }}>
-      <Space style={{ width: "100%", justifyContent: "space-between" }}>
-        <Text style={{ fontSize: 12 }} strong>
-          Instances
-        </Text>
-        {instanceMode && instanceMode !== "none" && (
-          <Tag color="blue" style={{ fontSize: 11 }}>
-            {instanceMode === "semantic" ? "semantic (derived)" : "instance"}
-          </Tag>
-        )}
-      </Space>
-
-      <Space style={{ marginTop: 8 }}>
-        <Button size="small" icon={<LeftOutlined />} onClick={onPrev} />
-        <Button size="small" icon={<RightOutlined />} onClick={onNext} />
-      </Space>
+      <Text style={{ fontSize: 12 }} strong>
+        Instances
+      </Text>
 
       <Input
         placeholder="Filter"
@@ -138,19 +123,20 @@ function InstanceNavigator({
                   <Text style={{ fontSize: 12 }} strong>
                     #{item.id}
                   </Text>
-                  <Tag
-                    color={statusColor[item.classification]}
-                    style={{ fontSize: 10 }}
-                  >
-                    {statusLabel[item.classification]}
-                  </Tag>
+                  {showClassification && (
+                    <Tag
+                      color={statusColor[item.classification]}
+                      style={{ fontSize: 10 }}
+                    >
+                      {statusLabel[item.classification]}
+                    </Tag>
+                  )}
                 </Space>
-                <Text type="secondary" style={{ fontSize: 12 }}>
-                  COM: {item.com_z}, {item.com_y}, {item.com_x}
-                </Text>
-                <Text type="secondary" style={{ fontSize: 12 }}>
-                  voxels: {item.voxel_count}
-                </Text>
+                <div style={{ display: "grid", gap: 2, marginTop: 4 }}>
+                  <Text type="secondary" style={{ fontSize: 12 }}>
+                    voxels: {Number(item.voxel_count || 0).toLocaleString()}
+                  </Text>
+                </div>
               </div>
             </div>
           ))}
diff --git a/client/src/views/ehtool/LayerGrid.js b/client/src/views/ehtool/LayerGrid.js
index 6447f3e9..209d4dec 100644
--- a/client/src/views/ehtool/LayerGrid.js
+++ b/client/src/views/ehtool/LayerGrid.js
@@ -101,10 +101,10 @@ function LayerGrid({
                 hoverable
                 style={{
                   border: isSelected
-                    ? "2px solid #1677ff"
+                    ? "2px solid var(--seg-accent-primary, #3f37c9)"
                     : "1px solid #e5e7eb",
                   boxShadow: isSelected
-                    ? "0 0 12px rgba(22, 119, 255, 0.18)"
+                    ? "0 0 12px var(--seg-focus-ring, rgba(63, 55, 201, 0.22))"
                     : "0 6px 20px rgba(15, 23, 42, 0.05)",
                   cursor: "pointer",
                   position: "relative",
diff --git a/client/src/views/ehtool/ProgressTracker.js b/client/src/views/ehtool/ProgressTracker.js
index 59273a14..59c76304 100644
--- a/client/src/views/ehtool/ProgressTracker.js
+++ b/client/src/views/ehtool/ProgressTracker.js
@@ -22,6 +22,7 @@ function ProgressTracker({
   onStartProofreading,
   onJumpToNext,
   compact = false,
+  showLoadDataset = true,
 }) {
   if (!stats) {
     return (
@@ -85,18 +86,22 @@ function ProgressTracker({
           </div>
         </div>
 
-        <Divider style={{ margin: compact ? "4px 0" : "8px 0" }} />
+        {showLoadDataset && (
+          <>
+            <Divider style={{ margin: compact ? "4px 0" : "8px 0" }} />
 
-        <Space direction="vertical" style={{ width: "100%" }} size="small">
-          <Button
-            icon={<FolderOpenOutlined />}
-            onClick={onNewSession}
-            block
-            size="small"
-          >
-            Load dataset
-          </Button>
-        </Space>
+            <Space direction="vertical" style={{ width: "100%" }} size="small">
+              <Button
+                icon={<FolderOpenOutlined />}
+                onClick={onNewSession}
+                block
+                size="small"
+              >
+                Load dataset
+              </Button>
+            </Space>
+          </>
+        )}
       </Space>
     </div>
   );
diff --git a/client/src/views/ehtool/ProofreadingEditor.js b/client/src/views/ehtool/ProofreadingEditor.js
index 7aa17e30..f33bb106 100644
--- a/client/src/views/ehtool/ProofreadingEditor.js
+++ b/client/src/views/ehtool/ProofreadingEditor.js
@@ -12,10 +12,10 @@ import {
   Slider,
   InputNumber,
   Space,
+  Tag,
   message,
   Tooltip,
   Collapse,
-  Segmented,
   Spin,
   Typography,
 } from "antd";
@@ -31,6 +31,7 @@ import {
   ZoomInOutlined,
   ZoomOutOutlined,
   DragOutlined,
+  SaveOutlined,
 } from "@ant-design/icons";
 
 const { Text } = Typography;
@@ -49,17 +50,23 @@ const ProofreadingEditor = forwardRef(
       overlayAllAlpha = 0.08,
       overlayActiveAlpha = 0.8,
       axis,
-      axisOptions,
-      onAxisChange,
       loading,
       activeInstanceId,
       onSave,
+      onMaskDraftChange,
       onNext,
       onPrevious,
       currentLayer,
       totalLayers,
       layerName,
+      canEdit = true,
+      saveDisabledReason = "Editable mask is not ready yet.",
       minimalChrome = true,
+      hideLayerToolbar = false,
+      editorHeightOverride = null,
+      keyboardEnabled = true,
+      hideToolPanel = false,
+      onToolStateChange,
     },
     ref,
   ) => {
@@ -76,6 +83,7 @@ const ProofreadingEditor = forwardRef(
     const [eraseBrushSize, setEraseBrushSize] = useState(10);
     const [showMask, setShowMask] = useState(true);
     const [zoom, setZoom] = useState(1.0);
+    const [hasUnsavedEdits, setHasUnsavedEdits] = useState(false);
     const [isDrawing, setIsDrawing] = useState(false);
     const [cursorPos, setCursorPos] = useState({ x: 0, y: 0 }); // Image coordinates
     const [mousePos, setMousePos] = useState(null); // Container/Screen coordinates
@@ -86,6 +94,8 @@ const ProofreadingEditor = forwardRef(
     const originalMaskRef = useRef(null);
     const overlayAllRef = useRef(null);
     const overlayActiveRef = useRef(null);
+    const overlayAllContextRef = useRef(null);
+    const overlayAllContextDirtyRef = useRef(true);
 
     // Undo/Redo stacks
     const [undoStack, setUndoStack] = useState([]);
@@ -99,11 +109,21 @@ const ProofreadingEditor = forwardRef(
       width: 0,
       height: 0,
     });
+    const [viewportSize, setViewportSize] = useState({
+      width: 0,
+      height: 0,
+    });
     const lastCanvasSizeRef = useRef({ width: 0, height: 0 });
     const lastDrawRef = useRef(null);
     const minimapRafRef = useRef(null);
     const axisViewStateRef = useRef({});
     const mousePosRafRef = useRef(null);
+    const shortcutHandlersRef = useRef({
+      handleRedo: null,
+      handleSave: null,
+      handleUndo: null,
+    });
+    const maskDraftRafRef = useRef(null);
     const pendingMousePosRef = useRef(null);
     const minimapLayoutRef = useRef(null);
     const minimapSourceRef = useRef(null);
@@ -112,18 +132,70 @@ const ProofreadingEditor = forwardRef(
     const minimapComposedRef = useRef(null);
     const activeOverlayDirtyRef = useRef(true);
     const minimapSourceDirtyRef = useRef(true);
+    const activeBrushSize = tool === "erase" ? eraseBrushSize : paintBrushSize;
+    const setBrushSize =
+      tool === "erase" ? setEraseBrushSize : setPaintBrushSize;
+    const normalizeBrushSize = (value) => {
+      const numeric = Number(value);
+      if (!Number.isFinite(numeric)) return activeBrushSize;
+      return Math.max(1, Math.min(50, Math.round(numeric)));
+    };
 
     // Expose handleSave to parent
     useImperativeHandle(ref, () => ({
       save: handleSave,
+      setTool,
+      setBrushSize: (value) => {
+        const nextSize = normalizeBrushSize(value);
+        if (tool === "erase") {
+          setEraseBrushSize(nextSize);
+        } else {
+          setPaintBrushSize(nextSize);
+        }
+      },
+      toggleMask: () => setShowMask((prev) => !prev),
+      zoomIn: () => setZoom((prev) => Math.min(10.0, prev + 0.1)),
+      zoomOut: () => {
+        setZoom((prev) => {
+          const nextZoom = Math.max(1, prev - 0.1);
+          setOffset((current) => clampOffsetToViewport(current, nextZoom));
+          return nextZoom;
+        });
+      },
+      resetZoom: () => {
+        setZoom(1.0);
+        setOffset({ x: 0, y: 0 });
+      },
     }));
 
+    useEffect(() => {
+      onToolStateChange?.({
+        tool,
+        showMask,
+        hasUnsavedEdits,
+        zoom,
+        canEdit,
+        activeBrushSize,
+      });
+    }, [
+      activeBrushSize,
+      canEdit,
+      hasUnsavedEdits,
+      onToolStateChange,
+      showMask,
+      tool,
+      zoom,
+    ]);
+
     useEffect(() => {
       if (!axis) return;
       const stored = axisViewStateRef.current[axis];
       if (stored) {
-        setZoom(stored.zoom ?? 1);
-        setOffset(stored.offset ?? { x: 0, y: 0 });
+        const nextZoom = Math.max(1, stored.zoom ?? 1);
+        setZoom(nextZoom);
+        setOffset(
+          clampOffsetToViewport(stored.offset ?? { x: 0, y: 0 }, nextZoom),
+        );
       }
     }, [axis]);
 
@@ -137,7 +209,7 @@ const ProofreadingEditor = forwardRef(
       if (imageBase64 && canvasRef.current) {
         loadImages();
       }
-    }, [imageBase64, maskBase64]);
+    }, [imageBase64, maskBase64, canEdit]);
 
     // Redraw canvas when zoom, offset, visibility, or dimensions change
     useEffect(() => {
@@ -170,9 +242,28 @@ const ProofreadingEditor = forwardRef(
         if (mousePosRafRef.current) {
           cancelAnimationFrame(mousePosRafRef.current);
         }
+        if (maskDraftRafRef.current) {
+          cancelAnimationFrame(maskDraftRafRef.current);
+        }
       };
     }, []);
 
+    useEffect(() => {
+      const node = containerRef.current;
+      if (!node || typeof ResizeObserver === "undefined") return;
+      const handleResize = () => {
+        const rect = node.getBoundingClientRect();
+        setViewportSize({
+          width: rect.width,
+          height: rect.height,
+        });
+      };
+      handleResize();
+      const resizeObserver = new ResizeObserver(handleResize);
+      resizeObserver.observe(node);
+      return () => resizeObserver.disconnect();
+    }, []);
+
     const resolveImageSource = (source) => {
       if (!source) return "";
       if (source.startsWith("data:image") || source.startsWith("blob:")) {
@@ -205,11 +296,128 @@ const ProofreadingEditor = forwardRef(
       };
     };
 
+    const getFittedCanvasSize = () => {
+      if (
+        !canvasDimensions.width ||
+        !canvasDimensions.height ||
+        !viewportSize.width ||
+        !viewportSize.height
+      ) {
+        return {
+          width: canvasDimensions.width,
+          height: canvasDimensions.height,
+          scale: 1,
+        };
+      }
+      const padding = minimalChrome ? 28 : 16;
+      const availableWidth = Math.max(1, viewportSize.width - padding);
+      const availableHeight = Math.max(1, viewportSize.height - padding);
+      const fitScale = Math.min(
+        availableWidth / canvasDimensions.width,
+        availableHeight / canvasDimensions.height,
+      );
+      return {
+        width: Math.max(1, canvasDimensions.width * fitScale),
+        height: Math.max(1, canvasDimensions.height * fitScale),
+        scale: fitScale,
+      };
+    };
+
+    const clampOffsetToViewport = (nextOffset, nextZoom = zoom) => {
+      const fitted = getFittedCanvasSize();
+      if (!fitted.width || !fitted.height || !viewportSize.width) {
+        return nextOffset;
+      }
+      const scaledWidth = fitted.width * nextZoom;
+      const scaledHeight = fitted.height * nextZoom;
+      const slack = 32;
+      const maxX = Math.max(0, (scaledWidth - viewportSize.width + slack) / 2);
+      const maxY = Math.max(
+        0,
+        (scaledHeight - viewportSize.height + slack) / 2,
+      );
+      return {
+        x: Math.max(-maxX, Math.min(maxX, nextOffset.x)),
+        y: Math.max(-maxY, Math.min(maxY, nextOffset.y)),
+      };
+    };
+
+    useEffect(() => {
+      if (!canvasDimensions.width || !viewportSize.width) return;
+      setZoom((prev) => Math.max(1, prev));
+      setOffset((prev) => clampOffsetToViewport(prev, Math.max(1, zoom)));
+    }, [
+      canvasDimensions.width,
+      canvasDimensions.height,
+      viewportSize.width,
+      viewportSize.height,
+    ]);
+
     const markOverlayDirty = () => {
       activeOverlayDirtyRef.current = true;
       minimapSourceDirtyRef.current = true;
     };
 
+    const markContextOverlayDirty = () => {
+      overlayAllContextDirtyRef.current = true;
+      minimapSourceDirtyRef.current = true;
+    };
+
+    const getContextOverlayCanvas = () => {
+      if (!overlayAllRef.current || canvasDimensions.width === 0) return null;
+      if (
+        !originalMaskRef.current ||
+        originalMaskRef.current.width !== canvasDimensions.width ||
+        originalMaskRef.current.height !== canvasDimensions.height
+      ) {
+        return overlayAllRef.current;
+      }
+
+      if (!overlayAllContextRef.current) {
+        overlayAllContextRef.current = document.createElement("canvas");
+        overlayAllContextDirtyRef.current = true;
+      }
+      const contextCanvas = overlayAllContextRef.current;
+      if (
+        contextCanvas.width !== canvasDimensions.width ||
+        contextCanvas.height !== canvasDimensions.height
+      ) {
+        contextCanvas.width = canvasDimensions.width;
+        contextCanvas.height = canvasDimensions.height;
+        overlayAllContextDirtyRef.current = true;
+      }
+      if (!overlayAllContextDirtyRef.current) return contextCanvas;
+
+      const context = contextCanvas.getContext("2d");
+      context.clearRect(0, 0, contextCanvas.width, contextCanvas.height);
+      context.drawImage(
+        overlayAllRef.current,
+        0,
+        0,
+        contextCanvas.width,
+        contextCanvas.height,
+      );
+
+      const overlayData = context.getImageData(
+        0,
+        0,
+        contextCanvas.width,
+        contextCanvas.height,
+      );
+      const originalMask = originalMaskRef.current.data;
+      for (let i = 0; i < overlayData.data.length; i += 4) {
+        if (originalMask[i] > 0) {
+          overlayData.data[i] = 0;
+          overlayData.data[i + 1] = 0;
+          overlayData.data[i + 2] = 0;
+          overlayData.data[i + 3] = 0;
+        }
+      }
+      context.putImageData(overlayData, 0, 0);
+      overlayAllContextDirtyRef.current = false;
+      return contextCanvas;
+    };
+
     const getActiveOverlayCanvas = () => {
       if (!maskDataRef.current || canvasDimensions.width === 0) return null;
       if (!activeOverlayCanvasRef.current) {
@@ -276,27 +484,12 @@ const ProofreadingEditor = forwardRef(
         );
         if (baseImage?.close) baseImage.close();
 
-        const previousCanvas = lastCanvasSizeRef.current;
-        if (previousCanvas.width > 0 && previousCanvas.height > 0) {
-          const scaleX = canvas.width / previousCanvas.width;
-          const scaleY = canvas.height / previousCanvas.height;
-          if (
-            Number.isFinite(scaleX) &&
-            Number.isFinite(scaleY) &&
-            scaleX > 0 &&
-            scaleY > 0
-          ) {
-            setOffset((prev) => ({
-              x: prev.x * scaleX,
-              y: prev.y * scaleY,
-            }));
-          }
-        }
         lastCanvasSizeRef.current = {
           width: canvas.width,
           height: canvas.height,
         };
         setCanvasDimensions({ width: canvas.width, height: canvas.height });
+        setZoom((prev) => Math.max(1, prev));
 
         if (maskBase64) {
           const maskImage = await loadRenderableImage(maskBase64);
@@ -317,14 +510,20 @@ const ProofreadingEditor = forwardRef(
             canvas.width,
             canvas.height,
           );
-        } else {
+        } else if (canEdit) {
           maskDataRef.current = new ImageData(canvas.width, canvas.height);
           originalMaskRef.current = new ImageData(canvas.width, canvas.height);
+        } else {
+          maskDataRef.current = null;
+          originalMaskRef.current = null;
         }
 
         markOverlayDirty();
+        markContextOverlayDirty();
         setUndoStack([]);
         setRedoStack([]);
+        setHasUnsavedEdits(false);
+        scheduleMaskDraftChange();
         drawCanvas();
         drawMinimap();
       } catch (error) {
@@ -341,10 +540,11 @@ const ProofreadingEditor = forwardRef(
       ctx.imageSmoothingEnabled = false;
       ctx.putImageData(imageDataRef.current, 0, 0);
 
-      if (showMask && overlayAllRef.current && overlayAllAlpha > 0.001) {
+      const contextOverlay = getContextOverlayCanvas();
+      if (showMask && contextOverlay && overlayAllAlpha > 0.001) {
         ctx.save();
         ctx.globalAlpha = overlayAllAlpha;
-        ctx.drawImage(overlayAllRef.current, 0, 0, canvas.width, canvas.height);
+        ctx.drawImage(contextOverlay, 0, 0, canvas.width, canvas.height);
         ctx.restore();
       }
 
@@ -373,6 +573,9 @@ const ProofreadingEditor = forwardRef(
     const loadOverlayImage = (source, targetRef) => {
       if (!source) {
         targetRef.current = null;
+        if (targetRef === overlayAllRef) {
+          markContextOverlayDirty();
+        }
         minimapSourceDirtyRef.current = true;
         drawCanvas();
         drawMinimap();
@@ -381,12 +584,18 @@ const ProofreadingEditor = forwardRef(
       const overlay = new Image();
       overlay.onload = () => {
         targetRef.current = overlay;
+        if (targetRef === overlayAllRef) {
+          markContextOverlayDirty();
+        }
         minimapSourceDirtyRef.current = true;
         drawCanvas();
         drawMinimap();
       };
       overlay.onerror = () => {
         targetRef.current = null;
+        if (targetRef === overlayAllRef) {
+          markContextOverlayDirty();
+        }
         minimapSourceDirtyRef.current = true;
         drawCanvas();
         drawMinimap();
@@ -431,11 +640,13 @@ const ProofreadingEditor = forwardRef(
           : 0;
       const ix = relX * canvasDimensions.width;
       const iy = relY * canvasDimensions.height;
+      const fitted = getFittedCanvasSize();
+      const nextOffset = {
+        x: -(ix / canvasDimensions.width - 0.5) * fitted.width * zoom,
+        y: -(iy / canvasDimensions.height - 0.5) * fitted.height * zoom,
+      };
 
-      setOffset({
-        x: -(ix - canvasDimensions.width / 2) * zoom,
-        y: -(iy - canvasDimensions.height / 2) * zoom,
-      });
+      setOffset(clampOffsetToViewport(nextOffset, zoom));
     };
 
     const drawMinimap = () => {
@@ -491,11 +702,12 @@ const ProofreadingEditor = forwardRef(
         sourceCtx.clearRect(0, 0, sourceCanvas.width, sourceCanvas.height);
         sourceCtx.putImageData(imageDataRef.current, 0, 0);
 
-        if (showMask && overlayAllRef.current && overlayAllAlpha > 0.001) {
+        const contextOverlay = getContextOverlayCanvas();
+        if (showMask && contextOverlay && overlayAllAlpha > 0.001) {
           sourceCtx.save();
           sourceCtx.globalAlpha = overlayAllAlpha;
           sourceCtx.drawImage(
-            overlayAllRef.current,
+            contextOverlay,
             0,
             0,
             sourceCanvas.width,
@@ -548,14 +760,21 @@ const ProofreadingEditor = forwardRef(
       // Draw viewport rectangle
       const scaleX = layout.drawWidth / canvasDimensions.width;
       const scaleY = layout.drawHeight / canvasDimensions.height;
+      const fitted = getFittedCanvasSize();
+      const displayWidth = fitted.width || canvasDimensions.width;
+      const displayHeight = fitted.height || canvasDimensions.height;
 
       const halfW = container.clientWidth / 2;
       const halfH = container.clientHeight / 2;
-      const viewLeft = (-halfW - offset.x) / zoom + canvasDimensions.width / 2;
-      const viewTop = (-halfH - offset.y) / zoom + canvasDimensions.height / 2;
-      const viewRight = (halfW - offset.x) / zoom + canvasDimensions.width / 2;
+      const viewLeftCss = (-halfW - offset.x) / zoom + displayWidth / 2;
+      const viewTopCss = (-halfH - offset.y) / zoom + displayHeight / 2;
+      const viewRightCss = (halfW - offset.x) / zoom + displayWidth / 2;
+      const viewBottomCss = (halfH - offset.y) / zoom + displayHeight / 2;
+      const viewLeft = (viewLeftCss / displayWidth) * canvasDimensions.width;
+      const viewTop = (viewTopCss / displayHeight) * canvasDimensions.height;
+      const viewRight = (viewRightCss / displayWidth) * canvasDimensions.width;
       const viewBottom =
-        (halfH - offset.y) / zoom + canvasDimensions.height / 2;
+        (viewBottomCss / displayHeight) * canvasDimensions.height;
 
       const clampedLeft = Math.max(
         0,
@@ -683,19 +902,64 @@ const ProofreadingEditor = forwardRef(
       return overlay;
     };
 
+    const buildMaskDraftPayload = () => {
+      if (!maskDataRef.current) return null;
+      const maskData = maskDataRef.current;
+      const positivePoints = [];
+      let positiveCount = 0;
+      for (let i = 0; i < maskData.data.length; i += 4) {
+        if (maskData.data[i] > 0) positiveCount += 1;
+      }
+      const targetPoints = 5200;
+      const stride = Math.max(
+        1,
+        Math.ceil(Math.sqrt(positiveCount / targetPoints)),
+      );
+      for (let y = 0; y < maskData.height; y += stride) {
+        for (let x = 0; x < maskData.width; x += stride) {
+          const idx = (y * maskData.width + x) * 4;
+          if (maskData.data[idx] > 0) {
+            positivePoints.push([x, y]);
+          }
+        }
+      }
+      return {
+        axis,
+        layerIndex: currentLayer,
+        width: maskData.width,
+        height: maskData.height,
+        positiveCount,
+        stride,
+        points: positivePoints,
+      };
+    };
+
+    const emitMaskDraftChange = () => {
+      if (!onMaskDraftChange) return;
+      onMaskDraftChange(buildMaskDraftPayload());
+    };
+
+    const scheduleMaskDraftChange = () => {
+      if (!onMaskDraftChange || maskDraftRafRef.current) return;
+      maskDraftRafRef.current = requestAnimationFrame(() => {
+        maskDraftRafRef.current = null;
+        emitMaskDraftChange();
+      });
+    };
+
     const saveToUndoStack = () => {
-      if (!maskDataRef.current) return;
+      if (!canEdit || !maskDataRef.current) return;
       const maskCopy = new ImageData(
         new Uint8ClampedArray(maskDataRef.current.data),
         maskDataRef.current.width,
         maskDataRef.current.height,
       );
-      setUndoStack((prev) => [...prev, maskCopy]);
+      setUndoStack((prev) => [...prev.slice(-24), maskCopy]);
       setRedoStack([]);
     };
 
     const handleUndo = () => {
-      if (undoStack.length === 0) return;
+      if (!canEdit || undoStack.length === 0 || !maskDataRef.current) return;
       const previousState = undoStack[undoStack.length - 1];
       const currentCopy = new ImageData(
         new Uint8ClampedArray(maskDataRef.current.data),
@@ -709,35 +973,47 @@ const ProofreadingEditor = forwardRef(
         previousState.height,
       );
       setUndoStack((prev) => prev.slice(0, -1));
+      setHasUnsavedEdits(true);
       markOverlayDirty();
       drawCanvas();
       drawMinimap();
+      scheduleMaskDraftChange();
     };
 
     const handleRedo = () => {
-      if (redoStack.length === 0) return;
+      if (!canEdit || redoStack.length === 0 || !maskDataRef.current) return;
       const nextState = redoStack[redoStack.length - 1];
       const currentCopy = new ImageData(
         new Uint8ClampedArray(maskDataRef.current.data),
         maskDataRef.current.width,
         maskDataRef.current.height,
       );
-      setUndoStack((prev) => [...prev, currentCopy]);
+      setUndoStack((prev) => [...prev.slice(-24), currentCopy]);
       maskDataRef.current = new ImageData(
         new Uint8ClampedArray(nextState.data),
         nextState.width,
         nextState.height,
       );
       setRedoStack((prev) => prev.slice(0, -1));
+      setHasUnsavedEdits(true);
       markOverlayDirty();
       drawCanvas();
       drawMinimap();
+      scheduleMaskDraftChange();
     };
 
     const getCanvasCoordinates = (e) => {
       const canvas = canvasRef.current;
       if (!canvas) return null;
       const rect = canvas.getBoundingClientRect();
+      if (
+        e.clientX < rect.left ||
+        e.clientX > rect.right ||
+        e.clientY < rect.top ||
+        e.clientY > rect.bottom
+      ) {
+        return null;
+      }
 
       // Calculate position relative to the transformed canvas
       const x = (e.clientX - rect.left) * (canvas.width / rect.width);
@@ -747,7 +1023,7 @@ const ProofreadingEditor = forwardRef(
     };
 
     const drawBrush = (x, y) => {
-      if (!maskDataRef.current) return;
+      if (!canEdit || !maskDataRef.current) return;
       const currentBrushSize =
         tool === "paint" ? paintBrushSize : eraseBrushSize;
       const radius = Math.floor(currentBrushSize / 2);
@@ -801,15 +1077,21 @@ const ProofreadingEditor = forwardRef(
         return;
       }
       if (e.button !== 0) return;
+      if (!canEdit) {
+        message.warning(saveDisabledReason);
+        return;
+      }
       const coords = getCanvasCoordinates(e);
       if (!coords) return;
       saveToUndoStack();
       setIsDrawing(true);
       lastDrawRef.current = coords;
       drawBrush(coords.x, coords.y);
+      setHasUnsavedEdits(true);
       markOverlayDirty();
       drawCanvas();
       scheduleMinimap();
+      scheduleMaskDraftChange();
     };
 
     const handleMouseMove = (e) => {
@@ -829,19 +1111,26 @@ const ProofreadingEditor = forwardRef(
       }
 
       const coords = getCanvasCoordinates(e);
-      if (coords) setCursorPos(coords);
+      setCursorPos(coords);
 
       if (isPanning) {
-        setOffset({ x: e.clientX - panStart.x, y: e.clientY - panStart.y });
+        setOffset(
+          clampOffsetToViewport({
+            x: e.clientX - panStart.x,
+            y: e.clientY - panStart.y,
+          }),
+        );
         return;
       }
       if (!isDrawing) return;
       if (coords) {
         drawLine(lastDrawRef.current, coords);
         lastDrawRef.current = coords;
+        setHasUnsavedEdits(true);
         markOverlayDirty();
         drawCanvas();
         scheduleMinimap();
+        scheduleMaskDraftChange();
       }
     };
 
@@ -851,15 +1140,16 @@ const ProofreadingEditor = forwardRef(
       lastDrawRef.current = null;
       setMousePos(null);
       drawMinimap();
+      scheduleMaskDraftChange();
     };
 
     const handleWheel = (e) => {
       e.preventDefault();
       const delta = e.deltaY > 0 ? -0.1 : 0.1;
-      const newZoom = Math.max(0.1, Math.min(10.0, zoom + delta));
+      const newZoom = Math.max(1, Math.min(10.0, zoom + delta));
 
       // Zoom-to-cursor logic
-      const rect = canvasRef.current.parentElement.getBoundingClientRect();
+      const rect = containerRef.current.getBoundingClientRect();
       const mouseX = e.clientX - rect.left - rect.width / 2;
       const mouseY = e.clientY - rect.top - rect.height / 2;
 
@@ -869,10 +1159,16 @@ const ProofreadingEditor = forwardRef(
       const newOffsetY = mouseY - (mouseY - offset.y) * zoomRatio;
 
       setZoom(newZoom);
-      setOffset({ x: newOffsetX, y: newOffsetY });
+      setOffset(
+        clampOffsetToViewport({ x: newOffsetX, y: newOffsetY }, newZoom),
+      );
     };
 
     const handleSave = () => {
+      if (!canEdit) {
+        message.warning(saveDisabledReason);
+        return;
+      }
       if (!maskDataRef.current) {
         message.error("No mask data to save");
         return;
@@ -883,10 +1179,28 @@ const ProofreadingEditor = forwardRef(
       const tempCtx = tempCanvas.getContext("2d");
       tempCtx.putImageData(maskDataRef.current, 0, 0);
       const mBase64 = tempCanvas.toDataURL("image/png").split(",")[1];
-      if (onSave) onSave(mBase64);
+      if (!onSave) {
+        setHasUnsavedEdits(false);
+        return;
+      }
+      const saveResult = onSave(mBase64);
+      scheduleMaskDraftChange();
+      if (saveResult && typeof saveResult.then === "function") {
+        saveResult
+          .then(() => setHasUnsavedEdits(false))
+          .catch(() => setHasUnsavedEdits(true));
+        return;
+      }
+      setHasUnsavedEdits(false);
+    };
+    shortcutHandlersRef.current = {
+      handleRedo,
+      handleSave,
+      handleUndo,
     };
 
     useEffect(() => {
+      if (!keyboardEnabled) return undefined;
       const handleKeyDown = (e) => {
         const target = e.target;
         if (
@@ -909,20 +1223,26 @@ const ProofreadingEditor = forwardRef(
           case "z":
             if (e.ctrlKey || e.metaKey) {
               e.preventDefault();
-              if (e.shiftKey) handleRedo();
-              else handleUndo();
+              if (e.shiftKey) shortcutHandlersRef.current.handleRedo?.();
+              else shortcutHandlersRef.current.handleUndo?.();
             }
             break;
           case "y":
             if (e.ctrlKey || e.metaKey) {
               e.preventDefault();
-              handleRedo();
+              shortcutHandlersRef.current.handleRedo?.();
             }
             break;
           case "s":
             if (e.ctrlKey || e.metaKey) {
               e.preventDefault();
-              handleSave();
+              shortcutHandlersRef.current.handleSave?.();
+            }
+            break;
+          case "enter":
+            if (e.ctrlKey || e.metaKey) {
+              e.preventDefault();
+              shortcutHandlersRef.current.handleSave?.();
             }
             break;
           case "a":
@@ -933,318 +1253,359 @@ const ProofreadingEditor = forwardRef(
           case "arrowright":
             if (onNext) onNext();
             break;
+          default:
+            break;
         }
       };
       window.addEventListener("keydown", handleKeyDown);
       return () => window.removeEventListener("keydown", handleKeyDown);
-    }, [
-      undoStack,
-      redoStack,
-      onNext,
-      onPrevious,
-      tool,
-      paintBrushSize,
-      eraseBrushSize,
-      zoom,
-      offset,
-    ]);
+    }, [keyboardEnabled, onNext, onPrevious]);
 
-    const activeBrushSize = tool === "erase" ? eraseBrushSize : paintBrushSize;
-    const setBrushSize =
-      tool === "erase" ? setEraseBrushSize : setPaintBrushSize;
     const axisLabel = axis ? axis.toUpperCase() : "XY";
-    const axisCursorLabel = () => {
-      if (axis === "zx") return { h: "X", v: "Z" };
-      if (axis === "zy") return { h: "Y", v: "Z" };
-      return { h: "X", v: "Y" };
-    };
-    const editorHeight = "clamp(560px, 74vh, 900px)";
+    const editorHeight =
+      editorHeightOverride ||
+      (minimalChrome
+        ? "clamp(420px, calc(100vh - 520px), 720px)"
+        : "clamp(560px, 74vh, 900px)");
+    const collapsedToolWidth = minimalChrome ? "60px" : "84px";
+    const expandedToolWidth = minimalChrome ? "232px" : "260px";
+    const fittedCanvasSize = getFittedCanvasSize();
 
     return (
       <div
         style={{
           display: "flex",
           height: editorHeight,
-          gap: "12px",
+          gap: hideToolPanel ? 0 : "12px",
           overflow: "hidden",
           alignItems: "stretch",
         }}
       >
         {/* Left Panel - Tools */}
-        <Card
-          title={
-            <div
-              style={{
-                display: "flex",
-                alignItems: "center",
-                justifyContent: toolPanelCollapsed ? "center" : "space-between",
-                gap: 8,
-              }}
-            >
-              {!toolPanelCollapsed && <span>Tools</span>}
-              <Tooltip
-                title={toolPanelCollapsed ? "Expand tools" : "Collapse tools"}
+        {!hideToolPanel && (
+          <Card
+            title={
+              <div
+                style={{
+                  display: "flex",
+                  alignItems: "center",
+                  justifyContent: toolPanelCollapsed
+                    ? "center"
+                    : "space-between",
+                  gap: 8,
+                }}
               >
-                <Button
-                  type="text"
-                  size="small"
-                  icon={
-                    toolPanelCollapsed ? <RightOutlined /> : <LeftOutlined />
-                  }
-                  onClick={() => setToolPanelCollapsed((prev) => !prev)}
-                  aria-label={
-                    toolPanelCollapsed ? "Expand tools" : "Collapse tools"
-                  }
-                  style={{
-                    width: 28,
-                    height: 28,
-                    display: "inline-flex",
-                    alignItems: "center",
-                    justifyContent: "center",
-                  }}
-                />
-              </Tooltip>
-            </div>
-          }
-          style={{
-            width: toolPanelCollapsed ? "84px" : "260px",
-            minWidth: toolPanelCollapsed ? "84px" : "260px",
-            height: "100%",
-            transition: "width 0.2s ease",
-          }}
-          headStyle={{
-            padding: toolPanelCollapsed ? "0 8px" : "0 12px",
-          }}
-          bodyStyle={{
-            height: "calc(100% - 40px)",
-            overflowY: "auto",
-            padding: toolPanelCollapsed ? "10px 8px" : "12px",
-          }}
-          size="small"
-        >
-          {toolPanelCollapsed ? (
-            <Space
-              direction="vertical"
-              size="small"
-              style={{ width: "100%", alignItems: "center" }}
-            >
-              <Tooltip title="Paint (P)">
-                <Button
-                  type={tool === "paint" ? "primary" : "default"}
-                  icon={<EditOutlined />}
-                  onClick={() => setTool("paint")}
-                />
-              </Tooltip>
-              <Tooltip title="Erase (E)">
-                <Button
-                  type={tool === "erase" ? "primary" : "default"}
-                  icon={<ClearOutlined />}
-                  onClick={() => setTool("erase")}
-                />
-              </Tooltip>
-              <Tooltip title="Hand (H)">
-                <Button
-                  type={tool === "hand" ? "primary" : "default"}
-                  icon={<DragOutlined />}
-                  onClick={() => setTool("hand")}
-                />
-              </Tooltip>
-              <Tooltip title={showMask ? "Hide mask" : "Show mask"}>
-                <Button
-                  icon={showMask ? <EyeInvisibleOutlined /> : <EyeOutlined />}
-                  onClick={() => setShowMask(!showMask)}
-                />
-              </Tooltip>
-              <Tooltip title="Zoom in">
-                <Button
-                  icon={<ZoomInOutlined />}
-                  onClick={() => setZoom((prev) => Math.min(10.0, prev + 0.1))}
-                />
-              </Tooltip>
-              <Tooltip title="Zoom out">
-                <Button
-                  icon={<ZoomOutOutlined />}
-                  onClick={() => setZoom((prev) => Math.max(0.1, prev - 0.1))}
-                />
-              </Tooltip>
-            </Space>
-          ) : (
-            <Collapse
-              bordered={false}
-              size="small"
-              activeKey={toolPanelSections}
-              onChange={(keys) =>
-                setToolPanelSections(Array.isArray(keys) ? keys : [keys])
-              }
-              items={[
-                {
-                  key: "minimap",
-                  label: "Minimap",
-                  children: (
-                    <div
-                      style={{
-                        background: "#eee",
-                        border: "1px solid #d9d9d9",
-                        position: "relative",
-                        width: "100%",
-                        aspectRatio: "4 / 3",
-                        margin: "0 auto",
-                        borderRadius: "4px",
-                        overflow: "hidden",
-                        cursor: "crosshair",
-                        display: canvasDimensions.width > 0 ? "block" : "none",
-                      }}
-                      onClick={handleMinimapClick}
-                    >
-                      <canvas
-                        ref={minimapRef}
-                        width={240}
-                        height={180}
-                        style={{
-                          width: "100%",
-                          height: "100%",
-                          display: "block",
-                        }}
-                      />
+                {!toolPanelCollapsed && <span>Tools</span>}
+                <Tooltip
+                  title={toolPanelCollapsed ? "Expand tools" : "Collapse tools"}
+                >
+                  <Button
+                    type="text"
+                    size="small"
+                    icon={
+                      toolPanelCollapsed ? <RightOutlined /> : <LeftOutlined />
+                    }
+                    onClick={() => setToolPanelCollapsed((prev) => !prev)}
+                    aria-label={
+                      toolPanelCollapsed ? "Expand tools" : "Collapse tools"
+                    }
+                    style={{
+                      width: 28,
+                      height: 28,
+                      display: "inline-flex",
+                      alignItems: "center",
+                      justifyContent: "center",
+                    }}
+                  />
+                </Tooltip>
+              </div>
+            }
+            style={{
+              width: toolPanelCollapsed
+                ? collapsedToolWidth
+                : expandedToolWidth,
+              minWidth: toolPanelCollapsed
+                ? collapsedToolWidth
+                : expandedToolWidth,
+              height: "100%",
+              transition: "width 0.2s ease",
+              borderRadius: minimalChrome ? 0 : undefined,
+              borderTop: minimalChrome ? 0 : undefined,
+              borderBottom: minimalChrome ? 0 : undefined,
+              borderLeft: minimalChrome ? 0 : undefined,
+            }}
+            headStyle={{
+              padding: toolPanelCollapsed ? "0 8px" : "0 12px",
+            }}
+            bodyStyle={{
+              height: "calc(100% - 40px)",
+              overflowY: "auto",
+              padding: toolPanelCollapsed ? "10px 8px" : "12px",
+            }}
+            size="small"
+          >
+            {toolPanelCollapsed ? (
+              <Space
+                direction="vertical"
+                size="small"
+                style={{ width: "100%", alignItems: "center" }}
+              >
+                <Tooltip title="Paint (P)">
+                  <Button
+                    type={tool === "paint" ? "primary" : "default"}
+                    icon={<EditOutlined />}
+                    onClick={() => setTool("paint")}
+                    disabled={!canEdit}
+                  />
+                </Tooltip>
+                <Tooltip title="Erase (E)">
+                  <Button
+                    type={tool === "erase" ? "primary" : "default"}
+                    icon={<ClearOutlined />}
+                    onClick={() => setTool("erase")}
+                    disabled={!canEdit}
+                  />
+                </Tooltip>
+                <Tooltip title="Hand (H)">
+                  <Button
+                    type={tool === "hand" ? "primary" : "default"}
+                    icon={<DragOutlined />}
+                    onClick={() => setTool("hand")}
+                  />
+                </Tooltip>
+                <Tooltip title={showMask ? "Hide mask" : "Show mask"}>
+                  <Button
+                    icon={showMask ? <EyeInvisibleOutlined /> : <EyeOutlined />}
+                    onClick={() => setShowMask(!showMask)}
+                  />
+                </Tooltip>
+                <Tooltip title="Save mask (Ctrl+S)">
+                  <Button
+                    type={hasUnsavedEdits ? "primary" : "default"}
+                    icon={<SaveOutlined />}
+                    onClick={handleSave}
+                    disabled={!canEdit}
+                  />
+                </Tooltip>
+                <Tooltip title="Zoom in">
+                  <Button
+                    icon={<ZoomInOutlined />}
+                    onClick={() =>
+                      setZoom((prev) => Math.min(10.0, prev + 0.1))
+                    }
+                  />
+                </Tooltip>
+                <Tooltip title="Zoom out">
+                  <Button
+                    icon={<ZoomOutOutlined />}
+                    onClick={() => {
+                      const nextZoom = Math.max(1, zoom - 0.1);
+                      setZoom(nextZoom);
+                      setOffset((prev) =>
+                        clampOffsetToViewport(prev, nextZoom),
+                      );
+                    }}
+                  />
+                </Tooltip>
+              </Space>
+            ) : (
+              <Collapse
+                bordered={false}
+                size="small"
+                activeKey={toolPanelSections}
+                onChange={(keys) =>
+                  setToolPanelSections(Array.isArray(keys) ? keys : [keys])
+                }
+                items={[
+                  {
+                    key: "minimap",
+                    label: "Minimap",
+                    children: (
                       <div
                         style={{
-                          position: "absolute",
-                          bottom: "4px",
-                          left: "4px",
-                          background: "rgba(0,0,0,0.5)",
-                          color: "white",
-                          fontSize: "10px",
-                          padding: "0 4px",
-                          borderRadius: "3px",
-                          pointerEvents: "none",
-                          opacity: 0.7,
+                          background: "#eee",
+                          border: "1px solid #d9d9d9",
+                          position: "relative",
+                          width: "100%",
+                          aspectRatio: "4 / 3",
+                          margin: "0 auto",
+                          borderRadius: "4px",
+                          overflow: "hidden",
+                          cursor: "crosshair",
+                          display:
+                            canvasDimensions.width > 0 ? "block" : "none",
                         }}
+                        onClick={handleMinimapClick}
                       >
-                        Minimap (click to jump)
+                        <canvas
+                          ref={minimapRef}
+                          width={240}
+                          height={180}
+                          style={{
+                            width: "100%",
+                            height: "100%",
+                            display: "block",
+                          }}
+                        />
+                        <div
+                          style={{
+                            position: "absolute",
+                            bottom: "4px",
+                            left: "4px",
+                            background: "rgba(0,0,0,0.5)",
+                            color: "white",
+                            fontSize: "10px",
+                            padding: "0 4px",
+                            borderRadius: "3px",
+                            pointerEvents: "none",
+                            opacity: 0.7,
+                          }}
+                        >
+                          Minimap (click to jump)
+                        </div>
                       </div>
-                    </div>
-                  ),
-                },
-                {
-                  key: "editing",
-                  label: "Editing",
-                  children: (
-                    <Space direction="vertical" style={{ width: "100%" }}>
-                      <Space>
-                        <Tooltip title="Paint (P)">
-                          <Button
-                            type={tool === "paint" ? "primary" : "default"}
-                            icon={<EditOutlined />}
-                            onClick={() => setTool("paint")}
-                          />
-                        </Tooltip>
-                        <Tooltip title="Erase (E)">
-                          <Button
-                            type={tool === "erase" ? "primary" : "default"}
-                            icon={<ClearOutlined />}
-                            onClick={() => setTool("erase")}
-                          />
-                        </Tooltip>
-                        <Tooltip title="Hand (H)">
-                          <Button
-                            type={tool === "hand" ? "primary" : "default"}
-                            icon={<DragOutlined />}
-                            onClick={() => setTool("hand")}
-                          />
-                        </Tooltip>
+                    ),
+                  },
+                  {
+                    key: "editing",
+                    label: "Editing",
+                    children: (
+                      <Space direction="vertical" style={{ width: "100%" }}>
+                        <Space>
+                          <Tooltip title="Paint (P)">
+                            <Button
+                              type={tool === "paint" ? "primary" : "default"}
+                              icon={<EditOutlined />}
+                              onClick={() => setTool("paint")}
+                              disabled={!canEdit}
+                            />
+                          </Tooltip>
+                          <Tooltip title="Erase (E)">
+                            <Button
+                              type={tool === "erase" ? "primary" : "default"}
+                              icon={<ClearOutlined />}
+                              onClick={() => setTool("erase")}
+                              disabled={!canEdit}
+                            />
+                          </Tooltip>
+                          <Tooltip title="Hand (H)">
+                            <Button
+                              type={tool === "hand" ? "primary" : "default"}
+                              icon={<DragOutlined />}
+                              onClick={() => setTool("hand")}
+                            />
+                          </Tooltip>
+                        </Space>
+                        {(tool === "paint" || tool === "erase") && (
+                          <>
+                            <Text style={{ fontSize: 12, fontWeight: 500 }}>
+                              {tool === "erase" ? "Erase" : "Paint"} size
+                            </Text>
+                            <Slider
+                              min={1}
+                              max={64}
+                              value={activeBrushSize}
+                              onChange={setBrushSize}
+                            />
+                            <InputNumber
+                              min={1}
+                              max={64}
+                              value={activeBrushSize}
+                              onChange={setBrushSize}
+                              style={{ width: "100%" }}
+                            />
+                          </>
+                        )}
+                      </Space>
+                    ),
+                  },
+                  {
+                    key: "history",
+                    label: "History & visibility",
+                    children: (
+                      <Space direction="vertical" style={{ width: "100%" }}>
+                        <Space>
+                          <Tooltip title="Undo (Ctrl+Z)">
+                            <Button
+                              icon={<UndoOutlined />}
+                              onClick={handleUndo}
+                              disabled={!canEdit || undoStack.length === 0}
+                            >
+                              Undo
+                            </Button>
+                          </Tooltip>
+                          <Tooltip title="Redo (Ctrl+Shift+Z)">
+                            <Button
+                              icon={<RedoOutlined />}
+                              onClick={handleRedo}
+                              disabled={!canEdit || redoStack.length === 0}
+                            >
+                              Redo
+                            </Button>
+                          </Tooltip>
+                        </Space>
+                        <Button
+                          icon={
+                            showMask ? (
+                              <EyeInvisibleOutlined />
+                            ) : (
+                              <EyeOutlined />
+                            )
+                          }
+                          onClick={() => setShowMask(!showMask)}
+                          block
+                        >
+                          {showMask ? "Hide Mask" : "Show Mask"}
+                        </Button>
+                        <Button
+                          type={hasUnsavedEdits ? "primary" : "default"}
+                          icon={<SaveOutlined />}
+                          onClick={handleSave}
+                          disabled={!canEdit}
+                          block
+                        >
+                          Save mask
+                        </Button>
                       </Space>
-                      {(tool === "paint" || tool === "erase") && (
-                        <>
-                          <Text style={{ fontSize: 12, fontWeight: 500 }}>
-                            {tool === "erase" ? "Erase" : "Paint"} size
-                          </Text>
-                          <Slider
-                            min={1}
-                            max={64}
-                            value={activeBrushSize}
-                            onChange={setBrushSize}
-                          />
-                          <InputNumber
-                            min={1}
-                            max={64}
-                            value={activeBrushSize}
-                            onChange={setBrushSize}
-                            style={{ width: "100%" }}
-                          />
-                        </>
-                      )}
-                    </Space>
-                  ),
-                },
-                {
-                  key: "history",
-                  label: "History & visibility",
-                  children: (
-                    <Space direction="vertical" style={{ width: "100%" }}>
+                    ),
+                  },
+                  {
+                    key: "zoom",
+                    label: `Zoom (${Math.round(zoom * 100)}%)`,
+                    children: (
                       <Space>
-                        <Tooltip title="Undo (Ctrl+Z)">
-                          <Button
-                            icon={<UndoOutlined />}
-                            onClick={handleUndo}
-                            disabled={undoStack.length === 0}
-                          >
-                            Undo
-                          </Button>
-                        </Tooltip>
-                        <Tooltip title="Redo (Ctrl+Shift+Z)">
-                          <Button
-                            icon={<RedoOutlined />}
-                            onClick={handleRedo}
-                            disabled={redoStack.length === 0}
-                          >
-                            Redo
-                          </Button>
-                        </Tooltip>
+                        <Button
+                          icon={<ZoomOutOutlined />}
+                          onClick={() => {
+                            const nextZoom = Math.max(1, zoom - 0.1);
+                            setZoom(nextZoom);
+                            setOffset((prev) =>
+                              clampOffsetToViewport(prev, nextZoom),
+                            );
+                          }}
+                        />
+                        <Button
+                          onClick={() => {
+                            setZoom(1.0);
+                            setOffset({ x: 0, y: 0 });
+                          }}
+                        >
+                          Reset
+                        </Button>
+                        <Button
+                          icon={<ZoomInOutlined />}
+                          onClick={() =>
+                            setZoom((prev) => Math.min(10.0, prev + 0.1))
+                          }
+                        />
                       </Space>
-                      <Button
-                        icon={
-                          showMask ? <EyeInvisibleOutlined /> : <EyeOutlined />
-                        }
-                        onClick={() => setShowMask(!showMask)}
-                        block
-                      >
-                        {showMask ? "Hide Mask" : "Show Mask"}
-                      </Button>
-                    </Space>
-                  ),
-                },
-                {
-                  key: "zoom",
-                  label: `Zoom (${Math.round(zoom * 100)}%)`,
-                  children: (
-                    <Space>
-                      <Button
-                        icon={<ZoomOutOutlined />}
-                        onClick={() =>
-                          setZoom((prev) => Math.max(0.1, prev - 0.1))
-                        }
-                      />
-                      <Button
-                        onClick={() => {
-                          setZoom(1.0);
-                          setOffset({ x: 0, y: 0 });
-                        }}
-                      >
-                        Reset
-                      </Button>
-                      <Button
-                        icon={<ZoomInOutlined />}
-                        onClick={() =>
-                          setZoom((prev) => Math.min(10.0, prev + 0.1))
-                        }
-                      />
-                    </Space>
-                  ),
-                },
-              ]}
-            />
-          )}
-        </Card>
+                    ),
+                  },
+                ]}
+              />
+            )}
+          </Card>
+        )}
 
         {/* Center - Canvas */}
         <div
@@ -1256,40 +1617,36 @@ const ProofreadingEditor = forwardRef(
             height: "100%",
           }}
         >
-          {totalLayers > 1 && (
+          {totalLayers > 1 && !hideLayerToolbar && (
             <Card size="small">
               <Space
                 style={{ width: "100%", justifyContent: "space-between" }}
                 align="center"
               >
                 <Space size="middle" align="center">
-                  {axisOptions && onAxisChange && (
-                    <Segmented
-                      size="small"
-                      options={axisOptions}
-                      value={axis}
-                      onChange={onAxisChange}
-                    />
-                  )}
                   <Text style={{ fontWeight: 600 }}>
                     {layerName || `${axisLabel} ${currentLayer + 1}`} /{" "}
                     {totalLayers}
                   </Text>
+                  {hasUnsavedEdits && (
+                    <Tag color="orange" style={{ margin: 0 }}>
+                      unsaved edits
+                    </Tag>
+                  )}
+                  {!canEdit && (
+                    <Tag color="blue" style={{ margin: 0 }}>
+                      editable mask loading
+                    </Tag>
+                  )}
                 </Space>
                 <Space>
                   <Button
-                    icon={<LeftOutlined />}
-                    onClick={onPrevious}
-                    disabled={currentLayer === 0}
-                  >
-                    Previous
-                  </Button>
-                  <Button
-                    icon={<RightOutlined />}
-                    onClick={onNext}
-                    disabled={currentLayer === totalLayers - 1}
+                    type={hasUnsavedEdits ? "primary" : "default"}
+                    icon={<SaveOutlined />}
+                    onClick={handleSave}
+                    disabled={!canEdit}
                   >
-                    Next
+                    Save mask
                   </Button>
                 </Space>
               </Space>
@@ -1310,7 +1667,7 @@ const ProofreadingEditor = forwardRef(
                   : tool === "paint" || tool === "erase"
                     ? "none"
                     : "default",
-              background: "#f5f5f5",
+              background: minimalChrome ? "#111827" : "#f5f5f5",
               padding: minimalChrome ? 0 : 4,
             }}
           >
@@ -1318,9 +1675,8 @@ const ProofreadingEditor = forwardRef(
               ref={containerRef}
               style={{
                 position: "relative",
-                width: "min(100%, 980px)",
-                maxHeight: "100%",
-                aspectRatio: "1 / 1",
+                width: "100%",
+                height: "100%",
                 display: "flex",
                 justifyContent: "center",
                 alignItems: "center",
@@ -1332,32 +1688,18 @@ const ProofreadingEditor = forwardRef(
               onMouseUp={handleMouseUp}
               onMouseLeave={handleMouseUp}
             >
-              <div
-                style={{
-                  position: "absolute",
-                  left: 12,
-                  top: 12,
-                  zIndex: 2,
-                  background: "rgba(15, 23, 42, 0.7)",
-                  color: "#fff",
-                  padding: "6px 10px",
-                  borderRadius: 10,
-                  fontSize: 12,
-                }}
-              >
-                {cursorPos ? (
-                  <Text style={{ color: "#fff" }}>
-                    {axisCursorLabel().h}: {cursorPos.x} · {axisCursorLabel().v}
-                    : {cursorPos.y}
-                  </Text>
-                ) : (
-                  <Text style={{ color: "#9ca3af" }}>Cursor: --</Text>
-                )}
-              </div>
               <canvas
                 ref={canvasRef}
                 style={{
                   border: "1px solid #d9d9d9",
+                  width: fittedCanvasSize.width
+                    ? `${fittedCanvasSize.width}px`
+                    : undefined,
+                  height: fittedCanvasSize.height
+                    ? `${fittedCanvasSize.height}px`
+                    : undefined,
+                  maxWidth: "100%",
+                  maxHeight: "100%",
                   transform: `translate(${offset.x}px, ${offset.y}px) scale(${zoom})`,
                   transformOrigin: "center",
                   imageRendering: "pixelated",
@@ -1368,17 +1710,18 @@ const ProofreadingEditor = forwardRef(
               {/* Cursor SVG overlay - follows mousePos directly for absolute tracking */}
               {!isPanning &&
                 (tool === "paint" || tool === "erase") &&
-                mousePos && (
+                mousePos &&
+                cursorPos && (
                   <div
                     style={{
                       position: "absolute",
                       left: mousePos.x,
                       top: mousePos.y,
-                      width: activeBrushSize * zoom,
-                      height: activeBrushSize * zoom,
+                      width: activeBrushSize * fittedCanvasSize.scale * zoom,
+                      height: activeBrushSize * fittedCanvasSize.scale * zoom,
                       border:
                         tool === "paint"
-                          ? "2px solid #1890ff"
+                          ? "2px solid var(--seg-accent-primary, #3f37c9)"
                           : "2px dashed #ff4d4f",
                       boxShadow: tool === "erase" ? "0 0 0 1px white" : "none", // High contrast for eraser
                       borderRadius: 4,
diff --git a/client/src/views/ehtool/UnifiedImageEditor.js b/client/src/views/ehtool/UnifiedImageEditor.js
index c53bd441..e8d625a6 100644
--- a/client/src/views/ehtool/UnifiedImageEditor.js
+++ b/client/src/views/ehtool/UnifiedImageEditor.js
@@ -72,7 +72,7 @@ function UnifiedImageEditor({
 
     window.addEventListener("keydown", handleKeyDown);
     return () => window.removeEventListener("keydown", handleKeyDown);
-  }, [visible, currentLabel]);
+  }, [visible, currentLabel, showClassification, onClose]);
 
   if (!layer) return null;
 
diff --git a/client/src/views/ehtool/proofreadingPaths.js b/client/src/views/ehtool/proofreadingPaths.js
new file mode 100644
index 00000000..ec9c6705
--- /dev/null
+++ b/client/src/views/ehtool/proofreadingPaths.js
@@ -0,0 +1,53 @@
+export const basename = (value) => {
+  if (!value) return "";
+  const trimmed = String(value).replace(/\/+$/, "");
+  return trimmed.split("/").pop() || trimmed;
+};
+
+export const getProofreadingImagePath = (workflow = {}) =>
+  workflow.image_path || workflow.dataset_path || "";
+
+export const getProofreadingMaskPath = (workflow = {}) =>
+  workflow.corrected_mask_path ||
+  workflow.inference_output_path ||
+  workflow.mask_path ||
+  workflow.label_path ||
+  "";
+
+export const getProofreadingProjectName = (workflow = {}) =>
+  workflow.project_name ||
+  workflow.metadata?.project_name ||
+  workflow.metadata?.projectName ||
+  workflow.title ||
+  "Proofreading review";
+
+export const getTrainingReadyCorrectedMask = ({
+  persistence = {},
+  workflow = {},
+} = {}) => {
+  if (persistence.last_export_path) {
+    return {
+      path: persistence.last_export_path,
+      source: "proofreading_export",
+    };
+  }
+
+  if (persistence.artifact_exists && persistence.artifact_path) {
+    return {
+      path: persistence.artifact_path,
+      source: "proofreading_persistence",
+    };
+  }
+
+  if (workflow.corrected_mask_path) {
+    return {
+      path: workflow.corrected_mask_path,
+      source: "workflow_corrected_mask",
+    };
+  }
+
+  return {
+    path: "",
+    source: "",
+  };
+};
diff --git a/client/src/views/ehtool/proofreadingPaths.test.js b/client/src/views/ehtool/proofreadingPaths.test.js
new file mode 100644
index 00000000..26b0d35b
--- /dev/null
+++ b/client/src/views/ehtool/proofreadingPaths.test.js
@@ -0,0 +1,105 @@
+import {
+  basename,
+  getProofreadingImagePath,
+  getProofreadingMaskPath,
+  getProofreadingProjectName,
+  getTrainingReadyCorrectedMask,
+} from "./proofreadingPaths";
+
+describe("proofreadingPaths", () => {
+  it("uses image or dataset paths for the source image, not prediction outputs", () => {
+    expect(
+      getProofreadingImagePath({
+        image_path: "/project/data/image/a.h5",
+        dataset_path: "/project/data/image/fallback.h5",
+        inference_output_path: "/project/outputs/pred.h5",
+      }),
+    ).toBe("/project/data/image/a.h5");
+
+    expect(
+      getProofreadingImagePath({
+        dataset_path: "/project/data/image/fallback.h5",
+        inference_output_path: "/project/outputs/pred.h5",
+      }),
+    ).toBe("/project/data/image/fallback.h5");
+
+    expect(
+      getProofreadingImagePath({
+        inference_output_path: "/project/outputs/pred.h5",
+      }),
+    ).toBe("");
+  });
+
+  it("chooses the most useful mask candidate for proofreading", () => {
+    expect(
+      getProofreadingMaskPath({
+        corrected_mask_path: "/project/corrected.tif",
+        inference_output_path: "/project/pred.h5",
+        mask_path: "/project/mask.h5",
+        label_path: "/project/label.h5",
+      }),
+    ).toBe("/project/corrected.tif");
+
+    expect(
+      getProofreadingMaskPath({
+        inference_output_path: "/project/pred.h5",
+        mask_path: "/project/mask.h5",
+        label_path: "/project/label.h5",
+      }),
+    ).toBe("/project/pred.h5");
+
+    expect(
+      getProofreadingMaskPath({
+        mask_path: "/project/mask.h5",
+        label_path: "/project/label.h5",
+      }),
+    ).toBe("/project/mask.h5");
+  });
+
+  it("only stages real corrected artifacts for retraining", () => {
+    expect(
+      getTrainingReadyCorrectedMask({
+        persistence: {
+          artifact_path: "/project/.pytc_instance_labels.tif",
+          artifact_exists: false,
+        },
+        workflow: {
+          mask_path: "/project/original-mask.h5",
+          label_path: "/project/original-label.h5",
+        },
+      }),
+    ).toEqual({ path: "", source: "" });
+
+    expect(
+      getTrainingReadyCorrectedMask({
+        persistence: {
+          artifact_path: "/project/.pytc_instance_labels.tif",
+          artifact_exists: true,
+        },
+      }),
+    ).toEqual({
+      path: "/project/.pytc_instance_labels.tif",
+      source: "proofreading_persistence",
+    });
+
+    expect(
+      getTrainingReadyCorrectedMask({
+        persistence: {
+          artifact_path: "/project/.pytc_instance_labels.tif",
+          artifact_exists: true,
+          last_export_path: "/project/corrected/export.tif",
+        },
+      }),
+    ).toEqual({
+      path: "/project/corrected/export.tif",
+      source: "proofreading_export",
+    });
+  });
+
+  it("keeps display names stable", () => {
+    expect(basename("/tmp/project/data/")).toBe("data");
+    expect(
+      getProofreadingProjectName({ metadata: { projectName: "Mouse EM" } }),
+    ).toBe("Mouse EM");
+  });
+});
diff --git a/docs/agent-role-spec.md b/docs/agent-role-spec.md
new file mode 100644
index 00000000..7a18d2d2
--- /dev/null
+++ b/docs/agent-role-spec.md
@@ -0,0 +1,324 @@
+# Agent Role Specification
+
+This defines the intended role of the agent in the TOCHI-facing PyTC Client
+prototype.
+
+## Product Role
+
+The agent is a workflow copilot for biomedical segmentation. It should help a
+biologist understand the current state, choose the next safe action, and inspect
+evidence. It is not a replacement for the human reviewer and should not silently
+execute risky training, inference, overwrite, export, or retraining actions.
+
+## Default Behavior
+
+- Recommend the next concrete workflow action first.
+- Keep answers skimmable: at most three bullets and usually under 90 words.
+- Ground UI instructions in visible app controls and documented workflows.
+- Show blockers clearly: missing image, label, checkpoint, prediction, export,
+  correction set, model version, or metric result.
+- Prefer app actions over command-line instructions for normal users.
+- Ask for approval before actions that run jobs, overwrite masks, stage
+  retraining, launch inference, launch training, or export evidence.
+
+## Agent Boundaries
+
+- The agent may navigate the user, summarize state, propose actions, explain
+  settings, populate form fields, and prepare commands.
+- The agent may generate a training/inference command only when explicitly
+  asked for a command.
+- The agent may not fabricate paths, scripts, shortcuts, results, model quality,
+  or hidden app features.
+- The agent may not claim autonomous closed-loop improvement until the app has
+  executed baseline inference, proofreading export, retraining, candidate
+  inference, and before/after evaluation using app-generated artifacts.
+
+## UI Role
+
+The agent should appear as a compact decision-support layer across the app, not
+as a verbose chatbot. It should connect File Management, Visualization,
+Inference, Proofreading, Training, Evaluation, and Evidence Export through the
+workflow evidence substrate.
+
+Implemented UI commitments:
+
+- The assistant drawer/status entry should always answer "what should I do
+  next?" from current workflow evidence without adding persistent canvas clutter.
+- The first action must match the recommendation. For example, "start
+  inference" should expose a start-inference action, not merely a navigation
+  button.
+- The agent can open the assistant evidence/context drawer from any module so
+  the user can inspect artifacts, correction sets, metrics, and proposals
+  without losing the active workflow.
+- Retraining handoff remains approval-gated: the agent may create a pending
+  proposal from corrected masks, but the human must approve staging.
+- Chat responses for workflow questions should reuse the same recommendation
+  state and use compact `Do this`, `Why`, `Ready`, `Watch out` structure.
+
+## 2026-04-25 Orchestrator Pass
+
+- The agent should speak in user goals, not implementation nouns. Use
+  "Proofread this data", "Run model", "Use edits for training", and "Compare
+  results" instead of "open artifact", "candidate output", or "retraining
+  handoff" in biologist-facing controls.
+- The primary action should mutate local app state when safe. `Proofread this
+data` now carries a `start_proofreading` runtime action with image/mask/review
+  overrides so the proofreading workbench can load the current pair directly.
+- Status panels should summarize readiness with domain labels: previous result,
+  new result, your saved edits, and reference mask. Full paths and dataset-key
+  options are still available, but should be secondary/debuggable details.
+- The agent is allowed to orchestrate navigation, form prefill, proofreading
+  load, inference launch, training launch, metric comparison, and report export
+  through explicit client effects. Risky steps remain user-triggered and
+  event-logged.
+
+## Success Criteria
+
+- A biologist can skim the response in under ten seconds.
+- The response identifies the next useful action or the single blocking input.
+- Risky actions are auditable as proposals, approvals, rejections, or workflow
+  events.
+- The agent improves workflow continuity without hiding provenance or control.
+
+## 2026-04-25 Prompt-Boundary Hardening
+
+- The active app assistant defaults to the deterministic workflow orchestrator
+  for greetings, repair phrases, slash commands, and recognizable workflow
+  intents. General/non-workflow text should still route to normal assistant/LLM
+  handling so the chat does not turn every message into a next-step card.
+- Internal system prompts, role text, routing rules, tool names, and response
+  style instructions are never valid user-facing output. If the generic LLM
+  leaks prompt scaffolding, the server replaces it with a compact safe fallback.
+- The orchestrator now handles greetings, incomplete intents, status checks,
+  module navigation, model launch, proofreading launch, retraining handoff,
+  before/after metric comparison, and evidence export as explicit, auditable
+  app actions.
+- The agent is not just a help sidebar: it is the controller that translates
+  user goals into workflow-state-aware next steps while preserving human
+  approval for long-running or artifact-changing operations.
+
+## 2026-04-26 Agent Routing and Help Cleanup
+
+- Unknown workflow-router text must return a compact clarification and no app
+  action cards. Gibberish should never produce "proofread/train/compare" cards.
+- The main assistant logs whether a message went through the workflow
+  orchestrator or the general assistant path.
+- Inline field help should be a compact local hint, not a docs viewer. It must
+  avoid raw headings such as "Relevant local docs" and keep file-selection help
+  focused on visible controls such as the folder icon, Browse, and Use folder.
+- File path text boxes remain editable fallback controls, but ordinary users
+  should be able to open the picker from the folder icon or Browse button.
+
+## 2026-04-26 Contextual Project Context
+
+- Do not use a startup splash or session-goal gate. The product goal is fixed:
+  move from an initial biomedical image volume to fully proofread
+  segmentations.
+- The agent should gather biological context only when it is needed to run or
+  stage a workflow action: inference, training, proofreading triage, or
+  comparison.
+- Minimal project context is `imaging_modality`, `target_structure`, and
+  `optimization_priority` such as speed versus accuracy. Store it under
+  `metadata.project_context`, distinct from workflow progress events.
+- The agent may ask one compact question before acting: modality, target
+  structure, and speed/accuracy preference. The user can also say "use
+  defaults" to proceed with conservative settings.
+- Running progress remains append-only workflow events and artifacts:
+  `dataset.loaded`, training/inference runs, correction sets, evaluation
+  results, and bundle exports.
+
+## 2026-04-27 Project Role Confirmation Contract
+
+- The app and agent may infer image, mask/label, prediction, checkpoint, and
+  config roles from a mounted directory, but workflow state is not populated
+  until the user confirms or edits those roles.
+- Image volume is the only required setup role. Mask/label, prediction,
+  checkpoint, and config roles are optional so image-only folders remain valid
+  starting points.
+- Confirmed roles are recorded as a `dataset.loaded` event with the inferred
+  profile mode, mounted directory, confirmed role paths, and resulting workflow
+  patch.
+- Config is now a first-class workflow path. It may seed agent-selected
+  training defaults, but the user still approves the resulting runtime action
+  before a job launches.
+- The agent should treat unconfirmed project-role guesses as suggestions, not
+  facts. After confirmation, it can use those paths to recommend visualization,
+  inference, proofreading, training, or comparison.
+
+## 2026-04-28 Directory and Batch Ingest Contract
+
+- A project usually contains folders of image volumes, not one canonical file.
+  Profiling must therefore surface both examples and role directories.
+- `pytc-project-profile/v1` now includes `role_directories` and
+  `volume_sets`. A volume set records image root, optional label root, counts,
+  matched pair count, and examples.
+- The confirmation UI should default to a folder when multiple images/labels
+  are detected, and to a file when the project is genuinely single-volume.
+- The user can add a compact natural-language project description during
+  confirmation. This is agent context and audit metadata, not a startup splash
+  or a blocker.
+- `dataset.loaded` should include confirmed roles, detected directories,
+  detected volume sets, and the user project context so downstream agent
+  actions can explain what they used.
+- The confirmation surface should read as a short agent check, not a technical
+  manifest. Avoid readiness chips and absolute paths; show concise inferred
+  structure in words, let the user correct the inference in natural language,
+  and keep relative role fields editable as fallback controls.
+- The project-setup correction box is an interaction loop, not passive notes:
+  Enter submits the question/correction, the agent replies in place, detectable
+  split changes such as "use val split" update the role fields, and the turn is
+  logged as `dataset.setup_feedback` before final `dataset.loaded`.
+- The correction loop must support repeated turns. Feedback submission should
+  operate on the latest confirmed draft roles and should not block subsequent
+  local corrections while workflow-event logging is in flight.
+- Project context comes before structure correction. The confirmation surface
+  has a dedicated `What is in this directory?` field for broad biological
+  context, then an agent summary of detected image/label sets, then a separate
+  `Correct my file mapping` loop.
+- Project context is durable workflow metadata, not correction feedback. When
+  supplied, it is stored under `metadata.project_context` and echoed in the
+  `dataset.loaded` event as `project_description` plus inferred lightweight
+  fields such as imaging modality, target structure, and speed/accuracy
+  preference.
+- Mapping feedback remains operational and append-only:
+  `dataset.setup_feedback` records questions/corrections and role changes, but
+  those turns should not be treated as the biological project description.
+- The confirmation flow is now a staged subworkflow, not one combined modal:
+  semantic project context comes first, file/folder mapping comes second, and
+  final confirmation comes third.
+- The semantic stage uses a deterministic completeness gate before advancing.
+  Required context is imaging modality, target structure, task goal, data
+  organization, and speed/accuracy preference. If the gate is incomplete, the
+  agent asks targeted follow-up questions instead of guessing from a vague
+  confidence score.
+- The hidden `.pytc_project_context.json` file is the local project memory
+  anchor. It stores compact semantic context, mechanistic mapping,
+  workflow-memory summary, and setup turns for agent continuity across modules
+  and app restarts. It is not the authoritative audit trail; workflow DB records
+  and events remain authoritative.
+- `.pytc_project_context.json` is hidden from the normal file-management UI and
+  ignored during project mounting.
+- Project setup must not infer biological context from project names alone.
+  Role classification can use path/name patterns, but modality, biological
+  target, and task hints should come from user description and lightweight file
+  content inspection such as manifests, configs, HDF5 dataset keys, and image
+  container metadata.
+
+## 2026-04-26 Agent-Run Training Defaults
+
+- The biologist should provide the goal, data, and approval; the agent should
+  choose the nearest safe training preset and fill routine runtime paths.
+- Low-level YAML, stride, blending, chunk, CPU/GPU, and iteration settings are
+  advanced controls. The assistant must not lead with them unless the user asks
+  to override defaults or debug a failed run.
+- Agent-triggered training uses `agent_default` mode: current image path,
+  corrected mask path, output/log directory, preset config, and conservative
+  memory-safe defaults are staged together before the user approves the run.
+- Meta questions such as "how did you run so quickly?" should state whether the
+  app actually ran a job. Do not answer those with retrieved training docs.
+
+## 2026-04-26 Project-Agnostic Setup Contract
+
+- The agent and UI should not depend on the mito25 demo path. Any mounted folder
+  can become a workable project if it contains a detectable image volume.
+- Folder profiling returns `pytc-project-profile/v1` with modes:
+  `not_workable`, `image_only`, `image_mask_pair`, and `closed_loop_ready`.
+- The biologist-facing blocker is the missing data artifact, not YAML. Training
+  configs and inference presets are agent-inferred implementation details unless
+  the user asks to override them.
+- Workflow preflight is exposed at `GET /api/workflows/{id}/preflight`. It
+  reports whether setup, visualization, inference, proofreading, training, and
+  evaluation can run from the current workflow records.
+- Image-only projects are valid starts. The next step is to add/run a model or
+  provide a mask/label, not to force the mito smoke fixture.
+
+## 2026-04-27 Quick Next-Step Affordance
+
+- The app shell can ask the workflow agent `What should I do next?` from any
+  module. This is a stable entry point, not a per-module card.
+- The quick action routes through the same workflow-agent chat path as typed
+  requests, so the answer is persisted, action cards are preserved in history,
+  and risky actions remain approval-gated.
+- The agent response should be derived from workflow preflight, artifacts, runs,
+  corrections, metrics, and current stage. The prompt/query is only a trigger;
+  it must not become a free-form hallucinated opinion.
+- Keep the answer compact: one recommended action, one reason, readiness count,
+  and at most one blocker.
+
+## 2026-04-25 Claude Code Pattern Pass
+
+- Treat chat as a control surface over typed workflow tools. The agent should
+  return app actions with risk metadata rather than long explanatory prose.
+- Every action should be classifiable as `view only`, `sets form`, `opens
+editor`, `runs job`, `writes record`, or `exports`. Long-running or
+  artifact-changing actions require an explicit user click and workflow-event
+  logging.
+- Support deterministic slash-style workflow commands for power users:
+  `/status`, `/infer`, `/proofread`, `/train`, `/compare`, `/export`, and
+  `/help`.
+- Keep command-like route details collapsed by default. Biologist-facing UI
+  should show the domain action first and reserve implementation details for
+  debugging/logging.
+- Maintain a structured loop checklist in the response payload so the assistant
+  can answer "what is left?" without inventing state from chat history.
+- Future subagents should be domain-specialized and tool-restricted:
+  data-curator, model-runner, proofreading-triage, and evidence-auditor.
+
+## 2026-04-25 Contextual Entry-Point Pass
+
+- Keep the main drawer/chat as the full conversation and evidence inspector.
+- Do not keep a persistent next-step strip on the main canvas by default; it
+  competes with the biomedical task UI.
+- Do not add per-module agent cards by default; they make the biomedical UI feel
+  busier than the task requires.
+- If a module needs agent help, expose it as a normal button near the relevant
+  control, with any explanation in a hover tooltip.
+- All agent-triggered buttons must still log client events and route through
+  `executeAssistantItem` or `queryAgent` so they remain auditable.
+- Training/inference terminal logs should be hidden by default. The main UI
+  should show a plain run state such as "Running", "Completed", or "Needs
+  attention" and only reveal raw logs on demand.
+
+## 2026-04-29 Agent Action Consistency Contract
+
+- Agent text, action cards, and command blocks must be generated from the same
+  workflow decision. The assistant must not say "Proofread this data" while only
+  offering generic status or setup cards.
+- Intent matching must be token/phrase aware. Raw substring matches are unsafe
+  because normal words such as "already" can accidentally trigger "ready" and
+  route the request to status.
+- If the requested action is possible, the response should include a runnable
+  app card/command for that exact action. For example, a proofread request with
+  an image plus mask/label should expose `start-proofreading`.
+- If the requested action is blocked, the response should state the missing
+  artifact plainly and offer the nearest executable setup step. For example:
+  "I can proofread this, but I need a mask, label, or prediction first."
+- Visualization requests are valid workflow actions. Running the card should
+  move to the viewer and populate image/label paths from workflow state, not
+  merely switch tabs.
+- If visualization paths are directories, the agent should first discover clear
+  image/segmentation pairs, offer the first concrete pair as the runnable
+  action, and ask whether there are more folders or pairs to include. Directory
+  paths are project context; concrete pairs are active viewing/proofreading
+  targets.
+- Visualization voxel scales are project context. Scale corrections like
+  "reload with 1-1-1" should be parsed into z,y,x nanometer values, persisted in
+  workflow metadata, logged as `visualization.scales_updated`, and exposed as a
+  single reload action rather than as documentation or raw tool JSON.
+- Backend agent logs should include the chosen intent, recommendation decision,
+  action ids/labels, command ids/titles, and blocker list so mismatched cards
+  can be debugged from `.logs/app/app-events.jsonl`.
+
+## 2026-06-04 Yixiao TapeReader Action Bounds
+
+- For TapeReader/XRI fibre projects, visualization should prioritize explicit
+  workflow selection: when `image_path` and `label_path` are concrete files, the
+  selected pair must be opened before fallback pair auto-selection.
+- Proofread launch should prefer draft masks first:
+  `corrected_mask_path` → `inference_output_path` → `mask_path` → `label_path`.
+- TapeReader training must not use raw prediction masks as labels. In this project
+  family, training requires confirmed labels or saved proofreading edits; if absent,
+  the agent should block with the correction/path-finding prompt.
+- Inference can only be proposed for image-only targets when a checkpoint exists.
+- Evaluation can only run when all required compare inputs exist: previous result,
+  new result, and reference mask.
diff --git a/docs/case-studies/yixiao-axis-order-diagnosis-20260604.md b/docs/case-studies/yixiao-axis-order-diagnosis-20260604.md
new file mode 100644
index 00000000..f92ec27d
--- /dev/null
+++ b/docs/case-studies/yixiao-axis-order-diagnosis-20260604.md
@@ -0,0 +1,63 @@
+# Yixiao Axis-Order Diagnosis (UG/UM Neuroglancer)
+
+- Date (UTC): 2026-06-04
+- Scope: `server_api/main.py`, `server_api/workflows/volume_io.py`, Yixiao TIFF pairs in
+  `/home/weidf/demo_data/yixiao_tapereader_xri_case_study`
+- Focus pair: `data/raw/1/1-xri_raw.tif` and `data/seg/1/1-mask.tif` (plus additional samples)
+
+## Findings (TIFF ground-truth pairs)
+
+Using `tifffile.imread` directly on raw/mask files:
+
+- `1/1`: raw `(49, 500, 500)`, raw dtype `uint16`; mask `(49, 500, 500)`, mask dtype `int32`.
+- `2/2`: raw `(49, 500, 500)`, raw dtype `uint16`; mask `(49, 500, 500)`, mask dtype `int64`.
+- `3/3`: raw `(49, 500, 500)`, raw dtype `uint16`; mask `(49, 500, 500)`, mask dtype `int64`.
+- `4_1`: raw `(40, 500, 500)`, raw dtype `uint16`; mask `(40, 500, 500)`, mask dtype `int64`.
+- `4_2`: raw `(40, 500, 500)`, raw dtype `uint16`; mask `(40, 500, 500)`, mask dtype `int64`.
+- `4_3`: raw `(40, 500, 500)`, raw dtype `uint16`; mask `(40, 500, 500)`, mask dtype `int64`.
+- `5_1`: raw `(40, 500, 500)`, raw dtype `uint16`; mask `(40, 500, 500)`, mask dtype `int64`.
+- `5_2`: raw `(40, 500, 500)`, raw dtype `uint16`; mask `(40, 500, 500)`, mask dtype `int64`.
+
+All sampled pairs have raw/label shape equality and match manifest `shape_zyx` for each volume, including the leading dimension being `49` or `40`.
+
+### Axis plausibility checks
+
+For each pair, I computed simple slice-alignment metrics between raw and mask under permutations where axis `axis` is considered the Neuroglancer “front” axis:
+
+- Axis 0 (as-is, z-first): produces low slice count (`49` or `40`) and mask bbox spans such as `(2,35)`, `(0,40)`, etc., matching the known physical depth.
+- Axis 1/2 (swapped candidates): forces `500` slices and full-length span across all near-all slices.
+
+Examples:
+
+- `1`: axis0 correlation (raw mean/mask mean) `0.853`, axis1 `0.390`, axis2 `0.252`; nonzero-slice occupancy axis0 `34/49`, axis1 `490/500`, axis2 `482/500`.
+- `4_1`: axis0 correlation `0.796`, axis1 `0.864`, axis2 `0.849`; however axis0 has expected 40 slices total while axis1/2 have 500.
+- `4_2`: axis0 correlation `0.731`, axis1 `0.733`, axis2 `0.781`; again expected depth is preserved only when first axis remains 40.
+
+Because the TIFF tensors already have one short depth-like axis (`40`/`49`) and one long axis pair (`500`/`500`), swapping to any 500-first interpretation would imply a physically implausible 500-slice z stack and would invert expected scale mapping.
+
+## Neuroglancer construction review
+
+In `server_api/main.py`:
+
+- `/neuroglancer` and `/neuroglancer/proofread` both derive scales with `_coerce_neuroglancer_scales(scales)` which validates required `z, y, x` order.
+- They build `CoordinateSpace(names=["z", "y", "x"], units=["nm","nm","nm"], scales=scales)`.
+- They pass image/label arrays directly into `neuroglancer.LocalVolume(data, dimensions=res, ...)` through `_build_neuroglancer_layer`.
+- No `np.moveaxis`/`np.transpose` is applied around loaded arrays in these paths.
+
+`load_volume()` in `server_api/workflows/volume_io.py` also returns arrays as read (with optional channel slicing only); no axis permutation is introduced for TIFF paths.
+
+## Diagnosis
+
+I did not find evidence of an axis-order bug in the current Neuroglancer path for Yixiao ground-truth pairs.
+
+Recommended action: **no code patch** for axis order at this time.
+
+Optional next step: add a lightweight regression test (skipped when dataset is missing) that asserts manifest-matched pairs preserve `shape_zyx` and that the smallest axis remains first (`shape[0] in {40,49}` for this case study).
+
+## Evidence artifacts
+
+- Diagnostic outputs generated from ad-hoc Python checks:
+  - `raw/mask shapes + dtype`
+  - `mask bbox` and `nonzero counts`
+  - `axis0/1/2 slice-alignment correlation` and `nonzero slice occupancy`
+- Code paths verified directly from `server_api/main.py`, `server_api/workflows/volume_io.py`.
diff --git a/docs/case-studies/yixiao-case-study-protocol-2026-06-04.md b/docs/case-studies/yixiao-case-study-protocol-2026-06-04.md
new file mode 100644
index 00000000..f23e31e8
--- /dev/null
+++ b/docs/case-studies/yixiao-case-study-protocol-2026-06-04.md
@@ -0,0 +1,499 @@
+# Yixiao TapeReader/XRI Case Study Protocol - 2026-06-04
+
+## Purpose
+
+This protocol defines a one-hour case study for the Yixiao TapeReader/XRI fixture in seg.bio. It is written for the facilitator and paper team, not as a participant-facing script.
+
+The case study should demonstrate that seg.bio is becoming a workflow-aware, mixed-initiative assistant for biomedical volume segmentation. The core claim is not that seg.bio improves segmentation accuracy by itself. The core claim is that the system helps a domain expert coordinate project context, volume state, inspection, proofreading, training, inference preparation, and evidence capture across a fragmented workflow.
+
+## Case Study Claim Boundary
+
+### Claims This Study Can Support
+
+- The app can inspect a mounted project and construct useful shared project context.
+- The app can maintain a visible volume-level workflow state.
+- The assistant can answer project and workflow questions from inspected state.
+- The assistant can propose bounded app actions instead of giving generic instructions.
+- Costly or mutating actions can be approval-gated.
+- Users can edit agent-proposed action fields before approving.
+- The progress view and assistant can refer to the same canonical volume split.
+- Evidence export can capture workflow state and action provenance.
+
+### Claims This Study Should Not Make Alone
+
+- The trained model improves over TapeReader or PyTC baselines.
+- The system reduces total biological analysis time in all settings.
+- The proofreading editor is production-grade.
+- The app faithfully reproduces every detail of the original TapeReader paper pipeline.
+- The agent is autonomous or safe for unreviewed execution.
+
+## Participant
+
+Primary participant:
+
+- Yixiao, a domain expert connected to the TapeReader/CytoTape XRI workflow.
+
+Desired role in the study:
+
+- Treat Yixiao as the scientific owner of the dataset and target task.
+- Ask her to judge whether the app's inferred project context, status split, and proposed next actions match how she thinks about the workflow.
+- Do not ask her to debug implementation details unless the app visibly fails.
+
+## Study Setup
+
+Demo URL:
+
+```text
+https://demo.seg.bio
+```
+
+Project root:
+
+```text
+/home/weidf/demo_data/yixiao_tapereader_xri_case_study
+```
+
+Expected initial state:
+
+| Category                  | Expected Value                             |
+| ------------------------- | ------------------------------------------ |
+| Project                   | Yixiao TapeReader XRI Case Study           |
+| Modality                  | X-ray / XRI volumetric microscopy          |
+| Target                    | CytoTape fibres                            |
+| Voxel size                | 40 x 16.3 x 16.3 nm in z,y,x               |
+| Total tracked volumes     | 10                                         |
+| Fully good / ground truth | 6                                          |
+| Needs proofreading        | 2                                          |
+| No segmentation           | 2                                          |
+| Training policy           | Train only on confirmed ground-truth masks |
+
+Volume split:
+
+| State              | Volumes                            |
+| ------------------ | ---------------------------------- |
+| Ground truth       | `1`, `2`, `3`, `4_1`, `4_2`, `4_3` |
+| Needs proofreading | `5_1`, `5_2`                       |
+| Image only         | `6_1`, `6_2`                       |
+
+## Taxonomy Of Study Tasks
+
+### 1. Project Common Ground
+
+Goal:
+
+- Determine whether the app can inspect the project and summarize it in terms that match the domain expert's understanding.
+
+What Yixiao does:
+
+- Opens the demo.
+- Mounts or opens the suggested Yixiao project.
+- Reviews the setup/project context surfaced by the app.
+- Uses the assistant to ask what the project is.
+
+What we ask Yixiao:
+
+1. "Does this summary match what you think this dataset is?"
+2. "What is missing from this summary that you would want the agent to know before acting?"
+3. "Are any of these terms wrong or too software-centric?"
+4. "Would this setup screen help you get started, or would it still feel like a blank prompt?"
+
+Specific prompts to ask the in-app agent:
+
+```text
+What project are we looking at?
+```
+
+```text
+What are the files and volumes in this project?
+```
+
+```text
+What do you know about the voxel size and target structure?
+```
+
+Evidence to capture:
+
+- Screenshot of setup/project context.
+- Assistant response.
+- "What I checked" or operational trace content.
+- Any user correction to project context.
+
+Paper construct:
+
+- Shared context / common ground.
+- Initial interaction support.
+- Reduced blank-box onboarding.
+
+### 2. Volume State And Workflow Progress
+
+Goal:
+
+- Determine whether the volume-level progress view is understandable and useful.
+
+What Yixiao does:
+
+- Opens the Progress view.
+- Reviews the 10-volume status split.
+- Clicks/filter/sorts if useful.
+- Identifies whether `5_1`, `5_2`, `6_1`, and `6_2` are correctly characterized.
+
+What we ask Yixiao:
+
+1. "Do these volume statuses match your mental model of the project?"
+2. "What would you call these states in your own words?"
+3. "Which of these statuses would you trust for training?"
+4. "Are the counts enough, or do you need examples/thumbnails/quality indicators?"
+5. "Would you expect this screen to be the source of truth for the agent?"
+
+Specific prompts to ask the in-app agent:
+
+```text
+How many volumes are ready for training, and which ones should be left out?
+```
+
+```text
+Which volumes still need human attention?
+```
+
+```text
+What would be the safest next step in this project?
+```
+
+Evidence to capture:
+
+- Progress summary counts.
+- Volume table status rows.
+- Agent response about train-eligible and excluded volumes.
+- Any mismatch between progress view and agent response.
+
+Paper construct:
+
+- Workflow state legibility.
+- Human-agent shared reference.
+- Trust calibration around labels.
+
+### 3. Data Inspection / Visualization
+
+Goal:
+
+- Determine whether the app and assistant can move from project state into visual inspection.
+
+What Yixiao does:
+
+- Asks the agent to show sample data.
+- Clicks the resulting action card or uses Visualize.
+- Inspects a ground-truth pair.
+- Optionally asks to view another volume or a proofreading target.
+
+What we ask Yixiao:
+
+1. "Is this the right kind of visual context for deciding what to do next?"
+2. "Are the voxel scale and orientation believable?"
+3. "Does the viewer make clear which image and mask are currently open?"
+4. "Would you expect the agent to automatically choose this first example?"
+
+Specific prompts to ask the in-app agent:
+
+```text
+Can we look at one fully good example?
+```
+
+```text
+Can you open a draft mask that needs proofreading?
+```
+
+```text
+What am I looking at here?
+```
+
+Evidence to capture:
+
+- Neuroglancer URL.
+- Active image and label paths.
+- Agent explanation of why it chose the volume.
+- Any scale/orientation correction from Yixiao.
+
+Paper construct:
+
+- Mixed-initiative handoff from chat to visual tool.
+- Context-aware visualization action.
+- Progressive disclosure of inspected evidence.
+
+### 4. Proofreading Decision
+
+Goal:
+
+- Determine whether the system correctly distinguishes draft masks from training-ready ground truth.
+
+What Yixiao does:
+
+- Reviews the draft-mask volumes `5_1` and `5_2`.
+- Says whether those masks are actually draft, accepted, or unusable.
+- Optionally promotes one draft mask to training-ready if appropriate for the simulated run.
+
+What we ask Yixiao:
+
+1. "Would you call these masks draft segmentations, preliminary labels, or ground truth?"
+2. "What evidence would you need before promoting one to training?"
+3. "Would you trust the agent to promote a mask automatically?"
+4. "What should happen if you disagree with the agent's status?"
+
+Specific prompts to ask the in-app agent:
+
+```text
+Which masks should I proofread before training?
+```
+
+```text
+Should these draft masks be used for training yet?
+```
+
+```text
+If I mark 5_1 as good, how does that change the training set?
+```
+
+Evidence to capture:
+
+- Current status before promotion.
+- User's judgment.
+- Status change event if performed.
+- Training proposal count before and after promotion.
+
+Paper construct:
+
+- Human correction loop.
+- Label trust and training eligibility.
+- Approval-gated state mutation.
+
+### 5. Training Proposal
+
+Goal:
+
+- Determine whether the assistant can stage a multi-volume training job from trusted ground truth only.
+
+What Yixiao does:
+
+- Asks the agent to train a model using the trusted labels.
+- Reviews the proposed training card.
+- Checks selected image root, label root, config, output path, and excluded volumes.
+- Edits at least one auto-filled field if possible, or confirms that editing is discoverable.
+- Does not need to actually launch a long GPU job unless the facilitator decides to.
+
+What we ask Yixiao:
+
+1. "Does this training proposal include the right volumes?"
+2. "Is it clear why the draft and image-only volumes were excluded?"
+3. "Is the proposed config meaningful to you, or does it need a domain-readable explanation?"
+4. "Can you tell what will happen if you approve?"
+5. "Would you feel comfortable editing the proposed fields before approving?"
+
+Specific prompts to ask the in-app agent:
+
+```text
+Train a model using only the fully good ground-truth volumes.
+```
+
+```text
+Why did you leave out 5_1, 5_2, 6_1, and 6_2?
+```
+
+```text
+What exactly will this training run use and produce?
+```
+
+Evidence to capture:
+
+- Training action card.
+- Included/excluded volume counts.
+- Editable fields.
+- Approval gate.
+- Operational trace.
+- Generated subset manifest.
+
+Paper construct:
+
+- Bounded agentic action.
+- Approval-gated execution.
+- Trust-aware data selection.
+- Editable automation.
+
+### 6. Inference Planning
+
+Goal:
+
+- Determine whether the assistant can identify image-only targets and prepare downstream inference without leaking withheld labels.
+
+What Yixiao does:
+
+- Asks what should happen after training.
+- Asks how to segment the remaining image-only volumes.
+- Reviews that `6_1` and `6_2` are treated as inference targets, not training labels.
+
+What we ask Yixiao:
+
+1. "Does this match how you would use a trained model on the rest of the data?"
+2. "What outputs would you expect after inference?"
+3. "How should predictions be marked before and after proofreading?"
+4. "What would you want the app to do with low-confidence predictions?"
+
+Specific prompts to ask the in-app agent:
+
+```text
+After training, which volumes should we run inference on?
+```
+
+```text
+Do we have labels for 6_1 and 6_2?
+```
+
+```text
+What should happen to predictions before they become training data?
+```
+
+Evidence to capture:
+
+- Agent response naming `6_1` and `6_2`.
+- Confirmation that withheld labels are not used.
+- Proposed inference action, if available.
+- State distinction between prediction and accepted reference.
+
+Paper construct:
+
+- State-aware planning.
+- Leakage prevention.
+- Separation of predictions and ground truth.
+
+### 7. Evidence / Provenance Export
+
+Goal:
+
+- Determine whether the workflow can produce a useful record of what happened.
+
+What Yixiao does:
+
+- Asks what evidence has been captured.
+- Optionally exports a bundle.
+- Reviews whether the exported summary would help reconstruct the workflow.
+
+What we ask Yixiao:
+
+1. "Would this be enough for you or a collaborator to understand what was done?"
+2. "What else would you need in the provenance bundle?"
+3. "Which artifacts matter most for a paper figure or methods section?"
+4. "Should the evidence be more human-readable, machine-readable, or both?"
+
+Specific prompts to ask the in-app agent:
+
+```text
+What have we done so far in this workflow?
+```
+
+```text
+Can you summarize the evidence for this case-study session?
+```
+
+```text
+What would go into an export bundle?
+```
+
+Evidence to capture:
+
+- Export endpoint result.
+- Bundle path.
+- Included events/artifacts/runs/proposals.
+- Any missing provenance noted by Yixiao.
+
+Paper construct:
+
+- Reproducible workflow evidence.
+- Provenance ledger.
+- Paper-grade audit trail.
+
+### 8. Overall Reflection
+
+Goal:
+
+- Get qualitative feedback aligned with the paper's HCI claims.
+
+What we ask Yixiao:
+
+1. "Where did the app feel like it understood the project?"
+2. "Where did it feel brittle or generic?"
+3. "Which agent suggestions saved effort?"
+4. "Which suggestions would you not trust?"
+5. "What context did you still have to carry in your head?"
+6. "What would make this useful in a real lab workflow?"
+7. "Would you prefer this over a manual-only PyTC/Neuroglancer workflow for this task? Why or why not?"
+8. "If you handed this project to someone else, would this progress/evidence state help them pick up the work?"
+
+Paper construct:
+
+- Perceived usefulness.
+- Trust calibration.
+- Workflow handoff.
+- Common ground.
+- Remaining design gaps.
+
+## Suggested One-Hour Schedule
+
+| Time      | Segment             | Activity                                                                                |
+| --------- | ------------------- | --------------------------------------------------------------------------------------- |
+| 0-5 min   | Intro               | Explain that this is a workflow-coordination prototype, not a model-accuracy benchmark. |
+| 5-12 min  | Project setup       | Open/mount Yixiao project and review inferred context.                                  |
+| 12-20 min | Progress state      | Inspect 10-volume status split and discuss training eligibility.                        |
+| 20-30 min | Visualization       | Open one ground-truth pair and one draft/proofreading target.                           |
+| 30-38 min | Proofreading status | Discuss or simulate promoting a draft mask.                                             |
+| 38-48 min | Training proposal   | Ask the agent to stage training from trusted ground truth; review/edit proposal.        |
+| 48-53 min | Inference planning  | Ask what happens to image-only targets after training.                                  |
+| 53-57 min | Evidence export     | Export or inspect session provenance.                                                   |
+| 57-60 min | Reflection          | Ask final study questions.                                                              |
+
+## Facilitator Checklist
+
+Before Yixiao arrives:
+
+- Run `scripts/manage_demo_instance.py status`.
+- Run `scripts/run_yixiao_case_study_smoke.py --prepare-live`.
+- Run `scripts/inspect_demo_instance.py`.
+- Confirm `https://demo.seg.bio` loads.
+- Confirm current workflow is Yixiao with 10 volumes and 6/2/2 split.
+- Confirm Neuroglancer URL starts with `https://demo.seg.bio/neuroglancer`.
+- Keep terminal open with logs available.
+
+During the study:
+
+- Do not over-explain how the app is supposed to work before Yixiao reacts.
+- Ask her to think aloud.
+- When the agent gives a proposal, ask her what she thinks will happen before clicking.
+- If a response is wrong, ask what she expected and record the mismatch.
+- Avoid running long GPU jobs unless the study goal explicitly includes runtime behavior.
+
+After the study:
+
+- Export evidence bundle.
+- Save screenshots of progress, proposal card, and any important agent responses.
+- Reset the case-study workflow to the initial 6/2/2 state.
+- Add notes to the progress log.
+
+## Success Criteria
+
+The case study is successful if it produces evidence for at least these points:
+
+1. Yixiao can understand the app's inferred project context and correct it where needed.
+2. The 10-volume progress split is legible and scientifically meaningful.
+3. The assistant can correctly answer project, progress, visualization, training, and inference questions from workflow state.
+4. The training proposal excludes draft and image-only volumes.
+5. The user can inspect and edit an action proposal before approval.
+6. The system captures an evidence trail for the session.
+7. The study identifies concrete gaps for the next prototype iteration.
+
+## Failure Modes To Watch
+
+- Agent answers from stale context after progress changes.
+- Agent treats draft masks as ground truth.
+- Agent proposes training on image-only targets.
+- Action card fields are clipped or hard to edit.
+- Neuroglancer URL uses local or insecure paths.
+- Progress view and agent response disagree.
+- User cannot tell what approving an action will do.
+- Evidence export is too low-level for paper use.
diff --git a/docs/case-study-prototype-readiness.md b/docs/case-study-prototype-readiness.md
new file mode 100644
index 00000000..9e11f659
--- /dev/null
+++ b/docs/case-study-prototype-readiness.md
@@ -0,0 +1,90 @@
+# Case-Study Prototype Readiness Protocol
+
+This protocol defines the researcher/facilitator evidence needed before using
+the prototype in paper-facing case studies. These gates are not participant UI.
+The participant-facing target remains an agent-mediated, closed-loop biomedical
+segmentation workflow, not a standalone PyTC GUI and not a case-study protocol
+manager.
+
+## Prototype Boundary
+
+- Do not expose case-study design, case-study readiness gates, or case-study
+  plan generation in the participant prototype.
+- Keep researcher-only checks available through backend tests, backend routes,
+  exported bundles, and this protocol document.
+- Participant-facing controls should stay biomedical-workflow focused: load
+  data, run inference, inspect hotspots, proofread, approve/reject risky agent
+  actions, retrain, compare outputs, and export evidence.
+- If a facilitator UI is added later, label it separately as researcher/study
+  instrumentation rather than part of the biomedical user workflow.
+
+## User Workflow Loop
+
+1. Create or resume a workflow project.
+2. Load image, label, mask, checkpoint, and configuration artifacts.
+3. Run or load baseline inference.
+4. Inspect results with workflow-aware agent guidance.
+5. Review ranked failure hotspots.
+6. Proofread selected masks and save corrections.
+7. Export a `CorrectionSet`.
+8. Preview correction impact and retraining readiness.
+9. Review an agent-proposed next action.
+10. Approve, reject, interrupt, or resume risky workflow actions.
+11. Run retraining from the staged corrections.
+12. Register the resulting `ModelVersion`.
+13. Re-run inference with the new checkpoint.
+14. Compare before/after outputs and metrics.
+15. Export the evidence bundle for analysis and paper figures.
+
+## Case Studies
+
+| ID  | Purpose                       | Participant Task                                                                | Required Prototype Gate                                                      |
+| --- | ----------------------------- | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| CS1 | Workflow continuity           | Load data, create viewer, run or inspect inference, proofread, inspect timeline | Workflow context, data artifacts, baseline inference                         |
+| CS2 | Agent-guided triage           | Ask where to inspect, review hotspot ranking, correct a selected region         | Persisted hotspots, workflow-grounded agent response                         |
+| CS3 | Correction-to-retraining loop | Export corrections, preview impact, approve retraining, produce checkpoint      | `CorrectionSet`, training `ModelRun`, `ModelVersion`                         |
+| CS4 | Before/after evidence         | Compare baseline and post-retraining inference                                  | Two inference runs plus `EvaluationResult`                                   |
+| CS5 | Approval-gated control        | Review, approve, reject, and inspect agent proposals                            | Proposal events, approval/rejection events                                   |
+| CS6 | Failure recovery              | Recover from failed training, bad config, or interrupted run                    | Terminal failure events, interrupted/resumed agent plan, visible next action |
+| CS7 | Study export                  | Export state, artifacts, metrics, events, screenshots, and task timing          | Evidence bundle with typed records                                           |
+
+## Instrumentation Checklist
+
+- Capture every task transition as a `WorkflowEvent`.
+- Materialize image, mask, correction, checkpoint, prediction, and report paths as
+  `WorkflowArtifact` records.
+- Record inference and training lifecycle as `WorkflowModelRun` records.
+- Register candidate checkpoints as `WorkflowModelVersion` records.
+- Store before/after metrics as `WorkflowEvaluationResult` records.
+- Store bounded plan previews and approval/interruption state as
+  `WorkflowAgentPlan` and `WorkflowAgentStep` records for researcher-only
+  protocol verification, not participant-facing app controls.
+- Export event logs, typed artifacts, run/version records, correction sets,
+  evaluation results, agent plans, and artifact-existence checks in the workflow
+  bundle.
+- Use `/api/workflows/{workflow_id}/case-study-readiness` before each session.
+
+## UI Consistency Checklist
+
+- Every stage page starts with the same `StageHeader` anatomy.
+- The workflow rail uses the same stage names as the paper: setup,
+  visualization, inference, proofreading, retraining staged, evaluation.
+- Agent proposals always display title, proposal type, approval state, rationale,
+  artifact references, and approve/reject controls.
+- Repeated functions keep consistent labels: `Approve`, `Reject`, `Refresh
+Insights`, `Start Training`, `Run Model`, `Open Proofreading`.
+- Status colors are semantic, not decorative: amber for review/staging, green for
+  completed/model-ready, red for failure/high risk, blue/teal for inspection.
+- Keyboard focus and accessible names must remain consistent across repeated
+  controls.
+- Case-study readiness and protocol-plan previews are intentionally absent from
+  the participant prototype.
+
+## Pre-Session Exit Criteria
+
+- The readiness endpoint has no missing P0 gates for the selected study.
+- The facilitator can complete the full scripted loop on the frozen sample data.
+- The evidence bundle includes typed artifacts, events, model runs, model
+  versions, correction sets, evaluation records, and agent plan records.
+- Screenshots for the paper can be regenerated from the scripted walkthrough.
+- The paper wording matches the demonstrated prototype behavior.
diff --git a/docs/closed-loop-smoke.md b/docs/closed-loop-smoke.md
new file mode 100644
index 00000000..d228dd38
--- /dev/null
+++ b/docs/closed-loop-smoke.md
@@ -0,0 +1,89 @@
+# Closed-Loop Workflow Smoke
+
+Run this when you want a quick researcher/developer check that the workflow evidence substrate still works:
+
+```bash
+uv run python scripts/run_closed_loop_smoke.py --output-dir /tmp/pytc-closed-loop-smoke
+```
+
+To run against the mito25 real image/segmentation pair without loading the full volume:
+
+```bash
+uv run python scripts/run_closed_loop_smoke.py \
+  --output-dir /tmp/pytc-mito25-smoke \
+  --image-path /Users/adamg/seg.bio/pytc-client/testing_projects/mito25_paper_loop_smoke/data/image/mito25_smoke_13312-15360_im.h5 \
+  --mask-path /Users/adamg/seg.bio/pytc-client/testing_projects/mito25_paper_loop_smoke/data/seg/mito25_smoke_13312-15360_seg.h5 \
+  --image-dataset main \
+  --mask-dataset data
+```
+
+If real prediction files exist, pass them directly instead of deriving
+baseline/candidate masks from the segmentation:
+
+```bash
+uv run python scripts/run_closed_loop_smoke.py \
+  --output-dir /tmp/pytc-real-prediction-smoke \
+  --image-path /path/to/image.h5 \
+  --mask-path /path/to/initial-or-ground-truth-mask.h5 \
+  --image-dataset main \
+  --mask-dataset data \
+  --baseline-prediction-path /path/to/baseline-prediction.h5 \
+  --candidate-prediction-path /path/to/candidate-prediction.h5 \
+  --baseline-dataset prediction \
+  --candidate-dataset prediction \
+  --crop 0:16,0:256,768:1024
+```
+
+For PyTC outputs such as `result_xy.h5`, pass the HDF5 dataset and select the
+prediction channel to compare:
+
+```bash
+uv run python scripts/run_closed_loop_smoke.py \
+  --output-dir /tmp/pytc-app-prediction-smoke \
+  --image-path /Users/adamg/seg.bio/pytc-client/testing_projects/mito25_paper_loop_smoke/data/image/mito25_smoke_13312-15360_im.h5 \
+  --mask-path /Users/adamg/seg.bio/pytc-client/testing_projects/mito25_paper_loop_smoke/data/seg/mito25_smoke_13312-15360_seg.h5 \
+  --image-dataset main \
+  --mask-dataset data \
+  --baseline-prediction-path /Users/adamg/seg.bio/pytc-client/testing_projects/mito25_paper_loop_smoke/predictions/baseline_result_xy.h5 \
+  --candidate-prediction-path /Users/adamg/seg.bio/pytc-client/testing_projects/mito25_paper_loop_smoke/predictions/candidate_result_xy.h5 \
+  --baseline-dataset vol0 \
+  --candidate-dataset vol0 \
+  --baseline-channel 0 \
+  --candidate-channel 0
+```
+
+For manual UI checks, use File Management -> `Mount Test Project`. The suggested
+project card should report detected image, label, prediction, config, and
+checkpoint roles before mounting.
+
+The smoke creates or stages voxel artifacts, drives the FastAPI workflow API through dataset loading, baseline inference capture, proofreading correction capture, correction staging, retraining completion capture, candidate inference capture, before/after evaluation, researcher-only readiness gates, and bundle export.
+
+What this proves:
+
+- Workflow events materialize typed artifacts, model runs, model versions, correction sets, evaluation results, hotspots, and bundle records.
+- Correction-set records include edit and region counts derived from the
+  proofreading event stream when corrections are exported.
+- Evidence bundle exports are recorded as `workflow.bundle_exported` audit
+  events.
+- The before/after evaluation path computes real segmentation metrics over TIFF, HDF5, NumPy, Zarr/N5, and common 2D image files, with optional NIfTI/MRC support if their parser packages are installed.
+- The researcher-only readiness/export path can produce an evidence bundle for planning a case-study walkthrough.
+- In `real_pair_real_predictions` mode, supplied prediction artifacts are used for the metric comparison.
+- PyTC channel-first/channel-last prediction outputs can be reduced to 3D voxel volumes with `--baseline-channel` and `--candidate-channel`.
+
+What this does not prove yet:
+
+- Real PyTC training subprocess execution.
+- Real PyTC inference subprocess execution.
+- Browser-level proofreading interaction inside EHTool.
+- Real biomedical or connectomics sample-data performance in synthetic mode.
+- Real model predictions in `real_pair_derived_predictions` mode; baseline/candidate masks are derived from the provided segmentation unless prediction paths are supplied.
+- Fresh PyTC subprocess launch quality; app-generated prediction files can now be captured into workflow evidence, but launching/recovering long-running jobs still needs hardening.
+- Long-running job queue behavior, retries, cancellation, or recovery.
+
+Outputs:
+
+- `smoke-report.json`: concise pass/fail summary and explicit simulated gaps.
+- `workflow-bundle.json`: exported workflow evidence bundle.
+- `readiness.json`: researcher-only readiness gate state.
+- `evaluation-report.json`: before/after metric report.
+- `artifacts/`: synthetic TIFFs, placeholder checkpoint, and training-output directory.
diff --git a/docs/codex-working-memory/README.md b/docs/codex-working-memory/README.md
new file mode 100644
index 00000000..f4b058ce
--- /dev/null
+++ b/docs/codex-working-memory/README.md
@@ -0,0 +1,17 @@
+# Codex Working Memory
+
+This directory vendors the local long-term notes from the main Codex session so
+remote Codex instances can pick up the same project context.
+
+Start here:
+
+1. `../remote-codex-handoff.md` for the short operational handoff.
+2. `research-log.md` for the detailed implementation/research chronology.
+3. `backlog.md` for unresolved prototype work.
+4. `progress-log.md` for earlier checkpoint history.
+5. `workflow-spine-spec.md` for the intended closed-loop workflow structure.
+6. `tochi-writing-synthesis.md` for paper-framing notes.
+
+These files are intentionally imperfect working notes. Treat them as context,
+not polished documentation. If remote work changes direction, update these notes
+or append a new dated section rather than relying only on chat history.
diff --git a/docs/codex-working-memory/backlog.md b/docs/codex-working-memory/backlog.md
new file mode 100644
index 00000000..0661a427
--- /dev/null
+++ b/docs/codex-working-memory/backlog.md
@@ -0,0 +1,83 @@
+# PyTC Client Backlog
+
+Local backlog for ideas, follow-ups, and possible improvements discovered while working on `pytc-client`.
+
+## Candidate Items
+
+- Keep this list lightweight: add items here when they are useful but not part of the current task.
+- Set up project and model config for the Yixiao case study. Initial case-study
+  project is now assembled at
+  `/home/weidf/demo_data/yixiao_tapereader_xri_case_study`; remaining work is
+  validating an exact barcode-branch PyTC runtime or explicitly using the
+  app-compatible fallback config for workflow-only demonstrations.
+- Formalize the progress tracking implementation.
+
+## Deep Research Synthesis Backlog - 2026-05-24
+
+### Highest Priority
+
+- Make workflow-agent intent contracts single-source: prompt-listed intents, validation allowlists, handlers, and tests should be generated from one typed registry.
+- Replace fragmented agent actions/client effects/durable commands/runtime actions with one `ActionExecution` envelope and state machine.
+- Stop treating chat/session storage as project memory. Hydrate the big workflow chat and mounted project state from server workflow records, with browser storage only as a display cache.
+- Promote project context into structured project memory: project facts, artifact index, per-volume state, run history, and evidence events.
+- Make multi-volume training sets a real artifact with PyTC-compatible representation and dry-run loader validation before launch.
+
+### Product / HCI Direction
+
+- Keep visible assistant messages conversational and short; put mechanics in expandable "What I checked" traces.
+- Replace blank project-context intake with inspect-first onboarding that asks concrete follow-up questions only when auto-detected facts are missing or ambiguous.
+- Treat Progress as the main project control surface: row actions for view, proofread, mark ground truth, infer missing, ignore, and train on selected.
+- Add task-family presets for semantic mitochondria, instance mitochondria, neuron affinity, synaptic clefts, and nuclei workflows so the UI does not flatten distinct PyTC pipelines into generic "segmentation."
+- Plan region-level and `valid_mask` support so partially proofread areas can become training-ready without marking a whole volume as complete.
+
+### Paper / Study Support
+
+- Frame the system around workflow coordination and handoff support, not segmentation-model novelty.
+- Add evidence export for project facts, status transitions, proposals, approvals, run configs, logs, metrics, and artifacts.
+- Avoid claims about accuracy/workload/generalization until backed by study evidence.
+
+## Codebase Audit Backlog - 2026-04-13
+
+### Highest Priority
+
+- Extend the Workflow Spine from "stage retraining" to an actual retraining run artifact: launch, checkpoint produced, model version created, and evaluation-ready output.
+- Add an evaluation stage that can compare pre/post-retraining masks or metrics and close the iteration loop.
+- Expand agent proposal allowlist beyond `stage_retraining_from_corrections`, while keeping explicit approval for every mutating action.
+
+### Product/Research Prototype
+
+- Explore CAVE integration for connectomics workflows: https://pmc.ncbi.nlm.nih.gov/articles/PMC10402030/
+- Add a "model failure regions" surface that can rank or surface uncertain/high-error regions for expert review.
+- Add explicit model/version/result management so training and inference runs become inspectable artifacts rather than transient process logs.
+- Make Project Manager data real enough for study use: replace static seed/mock values with imported datasets/tasks, durable storage, and role-aware server authorization.
+- Extend project setup beyond one active role set: backend profiling now detects role directories and volume sets, and the UI can confirm folder-level image/label roles. Remaining work is an active-set selector, batch actions across multiple confirmed sets, and agent-safe provenance for multi-set runs.
+- Improve project-context extraction after setup: the confirmation modal now captures freeform biological context before mapping correction and stores lightweight inferred metadata. Name/path regexes no longer infer biological context; backend content spot checks now provide conservative `context_hints`. Remaining work is a stronger parser/LLM extraction pass for uncommon modalities/structures and a clear way to inspect/edit saved project memory later.
+- Surface hidden project-memory persistence failures better: `.pytc_project_context.json` is now written best-effort, but read-only project directories should produce a clear nonblocking warning and maybe a fallback app-managed memory location.
+- Decide whether durable evidence bundles should copy large image/mask/checkpoint files or keep the safer default of path manifests plus small copied artifacts.
+- Add study/export support for interaction logs and workflow efficiency metrics.
+- Add region-level workflow state: selected slice/range, bounding box, active instance, and proofreader attention targets.
+- Add an action-log export format for paper evaluation: CSV/JSON with actor, stage, event type, payload, approval status, and timestamps.
+
+### Cleanup/Fixes
+
+- Remove or gate verbose `console.log`/`print` debug logging in API, training, inference, visualization, and EHTool paths.
+- Replace hardcoded Project Manager demo credentials and frontend-displayed passwords with a proper local auth flow or clearly labeled demo mode.
+- Replace the File Manager preview modal placeholders with the existing `/files/preview/{id}` endpoint and useful text preview support.
+- Address React build warnings: hook dependencies, unused imports/state, unsafe loop closures, and accessibility issues.
+- Add route/API contract tests for Project Manager and EHTool endpoints.
+- Move tracked runtime logs out of Git or stop mutating tracked `.logs/start/*.log` files.
+- Normalize JSON formatting/newline handling for `server_api/data_store/project_manager_data.json` to reduce noisy diffs.
+- Add package/test config for local modules instead of relying on command-specific import behavior.
+- Replace ad hoc SQLite schema patching with Alembic or an explicit local migration path before any multi-user deployment.
+- Reduce direct component knowledge of workflow side effects; over time, workflow events should be emitted from narrow service/API helpers rather than scattered UI code.
+- Add a controlled `start_visualization` runtime action so an approved agent
+  command can open Neuroglancer directly after setting image/label paths. Current
+  behavior only populates the viewer inputs and navigates to Visualize.
+- Consider replacing hand-rolled agent intent rules with a small typed intent
+  parser once more workflow actions accumulate. The current rule set is tested,
+  but every new biomedical phrasing increases maintenance burden.
+- Resolve folder-level active role paths before launching visualization or
+  proofreading. Current project setup can correctly register directories such as
+  `Image/train` and `Label/train`, but Neuroglancer and EHTool need a selected
+  volume file or a supported folder reader. The agent should ask which volume
+  pair to open, or auto-pick a small representative pair with approval.
diff --git a/docs/codex-working-memory/implementation-report-2026-06-04.md b/docs/codex-working-memory/implementation-report-2026-06-04.md
new file mode 100644
index 00000000..0acd77a6
--- /dev/null
+++ b/docs/codex-working-memory/implementation-report-2026-06-04.md
@@ -0,0 +1,607 @@
+# seg.bio Prototype Implementation Report - 2026-06-04
+
+## Summary
+
+This report records the major implementation work completed on the `checkpoint/tochi-agentic-prototype` branch for the seg.bio / PyTC Client prototype. The work moved the app from a mostly tab-and-chat prototype toward a workflow-aware, approval-gated project operator for biomedical volume segmentation case studies.
+
+The main throughline was:
+
+1. Make mounted projects inspectable and understandable to the app.
+2. Make project progress visible as workflow state, not hidden chat context.
+3. Let the agent propose bounded workflow actions with editable fields and approval gates.
+4. Keep chat human-readable while exposing operational traces separately.
+5. Build a Yixiao TapeReader/XRI case-study fixture and smoke-test path.
+6. Add enough runtime logging and operator diagnostics to support demo deployment.
+7. Preserve paper-facing research, provenance, and implementation context in markdown.
+
+The current deployed branch head is:
+
+```text
+a047f34 docs(research): capture paper prototype roadmap
+```
+
+Remote branch:
+
+```text
+origin/checkpoint/tochi-agentic-prototype
+```
+
+## Recent Commit Split
+
+The latest pushed split was:
+
+```text
+d706244 feat(workflows): harden project memory and provenance
+302a373 feat(auth): add project user management foundations
+e24c205 feat(ui): surface workflow agents and editable action cards
+e364ffb test(demo): add Yixiao case study gates
+a047f34 docs(research): capture paper prototype roadmap
+```
+
+These were pushed after earlier commits on the same branch:
+
+```text
+eb5cce6 feat(projects): confirm mounted project context
+1b80965 feat(workflows): add progress-aware agent commands
+c1f3d7a feat(assistant): keep workflow chat continuous
+143d127 feat(viewer): harden visualization and proofreading
+4ea4bb1 fix(runtime): launch multi-volume training subsets
+3292ff7 chore(logging): capture detailed app events
+c151bf9 docs: record agent prototype progress
+```
+
+## Project Context And Onboarding
+
+The mounted-project flow was changed from a blank text box into a guided, inspection-led intake.
+
+What changed:
+
+- Added mounted project context confirmation and project observation logic.
+- Added a compact shared project facts panel in the setup modal.
+- Propagated project facts such as modality, target structure, task family, voxel size, training policy, volume split, and image-only strategy into workflow metadata.
+- Removed brittle assumptions like hard-coded default image scales where possible and moved toward project-derived voxel sizes.
+- Added project suggestion handling so the demo can mount the intended Yixiao case-study project instead of a stale/default project.
+
+Why it matters:
+
+- Biologists should not need to know what facts the agent needs up front.
+- The app should inspect first, then ask concrete follow-up questions.
+- The agent needs canonical project context instead of relying on chat memory.
+
+Key files:
+
+- `client/src/views/FilesManager.js`
+- `client/src/utils/projectSuggestions.js`
+- `server_api/workflows/router.py`
+- `server_api/workflows/service.py`
+
+## Project Progress And Workflow State
+
+The progress surface was rebuilt into a workflow reference point for both users and the agent.
+
+What changed:
+
+- Added per-volume progress states:
+  - `ground_truth`
+  - `needs_proofreading`
+  - `missing_segmentation`
+  - `ignored`
+- Added canonical-ish derived state fields such as annotation state, role state, and execution state in progress snapshots.
+- Added progress summaries for total tracked volumes, fully good/reference volumes, proofreading targets, missing segmentation targets, completion percentage, and segmentation coverage.
+- Added volume-level status update routes and UI controls.
+- Made the agent read and use project progress when proposing training, proofreading, and inference actions.
+
+Why it matters:
+
+- The progress tab is not just a dashboard; it is shared memory for the workflow.
+- Training eligibility now depends on trusted volume status instead of mask file existence alone.
+- The user and the agent can refer to the same volume-level state.
+
+Key files:
+
+- `client/src/views/ProjectProgress.js`
+- `server_api/workflows/router.py`
+- `server_api/workflows/db_models.py`
+- `tests/test_workflow_routes.py`
+- `tests/test_workflow_case_study_acceptance.py`
+
+## Agentic Workflow Implementation
+
+The agent was reshaped away from generic chat and toward a workflow operator that can propose bounded routines.
+
+What changed:
+
+- Added agent action proposal cards.
+- Added approval/reject flow for costly or mutating actions.
+- Added editable action fields before approval, so users can correct auto-filled paths and parameters.
+- Added specialist-agent visual encoding with icons and color accents.
+- Added operational traces to cards and timeline entries.
+- Added continuous main workflow chat instead of fragmented chat history.
+- Added APIs for fetching workflow agent conversation.
+- Added route behavior for project, visualization, proofreading, training, and progress intents.
+- Improved natural-language handling for casual requests like "train on my good data" or "what are we looking at?"
+
+Why it matters:
+
+- The agent can propose real app routines without silently executing risky work.
+- The user can correct fields before launch rather than having only Approve/Reject.
+- The chat can sound normal while the mechanics remain inspectable in a trace.
+
+Key files:
+
+- `client/src/components/Chatbot.js`
+- `client/src/components/chat/AgentProposalCard.js`
+- `client/src/components/chat/AssistantActionCard.js`
+- `client/src/components/chat/AssistantTrace.js`
+- `client/src/components/chat/AgentVisuals.js`
+- `client/src/contexts/WorkflowContext.js`
+- `client/src/contexts/workflow/proposalCardConfig.js`
+- `server_api/workflows/router.py`
+
+## Operational Traces
+
+The app now exposes workflow traces without dumping robotic reasoning into the main answer.
+
+Trace sections include:
+
+- Inspected facts.
+- Policy decision.
+- Approval or execution status.
+- Affected artifacts.
+- Project-memory updates.
+
+Trace data can be parsed from:
+
+- `trace`
+- `params.trace`
+- `payload.trace`
+- `action_card.trace`
+- `payload_json`
+
+Why it matters:
+
+- This supports the paper framing around progressive disclosure.
+- It makes agent behavior auditable without showing raw hidden reasoning.
+- It makes the system feel more like a workflow harness than a plain chatbot.
+
+## Multi-Volume Training
+
+Training flow was changed to support clean multi-volume subsets.
+
+What changed:
+
+- The agent can stage a training run from all currently trusted ground-truth volumes.
+- Draft masks and image-only volumes are excluded by policy.
+- The system writes staged subset directories/manifests for training.
+- Training action cards show selected config, images, labels, output path, training set count, left-out volumes, and parameters.
+- Approval can populate the Train Model UI with staged paths.
+- Runtime config sanitization handles staged PyTC configs.
+
+Why it matters:
+
+- Case-study training should use all eligible reference volumes, not one currently selected image.
+- The paper needs the agent to coordinate stateful training selection from progress/memory.
+
+Key files:
+
+- `server_api/workflows/router.py`
+- `server_api/workflows/service.py`
+- `client/src/views/ModelTraining.js`
+- `tests/test_workflow_routes.py`
+- `tests/test_pytc_runtime_routes.py`
+
+## Visualization And Neuroglancer
+
+Visualization was hardened for agent-populated actions and demo deployment.
+
+What changed:
+
+- Fixed mixed-content and public Neuroglancer URL handling for `demo.seg.bio`.
+- Added runtime config for Neuroglancer bind port and public base.
+- Improved viewer URL generation so public URLs use `https://demo.seg.bio/neuroglancer/...`.
+- Added volume pair discovery and viewer metadata into workflow state.
+- Added smoke tests that verify viewer URL generation and pair discovery.
+- Added operator diagnostics to verify Neuroglancer port reachability and URL prefix.
+
+Why it matters:
+
+- The agent-triggered "Run in app" viewer path had been failing differently from manual usage.
+- Demo deployment needs public URLs, not local/insecure iframe URLs.
+
+Key files:
+
+- `server_api/main.py`
+- `server_api/workflows/volume_pairs.py`
+- `scripts/inspect_demo_instance.py`
+- `scripts/run_yixiao_case_study_smoke.py`
+
+## Proofreading
+
+The proofreading view and path handling were audited and hardened.
+
+What changed:
+
+- Added helper utilities for proofreading image/mask paths.
+- Added tests around proofreading path behavior.
+- Kept proofreading as a workflow stage that can be proposed by the agent.
+- Added progress integration so draft masks can be treated as proofreading targets rather than trusted ground truth.
+- Added UI and docs around using proofread edits for training.
+
+Why it matters:
+
+- The case-study story depends on moving from draft segmentations to accepted training references.
+- Draft masks must not silently enter the training set.
+
+Key files:
+
+- `client/src/views/ehtool/proofreadingPaths.js`
+- `client/src/views/ehtool/DatasetLoader.js`
+- `client/src/views/ehtool/DetectionWorkflow.js`
+- `server_api/workflows/router.py`
+
+## Runtime Logging And Demo Operations
+
+Logging and operator diagnostics were expanded substantially.
+
+What changed:
+
+- Added detailed app event logging.
+- Added runtime startup config event with API host/port, worker URL, Neuroglancer port, and public Neuroglancer base.
+- Added worker proxy logging for PyTC worker requests.
+- Added `scripts/manage_demo_instance.py` to start/stop/restart/status the demo API process.
+- Added `scripts/inspect_demo_instance.py` to inspect:
+  - API health.
+  - app log path.
+  - runtime config.
+  - worker reachability.
+  - `/training_status`.
+  - worker proxy target.
+  - current workflow.
+  - Neuroglancer port and public URL.
+  - recent app error events.
+  - app log and workflow bundle disk usage.
+- Fixed a false runtime-config warning by making the inspector scan enough app log history.
+- Added the missing `neuroglancer_public_base` field to startup runtime logging.
+
+Why it matters:
+
+- When the demo fails, we need to see whether it is the API, PyTC worker, Neuroglancer, Ollama, or workflow state.
+- The operator scripts make the deployed instance auditable by future agents.
+
+Key files:
+
+- `scripts/manage_demo_instance.py`
+- `scripts/inspect_demo_instance.py`
+- `server_api/main.py`
+- `tests/test_manage_demo_instance.py`
+- `tests/test_inspect_demo_instance.py`
+
+## Evidence And Provenance Export
+
+Evidence export was expanded into a more paper-appropriate provenance layer.
+
+What changed:
+
+- Added richer workflow bundle export metadata.
+- Added artifact path metadata and copy-policy handling.
+- Added structured evidence export sections:
+  - project memory summary.
+  - model context.
+  - agent proposal to approval links.
+  - proposal/approval/action/run/progress graph.
+  - user status changes.
+  - command and run lineage.
+  - withheld reference handling.
+- Added documentation for evidence export structure.
+
+Why it matters:
+
+- The strongest TOCHI-style systems contribution is not just "the agent answered"; it is that every meaningful workflow action leaves a reproducible trail.
+- Paper figures and case studies need exportable evidence of what was used and what changed.
+
+Key files:
+
+- `server_api/workflows/bundle_export.py`
+- `server_api/workflows/evidence_export.py`
+- `docs/research/workflow-evidence-export.md`
+- `tests/test_workflow_export_bundle.py`
+- `tests/test_workflow_evidence_export.py`
+
+## User Management Foundations
+
+A foundation for user/project management was added.
+
+What changed:
+
+- Expanded backend auth models and routes.
+- Added more substantial user/session/project-management surfaces in the backend.
+
+Why it matters:
+
+- Production use will need ownership, project mounting state, permissions, and audit attribution.
+- The evidence ledger needs actor identity over time.
+
+Key files:
+
+- `server_api/auth/models.py`
+- `server_api/auth/router.py`
+
+## Yixiao TapeReader/XRI Case Study
+
+A case-study fixture was assembled around the Yixiao TapeReader/XRI dataset.
+
+What changed:
+
+- Located and prepared the XRI project currently relevant to the demo.
+- Added project context for the TapeReader / CytoTape workflow.
+- Added manifest-driven status split:
+  - 10 tracked volumes.
+  - 6 confirmed ground-truth volumes.
+  - 2 draft masks needing proofreading.
+  - 2 image-only inference targets.
+- Added app-compatible PyTC config path:
+  - `configs/TapeReader-Fiber-BCS-AppCompat-Sanity.yaml`
+- Added smoke tests that mount the project, inspect context, stage workflow state, verify progress, open viewer metadata, query the agent, stage training, validate training subsets, and test export sanity.
+- Added manual demo guide.
+
+Why it matters:
+
+- This is the first concrete case study path for the paper prototype.
+- It exercises the actual mixed workflow: inspect, visualize, understand progress, stage training, avoid untrusted labels, and prepare downstream inference/proofreading.
+
+Key files:
+
+- `scripts/run_yixiao_case_study_smoke.py`
+- `tests/test_yixiao_pre_demo_smoke.py`
+- `docs/manual-yixiao-case-study-demo.md`
+
+## Browser And Smoke Testing
+
+The smoke testing system was expanded beyond unit tests.
+
+What changed:
+
+- Added deterministic Yixiao case-study gate.
+- Added browser smoke harness with Playwright detection.
+- Added tests for the browser smoke script itself.
+- Added checks for proposal card editability.
+- Added pre-demo gate modes:
+  - normal smoke.
+  - promotion roundtrip.
+  - restore state.
+  - readiness check.
+  - export sanity.
+
+Why it matters:
+
+- The app is now complex enough that endpoint tests alone are not sufficient.
+- Case-study readiness depends on complete flows, not isolated functions.
+
+Key files:
+
+- `scripts/browser_yixiao_case_study_smoke.py`
+- `scripts/run_yixiao_case_study_smoke.py`
+- `tests/test_browser_yixiao_case_study_smoke.py`
+- `tests/test_yixiao_pre_demo_smoke.py`
+
+## Research And Paper Planning
+
+Several internal research and planning reports were added.
+
+Important docs include:
+
+- `docs/codex-working-memory/paper-readiness-production-plan.md`
+- `docs/codex-working-memory/third-finish-line-lit-and-task-taxonomy.md`
+- `docs/codex-working-memory/yixiao-finish-line-task-taxonomy.md`
+- `docs/research/agentic-workflow-formalization-report.md`
+- `docs/research/internal-technical-audit-2026-05-24.md`
+- `docs/research/deep-research-engineering-synthesis-2026-05-24.md`
+- `docs/research/deep-research-agentic-workflow-formalization-2026-05-27.md`
+- `docs/research/deep-research-agentic-bioimage-segmentation.md`
+
+Core paper-facing framing:
+
+- This should be presented as a mixed-initiative workflow agent for iterative biomedical volume segmentation.
+- The central contribution is workflow coordination, not a new segmentation model.
+- The strongest system abstractions are:
+  - canonical project memory.
+  - composite volume state.
+  - typed action proposals.
+  - risk-graded approval.
+  - bounded execution.
+  - evidence/provenance ledger.
+  - progressive disclosure of operational traces.
+
+## Literature-Informed Design Direction
+
+The latest heuristic pass incorporated recent HCI/VIS/agent work around common ground, agentic visualization, feedback, and collaboration limits.
+
+The resulting design takeaways were:
+
+- Build explicit common ground between user and agent.
+- Do not make chat history the source of truth.
+- Make the current workflow state visible and queryable.
+- Use action cards for consequential actions.
+- Keep user-facing language conversational and short.
+- Put mechanical details in expandable traces.
+- Treat user corrections as durable project-memory events.
+- Make provenance export part of the workflow, not an afterthought.
+
+## Verification Completed
+
+The following verification was run after the third finish-line implementation pass:
+
+```text
+.venv/bin/python -m py_compile scripts/browser_yixiao_case_study_smoke.py scripts/manage_demo_instance.py scripts/inspect_demo_instance.py server_api/workflows/bundle_export.py server_api/workflows/evidence_export.py server_api/workflows/router.py server_api/workflows/service.py
+```
+
+Backend/test slices:
+
+```text
+.venv/bin/python -m pytest -q tests/test_browser_yixiao_case_study_smoke.py tests/test_manage_demo_instance.py tests/test_inspect_demo_instance.py tests/test_workflow_export_bundle.py tests/test_workflow_evidence_export.py tests/test_workflow_routes.py tests/test_yixiao_pre_demo_smoke.py tests/test_workflow_case_study_acceptance.py
+```
+
+Result:
+
+```text
+97 passed, 12 warnings
+```
+
+Frontend test slice:
+
+```text
+CI=true npm --prefix client test -- --runInBand --watchAll=false --runTestsByPath src/views/FilesManager.test.js src/components/Chatbot.test.js src/components/WorkflowTimeline.test.js src/components/chat/AgentProposalCard.test.js src/__tests__/agentProposalCards.test.js src/contexts/WorkflowContext.test.js
+```
+
+Result:
+
+```text
+69 passed
+```
+
+Build:
+
+```text
+npm --prefix client run build
+```
+
+Result:
+
+```text
+passed
+```
+
+Known remaining frontend build warnings are pre-existing warnings in older EHTool files:
+
+- `src/views/ehtool/DetectionWorkflow.js`
+- `src/views/ehtool/ProofreadingEditor.js`
+
+Whitespace check:
+
+```text
+git diff --check
+```
+
+Result:
+
+```text
+passed
+```
+
+## Demo Deployment State
+
+The demo API was restarted and verified on port `4342`.
+
+Runtime config:
+
+```text
+api_port=4342
+worker_url=localhost:4243
+neuroglancer_port=4244
+neuroglancer_public_base=https://demo.seg.bio/neuroglancer
+```
+
+Final live checks passed:
+
+- API `/health`.
+- Runtime config log comparison.
+- Worker `hello`.
+- API `/training_status`.
+- Worker proxy URL alignment.
+- Current workflow endpoint.
+- Neuroglancer port reachability.
+- Public Neuroglancer URL prefix.
+- Recent app error scan.
+
+Final warmed workflow:
+
+```text
+workflow_id=195
+title=Yixiao TapeReader XRI Case Study
+stage=visualization
+```
+
+Final Yixiao viewer URL prefix:
+
+```text
+https://demo.seg.bio/neuroglancer/
+```
+
+The Yixiao smoke pass reported:
+
+```text
+Yixiao case-study smoke passed.
+Workflow: 195
+```
+
+The Yixiao pre-demo gate passed:
+
+```text
+normal_smoke: pass
+promotion_roundtrip: pass
+restore_state: pass
+readiness_check: pass
+export_sanity: pass
+```
+
+## Remaining Known Gaps
+
+The prototype is much stronger, but not production-complete.
+
+Known gaps:
+
+- Playwright is not installed in the current environment, so the browser smoke script is present and tested structurally, but full browser automation was not run locally.
+- Real GPU training/inference/evaluation still needs end-to-end live validation for paper performance claims.
+- The evidence/provenance payload is much richer, but the schema is not yet fully typed or migration-backed as a stable public contract.
+- User management exists as a foundation, not a polished multi-user product.
+- The current Yixiao case-study config is app-compatible and sanity-oriented; paper-faithful TapeReader parity still needs explicit confirmation against the original pipeline.
+- The proofreading UI is useful for the prototype but not yet a full production-grade annotation/proofreading system.
+- The app still has older EHTool build warnings that should be cleaned before a polished release.
+- There is an untracked local file, `demo-proofread-3d.png`, which was not committed because it is not referenced by the app.
+
+## Recommended Next Steps
+
+1. Run the Yixiao case study manually from the demo link and record where the user feels friction.
+2. Validate one real training run from the staged ground-truth subset.
+3. Validate one inference run on the image-only targets.
+4. Decide whether draft masks `5_1` and `5_2` should be real proofreading targets or treated as simulated placeholders.
+5. Tighten the evidence export into a formal schema for the paper.
+6. Make the agent response style less mechanical in a few remaining fallback cases.
+7. Install Playwright and run the browser smoke harness against the deployed demo.
+8. Clean the remaining EHTool warnings.
+9. Decide the third case study fixture and implement its task-family preset.
+10. Write the paper methods section around the actual system architecture:
+    - project inspector.
+    - workflow memory.
+    - progress/volume state.
+    - action proposal cards.
+    - approval-gated execution.
+    - evidence ledger.
+
+## Current Git State At Report Time
+
+Branch:
+
+```text
+checkpoint/tochi-agentic-prototype
+```
+
+Remote:
+
+```text
+origin/checkpoint/tochi-agentic-prototype
+```
+
+Current head:
+
+```text
+a047f34 docs(research): capture paper prototype roadmap
+```
+
+Untracked local artifact:
+
+```text
+demo-proofread-3d.png
+```
+
+This file was intentionally not included in the pushed commits because no repository file references it.
diff --git a/docs/codex-working-memory/paper-readiness-production-plan.md b/docs/codex-working-memory/paper-readiness-production-plan.md
new file mode 100644
index 00000000..16e9b0cd
--- /dev/null
+++ b/docs/codex-working-memory/paper-readiness-production-plan.md
@@ -0,0 +1,1006 @@
+# Paper Readiness And Production System Plan
+
+Last updated: 2026-06-04
+
+This document turns the current product direction into a concrete execution
+plan for a paper-ready, production-shaped human-agent system for iterative
+biomedical image segmentation.
+
+The goal is not to build a generic biology chatbot. The goal is to build a
+workflow-aware system that can coordinate the actual segmentation loop:
+
+`mount project -> inspect context -> confirm volume state -> visualize -> run inference -> proofread -> promote corrections -> train/retrain -> run inference again -> evaluate -> export evidence`
+
+The paper should be ready only when the implemented system can perform that
+loop on real data, with durable project state, explicit user control, and
+exportable evidence that supports the manuscript claims.
+
+## Core Product Contract
+
+The final system implied by the paper should satisfy this contract:
+
+1. A biologist can mount a project without knowing the app's internal schema.
+2. The app inspects the project and presents concrete findings instead of a
+   blank prompt.
+3. The user can correct or confirm project facts through guided UI controls.
+4. Every volume has an explicit workflow state that both the user and agent can
+   reference.
+5. The assistant can answer from current project state, fresh file probes,
+   previous actions, and run evidence.
+6. The assistant proposes bounded app routines, not arbitrary hidden actions.
+7. Training, inference, proofreading, and evaluation are durable workflow
+   records with inputs, outputs, logs, and provenance.
+8. Consequential actions are approval-gated.
+9. The system can export enough evidence to reproduce the paper's walkthroughs,
+   figures, and claims.
+10. User-facing language is normal and helpful; mechanical details are available
+    through expandable evidence traces.
+
+## Paper Claim Contract
+
+The paper can safely claim the following only if the corresponding gates pass.
+
+| Claim                                                     | Required System Evidence                                                             | Paper Risk If Missing                                     |
+| --------------------------------------------------------- | ------------------------------------------------------------------------------------ | --------------------------------------------------------- |
+| The system maintains project-level workflow context.      | Canonical project memory, rescan/update behavior, per-volume state, evidence log.    | The assistant looks like a chat panel with stale guesses. |
+| The system coordinates fragmented segmentation stages.    | End-to-end loop across visualization, inference, proofreading, training, evaluation. | The paper overclaims beyond a prototype GUI.              |
+| The assistant supports mixed-initiative handoffs.         | Action cards with inspect/propose/approve/execute/update lifecycle.                  | The agent looks passive or unsafe.                        |
+| Users remain in control of expensive or mutating actions. | Approval gates, rejection, interruption, audit trail.                                | The system is not defensible for scientific workflows.    |
+| The interface reduces setup ambiguity for biologists.     | Guided onboarding with detected facts and concrete questions.                        | The first-run UX contradicts the HCI argument.            |
+| The workflow creates reusable evidence.                   | Bundle export with events, artifacts, configs, metrics, screenshots/links.           | Case-study results become anecdotal and hard to verify.   |
+| The loop supports iterative model improvement.            | Before/after inference and metrics from real app-generated artifacts.                | The paper must avoid accuracy or improvement claims.      |
+
+## Case-Study Readiness Taxonomy
+
+For the Yixiao workflow, the paper-ready surface is split by artifact maturity.
+
+| Claim Surface               | Required Artifact Set                                                                              | Pass Condition                                                                              |
+| --------------------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| Workflow coordination claim | project context snapshot, volume-state counts, and bounded proposal/action traces                  | Proposal + training drill demonstrates context-aware gating with `6/2/2` baseline           |
+| Review-control claim        | explicit proposal approvals and audit trails (`agent.proposal_*` and `agent.plan_*`)               | No mutating action appears without recorded approval step                                   |
+| Closed-loop claim           | training completion record, checkpoint/version, inference record, evaluation result, export bundle | At least one run is reproducible from `WorkflowExport` metadata with model/evaluation links |
+| Paper evidence claim        | export bundle with manifest-only policy and copied artifact summary                                | `export-bundle` call returns schema, paths, and copy policy metadata                        |
+
+This mapping is intentionally strict:
+
+- If only the coordination claim is backed by evidence, frame the case study as a
+  coordination demo.
+- If training/inference/eval are backed, the manuscript can include improvement
+  statements with caveats around target and dataset specificity.
+
+## One-hour Yixiao Acceptance Checklist
+
+These are the practical go/no-go items for a timed demo:
+
+- Baseline project state (`10` volumes, `6/2/2`, context roots, target IDs).
+- Agent context stays on the mounted fixture (no MitoEM/Lucchi regressions).
+- Training proposal is approval-gated and excludes draft/image-only masks from training.
+- Draft mask promotion can move `5_1`/`5_2` to a training-ready state.
+- Closed-loop rehearsal can reference held-out ground truth without mounting it as training data.
+- Real training/inference/evaluation artifacts exist before claiming model improvement.
+- Export bundle call succeeds with manifest/skip policy and required core fields.
+- Live health checks (`inspect_demo_instance.py --json`) are healthy enough to launch.
+
+## Definition Of Paper-Ready
+
+The prototype is paper-ready when all P0 gates pass and at least one full case
+study can be run without manual developer intervention.
+
+### P0 Gates
+
+- A fresh mounted project can be inspected, confirmed, and represented in
+  canonical project memory.
+- The Progress page accurately represents every volume state.
+- The assistant can explain the current project, current blockers, and next
+  useful action from project memory.
+- The assistant can propose visualization, inference, proofreading, training,
+  and evaluation actions using the same action-card contract.
+- Training on multiple selected ground-truth volumes works through app-created
+  artifacts, not fragile directory guessing.
+- Inference over image-only or draft volumes works and registers predictions.
+- Proofreading saves durable corrected masks and updates volume status.
+- Evaluation computes at least one relevant before/after metric for the main
+  case study.
+- Every run, artifact, status transition, and approval is exportable.
+- A reset script can return the demo dataset to its initial study state.
+
+### P1 Gates
+
+- Region-level proofreading state and `valid_mask` style partial supervision.
+- Multiple task-family presets beyond the primary case study.
+- More robust data backends such as OME-Zarr, OMERO, or Neuroglancer
+  precomputed.
+- Scheduler-aware long-running training and inference jobs.
+- Stronger multi-user authorization and deployment hardening.
+
+## Case Study Placeholders
+
+The paper should use three case studies that build the argument in layers.
+
+### Case Study 1: Guided Project Intake And Inspection
+
+Purpose:
+
+- Demonstrate that a biologist can mount a project and get a useful,
+  inspect-first onboarding flow without knowing what metadata the agent needs.
+
+Dataset placeholder:
+
+- `CASE_STUDY_1_DATASET`: likely Lucchi++ or a small MitoEM/MitoEM2 subset.
+
+Participant/task placeholder:
+
+- `CASE_STUDY_1_TASK`: mount the project, confirm detected images/masks,
+  correct voxel size or target structure, visualize one pair, and inspect the
+  project progress state.
+
+Required product capabilities:
+
+- Guided onboarding wizard.
+- Project profiler and file role detector.
+- Editable project facts.
+- Per-volume status creation.
+- Progress page with accurate counts.
+- Conversational assistant answer to "what am I looking at?"
+
+Evidence to export:
+
+- Initial project scan.
+- User corrections.
+- Confirmed project memory snapshot.
+- Volume table.
+- Visualization action event.
+- Chat response plus "What I checked" trace.
+
+Success criteria:
+
+- User does not need to type a free-form project description to get started.
+- The system identifies at least one valid image/mask pair or explains exactly
+  what is missing.
+- The final project memory matches the ground-truth setup for the fixture.
+
+Paper contribution supported:
+
+- Guided intent elicitation for domain experts who know their data but not the
+  software schema.
+
+### Case Study 2: Agent-Guided Proofreading And Data Curation
+
+Purpose:
+
+- Demonstrate that the system can coordinate the human correction loop and
+  maintain training readiness state.
+
+Dataset placeholder:
+
+- `CASE_STUDY_2_DATASET`: MitoEM2 progress demo with a mix of ground-truth,
+  draft segmentation, and image-only volumes.
+
+Participant/task placeholder:
+
+- `CASE_STUDY_2_TASK`: inspect draft segmentations, proofread selected masks,
+  promote corrected masks to ground truth, and decide which volumes are ready
+  for training.
+
+Required product capabilities:
+
+- Progress statuses: `ground_truth`, `needs_proofreading`, `image_only`,
+  `ignored`.
+- Row-level actions: view, proofread, mark as ground truth, mark as draft,
+  ignore.
+- Proofreading editor persistence.
+- Correction artifact registration.
+- Assistant awareness of which volumes are training-ready.
+
+Evidence to export:
+
+- Pre-proofreading volume status table.
+- Proofreading session events.
+- Correction artifacts.
+- Status transitions.
+- Assistant recommendation before and after corrections.
+- Screenshots or reproducible viewer links.
+
+Success criteria:
+
+- Corrected masks are saved as real files.
+- The corresponding volume status changes are durable.
+- The agent correctly excludes draft/unproofread masks from training unless the
+  user explicitly overrides.
+
+Paper contribution supported:
+
+- Workflow-aware coordination between human correction and model retraining.
+
+### Case Study 3: Closed-Loop Training, Inference, And Evaluation
+
+Purpose:
+
+- Demonstrate the complete iterative loop from curated ground truth to model
+  run to new predictions to evaluation.
+
+Dataset placeholder:
+
+- `CASE_STUDY_3_DATASET`: primary MitoEM or MitoEM2 subset with at least:
+  - two ground-truth volumes;
+  - two draft segmentation volumes;
+  - two image-only target volumes;
+  - a reset script and frozen initial snapshot.
+
+Participant/task placeholder:
+
+- `CASE_STUDY_3_TASK`: train on approved ground-truth volumes, run inference on
+  image-only volumes, proofread or inspect predictions, then compare outputs.
+
+Required product capabilities:
+
+- Multi-volume training subset creation.
+- PyTC-compatible staged training manifest/config.
+- Training run launch, log capture, TensorBoard link, checkpoint registration.
+- Inference run launch from selected checkpoint.
+- Prediction registration as draft segmentation.
+- Evaluation metrics against held-out or revealed labels.
+- Evidence bundle export.
+
+Evidence to export:
+
+- Training action card and approval.
+- Staged dataset manifest.
+- Runtime config.
+- Training logs.
+- Checkpoint/model version record.
+- Inference action card and approval.
+- Prediction artifacts.
+- Evaluation results.
+- Before/after project state snapshot.
+
+Success criteria:
+
+- The run can be reproduced from exported config, artifacts, and project memory.
+- The agent can explain what was trained on, what was left out, and why.
+- Evaluation results are attached to the relevant volumes and model runs.
+
+Paper contribution supported:
+
+- Approval-gated human-agent orchestration of a full closed-loop biomedical
+  segmentation workflow.
+
+## Workstream 1: Canonical Project Memory
+
+### Objective
+
+Replace scattered inference, browser state, and sidecar assumptions with one
+canonical project memory model that all UI surfaces and agent routines use.
+
+### Concrete Action Items
+
+- Define `ProjectMemory` schema:
+  - `project_id`
+  - `root_path`
+  - `dataset_name`
+  - `task_family`
+  - `modality`
+  - `target_structure`
+  - `voxel_size_zyx_nm`
+  - `confidence_by_field`
+  - `source_evidence_by_field`
+  - `volume_ids`
+  - `artifact_ids`
+  - `run_ids`
+  - `created_at`
+  - `updated_at`
+- Define `VolumeState` schema:
+  - `volume_id`
+  - `display_name`
+  - `image_path`
+  - `label_path`
+  - `prediction_path`
+  - `status`
+  - `status_source`
+  - `status_confidence`
+  - `last_reviewed_at`
+  - `eligible_for_training`
+  - `eligible_for_inference`
+  - `notes`
+- Define allowed volume statuses:
+  - `image_only`
+  - `draft_segmentation`
+  - `needs_proofreading`
+  - `ground_truth`
+  - `ignored`
+  - `invalid`
+- Define `Artifact` schema:
+  - raw image
+  - label
+  - prediction
+  - corrected mask
+  - config
+  - checkpoint
+  - metric report
+  - screenshot or viewer state
+  - evidence bundle
+- Define `ProjectEvent` schema:
+  - actor
+  - event type
+  - timestamp
+  - affected volumes
+  - affected artifacts
+  - previous state
+  - next state
+  - evidence payload
+- Implement server APIs:
+  - `GET /users/me/projects` for user-scoped mounted project inventory.
+  - `GET /api/workflows/{workflow_id}/volumes` for canonical workflow volume
+    state, refreshed from the mounted project when requested.
+  - `PATCH /api/workflows/{workflow_id}/volumes` for manual volume-state
+    corrections, training/inference eligibility, and path updates.
+  - `GET /api/workflows/{workflow_id}/export-bundle` for evidence, events,
+    artifacts, and volume state.
+  - Future project-memory endpoints can still be layered over this as
+    `/api/projects/{id}/memory`, `/api/projects/{id}/rescan`, and
+    `/api/projects/{id}/events` once project identity is separated from the
+    current workflow session model.
+- Move Progress page to read from project memory, not ad hoc derived values.
+- Move assistant context builder to project memory plus recent events.
+- Add migration/import path from existing `.pytc_project_context.json` and
+  `project_manifest.json` into the canonical schema.
+
+### Verification Gates
+
+- Unit tests validate status transitions.
+- API tests create, update, rescan, and export project memory.
+- Reloading the app preserves project memory exactly.
+- Rescanning a project adds newly discovered files without overwriting
+  user-confirmed facts.
+- Deleting or moving a file marks affected artifacts stale instead of silently
+  pretending they still work.
+
+### Paper Readiness Evidence
+
+- Exported project memory snapshot before and after each case-study session.
+- Event log showing detected facts, user corrections, and volume state changes.
+- Figure-ready Progress page state generated from canonical memory.
+
+## Workstream 2: Guided Onboarding And Context Elicitation
+
+### Objective
+
+Replace the blank context box with an inspect-first onboarding flow that guides
+biologists through concrete confirmations.
+
+### Concrete Action Items
+
+- Run project scan immediately after mount.
+- Present a wizard with detected facts:
+  - likely image files;
+  - likely mask/segmentation files;
+  - likely configs;
+  - likely checkpoints;
+  - likely voxel size;
+  - likely task family;
+  - ambiguous or missing fields.
+- Add editable fields:
+  - target structure;
+  - imaging modality;
+  - voxel size;
+  - label semantics: ground truth, draft prediction, unknown;
+  - priority: speed, accuracy, balanced;
+  - task family preset.
+- Replace free-form prompt as primary input with:
+  - confirmation chips;
+  - dropdowns;
+  - "not sure" choices;
+  - small examples;
+  - optional note field.
+- Ask one concrete follow-up question at a time when a required field is
+  missing.
+- Add "Use detected defaults" only when defaults are visible and editable.
+- Add "Show evidence" for each inferred fact.
+- Save every user confirmation or correction as a project event.
+
+### Verification Gates
+
+- A user can mount a known fixture and complete onboarding without typing a
+  paragraph.
+- The wizard identifies known fixture image/mask pairs correctly.
+- Unknown fields remain marked as unknown rather than fabricated.
+- User corrections are reflected in project memory and future agent responses.
+- Onboarding can be reopened to edit context later.
+
+### Paper Readiness Evidence
+
+- Screenshot sequence of guided onboarding.
+- Exported evidence showing auto-detected facts and user corrections.
+- Case-study notes showing reduced blank-prompt burden.
+
+## Workstream 3: Progress Page As Shared Source Of Truth
+
+### Objective
+
+Make Progress the user and agent's common map of the project.
+
+### Concrete Action Items
+
+- Rebuild Progress from `VolumeState`.
+- Show summary cards:
+  - total volumes;
+  - ground truth;
+  - needs proofreading;
+  - draft segmentation;
+  - image-only;
+  - ignored;
+  - stale/broken artifacts.
+- Add per-row actions:
+  - view image;
+  - view image plus label;
+  - proofread;
+  - mark ground truth;
+  - mark draft;
+  - run inference;
+  - include in training;
+  - exclude/ignore;
+  - inspect provenance.
+- Add bulk actions:
+  - train on selected ground-truth volumes;
+  - run inference on selected image-only volumes;
+  - mark selected as ignored;
+  - export selected manifest.
+- Add "Why this status?" provenance popover.
+- Add filters by status, split, source folder, task family, and stale state.
+- Add validation warnings for duplicate rows, missing labels, duplicate masks,
+  and impossible statuses.
+
+### Verification Gates
+
+- Progress counts match project memory after mount, reload, proofread save,
+  inference completion, and training completion.
+- Duplicate volumes are detected and surfaced.
+- Agent recommendations cite the same volume counts shown in Progress.
+- Bulk training selection excludes non-ground-truth volumes by default.
+
+### Paper Readiness Evidence
+
+- Progress screenshots before and after each case-study action.
+- Exported volume-state CSV/JSON.
+- Event log of status transitions.
+
+## Workstream 4: Unified Action Cards And Execution Envelope
+
+### Objective
+
+Make every agent-proposed action understandable, reviewable, executable, and
+auditable through one contract.
+
+### Concrete Action Items
+
+- Define `ActionProposal` schema:
+  - `proposal_id`
+  - `routine`
+  - `title`
+  - `plain_language_summary`
+  - `why_now`
+  - `inputs`
+  - `affected_volumes`
+  - `expected_outputs`
+  - `estimated_cost`
+  - `risk_level`
+  - `requires_approval`
+  - `approval_state`
+  - `created_from_evidence`
+  - `created_at`
+- Define allowed routines:
+  - `open_progress`
+  - `view_volume`
+  - `proofread_volume`
+  - `mark_volume_status`
+  - `stage_training_set`
+  - `start_training`
+  - `run_inference`
+  - `compute_evaluation`
+  - `export_evidence`
+  - `rescan_project`
+- Replace fragmented client effects, commands, and proposal payloads with this
+  envelope.
+- Render all cards with the same visual anatomy:
+  - title;
+  - short summary;
+  - affected volumes;
+  - expected output;
+  - approve/reject or run/open button;
+  - expandable details.
+- Store proposal, approval, execution start, execution completion, execution
+  failure, and artifact registration as events.
+- Add retry, cancel, and failure explanation states.
+
+### Verification Gates
+
+- All mutating or expensive routines require explicit approval.
+- Approving a card updates the corresponding app UI and creates durable events.
+- Rejecting a card leaves project state unchanged and records rejection.
+- Refresh/reload does not lose pending cards.
+- Tests cover each routine's happy path and failure path.
+
+### Paper Readiness Evidence
+
+- Action-card screenshots.
+- Approval/rejection event log.
+- Exported routine inputs and outputs for each case study.
+
+## Workstream 5: Workflow Agent Behavior
+
+### Objective
+
+Make the assistant useful as a workflow partner while keeping the visible chat
+human and concise.
+
+### Concrete Action Items
+
+- Separate internal trace from visible response:
+  - visible response: short, conversational, next-step oriented;
+  - trace: files checked, volume states read, configs inspected, blockers.
+- Add project tools:
+  - inspect project memory;
+  - inspect files;
+  - inspect HDF5/TIFF/Zarr metadata;
+  - inspect run history;
+  - inspect progress statuses;
+  - inspect checkpoints/configs;
+  - inspect logs and metrics.
+- Make the default response shape:
+  - direct answer;
+  - one suggested next move;
+  - optional action card if there is a concrete app routine.
+- Add clarification behavior:
+  - ask concrete questions only when required facts are missing;
+  - avoid asking the user to restate facts already in project memory.
+- Add conversational tone tests for canned/fallback paths.
+- Add regression tests for common user intents:
+  - "what am I looking at?"
+  - "train on the good ones"
+  - "segment the rest"
+  - "show me what changed"
+  - "why is this volume not training-ready?"
+  - "what failed?"
+
+### Verification Gates
+
+- General conceptual questions do not get hijacked by workflow routing.
+- Workflow questions cite current project memory accurately.
+- Agent does not hallucinate missing files or ground-truth state.
+- Agent proposes action cards only when a bounded routine exists.
+- User-facing text does not expose raw JSON, internal planner language, or
+  chain-of-thought style narration.
+
+### Paper Readiness Evidence
+
+- Chat transcripts with expandable evidence traces.
+- Intent-routing test results.
+- Case-study examples showing agent handoff support.
+
+## Workstream 6: Multi-Volume Training
+
+### Objective
+
+Make training a real multi-volume project operation driven by volume statuses.
+
+### Concrete Action Items
+
+- Add Training Set artifact:
+  - `training_set_id`
+  - included volumes;
+  - excluded volumes;
+  - exclusion reasons;
+  - staged image paths;
+  - staged label paths;
+  - generated manifest;
+  - source project memory version.
+- Default included volumes to `ground_truth`.
+- Default excluded volumes:
+  - `image_only`;
+  - `draft_segmentation`;
+  - `needs_proofreading`;
+  - `ignored`;
+  - stale or invalid artifacts.
+- Add UI to review training set before launch.
+- Generate PyTC-compatible config/manifest for multiple volumes.
+- Run a dry-run loader validation before training starts.
+- Populate Train Model UI fields from the approved proposal.
+- Register training run:
+  - config origin;
+  - staged config path;
+  - training set artifact;
+  - output path;
+  - log path;
+  - TensorBoard URL;
+  - process ID;
+  - terminal status;
+  - checkpoint path.
+- Avoid unloading the LLM unless resource policy says it is necessary.
+
+### Verification Gates
+
+- Training cannot start with an image directory path that PyTC treats as an
+  unrecognized file.
+- Training set dry-run catches missing labels, bad HDF5 keys, incompatible
+  shapes, and unreadable files.
+- Approving a training card visibly populates Train Model fields.
+- Completed training registers a model version/checkpoint.
+- Failed training surfaces the actual error and suggested repair.
+
+### Paper Readiness Evidence
+
+- Training action card.
+- Training set manifest.
+- Runtime config.
+- Training logs.
+- Model version/checkpoint record.
+
+## Workstream 7: Inference And Prediction Registration
+
+### Objective
+
+Make inference produce project-aware draft segmentations that feed Progress and
+Proofread.
+
+### Concrete Action Items
+
+- Add Inference Run artifact:
+  - checkpoint/model version;
+  - target volumes;
+  - config;
+  - output paths;
+  - run status;
+  - logs;
+  - metrics if available.
+- Let agent propose inference on:
+  - `image_only` volumes;
+  - selected held-out volumes;
+  - volumes with stale predictions;
+  - post-training comparison targets.
+- Require checkpoint selection before launch.
+- Register predictions as `draft_segmentation`.
+- Attach prediction path to each affected volume.
+- Provide "Open prediction" and "Proofread next" actions after completion.
+- Handle inference failures per volume where possible.
+
+### Verification Gates
+
+- Inference on multiple target volumes creates one registered prediction per
+  volume.
+- Progress counts update automatically after inference.
+- Viewer and proofreader can open app-generated predictions.
+- Failed inference does not mark volumes as predicted.
+
+### Paper Readiness Evidence
+
+- Inference proposal, approval, run logs, prediction artifacts, and status
+  updates.
+
+## Workstream 8: Proofreading And Correction Promotion
+
+### Objective
+
+Make human edits durable, inspectable, and reusable for training.
+
+### Concrete Action Items
+
+- Load proofreader from selected volume state.
+- Support draft segmentation and ground-truth mask inspection.
+- Save corrected masks as artifacts.
+- Create Correction Set records:
+  - corrected mask path;
+  - source image;
+  - source prediction/mask;
+  - edit summary;
+  - actor;
+  - timestamp;
+  - eligible for training flag.
+- Add "Use edits for training" state transition.
+- Add "Still needs review" state transition.
+- Record edit provenance and status changes.
+- Add optional region-level status design for future `valid_mask` support.
+
+### Verification Gates
+
+- Saved edits survive reload and remount.
+- Promoting corrections changes the corresponding volume status.
+- Training selection sees promoted corrections as eligible ground truth.
+- The system can explain which masks are original labels vs proofread edits.
+
+### Paper Readiness Evidence
+
+- Before/after correction artifacts.
+- Proofreading session event log.
+- Correction Set export.
+
+## Workstream 9: Evaluation And Comparison
+
+### Objective
+
+Provide enough quantitative evidence to support closed-loop workflow claims
+without overclaiming algorithmic novelty.
+
+### Concrete Action Items
+
+- Define evaluation tasks by task family:
+  - semantic masks: Dice, IoU, precision, recall;
+  - instance masks: adapted Rand, variation of information, object counts;
+  - affinity workflows: decoder-specific metrics where supported.
+- Add Evaluation Result artifact:
+  - prediction path;
+  - reference path;
+  - metric names;
+  - metric values;
+  - config;
+  - run status.
+- Add compare UI:
+  - baseline prediction;
+  - candidate prediction;
+  - reference label;
+  - metric delta.
+- Let agent propose evaluation when required artifacts exist.
+- Make missing-reference cases explicit.
+
+### Verification Gates
+
+- Evaluation refuses incompatible shapes or missing references with a clear
+  error.
+- Evaluation outputs are attached to model runs and volumes.
+- Before/after comparison can be regenerated from exported evidence.
+
+### Paper Readiness Evidence
+
+- Metrics table.
+- Before/after figure.
+- Exported evaluation JSON.
+
+## Workstream 10: Evidence Export And Reproducibility
+
+### Objective
+
+Make every paper claim traceable to exported system evidence.
+
+### Concrete Action Items
+
+- Expand evidence bundle to include:
+  - project memory snapshots;
+  - volume state table;
+  - action proposals;
+  - approvals/rejections;
+  - run configs;
+  - logs;
+  - model versions;
+  - prediction artifacts;
+  - correction sets;
+  - evaluation results;
+  - app version/commit;
+  - environment metadata;
+  - viewer states or screenshots where possible.
+- Add one-click export from a researcher-visible location.
+- Add script to validate an exported bundle.
+- Add script to regenerate paper figures/tables from bundle data.
+- Add reset script for every case-study fixture.
+
+### Verification Gates
+
+- Bundle validator passes for all three case studies.
+- A fresh checkout can inspect the bundle without database access.
+- Paper figures and tables can be regenerated from bundle content.
+- Reset script restores fixture to initial snapshot exactly.
+
+### Paper Readiness Evidence
+
+- Bundle file path and validation report for every case-study run.
+
+## Workstream 11: Production Hardening
+
+### Objective
+
+Remove prototype fragility that would undermine the case studies or demo.
+
+### Concrete Action Items
+
+- Add health checks for:
+  - API;
+  - frontend bundle;
+  - PyTC worker;
+  - Ollama/model server;
+  - Neuroglancer assets;
+  - TensorBoard;
+  - filesystem access;
+  - GPU availability if required.
+- Add structured logs for:
+  - route calls;
+  - agent decisions;
+  - file scans;
+  - status transitions;
+  - run lifecycle;
+  - frontend action execution.
+- Add user-visible failure messages for:
+  - missing files;
+  - unsupported volume formats;
+  - bad HDF5 keys;
+  - bad YAML config;
+  - missing checkpoint;
+  - shape mismatch;
+  - training process failure;
+  - mixed-content or asset loading failure.
+- Add end-to-end smoke tests for the golden path.
+- Add deployment checklist for `demo.seg.bio`.
+- Add rollback/reset steps.
+- Add database migration strategy before multi-user use.
+
+### Verification Gates
+
+- Golden-path smoke passes on demo fixture.
+- Error-path tests produce useful user-facing messages.
+- Demo can be reset and rerun without manual cleanup.
+- Logs are sufficient to diagnose every known failure mode from previous
+  sessions.
+
+### Paper Readiness Evidence
+
+- Smoke-test logs.
+- Demo reset logs.
+- Known-failure recovery examples.
+
+## Workstream 12: Manuscript Alignment
+
+### Objective
+
+Keep the manuscript synchronized with what the artifact can actually do.
+
+### Concrete Action Items
+
+- Maintain a claim-to-evidence table.
+- Remove future-tense language for implemented features.
+- Mark unimplemented ideas as future work.
+- Frame contribution around:
+  - workflow coordination;
+  - project memory;
+  - guided intent elicitation;
+  - approval-gated action proposals;
+  - evidence-bearing closed-loop segmentation.
+- Avoid unsupported claims:
+  - broad bioimage generalization;
+  - autonomous science;
+  - guaranteed accuracy improvements;
+  - safety beyond bounded routines.
+- Prepare paper figures:
+  - system architecture;
+  - project memory model;
+  - onboarding flow;
+  - Progress page;
+  - action card lifecycle;
+  - closed-loop case-study timeline;
+  - before/after evaluation.
+- Prepare methods appendix:
+  - datasets;
+  - system implementation;
+  - agent routines;
+  - logging/evidence export;
+  - case-study protocol;
+  - limitations.
+
+### Verification Gates
+
+- Every central claim has an exported artifact, screenshot, event log, or study
+  observation attached.
+- Every paper figure can be regenerated or traced to a specific fixture and
+  app version.
+- Limitations explicitly cover missing P1 features.
+- The manuscript does not imply the agent can do filesystem or workflow actions
+  that are not implemented.
+
+## Suggested Milestone Order
+
+### Milestone A: State Foundation
+
+Exit criteria:
+
+- Canonical project memory exists.
+- Guided onboarding writes to it.
+- Progress reads from it.
+- Agent reads from it.
+
+Paper value:
+
+- Supports the core claim that the system maintains workflow context.
+
+### Milestone B: Action Foundation
+
+Exit criteria:
+
+- Unified action cards exist.
+- Proposal/approval/execution events are durable.
+- Visualization, progress, and status changes use the same action envelope.
+
+Paper value:
+
+- Supports the mixed-initiative and approval-gated control argument.
+
+### Milestone C: Curation Loop
+
+Exit criteria:
+
+- Draft segmentation can be proofread.
+- Corrected masks are saved.
+- Status promotion affects training eligibility.
+
+Paper value:
+
+- Supports human correction as part of the model workflow, not an isolated UI.
+
+### Milestone D: Model Loop
+
+Exit criteria:
+
+- Multi-volume training works from selected ground-truth volumes.
+- Inference runs on image-only volumes.
+- Predictions become draft segmentations.
+
+Paper value:
+
+- Supports the closed-loop segmentation workflow claim.
+
+### Milestone E: Evaluation And Evidence
+
+Exit criteria:
+
+- Before/after evaluation works.
+- Evidence bundle validates.
+- Three case-study fixtures can be reset and replayed.
+
+Paper value:
+
+- Supports empirical case-study reporting and reproducibility.
+
+### Milestone F: Paper Freeze
+
+Exit criteria:
+
+- All screenshots and figures are regenerated from the frozen app.
+- Claim-to-evidence table is complete.
+- Case-study placeholders are replaced with real data and observations.
+- Unsupported claims are removed or moved to future work.
+
+Paper value:
+
+- Moves from prototype narrative to defensible systems/HCI paper.
+
+## Claim-To-Workstream Matrix
+
+| Paper Claim                                                             | Workstreams Required                     |
+| ----------------------------------------------------------------------- | ---------------------------------------- |
+| The system maintains project context over time.                         | 1, 2, 3, 5, 10                           |
+| The system supports biologist-friendly onboarding.                      | 2, 5, 12                                 |
+| The system enables visible volume-level workflow tracking.              | 1, 3, 8, 10                              |
+| The agent proposes bounded, approval-gated workflow actions.            | 4, 5, 11                                 |
+| The system supports closed-loop segmentation.                           | 6, 7, 8, 9                               |
+| The system produces reproducible evidence for case studies.             | 10, 11, 12                               |
+| The design is suitable for iterative biomedical segmentation workflows. | All workstreams plus case-study evidence |
+
+## Final Readiness Checklist
+
+Use this before claiming the system is paper-ready.
+
+- [ ] A non-developer can mount each case-study fixture.
+- [ ] The app detects useful project facts before asking the user to type.
+- [ ] The user can correct every important detected fact.
+- [ ] Every volume has a correct state.
+- [ ] The agent can explain current project state accurately.
+- [ ] The agent can propose the next useful action.
+- [ ] Action cards are understandable and auditable.
+- [ ] Training works on multiple approved ground-truth volumes.
+- [ ] Inference works on selected target volumes.
+- [ ] Proofreading saves durable corrections.
+- [ ] Corrected masks can become training-ready.
+- [ ] Evaluation works where references exist.
+- [ ] Evidence bundle export validates.
+- [ ] Demo reset restores initial state.
+- [ ] Case Study 1 is runnable and documented.
+- [ ] Case Study 2 is runnable and documented.
+- [ ] Case Study 3 is runnable and documented.
+- [ ] Paper figures are regenerated from frozen evidence.
+- [ ] Paper claims are mapped to evidence.
+- [ ] Unsupported claims are removed or clearly labeled future work.
diff --git a/docs/codex-working-memory/progress-log.md b/docs/codex-working-memory/progress-log.md
new file mode 100644
index 00000000..64afc0a4
--- /dev/null
+++ b/docs/codex-working-memory/progress-log.md
@@ -0,0 +1,1630 @@
+# PyTC Client Progress Log
+
+Local working log for Codex sessions on `pytc-client`.
+
+## 2026-06-04
+
+- Hardened agent proposal UX in chat for safer approval workflows:
+  - made proposal fields editable before approval via a visible `Edit details` action and clickable field values;
+  - ensured approved/rejected proposal cards remain locked (approve/reject disabled, no active edit mode).
+  - reduced long label clipping risk with wrapping-safe proposal header, type tag, field, and agent badge styles.
+  - propagated specialist agent metadata from proposal payload/action_card so non-PM badges render in chat cards.
+  - extended/updated focused React tests for edit-before-approve, disabled after decision, long-label/wrapping, and specialist badge behavior.
+  - verified with:
+    - `npm --prefix client test -- --watchAll=false --runInBand --runTestsByPath src/components/chat/AgentProposalCard.test.js src/__tests__/agentProposalCards.test.js src/components/Chatbot.test.js`.
+
+- Audited and stabilized the Yixiao browser smoke script at
+  `scripts/browser_yixiao_case_study_smoke.py`:
+  - fixed parser/help string syntax;
+  - fixed Playwright runtime validation flow (now uses an active Playwright context correctly);
+  - added an explicit install remediation message (`python3 -m pip install playwright` + `python3 -m playwright install chromium`).
+- Added focused unit coverage for smoke parser helpers in
+  `tests/test_browser_yixiao_case_study_smoke.py`:
+  - viewport parsing behavior,
+  - progress-text extraction (`10/6/2/2`, `60%`, `80%`),
+  - default arg parsing.
+- Documented browser smoke usage and operator-facing dependency gap in
+  `docs/manual-yixiao-case-study-demo.md`.
+
+- Refined Yixiao readiness taxonomy into explicit go/no-go gates for a one-hour case-study launch:
+  - baseline project state, agent context, approval-gated training proposal, proofread promotion, closed-loop rehearsal, real artifact production, export bundle health, and live demo health.
+- Added explicit claim boundary in paper-readiness plan: what can be claimed from the current prototype versus after real train/infer/eval closure.
+- Updated the Yixiao demo manual with a launch acceptance checklist and revised claim-tier language for facilitators.
+- Added one API gate-coverage regression test in `tests/test_workflow_case_study_acceptance.py` to assert readiness endpoint has all required gate IDs.
+- Added workflow evidence/export hardening:
+  - exported paths now retain provenance (`source_type`, `source_key`, `sources`) and copy-policy metadata;
+  - proposal/approval links and user status-change history are surfaced in evidence summaries;
+  - held-out/withheld ground-truth paths are treated as reference-only by default during bundle copy, while still being fully represented in `artifact_paths`;
+  - added focused bundle/artifact regression coverage for Yixiao-style `withheld_ground_truth` references.
+
+## 2026-04-10
+
+- Created this local-only progress log outside the repo Git root.
+
+## 2026-04-13
+
+- Audited the codebase against the TOCHI prototype framing for iterative biomedical image segmentation.
+- Verified the frontend production build succeeds, but with ESLint warnings and a large bundle warning.
+- Verified intended Python tests via `uv run python -m pytest -q tests`; 23 passed and 1 failed in `test_write_temp_config_uses_origin_parent_for_relative_bases`.
+- Found that plain `uv run pytest -q` collects the vendored `pytorch_connectomics` tree and fails during local package imports.
+- Found that the React package has Jest test files but no `test` npm script.
+- Created implementation branch `feat/workflow-spine` for the Workflow Spine milestone.
+- Added backend workflow spine models/API: `WorkflowSession`, `WorkflowEvent`, current workflow creation, patch/list/append events, pending agent proposals, approval, rejection, and deterministic workflow-agent fallback.
+- Wired workflow events into Neuroglancer visualization, model inference start, model training start, and EHTool dataset load/classify/save/export paths.
+- Re-enabled Mask Proofreading by restoring the EHTool surface and passing the active `workflow_id` into EHTool dataset loading.
+- Added frontend `WorkflowProvider`, API helpers, compact workflow timeline, workflow-aware chat query routing, proposal approve/reject controls, and a proofreading "Stage for retraining" action.
+- Added pytest config to keep normal project tests scoped to `tests/` and ignore vendored `pytorch_connectomics`.
+- Fixed the temp-config placement fixture to use the existing `configs/Lucchi-Mitochondria.yaml` config path.
+- Added backend tests for workflow creation/update/events, approve/reject proposal flow, and EHTool load/classify/mask-save/export event logging.
+- Verification: `uv run pytest -q tests/test_workflow_routes.py` passes with 3 tests.
+- Verification: `uv run pytest -q` passes with 27 tests; pytest now ignores vendored `pytorch_connectomics` through `pytest.ini`.
+- Verification: `uv run python -m pytest -q tests` passes with 27 tests.
+- Verification: `npm --prefix client test -- --watchAll=false` passes with 7 suites / 14 tests. The command prints a stale `baseline-browser-mapping` warning.
+- Verification: `npm --prefix client run build` completes. It still reports pre-existing ESLint warnings in FilePickerModal, YamlFileUploader, EHTool/DetectionWorkflow/ProofreadingEditor, FilesManager, and Project Manager modules, plus the existing bundle-size warning.
+- Manual browser smoke was not run in this pass; the EHTool workflow behavior is covered by backend API tests and frontend unit tests, but the full browser sequence with a human editing a mask remains a follow-up.
+- Committed implementation in two scoped commits:
+  - `2b48cf5` - `Add backend workflow spine`
+  - `fa97e5e` - `Wire workflow spine into frontend`
+- Push note: push to `sam4coding` was rejected by remote permissions; branch pushed successfully to `origin/feat/workflow-spine`.
+- Investigated the AI assistant "Network Error" path. The running API process was configured with `OLLAMA_BASE_URL=http://cscigpu08.bc.edu:11434`, `OLLAMA_MODEL=gpt-oss:20b`, and `OLLAMA_EMBED_MODEL=qwen3-embedding:8b`; that remote Ollama endpoint timed out from this machine.
+- Changed the LLM setup so chat no longer silently defaults to localhost or a hardcoded remote. `OLLAMA_BASE_URL`, `OLLAMA_MODEL`, and `OLLAMA_EMBED_MODEL` must now be exported before launch, and `OLLAMA_BASE_URL` must include an explicit service port.
+- Improved chat/helper error handling so backend LLM initialization and invocation failures return a structured user-facing message telling the user to contact their system administrator with the underlying error. The frontend now displays that message instead of raw `Network Error` where possible.
+- Verification: `uv run pytest -q tests/test_chatbot_config.py` passes with 3 tests.
+- Verification: `uv run pytest -q` passes with 30 tests.
+- Verification: `npm --prefix client test -- --watchAll=false` passes with 7 suites / 14 tests.
+- Verification: `npm --prefix client run build` completes with the existing lint and bundle-size warnings.
+- Committed and pushed LLM configuration/error-handling changes as `5a21f15` (`Improve LLM configuration errors`) to `origin/feat/workflow-spine`.
+- Diagnosed chat failure showing `AssertionError` in UI: FAISS index embedding dimension mismatch (`assert d == self.d`) when using local `nomic-embed-text` against an existing index built with a different embedding model.
+- Implemented chatbot resilience fix: if semantic retrieval fails, disable RAG for the process and transparently fall back to keyword-based documentation search instead of failing the request.
+- Verification: direct `build_chain().invoke(...)` no longer crashes under local `OLLAMA_MODEL=llama3.2:1b` and `OLLAMA_EMBED_MODEL=nomic-embed-text`.
+- Committed and pushed fix as `10d7766` (`Fallback to keyword docs when RAG retrieval fails`) to `origin/feat/workflow-spine`.
+- Added high-visibility backend chat logging (local working tree) to diagnose stalls:
+  - Request IDs for `/chat/query` and `/chat/helper/query`.
+  - Start/end timing logs with query/history sizes.
+  - Periodic progress heartbeat every ~5s while waiting for `chain.invoke(...)`.
+  - Helper/main chain initialization reuse/latency logs.
+  - Tool-level duration logs for doc search and training/inference delegation.
+  - Exception logs now include type/repr + traceback in chat paths.
+- Local environment setup for LLM chat:
+  - Verified local Ollama daemon is reachable at `http://127.0.0.1:11434`.
+  - Pulled small local chat model `llama3.2:1b` and embedding model `nomic-embed-text`.
+  - Added persistent shell exports in `~/.zshrc`:
+    - `OLLAMA_BASE_URL=http://127.0.0.1:11434`
+    - `OLLAMA_MODEL=llama3.2:1b`
+    - `OLLAMA_EMBED_MODEL=nomic-embed-text`
+  - Smoke-verified backend startup with these env vars on API port `4247`.
+  - Verification: `GET /health` returned `{"status":"ok"}`.
+  - Verification: `GET /chat/status` returned `{"configured":true,"error":null}`.
+- Rewrote manuscript Section 3/4 to foreground agentic collaboration:
+  - Added explicit agentic domain goal `G6` and autonomy requirement `R9`.
+  - Added draft task `T7` for bounded multi-step agent orchestration.
+  - Reframed Section 4 around agentic interaction modes (`M1` on-demand guidance, `M2` approve-then-execute, `M3` draft bounded autonomy).
+  - Added a new feature mapping table (`Feature x Status x Agentic Function x G/R/T`) in Section 4.
+  - Marked all future autonomy features as draft/ideation, not implemented.
+- Rewrote Introduction framing/contributions to position the assistant as a workflow harness rather than chat-only UI.
+- Re-rendered manuscript PDF after each text-edit round via `latexmk -pdf -interaction=nonstopmode sample-manuscript.tex`.
+- Manuscript styling update: removed explicit "implemented/draft/not yet implemented" status language from Sections 3/4 and feature table so the paper text reads as an integrated system design narrative.
+- Internal-only status tracking retained in local notes (`progress-log.md`, `research-log.md`) for implementation reality and planning.
+- Read/synthesized 9 recent TOCHI papers from local PDFs to extract writing structure patterns (contribution framing, question-driven sectioning, discussion/limitations calibration, and evidence traceability).
+- Applied a TOCHI-style manuscript revision pass:
+  - Added formative analysis questions (`FQ1`, `FQ2`) in Section 3.
+  - Added a Goal→Requirement→Task traceability table (`tab:grt-traceability`).
+  - Tightened Section 4 architecture framing with explicit workflow-state/agent-mediation/controlled-execution layers.
+  - Expanded Section 5 from placeholder bullets into a rigorous evaluation protocol (`EQ1`--`EQ3`, study phases, measures, analysis plan).
+- Recompiled manuscript PDF after each edit pass: `sample-manuscript.pdf` updated successfully (citations still unresolved as expected with placeholder keys).
+- Added internal synthesis artifact for later paper-assistant handoff: `/Users/adamg/seg.bio/pytc-client-codex-notes/tochi-writing-synthesis.md`.
+- Expanded manuscript prose substantially to better match recent TOCHI article length/style:
+  - Section 3: added richer formative-method detail, workflow breakdown taxonomy (B1--B5), and stronger narrative linking observations to requirements.
+  - Section 4: added architecture overview, deeper mode descriptions (M1--M3), fuller feature realization text (including F9--F11), and a closed-loop interaction walkthrough.
+  - Section 5: retained structured evaluation protocol and now sits within a fuller narrative flow.
+  - Added substantive draft text for `Discussion` and `Limitations/Conclusions` with explicit `\grace{TODO...}` anchors for user-fill details.
+- Re-rendered manuscript after this text expansion: `sample-manuscript.pdf` now builds to 22 pages.
+- Compile status remains: unresolved citation keys (expected placeholders), plus minor overfull/underfull box warnings in dense table/evaluation lines.
+- Corrected overclaim issue in manuscript: removed language implying interviews were already completed.
+- Reframed Section 3 as an explicit planned two-phase case study:
+  - Phase I requirements interviews (derive/validate goals, requirements, tasks),
+  - Phase II prototype user study (evaluate requirement coverage and agentic workflow support).
+- Added clearer cross-phase analysis narrative showing how Phase I outputs constrain Phase II evaluation claims.
+- Updated introduction/contribution wording to match pre-data status and avoid empirical-result claims.
+- Re-rendered manuscript PDF again; current output is 23 pages with expected placeholder citation warnings.
+
+## 2026-04-13 - Codex Draft PR Consolidation Wave
+
+- Created clean integration worktree/branch from `origin/feat/workflow-spine`:
+  - worktree: `/Users/adamg/seg.bio/pytc-client-codex-integration`
+  - branch: `feat/codex-wave-integration`
+- Ported codex draft outputs into existing architecture (behavior-first, no `server_api/workflow/*` path adoption):
+  - Backend:
+    - added hotspots + impact preview in workflow router,
+    - added `GET /api/workflows/{id}/metrics`,
+    - added `POST /api/workflows/{id}/export-bundle`,
+    - added workflow evidence utility modules (`metrics.py`, `bundle_export.py`, `evidence_export.py`) and research doc.
+  - Chat observability:
+    - added request lifecycle summary logger (`server_api/chatbot/logging_utils.py`),
+    - added request-id/duration/status/error summary logging in `/chat/query` and `/chat/helper/query`,
+    - retained progress-heartbeat style prints for long-running chain invocation diagnostics.
+  - Frontend:
+    - added workflow timeline actor/event filters,
+    - added richer pending-proposal cards with structured fields + approve/reject controls,
+    - wired workflow insights loading (`hotspots`, `impactPreview`) through `WorkflowContext`.
+- Added/updated tests:
+  - backend: `test_workflow_metrics.py`, `test_workflow_export_bundle.py`, `test_workflow_evidence_export.py`, `test_workflow_spine_smoke.py`, `test_chat_logging_fields.py`, expanded `test_workflow_routes.py`,
+  - frontend: `agentProposalCards.test.js`, `workflowTimelineFilters.test.js`, updated workflow timeline/context tests.
+- Verification run in integration worktree:
+  - `python3 -m pytest -q tests/test_workflow_routes.py tests/test_workflow_spine_smoke.py tests/test_chat_logging_fields.py tests/test_workflow_metrics.py tests/test_workflow_export_bundle.py tests/test_workflow_evidence_export.py`
+    - result: `2 passed, 5 skipped` (dependency-gated skips in this shell),
+  - `npm --prefix client test -- --watchAll=false --runInBand`
+    - result: `9 passed`,
+  - `npm --prefix client run build`
+    - result: success (existing unrelated eslint warnings remain).
+- Commit split on integration branch:
+  - `0bfcee9` `feat(workflows): add hotspots insights, metrics, and export bundle`
+  - `74c0d3e` `feat(chat): add request lifecycle observability logs`
+  - `ecc2493` `feat(chat-ui): add timeline filters and proposal cards`
+  - `0ace093` merge sync from `origin/main` with conflict resolution preserving required-env chatbot behavior.
+- Pushed branch and opened consolidated draft PR:
+  - https://github.com/PytorchConnectomics/pytc-client/pull/165
+- Closed codex source draft PRs `#139`-`#164` (codex branches) with redirect comment to PR `#165` for single-threaded review.
+
+## 2026-04-15 - Local Integration Launcher
+
+- Added temporary local-only helper script for manually running the integration worktree:
+  - `/Users/adamg/seg.bio/pytc-client-codex-integration/.local/play-integration.sh`
+- Added worktree-local exclude entry so `.local/` stays out of git for this worktree.
+- Purpose:
+  - single-command local start/stop/status/logs while `scripts/start.sh` and Electron remain brittle on `feat/codex-wave-integration`.
+- Cleanup note:
+  - remove this helper before any commit from the integration worktree, or keep it strictly local-only and untracked.
+
+## 2026-04-16 - Mainline Moved Past Codex Integration Branch
+
+- Fetched remote state and updated branch understanding after new merge to `origin/main`.
+- `origin/main` now points to:
+  - `5aa4eaa` `Fix PR 166 runtime cleanup and chatbot test collection`
+- Additional recent mainline commits ahead of the old codex integration base:
+  - `e8ecce8` `fixed isue with incorrect arguments for triaingin`
+  - `9cf43fc` `put training, inference, eval info into rag docs`
+- Important consequence:
+  - the codex consolidation branch `feat/codex-wave-integration` was **not** merged into `main`;
+  - draft PR `#165` remains open/draft;
+  - `origin/main` and `origin/feat/codex-wave-integration` now diverge substantially.
+- Operational interpretation:
+  - authoritative branch for new work/testing is now `origin/main` plus any fresh feature branch cut from it;
+  - the integration worktree remains useful as a reference branch for selectively porting codex workflow features forward, but should not be treated as current truth.
+- Local caveat:
+  - the integration worktree also has local-only runtime fixes (`pyproject.toml`, `uv.lock`) that were made to get it booting on this machine and are not part of remote `feat/codex-wave-integration`.
+
+## 2026-04-16 - Workflow Wave Forward-Port Onto Current Main
+
+- Created fresh branch from current mainline in primary checkout:
+  - branch: `feat/workflow-wave-forward-port`
+  - base: `origin/main` at `5aa4eaa`
+- Forward-ported the useful codex workflow-wave commits in dependency order:
+  - `2b48cf5` backend workflow spine
+  - `0bfcee9` workflow metrics/export/hotspots/evidence
+  - `74c0d3e` chat request lifecycle logging
+  - `fa97e5e` frontend workflow spine
+  - `ecc2493` timeline filters + proposal cards
+- Resolved drift against current mainline:
+  - kept current `server_api.main` chatbot/runtime behavior while layering workflow and logging hooks,
+  - kept current frontend layout (no project-manager tab resurrection),
+  - fixed test path drift in `Views.test.js` and `MaskProofreading.test.js`.
+- Fixed editable dependency packaging mismatch in repo proper:
+  - `pyproject.toml` now references editable package name `connectomics`
+  - refreshed `uv.lock`
+- Verification on forward-port branch:
+  - `npm --prefix client test -- --watchAll=false --runInBand`
+    - result: `9 passed`
+  - `npm --prefix client run build`
+    - result: success with existing unrelated eslint warnings
+  - `uv run pytest -q tests/test_workflow_routes.py tests/test_workflow_spine_smoke.py tests/test_chat_logging_fields.py tests/test_workflow_metrics.py tests/test_workflow_export_bundle.py tests/test_workflow_evidence_export.py`
+    - result: `11 passed`
+  - `uv run pytest -q tests/test_pytc_runtime_routes.py tests/test_worker_model_service.py`
+    - result: `13 passed`
+- Current interpretation:
+  - this fresh branch is the right candidate for review instead of stale PR `#165`.
+
+## 2026-05-03 - Workflow Context and Agent Orchestration Hardening
+
+- Investigated the project-context ingestion path after the visualization UI kept surfacing stale `30,6,6` voxel scales.
+- Removed remaining live coupling where viewer-loaded visualization scales were written back into `metadata.project_context.voxel_size_nm`; viewer scale choices now stay in `metadata.visualization_scales` with a visualization-specific source.
+- Hardened workspace reset/new-workflow behavior:
+  - frontend reset effects clear local training/inference/visualization inputs,
+  - workflow metadata clears `project_context`, `visualization_scales`, `active_volume_pair`, and marks `needs_project_context`,
+  - new workflow startup also clears local workflow form state.
+- Tightened project-context sidecar access:
+  - `GET/PUT/DELETE /files/project-context` now require the requested directory to be a managed upload path or mounted root/descendant for the current user,
+  - tests now mount temp project roots before saving/deleting project context profiles.
+- Fixed approval semantics for assistant cards:
+  - risky non-training cards now create `run_client_effects` approval proposals instead of directly executing,
+  - training proposals still create durable `start_training_run` commands,
+  - approval cards show generic app-action proposal details.
+- Connected approved durable training commands to the command runner:
+  - frontend approval now runs UI prefill effects with `runtime_action` stripped,
+  - backend command runner records accepted training launches as `submitted` instead of `completed`,
+  - `WorkflowCommand` accepts the new `submitted` status.
+- Reduced stale chat-card risk:
+  - persisted workflow-agent chat messages now store `workflow_id`,
+  - loading a conversation strips actions/commands/proposals from assistant messages bound to a different workflow,
+  - workflow-agent queries refresh workflow state and recommendation after the backend mutates context.
+- Narrowed chatbot routing so arbitrary nonempty text no longer always goes through the workflow orchestrator; greetings, slash commands, and workflow/domain language still route to the workflow agent.
+- Added coverage:
+  - risky non-training app cards must create approval proposals before running,
+  - stale workflow-bound chat history must not render runnable cards,
+  - `run_client_effects` backend approvals return client effects without creating commands,
+  - durable training commands now assert `submitted`.
+- Verification:
+  - `.venv/bin/python -m py_compile server_api/main.py server_api/workflows/router.py server_api/workflows/service.py server_api/auth/router.py server_api/auth/models.py` passed.
+  - `npm test -- --runTestsByPath src/components/Chatbot.test.js src/contexts/WorkflowContext.test.js src/__tests__/agentProposalCards.test.js --watchAll=false` passed: 30 tests.
+  - `.venv/bin/python -m pytest tests/test_pytc_runtime_routes.py tests/test_file_workspace_routes.py tests/test_workflow_routes.py -q` passed: 81 tests, 5 subtests.
+  - `npm run build` passed with existing EHTool hook dependency warnings.
+- Operational state:
+  - restarted the local API server from this checkout on port `4242` via detached `setsid` launch so the backend changes are live.
+  - follow-up repair after browser 502s: `demo.seg.bio` nginx proxies `/api/` to `127.0.0.1:4342`, so started a demo API process with `PYTC_API_PORT=4342`, `PYTC_NEUROGLANCER_PORT=4344`, and `PYTC_WORKER_URL=localhost:4243`.
+  - deployed `client/build/` to `/var/www/demo.seg.bio`; public `demo.seg.bio` now serves `main.e67c5997.js`.
+  - verified public routes after repair: `https://demo.seg.bio/api/api/workflows/current`, `https://demo.seg.bio/api/files?parent=root`, and `https://demo.seg.bio/api/files/project-suggestions` returned `200`.
+- Remaining known gap:
+  - generic non-training client actions are approval-gated, but still execute through client effects after approval; deeper durable command coverage is still needed for inference/proofreading/export/reset.
+
+## 2026-05-03 - Project Setup Context Editing
+
+- Updated the start-project confirmation modal so absorbed project context is editable item by item before confirmation.
+- Replaced the read-only generic context chips with editable concrete assumptions:
+  - imaging modality,
+  - target structure,
+  - voxel size in z/y/x nm,
+  - freeform notes.
+- Removed generic "goal", "data", "priority", and "labels" from the project brief display and generated summary because they were acting like boilerplate for every imported project.
+- Stopped inventing `task_goal`, `data_unit`, and `optimization_priority` defaults from folder profiles; project suggestions now only provide concrete context defaults from content hints such as modality, target, and voxel size.
+- Confirmation now stores the edited context into workflow metadata and uses edited voxel size to set `metadata.visualization_scales`.
+- Verification:
+  - `npm test -- --runTestsByPath src/views/FilesManager.test.js src/utils/projectSuggestions.test.js --watchAll=false` passed: 21 tests.
+  - `npm run build` passed with existing EHTool hook dependency warnings.
+- Operational state:
+  - deployed the rebuilt frontend to `/var/www/demo.seg.bio`; public `demo.seg.bio` now serves `main.92eb5817.js`.
+
+## 2026-05-03 - Chat Log Failure Follow-Up Routing and LLM Defaults
+
+- Investigated the browser-side `/api/chat/query` 503s from the public demo using `.logs/app/app-events.jsonl` and `.logs/start/demo-api-server.log`.
+- Root cause:
+  - the UI routed workflow follow-ups like "can we take a look at it first?" and "what?" to generic docs chat instead of the workflow orchestrator,
+  - generic docs chat was launched without Ollama env vars and fell back to stale defaults (`llama3.1:8b` and `nomic-embed-text:latest`), while the installed local models are `qwen3.5:9b` and `qwen3-embedding:8b`.
+- Fixed frontend chat routing so short contextual follow-ups after a `workflow_orchestrator` response stay with the workflow agent, while first-message unrelated gibberish still routes to generic chat/direct guard.
+- Hardened generic chat backend behavior:
+  - `/chat/query` now returns a plain degraded assistant response with `source=llm_unavailable` instead of a raw 503 when the docs LLM cannot initialize or invoke,
+  - `/chat/clear` no longer initializes the LLM, because clearing memory should work even when docs chat is down.
+- Aligned local defaults and launch scripts with the bundled FAISS index and installed models:
+  - `DEFAULT_OLLAMA_MODEL=qwen3.5:9b`,
+  - `DEFAULT_OLLAMA_EMBED_MODEL=qwen3-embedding:8b`,
+  - updated `scripts/start.sh`, `scripts/dev.sh`, `rag_eval.py`, and README notes.
+- Verification:
+  - `npm test -- --runTestsByPath src/components/Chatbot.test.js --watchAll=false` passed: 17 tests.
+  - `.venv/bin/python -m pytest -q tests/test_workflow_routes.py -k 'general_chat or clear_chat'` passed: 4 tests.
+  - `.venv/bin/python -m pytest -q tests/test_chatbot_faiss_generation.py` passed: 11 tests.
+  - `.venv/bin/python -m py_compile server_api/main.py server_api/chatbot/chatbot.py server_api/chatbot/update_faiss.py server_api/chatbot/rag_eval.py` passed.
+  - `npm run build` passed with existing EHTool hook dependency warnings.
+- Operational state:
+  - deployed the rebuilt frontend to `/var/www/demo.seg.bio`; public `demo.seg.bio` now serves `main.fae73634.js`.
+  - restarted the public demo API on port `4342` with `OLLAMA_BASE_URL=http://127.0.0.1:11434`, `OLLAMA_MODEL=qwen3.5:9b`, and `OLLAMA_EMBED_MODEL=qwen3-embedding:8b`.
+  - verified `https://demo.seg.bio/api/chat/status` returns `{"configured":true,"error":null}`.
+  - verified public generic chat returns `200` from `https://demo.seg.bio/api/chat/query` and `/chat/clear` returns `200`.
+
+## 2026-05-03 - Comprehensive Runtime Logging and Neuroglancer HTTPS Repair
+
+- Investigated the black Neuroglancer viewer reported from the public demo.
+- Root cause from logs + browser screenshot:
+  - `/api/neuroglancer` succeeded and resolved folder inputs to concrete HDF5 volumes,
+  - the returned viewer URL was `http://demo.seg.bio:4344/v/...`,
+  - the app was loaded from `https://demo.seg.bio`, so the browser blocked the iframe as mixed content.
+- Repaired the public runtime contract:
+  - restarted the public API on port `4342` with `PYTC_NEUROGLANCER_PUBLIC_BASE=https://demo.seg.bio/neuroglancer`,
+  - verified `/api/neuroglancer` now returns `https://demo.seg.bio/neuroglancer/v/...`,
+  - verified the HTTPS proxied Neuroglancer HTML and bundle load through nginx/Cloudflare.
+- Expanded frontend runtime logging in `client/src/logging/appEventLog.js`:
+  - console output is captured by default,
+  - fetch and XMLHttpRequest request/response/failure events are logged,
+  - DOM clicks, form/input/change/key/focus/drag/drop/paste events are logged with sanitized target metadata,
+  - resource load failures and resource timing entries are logged,
+  - navigation, hash/history changes, focus/blur, online/offline, visibility, and postMessage events are logged.
+- Expanded visualization-specific logging:
+  - viewer URL receipt,
+  - mixed-content detection before iframe mount,
+  - iframe mount/load/error events,
+  - viewer load failures with paths, scales, workflow id, and error detail.
+- Expanded backend Neuroglancer logging:
+  - `neuroglancer_request_prepared` captures requested paths, scales, workflow id, content type, host/forwarded headers, and configured public base,
+  - `neuroglancer_viewer_created` captures internal viewer URL, public URL, scheme, bind host/port, resolved paths, volume shapes, scales, and workflow id.
+- Verification:
+  - `npm test -- --runTestsByPath src/components/Chatbot.test.js src/views/FilesManager.test.js --watchAll=false` passed: 27 tests.
+  - `.venv/bin/python -m py_compile server_api/main.py` passed.
+  - `.venv/bin/python -m pytest -q tests/test_neuroglancer_url_contract.py tests/test_runtime_settings.py tests/test_neuroglancer_volume_normalization.py` passed: 18 tests.
+  - `npm run build` passed with existing EHTool hook dependency warnings.
+  - deployed `client/build/` to `/var/www/demo.seg.bio`; public `demo.seg.bio` now serves `main.ee2e6427.js`.
+  - smoke-posted `/api/app/log-event`; event appeared in `.logs/app/app-events.jsonl`.
+
+## 2026-05-03 - Restore Workflow Action Cards for Plain Data-Viewing Requests
+
+- Investigated why "can we view some data" produced a plain docs answer instead of the workflow agent's executable "View data" card.
+- Logs showed the regression clearly:
+  - client event `llm_chat_sent`,
+  - `workflowId=58`,
+  - query preview `can we view some data`,
+  - request went to `/api/chat/query` instead of the workflow orchestrator.
+- Root cause: client-side workflow routing covered `visualize`, `viewer`, and concrete object words, but missed plain action phrases like `view some data`.
+- Added workflow-agent action regexes for direct app routines:
+  - `view/show/open/inspect/see ... data|volume|image|label|mask|segmentation`,
+  - `look at ... data|volume|image|label|mask|segmentation`,
+  - `run/start/launch ... app|model|inference|training|proofread|viewer|visualization`.
+- Added frontend coverage asserting `can we view some data` routes to `queryAgent`, not generic chat, and renders the `View data` action card with `Run in app`.
+- Verification:
+  - `npm test -- --runTestsByPath src/components/Chatbot.test.js --watchAll=false` passed: 18 tests.
+  - `npm run build` passed with existing EHTool hook dependency warnings.
+- Operational state:
+  - deployed rebuilt frontend to `/var/www/demo.seg.bio`; public `demo.seg.bio` now serves `main.db5029c5.js`.
+
+## 2026-05-03 - Make Active Workflow Chat Default to Runnable Orchestrator
+
+- Investigated the follow-up regression where `can we vis some data` still produced a generic docs response.
+- Logs showed the exact failure:
+  - `dom_keydown` captured the submitted text,
+  - client emitted `llm_chat_sent` with `workflowId=61`,
+  - the request went to `/api/chat/query` instead of the workflow orchestrator,
+  - generic docs chat took ~27s and returned instructions instead of action cards.
+- Changed active-workflow chat routing so readable messages default to the workflow orchestrator when a workflow is mounted; only obvious single-token gibberish still goes to generic chat/direct guard.
+- Added explicit client routing support for shorthand visualization language:
+  - `vis`,
+  - `viz`,
+  - `view/show/open/inspect/see ... data|volume|image|label|mask|segmentation`.
+- Added backend workflow-agent visualization detection for `vis`/`viz` so direct API calls also produce `open-visualization` actions.
+- Added coverage:
+  - `can we vis some data` routes to `queryAgent`, not generic chat, and renders `View data` with `Run in app`,
+  - readable active-workflow requests such as `can you help me figure this out` route to the orchestrator by default,
+  - backend `/agent/query` maps `can we vis some data` to `intent=view_data` and `open-visualization`.
+- Verification:
+  - `npm test -- --runTestsByPath src/components/Chatbot.test.js --watchAll=false` passed: 20 tests.
+  - `.venv/bin/python -m pytest -q tests/test_workflow_routes.py -k visualize_request_populates_viewer_paths_not_status` passed: 1 test.
+  - `.venv/bin/python -m py_compile server_api/workflows/router.py` passed.
+  - `npm run build` passed with existing EHTool hook dependency warnings.
+- Operational state:
+  - deployed rebuilt frontend to `/var/www/demo.seg.bio`; public `demo.seg.bio` now serves `main.b529ca4e.js`.
+  - restarted the public API on port `4342` with the same Neuroglancer and Ollama env vars.
+  - verified public `POST /api/api/workflows/61/agent/query` with `can we vis some data` returns `source=workflow_orchestrator`, `intent=view_data`, and an `open-visualization` action with `run_label=Run in app`.
+
+## 2026-05-03 - Keep Agent-Launched Neuroglancer Viewers Alive
+
+- Investigated why `Run in app` from the assistant's `View data` action card opened a black Neuroglancer iframe while the form path was healthier.
+- Logs and direct curls showed the generated viewer token was already `404` at `127.0.0.1:4344` immediately after `/api/neuroglancer` returned.
+- Root cause: Neuroglancer's Python server stores viewers in a weak-reference map; `server_api.main` created a local `neuroglancer.Viewer()` and returned its URL without keeping a strong server-side reference.
+- Added a bounded, expiring in-memory viewer registry in `server_api/main.py`:
+  - retains visualization and proofreading viewers after URL creation,
+  - defaults to 12 live viewers for 2 hours,
+  - evicts old viewers by TTL/capacity,
+  - logs `neuroglancer_viewer_retained` with token, mode, paths, count, TTL, and evictions.
+- Hardened `/neuroglancer` JSON parsing to accept `image_path`/`imagePath` aliases and return `400` for missing image/scales instead of throwing a raw `KeyError`.
+- Verification:
+  - `.venv/bin/python -m py_compile server_api/main.py` passed.
+  - `.venv/bin/python -m pytest -q tests/test_neuroglancer_url_contract.py` passed: 5 tests.
+  - restarted public API as PID `1794274` on port `4342` with `PYTC_NEUROGLANCER_PUBLIC_BASE=https://demo.seg.bio/neuroglancer`.
+  - public `POST /api/neuroglancer` returned viewer `51d03712242b656c17f3985287555c380968cfe4`.
+  - verified public and local viewer HTML, `main.bundle.js`, `main.bundle.css`, and `?refresh=...` iframe URLs all return `200`.
+
+## 2026-05-03 - Repair Assistant Choose-Data Actions and Stale File Trees
+
+- Investigated the report that the assistant's `Choose data` Run in app action only opened Files and did not provide a way to choose training/visualization volumes.
+- Investigated why mounted project folders appeared empty after earlier workspace/index resets.
+- Log evidence:
+  - browser session kept clicking old folder ids such as `/files?parent=5`, `/files?parent=4`, and `/files?parent=3`;
+  - those ids were no longer present in the server file index, but the API previously returned `200 []`, so the stale client tree looked like real empty folders.
+- Backend fix:
+  - `/files?parent=<id>` now validates that non-root parents still exist as folders for the current user;
+  - missing/stale parents return `404 Folder is no longer mounted or indexed: <id>` instead of an empty list.
+- Files UI fix:
+  - root and active folder refreshes now force-fetch on initial load, focus, and visibility restore;
+  - stale parent 404s log `files_parent_missing_refreshed`, remove the stale subtree, and refresh root;
+  - fresh root/current-folder loads reconcile the active folder if it was removed by server truth.
+- Assistant action fix:
+  - workflow `Choose data` / `Choose labels` actions now include `runtime_action.kind=choose_project_data`;
+  - Files consumes that runtime action by opening the project setup/data mapping confirmation, preferring mounted/recommended projects and falling back to mounted root folders;
+  - the action risk is now `prefills_form`, so the card badge displays `sets form` instead of `view only`.
+- Verification:
+  - `npm test -- --runTestsByPath src/views/FilesManager.test.js --watchAll=false` passed: 11 tests.
+  - `npm test -- --runTestsByPath src/components/Chatbot.test.js --watchAll=false` passed: 20 tests.
+  - `.venv/bin/python -m pytest -q tests/test_file_workspace_routes.py -k 'missing_parent_file_listing_returns_404 or mount_directory_skips_os_metadata_files'` passed: 2 tests.
+  - `.venv/bin/python -m pytest -q tests/test_workflow_routes.py -k 'agent_train_model_names_missing_label_blocker or visualize_request_populates_viewer_paths_not_status'` passed: 2 tests.
+  - `.venv/bin/python -m py_compile server_api/auth/router.py server_api/workflows/router.py` passed.
+  - `npm run build` passed; remaining warnings are pre-existing EHTool hook dependency warnings.
+- Operational state:
+  - deployed rebuilt frontend to `/var/www/demo.seg.bio`; public `demo.seg.bio` now serves `main.45fb31fd.js`.
+  - restarted public API as PID `1860978` on port `4342`.
+  - verified `GET /health` returns OK.
+  - verified `GET /files?parent=999999` returns `404`.
+  - verified public `asset-manifest.json` references `main.45fb31fd.js`.
+
+## 2026-05-03 - Add Read-Only Project Observation to Workflow Agent
+
+- Addressed the core architecture gap highlighted by the chat: the workflow agent was answering mostly from workflow fields and cached context instead of probing the mounted project before responding.
+- Added a read-only project observation pass to every workflow-agent query:
+  - derives candidate project roots from `workflow.dataset_path`, current workflow file paths, and mounted root folders;
+  - scans candidate roots with the existing `_scan_project_profile()` project profiler;
+  - extracts observed volume sets with absolute image/label paths, role counts, current-set markers, roots, and context hints;
+  - stores a compact `metadata.project_observation` ledger with `observed_at`, roots, volume sets, errors, and current markers;
+  - logs `project_observed` app events with root and volume-set counts.
+- Extended semantic workflow state with the observed project summary so future semantic routing can see discovered volume sets, not only static workflow fields.
+- Added alternate data-set handling:
+  - detects phrasing like `another aptly named pair`, `other set`, `different pair`, etc.;
+  - forces these requests into `view_data` instead of letting `image and seg` drift into segmentation/model-launch context collection;
+  - selects a non-current observed image/seg volume set when one exists;
+  - bases "current set" primarily on the image root so shared label folders do not incorrectly mark every set as current.
+- Result for the screenshot-style query:
+  - the agent should inspect the project tree, find the alternate image/seg set, populate the visualization action with that set's paths, and avoid asking for modality/target/priority again.
+- Verification:
+  - `.venv/bin/python -m py_compile server_api/workflows/router.py` passed.
+  - `.venv/bin/python -m pytest -q tests/test_workflow_routes.py -k 'alternate_volume_set or visualize_request_discovers_directory_pairs or visualize_request_populates_viewer_paths_not_status'` passed: 3 tests.
+  - `.venv/bin/python -m pytest -q tests/test_workflow_routes.py` passed: 41 tests.
+- Operational state:
+  - restarted the public API as PID `1908400` on port `4342`.
+  - verified local `GET /health` and public `GET /api/health` return OK.
+  - did not mutate the live demo workflow for a synthetic smoke because the unauthenticated current workflow was empty after page reload.
+
+## 2026-05-03 - Humanize Workflow Agent Responses and Add Inspectable Traces
+
+- Addressed the regression where the workflow agent sounded like an internal planner:
+  - converted rigid `Do this` / `Why` / `Current read` style strings into normal chat responses while preserving rationale and recommendation wording;
+  - kept runnable app cards and command blocks intact so the agent can still propose direct `Run in app` routines;
+  - added a collapsed `What I checked` trace in chat for observable context such as workflow state, project file scans, and prepared app cards.
+- Persisted trace data in chat history:
+  - added `chat_messages.trace_json`,
+  - includes `trace` on conversation message responses and workflow-agent query responses,
+  - clears trace/actions/commands/proposals from stale loaded messages that belong to another workflow.
+- Added project-file overview behavior:
+  - queries like `what exactly are the files in my directory?` now use the read-only project observation instead of falling into generic status or validation cards;
+  - the response summarizes top-level entries, detected workflow artifacts, and observed image/seg volume sets without showing a misleading action card.
+- Tightened local model selection:
+  - kept `qwen3.5:9b` as the default local workflow-intent model after a quick current-source check for small-model tool calling;
+  - changed the semantic intent fallback from `qwen2.5:32b` to `qwen3.5:9b`;
+  - exported `PYTC_WORKFLOW_INTENT_MODEL=${OLLAMA_MODEL}` in start scripts and documented it in the README.
+- Verification:
+  - `.venv/bin/python -m py_compile server_api/workflows/router.py server_api/auth/models.py server_api/main.py` passed.
+  - `.venv/bin/python -m pytest tests/test_workflow_routes.py -q` passed: 42 tests.
+  - `npm test -- --runTestsByPath src/components/Chatbot.test.js --watchAll=false` passed: 21 tests.
+  - `npm run build` passed with the existing EHTool hook dependency warnings.
+- Operational state:
+  - deployed rebuilt frontend to `/var/www/demo.seg.bio`; public `demo.seg.bio` now serves `main.e7661a66.js`.
+  - restarted the public API as PID `1992825` on port `4342` with `PYTC_WORKFLOW_INTENT_MODEL=qwen3.5:9b`.
+  - verified local `GET /health` and public `GET /api/health` return OK.
+  - verified live SQLite schema has `chat_messages.trace_json`.
+
+## 2026-05-03 - Workflow-Native Project Progress Tracker
+
+- Revisited the main-branch Project Manager lineage after the user pointed at the main commits page:
+  - main currently contains `9973906` (`Add project manager core`) and earlier PM commits;
+  - used the old `ProjectManager`, `VolumeTracker`, and `ProjectManagerContext` as reference only, because the demo app now needs workflow-session-native tracking instead of the old login/RBAC PM surface.
+- Added backend workflow project-progress support:
+  - new `GET /api/workflows/{workflow_id}/project-progress` endpoint;
+  - new `POST /api/workflows/{workflow_id}/project-progress/volume-status` endpoint for per-volume manual status overrides;
+  - project observation now feeds a volume-level tracker that classifies images as `ground_truth`, `needs_proofreading`, `missing_segmentation`, or `ignored`;
+  - pairing uses observed image/label roots, normalized image-vs-seg names, existing labels/predictions, correction-set evidence, and ground-truth/proofread filename markers;
+  - stores a compact `metadata.project_progress_snapshot` and manual `metadata.project_progress_overrides` so both the user and agent have a shared progress reference.
+- Added frontend progress module:
+  - new top-level `Progress` tab in the workflow nav;
+  - summary cards for tracked volumes, fully good ground truth, needs proofreading, and no segmentation;
+  - completion and segmentation-coverage progress bars;
+  - filterable volume table with image path, matched segmentation path, source/kind, and editable per-volume status.
+- Updated agentic implementation:
+  - semantic routing now recognizes progress-manager language such as "project progress", "how many volumes are done", "ground truth", "unproofread", and "missing segmentation";
+  - workflow-agent responses can open the Progress tab via an `open-project-progress` app action;
+  - client effects refresh the progress snapshot when the agent routes the user there;
+  - normal agent query refresh now also refreshes project progress so the tracker stays aligned with file/project observation.
+- Verification:
+  - `.venv/bin/python -m py_compile server_api/workflows/router.py` passed.
+  - `.venv/bin/python -m pytest tests/test_workflow_routes.py -q` passed: 44 tests.
+  - `npm test -- --runTestsByPath src/views/ProjectProgress.test.js src/views/Views.test.js src/contexts/WorkflowContext.test.js src/components/Chatbot.test.js --watchAll=false` passed: 40 tests.
+  - `npm test -- --runTestsByPath src/views/ProjectProgress.test.js --watchAll=false` passed after the hook-warning cleanup: 2 tests.
+  - `npm run build` passed; remaining warnings are the pre-existing EHTool hook dependency warnings.
+- Operational state:
+  - deployed rebuilt frontend to `/var/www/demo.seg.bio`; public `demo.seg.bio` now serves `main.7dc1196c.js`.
+  - restarted the public API as PID `2088314` on port `4342` with `PYTC_WORKFLOW_INTENT_MODEL=qwen3.5:9b`.
+  - verified local `GET /health` and public `GET /api/health` return OK.
+
+## 2026-05-03 - Switch Demo Assistant Back to 32B Model
+
+- Switched the local assistant and workflow intent defaults from `qwen3.5:9b` back to the previously used 32B model:
+  - `OLLAMA_MODEL=qwen2.5:32b`,
+  - `PYTC_WORKFLOW_INTENT_MODEL=qwen2.5:32b`,
+  - `OLLAMA_EMBED_MODEL=qwen3-embedding:8b` unchanged.
+- Updated defaults in:
+  - `README.md`,
+  - `scripts/start.sh`,
+  - `scripts/dev.sh`,
+  - `server_api/chatbot/chatbot.py`,
+  - `server_api/workflows/router.py`.
+- Verification:
+  - `.venv/bin/python -m py_compile server_api/workflows/router.py server_api/chatbot/chatbot.py` passed.
+  - Direct Ollama smoke for `qwen2.5:32b` returned `OK`.
+  - restarted public API as PID `2136963` on port `4342`.
+  - verified process env has `OLLAMA_MODEL=qwen2.5:32b` and `PYTC_WORKFLOW_INTENT_MODEL=qwen2.5:32b`.
+  - verified local and public `GET /health` return OK.
+  - verified local and public `GET /chat/status` return `{"configured":true,"error":null}`.
+
+## 2026-05-03 - Humanize Visible Chat Language and Try Qwen3.6 27B
+
+- Addressed visible chat tone that still sounded like backend state formatting:
+  - changed the general chatbot response-style prompt to ask for normal conversational labmate-style replies;
+  - removed rigid prompt-leak fallback phrases such as `Do this` / `Watch out`;
+  - changed workflow-agent status, greeting, context, missing-input, and style-feedback replies away from `My read`, `Current read`, `Why this fits`, and `Tell me the job`;
+  - added a `style_feedback` workflow-agent intent so feedback like "this is robotic" is acknowledged directly instead of being misrouted to a generic greeting/status reply;
+  - kept app action cards and the expandable `What I checked` trace intact for structured details.
+- Switched the configured local assistant model again after checking current top-small-model availability:
+  - pulled `qwen3.6:27b` from Ollama successfully;
+  - changed defaults to `OLLAMA_MODEL=qwen3.6:27b` and `PYTC_WORKFLOW_INTENT_MODEL=qwen3.6:27b`;
+  - added `think=false` to the direct Ollama workflow-intent call and `reasoning=False` to LangChain `ChatOllama` construction so thinking-model output does not replace the visible final answer.
+- Verification:
+  - `.venv/bin/python -m py_compile server_api/workflows/router.py server_api/chatbot/chatbot.py` passed.
+  - Direct Ollama `/api/generate` with `qwen3.6:27b` and `think=false` returned `OK`.
+  - Direct `ChatOllama(..., reasoning=False)` invocation with `qwen3.6:27b` returned `OK`.
+  - `.venv/bin/python -m pytest tests/test_workflow_routes.py -k 'greetings_without_prompt_leakage or tone_feedback or project_file_overview' -q` passed: 3 tests.
+  - `.venv/bin/python -m pytest tests/test_workflow_routes.py -q` passed: 45 tests.
+- Operational state:
+  - restarted public API as PID `2173819` on port `4342`.
+  - verified process env has `OLLAMA_MODEL=qwen3.6:27b` and `PYTC_WORKFLOW_INTENT_MODEL=qwen3.6:27b`.
+  - verified local and public `GET /health` return OK.
+  - verified local and public `GET /chat/status` return `{"configured":true,"error":null}`.
+
+## 2026-05-03 - Seed MitoEM2.0 Progress Demo Project
+
+- Created a lightweight app-mountable MitoEM2.0 fixture at `/home/weidf/demo_data/mitoem2_progress_demo`.
+- Based it on the official Hugging Face `pytc/MitoEM2.0` `Dataset006_ME2-Pyra` metadata and source filenames without downloading the full 17.1 GB benchmark payload.
+- Initial active state:
+  - 6 tiny HDF5 raw image volumes in `data/image`;
+  - 2 active curated masks in `data/seg` that classify as `ground_truth`;
+  - 2 active draft masks in `data/seg` that classify as `needs_proofreading`;
+  - 2 image-only volumes with no active mask that classify as `missing_segmentation`.
+- Stored withheld ground-truth masks for every volume outside the mounted project root at `/home/weidf/demo_data/mitoem2_progress_demo_holdout_masks` so they do not pollute app scanning.
+- Added reset/snapshot support:
+  - snapshot archive: `/home/weidf/demo_data/mitoem2_progress_demo/snapshots/initial_state.tar.gz`;
+  - snapshot manifest with file hashes and expected progress counts: `/home/weidf/demo_data/mitoem2_progress_demo/snapshots/initial_state_manifest.json`;
+  - reset command: `cd /home/weidf/demo_data/mitoem2_progress_demo && ./reset_to_initial.sh`.
+- Verification:
+  - `_scan_project_profile` sees 6 images, 4 labels, and one `image + seg` volume set.
+  - Direct progress classification returns `{'ground_truth': 2, 'needs_proofreading': 2, 'missing_segmentation': 2}`.
+  - Reset script removes generated top-level project artifacts, restores from the snapshot archive, and preserves the snapshot directory.
+
+## 2026-05-03 - Make MitoEM2.0 Demo the Active Mounted Project
+
+- Swapped the live demo instance from `/home/weidf/demo_data/prepilot_lucchi_pp` to `/home/weidf/demo_data/mitoem2_progress_demo`.
+- App state changes:
+  - unmounted the old `prepilot_lucchi_pp` root;
+  - mounted `mitoem2_progress_demo` as the only root-level project (`mounted_root_id=1`);
+  - reset the current workflow to `MitoEM2.0 Progress Demo` (`workflow_id=87`);
+  - patched workflow paths to the new project root, `data/image`, `data/seg`, and `configs/MitoEM2-Pyra-Demo-BC.yaml`;
+  - set workflow project context and visualization scales to `30,8,8` nm.
+- Source-default changes so a restart stays on the new fixture:
+  - `server_api/auth/router.py` now recommends `mitoem2_progress_demo` first and no longer marks Lucchi or mito25 as recommended;
+  - `server_api/workflows/router.py` default mount path is now `/home/weidf/demo_data/mitoem2_progress_demo`;
+  - `server_api/workflows/service.py` initial project defaults now use the MitoEM2 image/seg roots, config, project context, and scale metadata;
+  - `client/src/views/FilesManager.js` fallback remote project path now points at the MitoEM2 fixture.
+- Verification:
+  - backend compile passed for `server_api/auth/router.py`, `server_api/workflows/router.py`, and `server_api/workflows/service.py`;
+  - restarted API as PID `2385097` with `PYTC_INITIAL_PROJECT_ROOT=/home/weidf/demo_data/mitoem2_progress_demo` and `qwen3.6:27b`;
+  - `GET /health` and `GET /chat/status` are OK;
+  - `GET /files/project-suggestions` shows `mitoem2_progress_demo` as the only recommended and already-mounted suggestion;
+  - `GET /api/workflows/87/project-progress` returns 6 tracked volumes: 2 ground truth, 2 needs proofreading, 2 missing segmentation.
+
+## 2026-05-03 - Deploy Mount Project Button Default to MitoEM2.0
+
+- Clarified that the user wanted the actual web `Mount Project` button fallback to target the MitoEM2.0 fixture the same way it previously targeted `prepilot_lucchi_pp`.
+- Rebuilt the React frontend after the `DEFAULT_REMOTE_PROJECT_PATH` source change and deployed it to `/var/www/demo.seg.bio`.
+- Public bundle now serves `main.a8775384.js` and contains `/home/weidf/demo_data/mitoem2_progress_demo` with no compiled `prepilot_lucchi_pp` fallback.
+- Cleaned up a stale Lucchi mount that was reintroduced by the old bundle before refresh; root-level file state now contains only `MitoEM2.0 Progress Demo`.
+- Verification:
+  - `https://demo.seg.bio/` references `./static/js/main.a8775384.js`;
+  - direct bundle check finds `/home/weidf/demo_data/mitoem2_progress_demo`;
+  - `POST /files/mount` with the MitoEM2 path returns existing `mounted_root_id=1`;
+  - `GET /files/project-suggestions` shows MitoEM2 as recommended/already-mounted and Lucchi as not mounted.
+
+## 2026-05-03 - Progress-Aware Multi-Volume Training Agent
+
+- Fixed the workflow agent intent precedence that made training requests containing phrases like “ground truth” or “no segmentation” fall into the progress-tracker response path.
+- Added progress-aware training subset staging:
+  - when the user asks to train from ground truth / fully good volumes / segment the rest, the agent now reads the project progress state;
+  - creates a clean training subset outside the mounted project root under `/home/weidf/demo_data/.pytc_training_subsets/<project>/<run>/`;
+  - links/copies only the selected training image/seg pairs into `image/` and `seg/`;
+  - writes `volume_subset_manifest.json` with selected training pairs, image-only inference targets, excluded draft masks, and the source progress counts;
+  - routes the training run card to the subset directories while preserving the project config and project-root training output path.
+- Fixed training config selection so an explicit workflow `config_path` is used as-is. The MitoEM2 demo now proposes `/home/weidf/demo_data/mitoem2_progress_demo/configs/MitoEM2-Pyra-Demo-BC.yaml` instead of falling back to the older MitoEM case-study default.
+- Updated training approval payload/cards to include `training_volume_subset`, so the UI can show why a run uses a particular subset.
+- Tightened user-facing copy for this path so the assistant says plainly what it found and what it will train on instead of returning a “Do this / Why” checklist.
+- Verification:
+  - `.venv/bin/python -m py_compile server_api/workflows/router.py` passed;
+  - `.venv/bin/python -m pytest tests/test_workflow_routes.py -k "ground_truth_progress_subset or project_progress_counts or opens_project_progress or train_model_from_current_labels or start_training_uses_data_derived_defaults or approved_training_run"` passed: 6 tests;
+  - after narrowing the progress-subset trigger so generic “saved edits” retraining is not hijacked by semantic routing, `.venv/bin/python -m pytest tests/test_workflow_routes.py -k "ground_truth_progress_subset or train_model_from_current_labels or start_training_uses_data_derived_defaults"` passed: 3 tests;
+  - `npm test -- --runTestsByPath src/contexts/WorkflowContext.test.js src/components/Chatbot.test.js --watchAll=false` passed: 33 tests;
+  - `npm run build` passed with the existing React hook dependency warnings in `DetectionWorkflow.js` and `ProofreadingEditor.js`;
+  - deployed `main.da9bd95e.js` to `/var/www/demo.seg.bio`;
+  - restarted API as PID `2469115` with `OLLAMA_MODEL=qwen3.6:27b` and the MitoEM2 initial project env;
+  - live local query “train a model on my ground truth to segment the rest” returns intent `start_training`, 2 GT training volumes, 2 image-only targets, 2 draft-mask exclusions, and the MitoEM2 config path.
+
+## 2026-05-04 - Make Agent Suggestions Actionable and Training Approval Legible
+
+- Turned the visualization “found image/seg pairs” discovery toast into an actionable notification:
+  - shows the discovered pair count;
+  - keeps the current first-pair auto-open behavior;
+  - offers direct buttons to open the Progress view or return to Files.
+- Fixed the approval path for project-local training configs:
+  - backend `/pytc/config` now accepts absolute YAML paths under allowed mounted/demo project roots;
+  - MitoEM2 project config `/home/weidf/demo_data/mitoem2_progress_demo/configs/MitoEM2-Pyra-Demo-BC.yaml` now loads instead of returning `404`;
+  - added route coverage for external project config loading.
+- Made “Review run” for training approvals populate the Train Model form immediately without starting runtime.
+- Made “Approve” for agent-staged training runs start the durable workflow command and switch the Train Model runtime panel into monitor mode instead of leaving the screen idle.
+- Reworked the training proposal card display so it summarizes the run in human-sized fields:
+  - config;
+  - image/label roots;
+  - output folder;
+  - number of fully good GT training volumes;
+  - target and draft-mask volume counts;
+  - manifest path;
+  - parameter mode.
+- Verification:
+  - `.venv/bin/python -m py_compile server_api/main.py server_api/workflows/router.py` passed;
+  - `.venv/bin/python -m pytest tests/test_pytc_runtime_routes.py -k "config_route_allows_project_config or start_model_training_proxy_returns_504"` passed: 2 tests;
+  - `npm test -- --runTestsByPath src/contexts/WorkflowContext.test.js src/components/Chatbot.test.js --watchAll=false` passed: 33 tests;
+  - `npm run build` passed with only the existing React hook dependency warnings in `DetectionWorkflow.js` and `ProofreadingEditor.js`;
+  - deployed frontend bundle `main.01530754.js` to `/var/www/demo.seg.bio`;
+  - restarted the demo2 API as PID `3696204` on port `4342` with `qwen3.6:27b` and the MitoEM2 progress project mounted;
+  - verified `GET /health`, `GET /chat/status`, and the absolute MitoEM2 `/pytc/config` lookup.
+
+## 2026-05-04 - Populate Train Form After Approving Agent Training Runs
+
+- Addressed the Train Model screen staying visually empty after approving an agent-proposed training run even though the durable training command was submitted.
+- Client-side approval fix:
+  - approval now carries the accepted training client effects into the `monitor_training` runtime action;
+  - monitor actions include explicit overrides for input image, input label, output path, log path, config origin, and autopick-parameter state;
+  - Train Model applies those overrides directly to the visible form before consuming the monitor action.
+- Runtime-state fallback:
+  - the PyTC worker now stores `inputImagePath`, `inputLabelPath`, `configOriginPath`, `workflowId`, `runId`, `commandId`, and `autoParameters` in training runtime metadata;
+  - Train Model mirrors active runtime metadata back into the same four visible fields, so a refreshed or late-arriving runtime snapshot still shows what is actually running.
+- Verification:
+  - `.venv/bin/python -m py_compile server_pytc/services/model.py server_api/main.py` passed;
+  - `npm test -- --runTestsByPath src/contexts/WorkflowContext.test.js --watchAll=false` passed: 12 tests;
+  - `npm test -- --runTestsByPath src/components/Chatbot.test.js --watchAll=false` passed: 21 tests;
+  - `npm run build` passed with the existing React hook dependency warnings in `DetectionWorkflow.js` and `ProofreadingEditor.js`;
+  - deployed frontend bundle `main.30d6c5f1.js` to `/var/www/demo.seg.bio`;
+  - restarted the PyTC worker as PID `3784579` on port `4243` after confirming no training job was active;
+  - verified worker `/hello` and API `/health` are OK.
+
+## 2026-05-04 - Keep Assistant LLM Loaded During Training by Default
+
+- Changed the GPU-training preflight policy so Ollama model unloading is opt-in instead of automatic.
+- `server_pytc.services.model._unload_ollama_before_gpu_training()` now defaults `PYTC_UNLOAD_OLLAMA_BEFORE_TRAINING` to disabled.
+- When disabled, training runtime logs a clear keep-loaded preflight event instead of calling `ollama stop`.
+- `scripts/start.sh` and `scripts/dev.sh` now export `PYTC_UNLOAD_OLLAMA_BEFORE_TRAINING=0` by default.
+- README runtime variables now document setting `PYTC_UNLOAD_OLLAMA_BEFORE_TRAINING=1` only for memory-constrained GPUs.
+- Verification:
+  - `.venv/bin/python -m py_compile server_pytc/services/model.py` passed;
+  - `.venv/bin/python -m pytest tests/test_worker_model_service.py` passed: 5 tests;
+  - confirmed no training job was active;
+  - restarted the PyTC worker as PID `3804081` on port `4243` with `PYTC_UNLOAD_OLLAMA_BEFORE_TRAINING=0`, `OLLAMA_MODEL=qwen3.6:27b`, and `OLLAMA_EMBED_MODEL=qwen3-embedding:8b`;
+  - verified worker `/hello`, API `/health`, and idle training status.
+
+## 2026-05-04 - Repair Stale Chat Approval Cards
+
+- Investigated the live `Approve` button regression from the app event log.
+- Root cause:
+  - the button did fire;
+  - it posted `POST /api/workflows/112/agent-actions/334/approve`;
+  - backend returned `404 Agent proposal not found` because proposal event `334` belonged to an older workflow while the page had booted fresh workflow `112`;
+  - the client surfaced this only as an unhandled promise rejection, so the card looked inert.
+- Frontend fix:
+  - approval card clicks now handle errors explicitly;
+  - if an approval event is missing/stale, the client recreates the same proposal in the current workflow and approves the fresh event;
+  - stale local proposal cards are marked superseded and recreated cards are marked approved;
+  - proposal cards carry `workflow_id` from the event/message context where available.
+- Verification:
+  - `npm test -- --runTestsByPath src/components/Chatbot.test.js --watchAll=false` passed: 22 tests;
+  - `npm test -- --runTestsByPath src/contexts/WorkflowContext.test.js --watchAll=false` passed: 12 tests;
+  - `npm run build` passed with the existing EHTool hook dependency warnings;
+  - deployed frontend bundle `main.998633fb.js` to `/var/www/demo.seg.bio`;
+  - verified API `/health` and idle training status.
+
+## 2026-05-04 - Fix Multi-Volume Training Subsets and Continuous Workflow Chat
+
+- Fixed the failed agent-approved MitoEM2 training launch:
+  - root cause was `DATASET.IMAGE_NAME` / `DATASET.LABEL_NAME` being rewritten to staged subset directories such as `.../workflow_113.../image`;
+  - PyTC then tried to open the directory as a single volume and raised `ValueError: unrecognizable file format`;
+  - runtime overrides now detect paired training directories, read `volume_subset_manifest.json` when present, and rewrite the staged subset into explicit image/label volume lists.
+- Hardened launch validation:
+  - training and inference image inputs now reject unexpanded plain directories;
+  - list-valued image/label inputs are accepted only when every listed volume path exists.
+- Simplified the main workflow assistant into one continuous session chat:
+  - removed saved-chat history/sidebar/new-chat controls from the big assistant pane;
+  - the pane stores its current messages and backend `conversationId` in `sessionStorage`;
+  - closing and reopening the drawer in the same browser session restores the exact thread and keeps future messages on the same backend conversation.
+- Verification:
+  - `.venv/bin/python -m py_compile server_pytc/services/model.py` passed;
+  - `.venv/bin/python -m pytest tests/test_pytc_runtime_routes.py -q` passed: 34 tests, 5 subtests;
+  - `.venv/bin/python -m pytest tests/test_worker_model_service.py -q` passed: 5 tests;
+  - `npm test -- --runTestsByPath src/components/Chatbot.test.js --watchAll=false` passed: 23 tests;
+  - `npm test -- --runTestsByPath src/contexts/WorkflowContext.test.js --watchAll=false` passed: 12 tests;
+  - `npm run build` passed with only existing EHTool hook dependency warnings;
+  - deployed frontend bundle `main.f7e1aa6b.js` to `/var/www/demo.seg.bio`;
+  - restarted the PyTC worker as PID `3994027` on port `4243` with `PYTC_UNLOAD_OLLAMA_BEFORE_TRAINING=0`;
+  - verified worker `/hello` and idle training status.
+
+## 2026-05-04 - Make Training Review Cards Actually Populate the Form
+
+- Fixed the apparent no-op after clicking an agent-proposed training run's `Review run` button.
+- Root cause:
+  - the chat action could create the backend approval proposal before the visible Train Model form effects ran;
+  - if the continuous chat remounted against a newer workflow, old action/proposal cards were correctly stripped, but their text still said to review a run card that no longer existed.
+- Frontend fix:
+  - training review actions now apply the form-populating client effects first, then create the approval card;
+  - if a full effect pass fails, the client still navigates to Train Model and fills image, label, output, and log paths from a fallback effect set;
+  - stale reviewed-run cards now explain that their button was hidden because it belonged to an earlier workflow, instead of leaving misleading text-only instructions.
+- Verification:
+  - `npm test -- --runTestsByPath src/components/Chatbot.test.js --watchAll=false` passed: 25 tests;
+  - `npm test -- --runTestsByPath src/contexts/WorkflowContext.test.js --watchAll=false` passed: 12 tests;
+  - `npm run build` passed with only existing EHTool hook dependency warnings;
+  - deployed frontend bundle `main.3cb1a337.js` to `/var/www/demo.seg.bio`;
+  - verified API `/health`, worker `/hello`, and idle worker `/training_status`.
+
+## 2026-05-05 - Add Mechanical Project Context Audits
+
+- Added a bounded project scan audit that samples readable volume files instead of relying only on file names or user prose.
+- Backend project profiles now include `audit` / `schema.audit` with:
+  - sampled HDF5/TIFF volume metadata and simple statistics;
+  - image/mask pair shape checks;
+  - warnings for unreadable, empty, all-zero, or low-dynamic-range sampled data;
+  - source-tagged `context_facts`, currently including voxel size pulled from volume metadata attributes.
+- Project context defaults now prefer high-confidence audit facts over stale text/default hints, so metadata can correct bad scales before the workflow starts.
+- Project setup UI now shows a "What I checked automatically" panel with audited volume counts, pair checks, source-tagged facts, and warnings/errors.
+- Persisted `.pytc_project_context.json` now carries `project_audit` and `context_facts` so the workflow assistant can reference mechanically verified project facts later.
+- Verification:
+  - `.venv/bin/python -m pytest tests/test_file_workspace_routes.py -q` passed: 15 tests;
+  - `npm test -- --runTestsByPath src/utils/projectSuggestions.test.js src/views/FilesManager.test.js --watchAll=false` passed: 23 tests, with existing React `act(...)` warnings from file-loading effects;
+  - `npm run build` passed with the existing EHTool hook dependency warnings;
+  - deployed frontend bundle `main.5c07d5d9.js` to `/var/www/demo.seg.bio`;
+  - restarted the public demo API as PID `2188115` on port `4342` with `PYTC_ALLOWED_ORIGINS=https://demo.seg.bio,...`;
+  - remounted `mitoem2_progress_demo` as root item `1`;
+  - verified public `/api/health`, root files, worker `/hello`, and project suggestions with audit summary `{audited_volumes: 10, pair_checks: 4, warnings: 0, errors: 0}`.
+
+## 2026-05-05 - Replace Blank Project Setup Prompt With Guided Context
+
+- Removed the stranded blank first step for mounted projects when the app already has enough detected context.
+- Project setup now:
+  - jumps directly to the mapping/start confirmation when modality, target, voxel size, and image data are already inferred;
+  - otherwise shows a guided "Project basics" checklist for modality, target, and voxel size;
+  - keeps free-text as an optional note instead of the primary required input.
+- Backend project suggestions now use a lightweight audit summary:
+  - still checks metadata, image/mask pair shapes, findings, and context facts;
+  - avoids full sample statistics and bulky per-volume payloads while rendering the project list.
+- Project scanning now ignores transient runtime config files like `.__pytc_runtime_training_*.yaml`.
+- Verification:
+  - `.venv/bin/python -m pytest tests/test_file_workspace_routes.py -q` passed: 15 tests;
+  - `npm test -- --runTestsByPath src/utils/projectSuggestions.test.js src/views/FilesManager.test.js --watchAll=false` passed: 24 tests, with existing React `act(...)` warnings from file-loading effects;
+  - `npm run build` passed with the existing EHTool hook dependency warnings;
+  - deployed frontend bundle `main.32c3c460.js` to `/var/www/demo.seg.bio`;
+  - restarted the public demo API as PID `2335698` on port `4342`;
+  - verified public `/api/health`, root files, worker `/hello`, and project suggestions returning in roughly `0.27s` with MitoEM2 audit summary `{audited_volumes: 10, pair_checks: 4, warnings: 0, errors: 0}`.
+
+## 2026-05-23 - Sunset Monitor Tab
+
+- Removed the Monitor module from the top navigation and stopped mounting the standalone Monitoring view.
+- Retargeted legacy `navigate_to: monitoring` client effects to Train Model so older agent cards or saved actions do not strand users on a removed screen.
+- Updated workflow-agent monitor/log/TensorBoard actions to open Train Model runtime details instead of proposing an "Open Monitor" card.
+- Verification:
+  - `.venv/bin/python -m py_compile server_api/workflows/router.py` passed;
+  - `npm test -- --runTestsByPath src/views/Views.test.js --watchAll=false` passed: 6 tests;
+  - `npm run build` passed with the existing EHTool hook dependency warnings;
+  - deployed frontend bundle `main.a299bdfd.js` to `/var/www/demo.seg.bio`;
+  - restarted the public demo API as PID `1118358` on port `4342`;
+  - verified public `/api/health`.
+
+## 2026-05-23 - Soften Workflow Agent Chat Tone
+
+- Replaced the most robotic canned workflow-agent responses:
+  - removed "The next useful move looks like..." from greeting/status-style paths;
+  - changed greeting replies from status-template language to conversational guidance;
+  - softened "workflow checks are ready" and style-feedback acknowledgements.
+- Kept mechanical details in the expandable evidence/status surfaces rather than front-loading them in the chat response.
+- Verification:
+  - `.venv/bin/python -m py_compile server_api/workflows/router.py` passed;
+  - `.venv/bin/python -m pytest tests/test_workflow_routes.py -q` passed: 46 tests;
+  - restarted `pytc-demo@pytc-client-demo2.service` and `pytc-worker-demo2.service`;
+  - verified public `/api/health`;
+  - verified local demo workflow-agent greeting returns: "Hey. We are still in proofreading. I would probably keep proofreading likely mistakes. I can open the right screen, walk through what I am seeing, or help decide the next step."
+
+## 2026-05-23 - Technical Incongruity Pass
+
+- Fixed a sunset-monitoring inconsistency:
+  - the top-level Monitor tab was already gone, but chatbot/RAG help still described a standalone TensorBoard/Monitoring page;
+  - updated `Monitoring.md`, `GettingStarted.md`, `rag_eval.py`, and the manual checklist so user-facing help now points to Train Model runtime details instead.
+- Fixed the Train Model completion card's TensorBoard button:
+  - it had become a no-op that navigated back to Train Model;
+  - it now starts TensorBoard for the resolved training output path, stores the returned URL in app context, and opens it in a new tab when available.
+- Verification:
+  - `npm test -- --runInBand src/contexts/WorkflowContext.test.js src/components/Chatbot.test.js src/views/Views.test.js src/views/FilesManager.test.js src/utils/projectSuggestions.test.js` passed: 67 tests, with existing FilesManager `act(...)` warnings;
+  - `CI=true npm test -- --runInBand src/views/ModelTraining.js src/views/Views.test.js src/components/Chatbot.test.js` passed the matching test suites: 31 tests;
+  - `CI=true npm run build` passed with existing EHTool hook dependency warnings;
+  - `.venv/bin/python -m py_compile server_api/workflows/router.py server_api/auth/router.py server_api/main.py` passed;
+  - direct backend `pytest` without the venv used system Python 2 and failed at collection; venv-targeted workflow tests were attempted but timed out while executing the selected agent-query test.
+
+## 2026-05-24 - Deep Technical Audit Report
+
+- Created `docs/research/internal-technical-audit-2026-05-24.md` as a broad internal audit of the current agentic PyTC client.
+- Covered frontend workflow surfaces, backend workflow orchestration, project ingestion/context, training/runtime launch, proofread/EHTool persistence, logging/observability, and UI streamlining.
+- Key risks called out:
+  - workflow semantic intent prompt/schema drift rejects valid LLM intents;
+  - app boot still clears mounted file/workflow state in places that conflict with continuous workflow memory;
+  - workflow-agent routing captures nearly every chat message once a workflow exists, starving general help/RAG;
+  - training subset staging points PyTC at directories, which can reproduce the previous "unrecognizable file format" failure;
+  - chat/action execution remains split across multiple command/action paths;
+  - project context and proofread artifacts are still sidecar-heavy rather than a first-class project memory model.
+- UI and agent expansion notes include guided context intake, richer progress row actions, explicit agent readouts, traceable tool probes, continuous chat hydration, and a unified action proposal model.
+- Verification:
+  - `.venv/bin/python -m py_compile server_api/workflows/router.py server_api/auth/router.py server_api/main.py server_pytc/services/model.py server_api/ehtool/router.py server_api/ehtool/data_manager.py runtime_settings.py app_event_logger.py` passed;
+  - `CI=true npm test -- --runInBand src/views/Views.test.js src/components/Chatbot.test.js src/views/FilesManager.test.js src/utils/projectSuggestions.test.js` passed: 55 tests, with existing FilesManager `act(...)` warnings;
+  - `CI=true npm run build` passed with existing EHTool hook dependency warnings and bundle-size warnings;
+  - `.venv/bin/python -m pytest tests/test_workflow_routes.py tests/test_file_workspace_routes.py -q` passed: 61 tests, with existing framework deprecation warnings.
+
+## 2026-05-24 - Deep Research Synthesis And Semantic Intent Hardening
+
+- Synthesized the user-provided deep research report into `docs/research/deep-research-engineering-synthesis-2026-05-24.md`.
+- Updated `docs/codex-working-memory/backlog.md` with research-driven engineering priorities:
+  - structured project memory as the core state model;
+  - one approval-gated action execution envelope;
+  - server-backed continuous workflow chat and project hydration;
+  - first-class per-volume state and multi-volume training artifacts;
+  - conversational visible agent responses with mechanics in expandable traces;
+  - task-family presets and eventual `valid_mask`/region-level support.
+- Fixed the semantic workflow router prompt/validator mismatch:
+  - introduced `SEMANTIC_WORKFLOW_INTENT_ORDER` as the prompt source of truth;
+  - derived `SEMANTIC_WORKFLOW_INTENTS` from it;
+  - included `style_feedback`, `project_files`, and `project_progress` so LLM classifications for those prompt-listed intents are no longer discarded.
+- Added a regression test asserting the semantic prompt intent list and validation set stay aligned.
+- Verification:
+  - `.venv/bin/python -m py_compile server_api/workflows/router.py tests/test_workflow_routes.py` passed;
+  - `.venv/bin/python -m pytest tests/test_workflow_routes.py -k "semantic_workflow_intents or project_file_overview or opens_project_progress or style_feedback" -q` passed: 3 tests, with existing framework deprecation warnings;
+  - `.venv/bin/python -m pytest tests/test_workflow_routes.py -q` passed: 47 tests, with existing framework deprecation warnings.
+
+## 2026-05-24 - Code Sweep Bug Fix Pass
+
+- Fixed app boot wiping useful state:
+  - removed the frontend `CacheBootstrapper` that reset file state before rendering;
+  - restored localforage-backed hydration/persistence for global app state, while leaving the live Neuroglancer viewer object non-persisted;
+  - changed workflow boot from "start a fresh workflow on every reload" to resuming the current workflow session.
+- Kept explicit resets explicit:
+  - `startNewWorkflow` and agent `start_new_workflow` effects still reset the file workspace and local workflow inputs before creating a new workflow;
+  - the workspace reset route now preserves mounted-source `.pytc_project_context.json` sidecars instead of deleting project context during cleanup.
+- Fixed workflow chat continuity:
+  - added `GET /api/workflows/{workflow_id}/agent/conversation`;
+  - hydrated the big workflow chat from the latest server-side workflow-agent conversation when reopening the panel in the same workflow session.
+- Fixed over-eager workflow-agent routing:
+  - general conceptual questions now stay on the regular chatbot/RAG path;
+  - project/file/data/workflow questions and workflow follow-ups still route to the workflow agent.
+- Reduced debug noise:
+  - gated verbose training/inference client API logs behind `REACT_APP_DEBUG_API_LOGS`;
+  - removed EHTool module-load prints and replaced a layer-preview failure print with structured event logging.
+- Confirmed the existing training-subset path expansion test passes, covering the earlier "unrecognizable file format for .../image" failure mode.
+- Verification:
+  - `.venv/bin/python -m py_compile server_api/workflows/router.py server_api/auth/router.py server_api/ehtool/router.py` passed;
+  - `.venv/bin/python -m pytest tests/test_workflow_routes.py tests/test_file_workspace_routes.py -q` passed: 63 tests, with existing framework deprecation warnings;
+  - `CI=true npm test -- --runInBand src/contexts/WorkflowContext.test.js src/components/Chatbot.test.js` passed: 38 tests, with one existing intentional network-error warning;
+  - `CI=true npm run build` passed with existing browser-data, EHTool hook dependency, and bundle-size warnings;
+  - `CI=true npm test -- --runInBand src/views/Views.test.js src/views/FilesManager.test.js src/utils/projectSuggestions.test.js` passed: 30 tests, with existing FilesManager `act(...)` warnings;
+  - `.venv/bin/python -m pytest tests/test_pytc_runtime_routes.py -k training_subset -q` passed: 1 test, with existing framework deprecation warnings.
+
+## 2026-05-24 - Paper Readiness Production Plan
+
+- Created `docs/codex-working-memory/paper-readiness-production-plan.md` as the detailed bridge from the current prototype to the paper-implied final product.
+- The plan defines:
+  - the core product contract for a production-shaped human-agent segmentation workflow;
+  - the paper claim contract mapping claims to required system evidence;
+  - P0/P1 readiness gates;
+  - three case-study placeholders for guided intake, proofreading/data curation, and closed-loop training/inference/evaluation;
+  - twelve implementation workstreams with concrete action items, verification gates, and paper evidence outputs;
+  - milestone ordering from state foundation through paper freeze;
+  - a final readiness checklist for claim-to-evidence alignment.
+
+## 2026-05-24 - Backend Volume State And Project Management Hardening
+
+- Added durable workflow-level volume state:
+  - introduced `workflow_volume_states` with one row per workflow volume;
+  - stores status, provenance/source, confidence, image/label/prediction/corrected-mask paths, training eligibility, inference eligibility, notes, metadata, and event linkage;
+  - exposes volume state in workflow export bundles so paper/evidence snapshots include the actual project status map.
+- Hardened the project progress loop:
+  - project-progress refresh now syncs derived volume rows into durable volume state;
+  - manual progress/status edits are preserved as manual volume-state overrides instead of being overwritten by rescans;
+  - progress rows now include durable volume-state ids plus training/inference eligibility flags.
+- Added backend APIs for the workflow loop:
+  - `GET /api/workflows/{workflow_id}/volumes` refreshes and returns canonical workflow volume state with summary counts;
+  - `PATCH /api/workflows/{workflow_id}/volumes` updates one volume's status, paths, eligibility, note, and metadata while appending a workflow event.
+- Added a user-scoped mounted-project inventory:
+  - `GET /users/me/projects` returns the current user plus mounted project roots owned by that user, indexed file/folder counts, and a summary project profile.
+- Updated the production plan so its backend endpoint checklist matches the implemented workflow-scoped API surface.
+- Verification:
+  - `.venv/bin/python -m py_compile server_api/workflows/db_models.py server_api/workflows/service.py server_api/workflows/bundle_export.py server_api/workflows/router.py server_api/auth/models.py server_api/auth/router.py` passed;
+  - `.venv/bin/python -m pytest tests/test_workflow_routes.py -k "project_progress_counts or workflow_volume_state_api" -q` passed: 2 tests, with existing framework deprecation warnings;
+  - `.venv/bin/python -m pytest tests/test_file_workspace_routes.py -k "users_me_projects" -q` passed: 1 test, with existing framework deprecation warnings;
+  - `.venv/bin/python -m pytest tests/test_workflow_routes.py tests/test_file_workspace_routes.py tests/test_workflow_export_bundle.py -q` passed: 66 tests, with existing framework deprecation warnings.
+
+## 2026-05-24 - Canonical Workflow Overview Surface
+
+- Formalized workflow progress display around one backend overview object:
+  - added `GET /api/workflows/{workflow_id}/overview`;
+  - overview includes current phase, phase reason, volume summary, full project progress snapshot, workflow stages, blockers, recommended next actions, active runs, and recent events;
+  - derives from the same workflow/project-progress/model-run/event state that the agent and progress tables use.
+- Updated frontend workflow state:
+  - `WorkflowContext` now refreshes and stores `workflowOverview`;
+  - overview refresh also hydrates the existing `projectProgress` cache when returned;
+  - project progress status changes refresh the overview so manual volume edits are reflected in the shared state map.
+- Reworked the visible workflow UI:
+  - top navigation now has an always-visible workflow overview strip showing project name, phase, GT/draft/missing counts, blocker/run state, and the top next action;
+  - renamed the old `Progress` tab to `Workflow`;
+  - the page title is now `Workflow Overview` and includes phase/stage tiles, blockers, recommended next moves, completion summary, and the volume table;
+  - chat drawer's old `Status` toggle is now `Evidence`, keeping traces/details separate from canonical workflow state.
+- Verification:
+  - `.venv/bin/python -m py_compile server_api/workflows/router.py` passed;
+  - `.venv/bin/python -m pytest tests/test_workflow_routes.py -k "workflow_overview or project_progress_counts or workflow_volume_state_api" -q` passed: 3 tests, with existing framework deprecation warnings;
+  - `CI=true npm test -- --runInBand src/views/Views.test.js src/views/ProjectProgress.test.js src/contexts/WorkflowContext.test.js src/components/Chatbot.test.js` from `client/` passed: 46 tests, with the existing intentional workflow-event network warning;
+  - `.venv/bin/python -m pytest tests/test_workflow_routes.py tests/test_file_workspace_routes.py tests/test_workflow_export_bundle.py -q` passed: 67 tests, with existing framework deprecation warnings;
+  - `CI=true npm run build` from `client/` passed with existing browser-data, EHTool hook dependency, and bundle-size warnings.
+
+## 2026-05-24 - Deploy Workflow Overview To demo.seg.bio
+
+- Deployed the current React build to `/var/www/demo.seg.bio`.
+- Restarted `pytc-demo@pytc-client-demo2.service` so the new workflow overview API is live.
+- Verification:
+  - `https://demo.seg.bio/` serves `static/js/main.1166f4b3.js`;
+  - `https://demo.seg.bio/api/health` returns `{"status":"ok"}`;
+  - `https://demo.seg.bio/api/api/workflows/current` returns the active workflow;
+  - `https://demo.seg.bio/api/api/workflows/167/overview` returns the new overview payload with phase `proofread`, volume summary, project progress, blockers/actions, and recent events.
+
+## 2026-05-24 - Remove Assistant Evidence Drawer
+
+- Removed the assistant drawer's local `Evidence`/timeline panel so the chat surface stays focused on plain conversation, action cards, proposals, and expandable per-message traces.
+- Redirected legacy `show_workflow_context` client effects to the main `Workflow` page instead of opening a hidden drawer-specific context panel.
+- Kept workflow state and provenance anchored in the app-level workflow surfaces rather than duplicating them in the chat header.
+- Verification:
+  - `CI=true npm test -- --runInBand src/components/Chatbot.test.js src/views/Views.test.js` from `client/` passed: 32 tests;
+  - `CI=true npm run build` from `client/` passed with existing browser-data, EHTool hook dependency, and bundle-size warnings;
+  - deployed the new React bundle to `/var/www/demo.seg.bio`;
+  - `https://demo.seg.bio/` serves `static/js/main.d076d1c1.js`;
+  - `https://demo.seg.bio/api/health` returns `{"status":"ok"}`;
+  - verified the served bundle no longer contains `Hide Evidence`, `Show timeline`, `Hide timeline`, `forceShowWorkflowInspector`, or `onWorkflowInspectorConsumed`.
+
+## 2026-05-24 - Yixiao TapeReader XRI Case Study Fixture
+
+- Located the XRI data backing the older `view.seg.bio` visualization demo at `/home/weidf/Downloads/PT37_round2`.
+- Cloned `https://github.com/LinghuLab/TapeReader` into `/home/weidf/reference_repos/TapeReader` and inspected the pipeline/PyTC configs.
+- Assembled a current-app case-study project at `/home/weidf/demo_data/yixiao_tapereader_xri_case_study`:
+  - 10 PT37 round-2 XRI raw TIFF volumes;
+  - 6 ground-truth volumes matching the TapeReader training split (`1`, `2`, `3`, `4_1`, `4_2`, `4_3`);
+  - 2 draft-mask volumes for proofreading (`5_1`, `5_2`);
+  - 2 image-only inference targets (`6_1`, `6_2`) with masks withheld outside the project root at `/home/weidf/demo_data/yixiao_tapereader_xri_case_study_holdout_masks`.
+- Added project-facing artifacts:
+  - `project_manifest.json` with TapeReader/paper provenance, volume state, source paths, label counts, and voxel size `40 x 16.3 x 16.3 nm`;
+  - `configs/TapeReader-Fiber-BCS-Original-Barcode.yaml`, preserving the paper pipeline's PyTC target list `["0", "4-0-1", "a-0-40-16-16"]`;
+  - `configs/TapeReader-Fiber-BCS-AppCompat-Sanity.yaml`, using a current PyTC-compatible fallback target list `["0", "4-0-1", "5-2d-1-0-1.0-0"]`;
+  - `configs/tapereader_pipeline_config.yaml`, `README.md`, case-study notes, copied TapeReader source/config references, a reset script, and an initial-state metadata snapshot.
+- Added the Yixiao project to backend project suggestions so it can be mounted from the app.
+
+### 2026-05-24 - Yixiao TapeReader XRI Case Study Verification
+
+- Hardened `/home/weidf/demo_data/yixiao_tapereader_xri_case_study/reset_to_initial.sh` to use the demo app venv when regenerating CLAHE training inputs, so reset does not depend on ambient `python` packages.
+- Verified fixture counts after reset: 10 raw volumes, 8 visible segmentation masks, 12 PyTC training files, and 10 withheld masks in `/home/weidf/demo_data/yixiao_tapereader_xri_case_study_holdout_masks`.
+- Verified manifest split remains 6 ground-truth volumes, 2 draft/needs-proofreading volumes, and 2 image-only/missing-segmentation volumes.
+- Verified both TapeReader YAML configs parse and load through the local PyTC config loader. The app-compatible sanity target builds local PyTC training targets on a crop; the original barcode-branch target intentionally fails under bundled current PyTC with `Target option a is not valid`, preserving the known compatibility boundary.
+- Restarted the live `pytc-demo@pytc-client-demo2.service` process via systemd auto-restart and confirmed `https://demo.seg.bio/api/files/project-suggestions` now includes `yixiao-tapereader-xri-case-study`.
+
+## 2026-05-24 - Guided Project Context Intake Pass
+
+- Reworked mounted-project setup toward inspect-first guided confirmation:
+  - added a detected-data summary showing image, mask, prediction, config, and checkpoint counts;
+  - added quick confirmation chips for task family, mask readiness, image-only volume behavior, and training policy;
+  - persisted those confirmations into project context/profile memory so they can be reused by the workflow agent and future setup passes.
+- Improved XRI/TapeReader context handling:
+  - frontend context inference now recognizes XRI / X-ray microscopy and fibres/CytoTape;
+  - Yixiao project suggestions now carry task-family, mask-state, image-only strategy, and training-policy hints;
+  - fixed suggestion hint merging so hand-authored case-study hints override noisy scanned text rather than being overwritten by it.
+- Softened required agent context collection:
+  - the workflow agent no longer requires generic speed-vs-accuracy as a hard prerequisite;
+  - it asks for concrete project facts like imaging modality and target structure, with XRI/fibre examples.
+- Verification:
+  - `CI=true npm test -- --runInBand src/views/FilesManager.test.js src/utils/projectSuggestions.test.js --watchAll=false` passed: 25 tests, with existing FilesManager React `act(...)` warnings;
+  - `.venv/bin/python -m py_compile server_api/auth/router.py server_api/workflows/router.py` passed;
+  - `.venv/bin/python -m pytest tests/test_workflow_routes.py -k "project_context or train_short_phrases or stores_context" -q` passed: 3 tests, with existing framework deprecation warnings;
+  - `CI=true npm run build` passed with existing EHTool hook dependency and bundle-size warnings;
+  - deployed frontend bundle `main.46186d5c.js` to `/var/www/demo.seg.bio`;
+  - restarted the public demo API as PID `4107560` and verified `https://demo.seg.bio/api/health`;
+  - verified public Yixiao project suggestion context now reports XRI fibre instance segmentation, 40 x 16.3 x 16.3 nm, mixed masks/image-only volumes, and GT-only training policy.
+
+## 2026-05-24 - Canonical Project Memory Endpoint
+
+- Added a backend project-memory read model for the workflow agent and UI to share:
+  - `project_facts` with mounted path, project context, audit facts, and task-family preset;
+  - `artifact_index` with canonical paths and registered workflow artifacts;
+  - `volume_states` with summary, items, and progress snapshot;
+  - `run_history` and `evidence_events` for provenance-aware answers and action proposals.
+- Added task-family presets for TapeReader/XRI fibre, MitoEM-style mitochondria instance segmentation, and generic volumetric segmentation so the agent does not treat every project as the same generic task.
+- Exposed `GET /api/workflows/{workflow_id}/memory` and records a `workflow_project_memory/project_memory_refreshed` event when refreshed.
+- Verification:
+  - `.venv/bin/python -m py_compile server_api/workflows/router.py server_api/auth/router.py` passed;
+  - `.venv/bin/python -m pytest tests/test_workflow_routes.py -q` passed: 51 tests, with existing framework deprecation warnings;
+  - `CI=true npm test -- --runInBand src/views/FilesManager.test.js src/utils/projectSuggestions.test.js --watchAll=false` passed: 25 tests, with existing FilesManager React `act(...)` warnings;
+  - restarted the public demo API and verified `https://demo.seg.bio/api/health`;
+  - verified `https://demo.seg.bio/api/api/workflows/168/memory` returns `pytc-project-memory/v1` with canonical paths, task-family preset, volume states, and evidence events.
+
+## 2026-05-24 - Agent Context And Tone Integration
+
+- Fed richer canonical context into semantic intent routing:
+  - task family, mask status, image-only strategy, training policy, and project-progress summary now appear in the workflow state sent to intent classification;
+  - server-side casual context extraction now recognizes XRI/X-ray, CytoTape fibres, mixed masks/image-only projects, and GT-only training policy.
+- Softened front-facing workflow-agent responses:
+  - project-context answers now read as a short human summary of the current project, paths, tracker counts, and likely next move;
+  - generic follow-up answers no longer end with the stiff "I will not launch..." template;
+  - capabilities copy now emphasizes natural requests plus reviewable app-action cards.
+- Verification:
+  - `.venv/bin/python -m py_compile server_api/workflows/router.py server_api/auth/router.py` passed;
+  - `.venv/bin/python -m pytest tests/test_workflow_routes.py -q` passed: 51 tests, with existing framework deprecation warnings;
+  - restarted the public demo API as PID `4164882` and verified `https://demo.seg.bio/api/health`;
+  - verified live workflow-agent response for `what project are we looking at?` returns a concise project summary and tracker counts rather than the old status-template response.
+
+## 2026-05-27 - Yixiao Case Study Live Prep And Smoke Test
+
+- Mounted `/home/weidf/demo_data/yixiao_tapereader_xri_case_study` as the active demo2 project and reset the live workflow to `170` with Yixiao/TapeReader context:
+  - active raw root `data/raw`;
+  - active segmentation root `data/seg`;
+  - active config `configs/TapeReader-Fiber-BCS-AppCompat-Sanity.yaml`;
+  - voxel spacing `40 x 16.3 x 16.3 nm`;
+  - project split: 10 tracked volumes, 6 confirmed ground truth, 2 draft masks needing proofreading, 2 image-only inference targets.
+- Hardened mounted-project ingestion for manifest-backed case studies:
+  - the scanner now uses `project_manifest.json` to seed canonical image/label/config roots before noisy derivative folders like `data/pytc_train`;
+  - manifest-declared image/label pairs are included in project audits before the sample budget is filled;
+  - nested XRI raw/mask folders now pair by matching per-volume folder IDs, so `data/raw/5_1/...` maps to `data/seg/5_1/...`.
+- Hardened Neuroglancer volume-pair diagnostics:
+  - single image/single label fallback pairs no longer report the same selected image as unpaired;
+  - added a regression test for that fallback path.
+- Smoke-tested the live demo2 stack:
+  - systemd services `pytc-demo@pytc-client-demo2.service` and `pytc-worker-demo2.service` are active;
+  - `http://127.0.0.1:4342/health` and `https://demo.seg.bio/api/health` return `{"status":"ok"}`;
+  - public project suggestions include `yixiao-tapereader-xri-case-study` and report it as already mounted;
+  - public progress endpoint reports 10 tracked volumes, 6 ground truth, 2 needs-proofreading, 2 missing segmentation, 60% completion, and 80% segmentation coverage;
+  - workflow agent answers `what project are we looking at?` with XRI/CytoTape context and the 6/2/2 tracker readout;
+  - workflow agent stages a review-gated training action from the 6 fully good masks and preserves the 2 draft masks plus 2 image-only targets in the generated subset manifest;
+  - Neuroglancer route opens the first Yixiao image/mask pair at `40,16.3,16.3` nm and returns a live `/neuroglancer/v/...` URL.
+- Verification:
+  - `.venv/bin/python -m py_compile server_api/auth/router.py server_api/workflows/router.py server_api/workflows/volume_pairs.py` passed during the pass;
+  - targeted file-workspace manifest/profile tests passed;
+  - targeted project-progress nested XRI pairing test passed;
+  - `tests/test_neuroglancer_volume_normalization.py` passed: 12 tests.
+- Caveat:
+  - FastAPI `TestClient` endpoint smoke tests still hang in this environment even for `/health`, so live local/public HTTP smoke checks were used for route-level verification.
+
+## 2026-05-27 - Agentic Workflow Deep Research Brief
+
+- Added `docs/research/deep-research-agentic-workflow-formalization-2026-05-27.md`.
+- The brief asks a follow-on Codex/deep-research agent to investigate how to formalize the app's agentic implementation into a workflow-aware, approval-gated project operator for biomedical image segmentation.
+- It includes:
+  - local repo/data context for demo2;
+  - MitoEM/MitoEM2, Yixiao/TapeReader XRI, and third-case-study placeholders;
+  - code areas to inspect;
+  - literature areas to review;
+  - required deliverable structure for project memory schema, action cards, state machine, context elicitation, evaluation plan, and engineering roadmap.
+
+## 2026-05-27 - Yixiao Repeatable Demo Harness
+
+- Added `scripts/run_yixiao_case_study_smoke.py`, a live API harness for the Yixiao/TapeReader XRI case study.
+- The harness can prepare live demo state with `--prepare-live`:
+  - reset indexed workspace state;
+  - mount `/home/weidf/demo_data/yixiao_tapereader_xri_case_study`;
+  - create and patch a fresh Yixiao workflow;
+  - verify project profile, progress, project memory, Neuroglancer, and agent training proposal behavior.
+- The harness now also validates the worker-side PyTC training-subset path without launching training:
+  - generated subset image/seg directories resolve through `volume_subset_manifest.json`;
+  - six concrete training image/label files are found;
+  - the staged training config passes runtime path validation.
+- Fixed a staging bug exposed by the harness:
+  - agent-proposed multi-volume training now creates the output/log directory during subset proposal staging, so the Train Model UI receives an existing output path.
+- Added `docs/manual-yixiao-case-study-demo.md` with the facilitator walkthrough, expected UI states, agent prompts, reset/smoke commands, and known caveats.
+- Verification:
+  - `.venv/bin/python -m py_compile server_api/workflows/router.py scripts/run_yixiao_case_study_smoke.py` passed;
+  - `scripts/run_yixiao_case_study_smoke.py --prepare-live --verbose` passed against local demo2 API;
+  - live workflow created by the latest smoke run: `174`;
+  - live viewer URL returned: `https://demo.seg.bio/neuroglancer/v/2c26be144fec3d205344aca6f59b9c519ae0c9dc/`.
+
+## 2026-05-27 - Preliminary Agentic Report Triage
+
+- Reviewed `docs/research/agentic-workflow-formalization-report.md`, the fast preliminary research/architecture report.
+- Reviewed the ChatGPT Deep Research prompt files already present:
+  - `docs/research/deep-research-agentic-workflow-formalization-chatgpt-prompt-2026-05-27.md`;
+  - `docs/research/deep-research-agentic-workflow-lit-review-chatgpt-prompt-2026-05-27.md`.
+- Added `docs/research/preliminary-agentic-report-triage-2026-05-27.md` to separate:
+  - recommendations solid enough to implement now;
+  - claims needing deeper literature validation;
+  - Yixiao-focused engineering work to continue while the full deep research pass runs.
+- Current triage recommendation: work next on the Yixiao proofreading roundtrip so a draft mask can be promoted to ground truth and the agent's future training proposal updates from 6 GT volumes to 7 GT volumes.
+
+## 2026-05-27 - Project Memory And Yixiao Roundtrip Hardening
+
+- Enriched workflow project memory with paper-facing canonical volume states while preserving legacy app statuses:
+  - `ground_truth` -> `proofread_ground_truth`;
+  - `needs_proofreading` -> `draft_needs_proofreading`;
+  - `missing_segmentation` -> `image_only`;
+  - `ignored` -> `ignored`.
+- Added memory freshness metadata so downstream agent logic and evidence bundles can see when project progress, volume states, and assistant context were generated.
+- Embedded the project-memory snapshot into workflow evidence bundles and fixed datetime serialization so bundle export remains JSON-safe.
+- Extended `scripts/run_yixiao_case_study_smoke.py` with `--exercise-promotion`:
+  - promotes one draft Yixiao mask to `ground_truth`;
+  - verifies progress updates from 6/2/2 to 7/1/2;
+  - verifies project memory records canonical `proofread_ground_truth`;
+  - verifies the next agent training proposal uses 7 training pairs, 1 review pair, and 2 image-only inference targets.
+- Updated `docs/manual-yixiao-case-study-demo.md` with the promotion smoke flow and reset guidance.
+- Verification:
+  - `.venv/bin/python -m py_compile server_api/workflows/router.py scripts/run_yixiao_case_study_smoke.py tests/test_workflow_routes.py tests/test_workflow_export_bundle.py` passed;
+  - `timeout 60 .venv/bin/python -m pytest tests/test_workflow_export_bundle.py -q` passed;
+  - `timeout 60 .venv/bin/python -m pytest tests/test_workflow_routes.py::WorkflowRouteTests::test_project_memory_endpoint_returns_canonical_context -q` passed;
+  - `scripts/run_yixiao_case_study_smoke.py --prepare-live --exercise-promotion --report /tmp/yixiao-case-study-smoke-promotion-report.json --verbose` passed against local demo2 API;
+  - live bundle export for workflow `175` returned `workflow-export-bundle/v1` with embedded `pytc-project-memory/v1` and 7 ground-truth volumes after promotion;
+  - reran `scripts/run_yixiao_case_study_smoke.py --prepare-live --report /tmp/yixiao-case-study-smoke-report.json --verbose` to restore the public demo to the initial 6/2/2 state as workflow `176`;
+  - live bundle export for workflow `176` returned embedded project memory with 6 ground-truth volumes and 2 image-only volumes.
+
+## 2026-05-27 - Subagent Architecture Sprint Started
+
+- Spawned six focused subagents for the next prototype-hardening pass:
+  - Backend State: composite volume state and memory backend;
+  - App Agent Capability: assistant intent/action behavior;
+  - Action Policy: action-card schema and approval tiers;
+  - Trace/Evidence: structured trace and provenance export;
+  - UI Workflow: coherent manual-agent handoff surfaces;
+  - Yixiao Case Study: first case-study demo readiness.
+- Reliability/QA was deferred because the agent thread limit was reached; queue it after one current subagent completes.
+- Added `docs/research/subagent-orchestration-integration-2026-05-27.md` to keep subagent outputs tied to one implementation path and acceptance criteria.
+
+## 2026-05-27 - Subagent Sprint Implementation Pass
+
+- Integrated the subagent recommendations into the backend workflow substrate:
+  - added composite volume-state columns to `WorkflowVolumeState`;
+  - retained legacy progress statuses while adding `annotation_state`, `role_state`, `execution_state`, `region_scope`, and `workflow-volume-state/v2`;
+  - projected manual progress edits through the same composite-state helper so the Progress page, project memory, and agent training eligibility do not drift;
+  - rejected contradictory legacy/composite volume-state updates.
+- Expanded agent action cards without breaking existing frontend `client_effects`:
+  - every `AgentChatAction` now carries `workflow.action_card/v2`;
+  - action cards include action type, target, risk tier, approval reason, summary fields, input/output artifacts, expected effects, and bounded executor metadata;
+  - runtime training cards are now explicitly `R4_runtime_job`, while navigation/status cards remain `R0_view`.
+- Expanded assistant traces into a structured `agent_trace/v1` shape:
+  - trace rows now include `category`, `data`, and `evidence_refs`;
+  - persisted assistant messages retain those structured traces for later inspection;
+  - workflow evidence bundles now include `agent_messages`, `action_card_index`, and `trace_index`.
+- Added `docs/research/subagent-reliability-qa-2026-05-27.md` via the QA subagent and updated `docs/research/subagent-orchestration-integration-2026-05-27.md` with the full subagent synthesis.
+- Verification:
+  - `.venv/bin/python -m pytest tests/test_workflow_routes.py tests/test_workflow_export_bundle.py -q` passed: 53 tests;
+  - relaunched the demo2 backend manually on `127.0.0.1:4342` after systemd restart required interactive auth;
+  - `scripts/run_yixiao_case_study_smoke.py --prepare-live --report /tmp/yixiao-case-study-smoke-report.json --verbose` passed as workflow `178`;
+  - live viewer returned `https://demo.seg.bio/neuroglancer/v/baff3168abe7f9a2ea7e10e96770100ec0b13b54/`;
+  - live bundle export for workflow `178` returned `workflow-export-bundle/v1`, embedded `pytc-project-memory/v1`, 4 agent messages, 6 trace entries, and 2 action-card entries.
+
+## 2026-05-27 - App Agent Organization: Orchestrator And Specialist Agents
+
+- Reorganized the app-facing assistant model around a main Project Manager orchestrator plus typed specialist subagents:
+  - Project Manager / Orchestrator;
+  - Data Scout;
+  - Visualization Agent;
+  - Proofreading Agent;
+  - Training Agent;
+  - Inference Agent;
+  - Evaluation Agent;
+  - Evidence Agent.
+- Backend agent responses now include:
+  - `orchestrator_agent`;
+  - `subagents`;
+  - per-action `specialist_agent`, `agent_type`, `agent_label`, and `agent_color`;
+  - per-trace `agent_type`, `agent_label`, and `agent_color`;
+  - `workflow.action_card/v2` cards with both orchestrator and specialist agent metadata.
+- Chat UI now presents the drawer as `Project Manager`, describes it as an orchestrator, and uses colored badges/borders to distinguish specialist agents on action cards, approval cards, and trace rows.
+- Verification:
+  - `.venv/bin/python -m py_compile server_api/workflows/router.py` passed;
+  - targeted route tests for project-progress and training agent cards passed;
+  - `npm test -- --runTestsByPath src/components/Chatbot.test.js --watchAll=false` passed: 26 tests;
+  - relaunched the manual demo2 backend on `127.0.0.1:4342`;
+  - `scripts/run_yixiao_case_study_smoke.py --prepare-live --report /tmp/yixiao-case-study-smoke-report.json --verbose` passed as workflow `179`;
+  - live agent query returned Project Manager as orchestrator, the full specialist-agent catalog, Training Agent for the training action, and Data Scout for file-inspection trace rows.
+
+## 2026-05-27 - Chat-Visible Agent Operation Trace
+
+- Moved the assistant trace above the final natural-language answer in the workflow chat, so the chat now reads more like an agent run:
+  - expandable operation trace first;
+  - final response second;
+  - action/proposal cards after that.
+- Relabeled the trace affordance to `Agent trace · What I checked`.
+- Trace rows now show the responsible specialist-agent badge and the operation category (`Checked`, `Inferred`, `Proposed`, `Blocked`).
+- This deliberately exposes structured operation summaries rather than raw hidden chain-of-thought.
+- Verification:
+  - `npm test -- --runTestsByPath src/components/Chatbot.test.js --watchAll=false` passed: 26 tests;
+  - relaunched the manual demo2 backend on `127.0.0.1:4342`.
+
+## 2026-05-27 - demo.seg.bio Frontend Deployment
+
+- Rebuilt the React production bundle for the demo2 checkout with `npm run build`.
+- Synced the resulting `client/build/` output into the nginx web root at `/var/www/demo.seg.bio/`.
+- Verified `https://demo.seg.bio` now serves `static/js/main.2441c22e.js` instead of the stale May 24 bundle.
+- Verified the served bundle contains the new workflow-agent UI strings:
+  - `Project Manager`;
+  - `Orchestrates specialist workflow agents`;
+  - `Agent trace`.
+- Verified the live demo backend is reachable through nginx at `https://demo.seg.bio/api/api/workflows/current` and reports the mounted Yixiao TapeReader XRI workflow `179`.
+- Verified live agent query for workflow `179` returns:
+  - Project Manager orchestrator metadata;
+  - specialist subagent catalog;
+  - structured trace rows.
+- Ran `scripts/run_yixiao_case_study_smoke.py --prepare-live --report /tmp/yixiao-case-study-smoke-report.json --verbose` after deployment; it passed as workflow `180` with viewer `https://demo.seg.bio/neuroglancer/v/d1a4256dc058d12b516f5f168c84bd61b7d79fdd/`.
+- Note: the demo backend is still running via the manual `server_api.main` process on `127.0.0.1:4342`; systemd user unit lookup/restart was not available in this shell.
+
+## 2026-05-28 - Proofreading Route Hardening
+
+- Audited the proofreading view stack across `DatasetLoader`, `DetectionWorkflow`, `ProofreadingEditor`, `server_api/ehtool`, and workflow event handling.
+- Fixed proofreading source selection by centralizing path priority in `client/src/views/ehtool/proofreadingPaths.js`:
+  - source image now comes from `image_path` or `dataset_path`, not prediction output;
+  - editable mask priority is corrected mask, then inference prediction, then original mask, then label.
+- Mirrored the same path priority in backend agent proofreading action effects so chat-proposed `start_proofreading` launches cannot reintroduce stale source/mask selection.
+- Fixed retraining staging from proofreading so `Use edits for training` no longer silently stages an original mask/label or a non-existent planned persistence path.
+- Added focused frontend coverage for proofreading path priority and edited-mask staging eligibility.
+- Added backend coverage for agent proofreading launch priority across corrected masks and prediction masks.
+- Verification:
+  - `npm test -- --runTestsByPath src/views/ehtool/proofreadingPaths.test.js src/views/ehtool/DatasetLoader.test.js src/views/MaskProofreading.test.js --watchAll=false` passed: 3 suites, 9 tests;
+  - `.venv/bin/python -m pytest tests/test_ehtool_data_manager.py tests/test_ehtool_mesh_preview.py tests/test_workflow_routes.py::WorkflowRouteTests::test_ehtool_load_classify_save_and_export_append_workflow_events tests/test_workflow_routes.py::WorkflowRouteTests::test_agent_can_start_proofreading_from_current_image_mask_pair tests/test_workflow_routes.py::WorkflowRouteTests::test_agent_proofreading_launch_prefers_corrected_or_prediction_masks tests/test_workflow_routes.py::WorkflowRouteTests::test_agent_proofread_request_names_blocker_when_inputs_missing -q` passed: 9 tests.
+
+## 2026-05-28 - Editable Agent Approval Cards
+
+- Added an edit-before-approval path for agent proposal cards:
+  - pending training, retraining, inference, visualization, and proofreading cards can expose editable auto-filled fields;
+  - users can click `Adjust`, change the proposed paths/parameters, and approve the same card as `Approve with edits`;
+  - unchanged approvals keep the existing one-click behavior.
+- Threaded field overrides through the frontend approval path:
+  - `AgentProposalCard` emits only changed fields;
+  - `Chatbot`, `WorkflowTimeline`, `WorkflowContext`, and `api.js` pass overrides to the approval endpoint only when present.
+- Hardened backend approval handling:
+  - added an allowlisted `overrides` request body for approval;
+  - merged approved edits into nested `client_effects` before training commands are queued;
+  - recorded applied `user_edits` in approval/staging workflow events.
+- Added focused coverage:
+  - `AgentProposalCard.test.js` verifies editable training and client-effect fields;
+  - `test_approved_training_run_applies_user_field_overrides` verifies edited training paths reach the queued command.
+- Verification:
+  - `npm test -- --runTestsByPath src/components/chat/AgentProposalCard.test.js src/components/WorkflowTimeline.test.js src/components/Chatbot.test.js --watchAll=false` passed: 3 suites, 32 tests;
+  - `npm test -- --runTestsByPath src/contexts/WorkflowContext.test.js --watchAll=false` passed: 1 suite, 12 tests;
+  - `.venv/bin/python -m py_compile server_api/workflows/router.py` passed;
+  - `.venv/bin/python -m pytest tests/test_workflow_routes.py::WorkflowRouteTests::test_approved_training_run_proposal_returns_runtime_launch_effects tests/test_workflow_routes.py::WorkflowRouteTests::test_approved_training_run_applies_user_field_overrides -q` passed: 2 tests.
+
+## 2026-05-28 - demo.seg.bio Deploy Editable Approval Cards
+
+- Built the current React production bundle and synced it to `/var/www/demo.seg.bio/`.
+- Public frontend now serves `static/js/main.721ed937.js`.
+- Verified the served bundle contains the editable approval UI string `Approve with edits`.
+- Restarted the demo2 backend from `/home/weidf/deploy/pytc-client-demo2` as PID `83317` on port `4342` with:
+  - `PYTC_ALLOWED_ORIGINS=https://demo.seg.bio,http://localhost:3000,http://127.0.0.1:3000,null`;
+  - `PYTC_NEUROGLANCER_PUBLIC_BASE=https://demo.seg.bio/neuroglancer`;
+  - `PYTC_WORKER_URL=localhost:4343`.
+- Verification:
+  - `https://demo.seg.bio/api/health` returned `{"status":"ok"}`;
+  - `https://demo.seg.bio/api/api/workflows/current` returned active workflow `180`;
+  - live OpenAPI exposes `AgentActionApprovalRequest` / `overrides`.
+
+## 2026-05-28 - More Disparate Workflow Agent Palette
+
+- Replaced the agent/subagent palette with more visually separated hues:
+  - Project Manager: charcoal `#111827`;
+  - Data Scout: green `#00843D`;
+  - Visualization Agent: royal blue `#0057B8`;
+  - Proofreading Agent: hot magenta `#E0007A`;
+  - Training Agent: violet `#7B2CBF`;
+  - Inference Agent: burnt orange `#D55E00`;
+  - Evaluation Agent: ochre `#B58900`;
+  - Evidence Agent: cyan `#00A6A6`.
+- Updated frontend fallback/orchestrator colors to match the backend palette.
+- Deployed the rebuilt frontend to `/var/www/demo.seg.bio`; public bundle is now `static/js/main.99644842.js`.
+- Restarted the demo2 backend from this checkout; live API process is PID `120119` on port `4342`.
+- Verification:
+  - `.venv/bin/python -m py_compile server_api/workflows/router.py` passed;
+  - `npm test -- --runTestsByPath src/components/chat/AgentProposalCard.test.js src/components/Chatbot.test.js --watchAll=false` passed: 2 suites, 28 tests;
+  - `https://demo.seg.bio/api/health` returned `{"status":"ok"}`;
+  - served bundle contains the new palette values.
+
+## 2026-05-28 - Agent Icon and Border Encodings
+
+- Added non-color visual encodings for the project manager and workflow specialist agents:
+  - Project Manager uses the workflow/project icon with a solid rail;
+  - Data Scout uses the Files/folder icon with a dotted rail;
+  - Visualization Agent uses the Visualize/eye icon with a double rail;
+  - Proofreading Agent uses the Proofread/bug icon with a dashed rail;
+  - Training Agent uses the Train Model/experiment icon with a heavier rail;
+  - Inference Agent uses the Run Model/thunderbolt icon with a dash/top accent;
+  - Evaluation Agent uses a bar-chart icon with a top accent;
+  - Evidence Agent uses a file-done icon with an inset rail.
+- Extended backend agent metadata with `icon_key` and `border_style`, and mirrored those fields onto chat actions and trace items.
+- Added shared frontend agent visual helpers so action cards, approval cards, and trace rows use the same badge and rail encoding.
+- Deployed the rebuilt frontend to `/var/www/demo.seg.bio`; public bundle is now `static/js/main.45e34a89.js`.
+- Restarted the demo2 backend from this checkout as a detached `setsid` process; live API process is PID `158563` on port `4342`.
+- Verification:
+  - `.venv/bin/python -m py_compile server_api/workflows/router.py` passed;
+  - `npm test -- --watchAll=false --runTestsByPath src/__tests__/assistantActionCard.test.js src/__tests__/agentProposalCards.test.js` passed: 2 suites, 4 tests;
+  - `.venv/bin/python -m pytest tests/test_workflow_routes.py::WorkflowRouteTests::test_agent_train_model_uses_ground_truth_progress_subset -q` passed;
+  - `npm run build` passed with existing hook dependency warnings in proofreading/detection views;
+  - `https://demo.seg.bio/api/health` returned `{"status":"ok"}`.
+
+## 2026-05-28 - Visible Consulted-Agent Strip
+
+- Follow-up after staged-demo feedback that the chat still looked like everything came only from Project Manager.
+- Added a visible `Agents` strip at the top of workflow-assistant replies, derived from trace/action/proposal metadata.
+- Switched agent badges to compact, non-clipping labels:
+  - `PM`, `Data`, `Vis`, `Proof`, `Train`, `Infer`, `Eval`, `Evidence`;
+  - each chip keeps the full agent name in its hover title and preserves the icon/color encoding.
+- Deployed the rebuilt frontend to `/var/www/demo.seg.bio`; public bundle is now `static/js/main.b4d6fb58.js`.
+- Verification:
+  - `npm test -- --watchAll=false --runTestsByPath src/__tests__/assistantActionCard.test.js src/__tests__/agentProposalCards.test.js src/components/Chatbot.test.js` passed: 3 suites, 30 tests;
+  - `npm run build` passed with the existing hook dependency warnings in proofreading/detection views;
+  - `https://demo.seg.bio/api/health` returned `{"status":"ok"}`;
+  - backend remained healthy as PID `158563` on port `4342`.
+
+## 2026-05-28 - PyTC Worker Proxy Logging and Demo Service Repair
+
+- Investigated a staged training approval failure:
+  - browser/API error was `503: Failed to connect to PyTC worker`;
+  - live API had been manually launched with `PYTC_WORKER_URL=localhost:4343`;
+  - the actual PyTC worker was on `localhost:4243`.
+- Added structured API-to-worker proxy events in `server_api/main.py`:
+  - `api_runtime_configured` logs API/worker/neuroglancer runtime settings on startup;
+  - `worker_proxy_request_started` logs each proxied worker call;
+  - `worker_proxy_request_completed` logs latency and status;
+  - `worker_proxy_request_failed` logs connection failures, timeouts, and upstream request errors.
+- Added focused test coverage for connection-refused logging on `/training_status`.
+- Repaired the live demo process topology:
+  - killed the stale detached May 4 worker that was occupying `4243`;
+  - killed the manually detached API process;
+  - restarted `pytc-worker-demo2.service` and `pytc-demo@pytc-client-demo2.service` under systemd;
+  - confirmed the deployed env file uses `PYTC_WORKER_URL=localhost:4243`.
+- Verification:
+  - `pytc-worker-demo2.service` active on port `4243`;
+  - `pytc-demo@pytc-client-demo2.service` active on port `4342`;
+  - `http://localhost:4243/hello` returned `["hello"]`;
+  - `https://demo.seg.bio/api/health` returned `{"status":"ok"}`;
+  - `https://demo.seg.bio/api/training_status` returned idle worker state through the API proxy;
+  - app event log now records the full API proxy request path and worker latency.
+
+## 2026-06-03 - Yixiao Case-Study Finish-Line Reorientation
+
+- Re-read the current Yixiao case-study runbook, prototype readiness protocol,
+  backlog, and progress log after returning to the project.
+- Re-ran the live Yixiao smoke harness against the demo backend:
+  - command: `.venv/bin/python scripts/run_yixiao_case_study_smoke.py --report /tmp/yixiao-case-study-smoke-report-latest.json --verbose`;
+  - first sandboxed attempt was blocked from localhost HTTP;
+  - reran with approved local API access.
+- Smoke result: passed.
+- Current verified workflow: `181`.
+- Current verified viewer:
+  `https://demo.seg.bio/neuroglancer/v/33755065f156f05d7d4ba86918a641c02d8d90de/`.
+- Verified gates:
+  - Yixiao project root and manifest exist;
+  - manifest has 10 volumes: 6 ground truth, 2 needs proofreading, 2 missing segmentation;
+  - backend health passes;
+  - Yixiao project suggestion is mounted;
+  - profile resolves `data/raw`, `data/seg`, and `configs/TapeReader-Fiber-BCS-AppCompat-Sanity.yaml`;
+  - progress summary reports 60% complete and 80% segmentation coverage;
+  - project memory schema and `tapereader_xri_fiber` preset are present;
+  - Neuroglancer viewer generation succeeds for the first image/mask pair;
+  - agent correctly identifies Yixiao/XRI/CytoTape project context;
+  - agent stages an approval-gated training action using 6 GT volumes, leaving 2 draft masks and 2 image-only targets out;
+  - PyTC subset resolver maps staged training directories to 6 concrete image/label files;
+  - staged training config validates without launching a full GPU job.
+
+## 2026-06-04 - Evidence Bundle Hygiene For Yixiao Case Study
+
+- Hardened workflow evidence export to avoid repeated raw-volume copies by default:
+  - added raw-image path detection (`.../raw/...` and `*_raw*` patterns),
+  - added separate `raw_copy_max_bytes` policy (default `0`),
+  - retained general `copy_max_bytes` cap for non-raw artifacts,
+  - added manifest-only mode via `copy_manifest_only=true`.
+- Exposed export copy controls on `POST /api/workflows/{workflow_id}/export-bundle`:
+  - `copy_max_bytes`
+  - `raw_copy_max_bytes`
+  - `copy_manifest_only`
+- Included `copy_settings` in bundle metadata and `workflow.bundle_exported` audit
+  event payload.
+- Added focused regression coverage in `tests/test_workflow_export_bundle.py` to verify
+  raw-like paths are skipped by default and manifest-only export skips binary copies.
+- Updated `docs/manual-yixiao-case-study-demo.md` and
+  `docs/research/workflow-evidence-export.md` with operator guidance for large-volume
+  case-study exports.
+- Verification:
+  - `.venv/bin/python -m pytest tests/test_workflow_export_bundle.py -q` passed.
+
+## 2026-06-04 - Yixiao Pre-Demo Gate Fastening
+
+- Extended `scripts/run_yixiao_case_study_smoke.py` with a deterministic pre-demo mode:
+  - added `--pre-demo-gate` orchestration that runs baseline smoke, promotion smoke, and final restore smoke,
+  - optionally performs lightweight readiness and export checks (`/case-study-readiness`, `/export-bundle`) and records residual caveats in the JSON output,
+  - writes per-step reports at deterministic sibling paths and a composite report at `--report`.
+- Added focused unit tests in `tests/test_yixiao_pre_demo_smoke.py` with mocked `run` and `SmokeHarness.request_json`:
+  - verifies step ordering and pass/fail aggregation,
+  - verifies residual readiness caveat behavior,
+  - verifies export payload failure is surfaced as a gate failure.
+- Updated `docs/manual-yixiao-case-study-demo.md` with the new fast pre-demo command and defaults,
+  including readiness/export skip options.
+- Updated `docs/research/subagent-reliability-qa-2026-05-27.md` to document the new pre-demo gate in the Yixiao QA flow.
+- Verification:
+  - `.venv/bin/python -m py_compile scripts/run_yixiao_case_study_smoke.py` passed;
+  - `uv run pytest tests/test_yixiao_pre_demo_smoke.py -q` passed.
+  - pre-demo gate error handling is covered for readiness/export endpoint failures and reports them as residual caveats.
+
+## 2026-06-04 - Deployment Runtime Diagnostics Helper
+
+- Added `scripts/inspect_demo_instance.py` as a fast operator-only diagnostics script for
+  case-study readiness triage.
+- Checks implemented:
+  - API health and `/app/log-path` connectivity;
+  - API runtime config log reconciliation (`api_runtime_configured`);
+  - worker direct `GET /hello` and API `GET /training_status`;
+  - worker URL mismatch detection from runtime log/proxy observations;
+  - current workflow read for active-state visibility (`/api/workflows/current`);
+  - Neuroglancer reachability and public-base/url alignment checks;
+  - Ollama model/chat reachability checks with env-variable diagnostics;
+  - workflow bundle disk usage and recent app-log ERROR count from log tail.
+- Updated `docs/manual-yixiao-case-study-demo.md` with an operator section including
+  pre-demo command (`inspect_demo_instance.py`) and failure interpretation.
+- Added focused unit coverage in `tests/test_inspect_demo_instance.py` covering:
+  - API health/workflow auth-state checks,
+  - runtime-config worker mismatch check,
+  - worker mismatch detection via proxy log target,
+  - Neuroglancer connectivity checks with mocked socket failure,
+  - disk/error tail behavior.
+- Verification:
+  - `.venv/bin/python -m py_compile scripts/inspect_demo_instance.py tests/test_inspect_demo_instance.py` passed;
+  - `.venv/bin/pytest -q tests/test_inspect_demo_instance.py` passed.
+
+## 2026-06-04 - Demo2 API Runtime Manager
+
+- Added `scripts/manage_demo_instance.py` for safe, scoped control of demo2 API:
+  - supports `start|stop|restart|status` with `nohup` + `setsid`;
+  - discovers matching processes by repo checkout path and `server_api.main` command, and
+    requires `PYTC_API_PORT` match (defaults to `4342`) to avoid touching demo3/user-seg-bio;
+  - verifies persistence with `/health` and prints recent startup log output when a fresh start does not become ready;
+  - uses graceful SIGTERM then SIGKILL fallback on stop.
+- Added `tests/test_manage_demo_instance.py` with unit coverage for:
+  - process discovery filtering by root/port,
+  - command composition including required `nohup setsid`,
+  - env override parsing,
+  - stop path behavior and status when no process exists.
+- Updated `docs/manual-yixiao-case-study-demo.md` with an operator restart command for demo2.
+- Verification:
+  - `uv run pytest tests/test_manage_demo_instance.py -q` passed.
+
+## 2026-06-04 - Agent Bounded-Action Audit for TapeReader Workflow
+
+- Audited `server_api/workflows/router.py` for TapeReader/TapeReader-XRI routing gaps and enforced bounded routines:
+  - explicit workflow pair selection is used for visualization when concrete image/label paths are set;
+  - proofreading keeps preferring draft/corrected masks first;
+  - TapeReader training now requires trusted label sources (confirmed labels or saved proofreading edits) before launch, and does not accept raw predictions as training labels;
+  - inference still requires a checkpoint before launch;
+  - evaluation requires previous result, new result, and reference mask before comparison.
+- Added focused backend coverage in `tests/test_workflow_routes.py` for:
+  - explicit visualization pair selection;
+  - TapeReader training trust-boundary blocker and recovery with corrected edits;
+  - checkpoint requirement for image-only inference requests;
+  - evaluation blocker when reference mask is missing.
+- Updated `docs/agent-role-spec.md` with a TapeReader bounded-action contract section.
+- Verification:
+  - `.venv/bin/python -m py_compile server_api/workflows/router.py`
+  - `.venv/bin/pytest tests/test_workflow_routes.py -k 'agent_visualize_request_uses_explicit_selected_pair or agent_train_on_trusted_masks_only_for_tapereader_context or agent_infer_on_image_only_projects_only_with_checkpoint or agent_evaluation_blocks_when_reference_mask_missing' -q`
+
+## 2026-06-04 - Workflow Session Continuity and Training Proposal Hardening
+
+- Hardened workflow chat/proposal continuity for browser refresh and reopen:
+  - workflow session hydration now merges server-side proposal status into persisted local chat entries so approved/reviewed runs keep correct card state after reload,
+  - proposal cards now render approval state and action visibility from proposal status,
+  - proposal payload now carries action-card/agent context through card rendering.
+- Added durable runtime resume support for training monitoring:
+  - `approveAgentAction` stores a `monitor_training` pending action after durable training approval,
+  - `WorkflowContext` restores monitor actions from sessionStorage with workflow-scoped TTL,
+  - stale/invalid persisted actions are cleared, preventing cross-workflow bleed-through.
+- Reduced action-card clipping/clarity risks:
+  - wrapped proposal field and rationale text in `AgentProposalCard` and `App.css`.
+- Added focused React verification:
+  - `client/src/contexts/WorkflowContext.test.js` covers restore/persist pending runtime actions.
+  - `client/src/components/Chatbot.test.js` covers proposal-status reconciliation across reopen plus routing guard for non-workflow conceptual questions.
+  - `client/src/components/chat/AgentProposalCard.test.js` covers disabled action state after approval.
+- Verification:
+  - `npm --prefix client test -- --watchAll=false --runInBand --runTestsByPath src/contexts/WorkflowContext.test.js src/components/Chatbot.test.js src/components/chat/AgentProposalCard.test.js`
+
+## 2026-06-04 - Yixiao Closed-Loop Evaluation Rehearsal Guard
+
+- Added a Yixiao-specific closed-loop rehearsal mode to
+  `scripts/run_yixiao_case_study_smoke.py`:
+  - `--closed-loop-rehearsal` runs the existing local closed-loop evidence harness
+    for image-only targets `6_1` and `6_2`;
+  - the mode requires explicit external withheld masks and refuses mounted-project
+    truth for the image-only targets;
+  - rehearsal now enforces explicit holdout usage for real-artifact evaluation
+    (`require_explicit_ground_truth`) and records per-target source checkpoints,
+    model versions, and runtime sync summaries;
+  - the default crop is `0:8,0:128,0:128` so it is fast enough for operator checks;
+  - defaults now include dry-run iteration overrides
+    (`--closed-loop-training-iterations`, `--closed-loop-inference-iterations`);
+  - reports are written under `/tmp/yixiao-closed-loop-rehearsal-report.json` by default.
+- Updated `docs/manual-yixiao-case-study-demo.md` with the command and clear
+  scope boundaries: this validates closed-loop training/inference/evaluation
+  wiring, checkpoint/model-version capture, and explicit holdout constraints.
+- Added focused test coverage in `tests/test_yixiao_pre_demo_smoke.py` verifying
+  that the rehearsal passes external withheld masks for `6_1` and `6_2`, and that
+  rehearsal fails when holdout paths are not outside the mounted project.
+- Added focused test coverage in `tests/test_closed_loop_smoke_script.py` for
+  runtime sync/report shape and explicit ground-truth requirements in real-artifact mode.
+
+## 2026-06-04 - Parallel Finish-Line Integration Pass
+
+- Re-ran the finish-line heuristic for the Yixiao case-study prototype and split the remaining work across six focused subagents:
+  - closed-loop rehearsal/execution evidence,
+  - browser-facing QA harness,
+  - approval-card editing UX,
+  - workflow memory/provenance export,
+  - demo deployment survivability,
+  - paper/case-study readiness gates.
+- Integrated the subagent results into the main demo2 checkout and verified the combined system:
+  - `.venv/bin/python -m py_compile ...` passed for touched smoke scripts and workflow backend modules;
+  - focused backend suite passed: `102 passed`;
+  - focused React suite passed: `50 passed`;
+  - `npm --prefix client run build` completed with only pre-existing React hook warnings in `DetectionWorkflow.js` and `ProofreadingEditor.js`;
+  - closed-loop rehearsal passed for Yixiao image-only targets `6_1` and `6_2`;
+  - post-deploy Yixiao pre-demo gate passed all 5 steps: normal smoke, promotion roundtrip, restore state, readiness check, export sanity;
+  - demo2 API was restarted with `scripts/manage_demo_instance.py` and came back healthy as PID `976573`;
+  - final `inspect_demo_instance.py` passed API, worker proxy, current workflow, Neuroglancer, app-error, and disk checks against configured Neuroglancer port `4244`.
+- Remaining known gaps:
+  - browser smoke is implemented but requires installing Playwright before it can run end-to-end in this checkout;
+  - real GPU train/infer/eval remains outside the automated paper-strength gate and should be run manually before any performance claims;
+  - evidence export still has deeper schema polish remaining around strict response models and durable proposal-to-approval foreign-key edges.
+
+## 2026-06-04 - Literature-Informed Third Finish-Line Pass
+
+- Ran a new HCI/VIS-oriented scan and captured the resulting task taxonomy in
+  `docs/codex-working-memory/third-finish-line-lit-and-task-taxonomy.md`.
+  Source anchors included common-ground workflow schemas, agentic visualization
+  patterns, multimodal visual-analytics agents, feedback-barrier work, and a
+  recent human-AI collaboration review.
+- Split implementation across six focused workers:
+  - common-ground project facts in Files setup,
+  - visible operational traces in chat/proposal/timeline UI,
+  - backend action policy/freshness regressions,
+  - evidence/export contract strengthening,
+  - browser certification and proposal-edit smoke coverage,
+  - runtime/deploy observability.
+- Integrated the worker outputs:
+  - setup now shows a compact "Shared project facts" surface for modality,
+    target, voxel size, volume split, task family, and training policy;
+  - proposal cards and timeline entries now expose concise operational traces
+    with inspected facts, policy decision, approval/execution status, affected
+    artifacts, and project-memory updates;
+  - evidence export now includes stronger copy-policy/provenance metadata and a
+    proposal -> approval -> command/run/progress graph;
+  - browser smoke now checks editable proposal behavior and reports exact
+    Playwright installation commands when the dependency is missing;
+  - inspector now reports a unified runtime-config check and treats transient
+    training-status timeouts as warnings rather than hard failures;
+  - backend route tests now cover existing policy/freshness payloads around
+    missing/stale project context and approval-required actions.
+- Integration fixes:
+  - updated `_build_proofreading_action` to pass through `policy_decision`,
+    `blocking_reasons`, and `freshness` to action cards;
+  - removed fresh frontend lint warnings from the operational-trace changes.
+- Verification before deploy:
+  - `git diff --check` passed;
+  - py_compile passed for changed scripts and workflow backend modules;
+  - backend integration slice passed: `97 passed`;
+  - React integration slice passed: `69 passed`;
+  - focused proposal/timeline tests passed: `42 passed`;
+  - production build passed with only pre-existing hook warnings in
+    `DetectionWorkflow.js` and `ProofreadingEditor.js`.
+- Remaining known gaps:
+  - Playwright is still not installed in this checkout, so browser smoke is
+    ready but not executed end-to-end here;
+  - real GPU train/infer/eval remains required before claiming model-performance
+    improvement;
+  - evidence payloads are more structured but still not fully typed with
+    strict Pydantic nested models.
diff --git a/docs/codex-working-memory/research-log.md b/docs/codex-working-memory/research-log.md
new file mode 100644
index 00000000..82df6753
--- /dev/null
+++ b/docs/codex-working-memory/research-log.md
@@ -0,0 +1,776 @@
+# PyTC Client Research Log
+
+Paper-facing implementation notes for the TOCHI prototype. This file is local-only and outside the Git-tracked repo.
+
+## 2026-04-28 - PyTC Dataset Prepilot Stress Test Plan
+
+### Design Decision
+
+Drafted a solo prepilot plan that uses real PyTorch Connectomics dataset/config families before recruiting case-study participants. The ladder starts with local Mito25, then uses public MitoEM toy crops, Lucchi/Lucchi++, CREMI, SNEMI3D, and NucMM to progressively stress project setup, data role inference, config selection, runtime orchestration, proofreading, correction export, metrics, and evidence bundles.
+
+### Research Rationale
+
+The prototype should fail in private on realistic PyTC data before it is shown in case studies. The selected datasets cover the main PyTC workflow families: mitochondria semantic segmentation, mitochondria instance segmentation, synaptic cleft detection, dense neuron affinity segmentation, and nuclei instance segmentation. This intentionally tests whether the app is project-agnostic or still implicitly shaped around the mito25 demo path.
+
+### User-Control Implication
+
+The prepilot emphasizes explicit confirmation of project roles and approval-gated agent actions. It also checks whether the agent gives workflow-specific next actions rather than exposing PyTC docs or raw config mechanics to a biologist.
+
+### Evidence Captured In Docs
+
+- Added `docs/research/pytc-prepilot-dataset-stress-test.md`.
+- The doc includes source grounding, public data links, matching local config paths, a dataset ladder, solo test script, expected failure modes, and a minimum completion bar before external case studies.
+- Added and ran `scripts/ingest_prepilot_datasets.py`.
+- Staged local prepilot projects under `/Users/adamg/seg.bio/testing_projects`: `prepilot_mito25_smoke`, `prepilot_mitoem_toy`, `prepilot_lucchi_pp`, `prepilot_snemi3d_local`, `prepilot_cremi_official`, and `prepilot_nucmm_mouse`.
+- Each staged project has `project_manifest.json`, `notes/README.md`, and `notes/prepilot-log.md`; public sources were downloaded from Hugging Face and CREMI where needed, while existing local data was symlinked.
+
+### Open Paper Question
+
+Decide which two non-mito25 datasets should become paper-demo fixtures. MitoEM toy crop plus Lucchi/CREMI is the most practical pair because they stress project agnosticism without requiring the full MitoEM2.0 or NucMM scale.
+
+## 2026-04-13 - Workflow Spine Milestone
+
+### Design Decision
+
+The prototype now has an explicit workflow spine: `WorkflowSession` stores the current loop state, and `WorkflowEvent` stores chronological evidence of user, agent, and system actions. The first loop target is load data, visualize/infer, proofread, export corrected masks, stage corrected masks for retraining, and preserve the evidence trail.
+
+### Research Rationale
+
+The paper framing argues that biomedical segmentation is not a one-shot inference task. The workflow state model makes the iterative cycle concrete in the system: each step can be inspected, replayed in a timeline, and used by the agent when recommending next actions.
+
+### User-Control Implication
+
+Agent actions are proposal-first. The workflow-aware agent can create a pending proposal, but mutation happens only when the user approves the allowlisted action. The first action is intentionally narrow: `stage_retraining_from_corrections`.
+
+### Evidence Captured In Code/Logs
+
+- `workflow.created` records session creation.
+- `viewer.created` records Neuroglancer viewer creation and URL.
+- `inference.started`, `inference.completed`, and `inference.failed` record inference transitions.
+- `dataset.loaded` and `proofreading.session_loaded` link EHTool sessions to workflow state.
+- `proofreading.instance_classified`, `proofreading.mask_saved`, and `proofreading.masks_exported` record proofreading work.
+- `agent.proposal_created`, `agent.proposal_approved`, and `agent.proposal_rejected` record mixed-initiative control decisions.
+- `retraining.staged` records the corrected mask artifact selected for retraining.
+
+### Open Paper Question
+
+The current milestone stages retraining but does not prove that retraining improves the model. For the paper, this supports the workflow-orchestration claim, but a stronger evaluation needs model-version artifacts and before/after evidence.
+
+## 2026-04-13 - Workflow Timeline And Chat Integration
+
+### Design Decision
+
+The chat drawer now includes a compact workflow timeline. Workflow-related user queries route to `POST /api/workflows/{id}/agent/query`; unrelated chat still uses the existing chatbot path.
+
+### Research Rationale
+
+This keeps the agent grounded in current system state without pretending that every general chat message is an executable workflow instruction.
+
+### User-Control Implication
+
+Pending proposals appear with explicit Approve and Reject controls. Approval returns client effects such as navigation to Model Training and prefilled training label path, but only after the user clicks Approve.
+
+### Evidence Captured In Code/Logs
+
+Frontend tests cover timeline rendering and approve/reject controls. Backend tests cover approval/rejection state transitions and event creation.
+
+### Open Paper Question
+
+The current agent response is deterministic fallback logic. If an LLM-backed planner is added later, the paper should distinguish between agent UX/design contribution and LLM reasoning capability.
+
+## 2026-04-13 - Verification Notes
+
+### Design Decision
+
+Automated verification currently emphasizes API contracts and UI-state wiring rather than a browser-level human proofreading session.
+
+### Research Rationale
+
+The tests prove that evidence is generated for the intended loop transitions, which is directly relevant for later paper claims about inspectable workflow history. They do not yet prove usability or interaction efficiency.
+
+### User-Control Implication
+
+Approval/rejection is covered at both backend and frontend levels. This supports the claim that the prototype uses user-approved agent execution rather than hidden automation.
+
+### Evidence Captured In Code/Logs
+
+- Backend tests pass for workflow current/create/update/events and agent approve/reject.
+- Backend EHTool test passes for dataset load, instance classify, mask save, and mask export event logging.
+- Frontend tests pass for EHTool re-enable, workflow timeline, approve/reject controls, and approval client effects.
+- Production build succeeds with warnings that are mostly existing technical debt.
+
+### Open Paper Question
+
+Before evaluation, add a realistic walkthrough dataset and run a browser-level smoke or study-pilot task that records time/order of actions, agent proposal usefulness, and points of user override.
+
+## 2026-04-13 - LLM Configuration Failure UX
+
+### Design Decision
+
+The AI assistant no longer relies on implicit local or hardcoded remote Ollama defaults. Operators must export `OLLAMA_BASE_URL`, `OLLAMA_MODEL`, and `OLLAMA_EMBED_MODEL` before starting the app. Backend failures are logged and returned as structured LLM-unavailable errors; the frontend prioritizes the user-facing administrative message.
+
+### Research Rationale
+
+For a research prototype, failed agent infrastructure should be explicit rather than mistaken for a failed user action. Making the LLM endpoint an operator-controlled environment variable separates system deployment configuration from the interaction design being evaluated.
+
+### User-Control Implication
+
+Users see that the assistant is unavailable because of system configuration or connectivity, not because their request was invalid. The error text directs them to an administrator while preserving the underlying message needed for diagnosis.
+
+### Evidence Captured In Code/Logs
+
+- Missing `OLLAMA_BASE_URL`, `OLLAMA_MODEL`, or `OLLAMA_EMBED_MODEL` raises a configuration error before chat execution.
+- `OLLAMA_BASE_URL` must be a full URL with an explicit port.
+- Chat and helper-chat initialization/invocation failures are logged with `[CHATBOT]` prefixes and returned as structured `llm_unavailable` responses.
+- Frontend API handling surfaces `detail.user_message` without prefixing it with an HTTP status.
+
+### Open Paper Question
+
+For study deployments, decide whether LLM availability should be preflighted in the UI before sessions begin, so participants do not encounter infrastructure failures during timed workflow tasks.
+
+## 2026-04-13 - Agentic Framing Rewrite For Manuscript Sections 3/4
+
+### Design Decision
+
+Reframed manuscript Sections 3 and 4 so the assistant is modeled as an agentic workflow harness with explicit autonomy modes, rather than as an add-on chat interface.
+
+### Research Rationale
+
+Paper title and contribution claims require an explicit mapping from expert workflow pain points to agent-mediated capabilities. The revised structure now makes that mapping inspectable:
+
+- Section 3 now includes `G6` (agent leverage under human control), `R9` (configurable autonomy envelope), and `T7` (draft bounded multi-step delegation).
+- Section 4 now describes implemented and draft agent modes (`M1`/`M2`/`M3`) and ties concrete features to `G/R/T`.
+
+### User-Control Implication
+
+The rewritten framing keeps control boundaries explicit: implemented behavior is approve-then-execute, while project-level autonomy is clearly labeled draft/planned with guardrails and interruption rights.
+
+### Evidence Captured In Code/Logs
+
+- Added a Section 4 feature matrix table (`Feature`, `Status`, `Agentic Function`, `G/R/T` mapping).
+- Added explicit draft labeling in manuscript text for non-implemented autonomy features.
+- Recompiled manuscript PDF after each text-edit iteration.
+
+### Open Paper Question
+
+Decide whether the final paper should present bounded autonomy as a design implication only, or include an implemented minimal version (`T7`) before submission to support stronger empirical claims.
+
+## 2026-04-13 - Manuscript Status-Language Policy
+
+### Design Decision
+
+Removed explicit implementation-status markers (e.g., "implemented", "draft", "not yet implemented") from manuscript Sections 3 and 4, including the feature mapping table.
+
+### Research Rationale
+
+For paper readability and narrative coherence, the public manuscript now presents a unified system-design view centered on human--agent collaboration patterns, while implementation maturity distinctions are maintained separately in internal project logs.
+
+### User-Control Implication
+
+Control-boundary claims remain explicit in manuscript text (approval gates, bounded autonomy guardrails), but maturity-level tracking moved to internal documentation.
+
+### Evidence Captured In Code/Logs
+
+- Section 4 table schema changed from `Feature | Status | Agentic Function | Mapping` to `Feature | Agentic Function | Mapping`.
+- Section 3/4 wording updated to remove direct status qualifiers.
+- Internal logs now carry the implementation-vs-ideation distinction.
+
+### Open Paper Question
+
+Before submission freeze, decide whether to reintroduce concise scoping language in a limitations paragraph to avoid over-claim risk while preserving the cleaner narrative flow.
+
+## 2026-04-13 - TOCHI Writing Pattern Synthesis and Manuscript Refactor
+
+### Design Decision
+
+Used a targeted corpus pass over nine recent TOCHI papers to refactor manuscript Sections 3--5 toward a question-driven, traceable, and claims-calibrated narrative structure.
+
+### Research Rationale
+
+The strongest recurring pattern was explicit traceability: empirical observations are translated into goals/requirements/tasks, then mapped to design features and evaluated against explicit questions. We mirrored that pattern by adding:
+
+- formative questions (`FQ1`, `FQ2`) in Section 3,
+- a `G -> R -> T` traceability table,
+- a structured evaluation protocol (`EQ1`--`EQ3`, measures, analysis plan).
+
+### User-Control Implication
+
+The revised writing keeps control boundaries explicit while avoiding status labels in paper text:
+
+- human approval remains central for mutating agent actions,
+- agent orchestration remains bounded by guardrails,
+- provenance is treated as a first-class evaluation target.
+
+### Evidence Captured In Code/Logs
+
+- Manuscript edits in `sample-manuscript.tex` covering Sections 3, 4, and 5.
+- PDF re-rendered after edits (`sample-manuscript.pdf`).
+- Internal synthesis notes recorded in `tochi-writing-synthesis.md`.
+
+### Internal Implementation Distinction (Not In Manuscript Text)
+
+Implemented evidence-backed features:
+
+- workflow session/event model and APIs,
+- event-linked inference/proofreading flows,
+- approval/rejection action gating,
+- workflow-aware chat timeline,
+- LLM configuration hardening and backend diagnostics.
+
+Ideation/planned feature set:
+
+- failure hotspot prioritization,
+- correction impact preview,
+- bounded project-level autonomous run manager,
+- versioned experiment bundles,
+- CAVE-compatible integration,
+- autonomous plan simulation/edit-before-run.
+
+### Open Paper Question
+
+In final drafting, decide whether to keep Section 5 as protocol-forward (pre-summative-study) or split into "Evaluation Plan" and "Preliminary Instrumentation Results" if pilot data is available by submission lock.
+
+## 2026-04-13 - Long-Form TOCHI-Style Expansion Pass
+
+### Design Decision
+
+Performed a high-volume prose expansion across Sections 3--6 to align narrative density with recent TOCHI papers while preserving technical traceability and agentic framing.
+
+### Research Rationale
+
+Recent TOCHI articles in the reviewed corpus consistently combine: (1) explicit framing questions, (2) richer methodological prose, (3) stronger bridge text between findings and design, and (4) substantial discussion/limitations narratives. To better match that shape, the manuscript was expanded from concise scaffolding to fuller paragraph-based argumentation.
+
+### User-Control Implication
+
+The expanded text continues to center user authority:
+
+- agent guidance is grounded in workflow evidence,
+- mutating actions remain approval-gated,
+- bounded autonomy is framed around checkpoints and interruption rights.
+
+### Evidence Captured In Code/Logs
+
+- `sample-manuscript.tex` expanded in:
+  - Section 3 (`Formative Participants`, `Observed Workflow Pattern`, new `Workflow Breakdowns and Agent Opportunities`, expanded goal/requirement/task bridge),
+  - Section 4 (new `Architecture Overview`, richer interaction-model interpretation, added F9--F11 prose, closed-loop walkthrough),
+  - Section 6 (`Discussion`) and `Limitations/Conclusions` (now draft prose, not placeholders).
+- Added additional `\grace{TODO...}` anchors for user-fill specifics (protocol details, figures, deployment constraints, final takeaway line).
+- Recompiled PDF successfully (`sample-manuscript.pdf`, 22 pages).
+
+### Internal Implementation Distinction (Not In Manuscript Text)
+
+The manuscript text remains status-neutral. Implementation-vs-ideation distinctions continue to be tracked only in internal logs and synthesis notes.
+
+### Open Paper Question
+
+Decide whether to keep F9--F11 and extension narrative at current length in the final camera-ready draft, or reduce forward-looking feature text if reviewer emphasis shifts toward strictly demonstrated capabilities.
+
+## 2026-04-13 - Case-Study Framing Correction (Pre-Interview Status)
+
+### Design Decision
+
+Removed manuscript wording that implied interviews had already been completed; restructured Section 3 to present a planned two-phase case study.
+
+### Research Rationale
+
+Claim calibration is critical for TOCHI review. Since interviews and user studies are not yet run, the paper should present:
+
+- a rigorous study design and requirement framework,
+- a concrete implemented prototype,
+- clearly planned empirical phases.
+
+### User-Control Implication
+
+The revised text still centers human-control boundaries, but now frames them as design hypotheses and evaluation targets to be tested in Phase II rather than as concluded findings.
+
+### Evidence Captured In Code/Logs
+
+- Intro and contribution bullets updated to protocol-first wording.
+- Section 3 retitled and reorganized around:
+  - two-phase structure,
+  - Phase I interview plan,
+  - provisional workflow/breakdown model,
+  - provisional G/R/T traceability,
+  - explicit Phase II linkage.
+- Discussion/limitations language adjusted to avoid post-hoc empirical claims.
+- PDF re-rendered (`sample-manuscript.pdf`, 23 pages).
+
+### Open Paper Question
+
+When Phase I starts, decide whether to preserve all provisional framing text as “study design” context or replace portions with empirical findings immediately to reduce redundancy.
+
+## 2026-04-13 - Consolidated Codex Wave (Implemented vs Deferred)
+
+### Design Decision
+
+Consolidated all codex-generated draft PR outputs into one architecture-aligned integration branch and one draft PR, instead of merging each draft branch directly.
+
+### Research Rationale
+
+The codex draft branches were generated against mixed assumptions (notably `server_api/workflow/*` vs repo-standard `server_api/workflows/*`). A direct-merge strategy would obscure evaluation evidence and create fragile behavior. Behavior-first porting preserves traceability and keeps implementation consistent with the workflow-spine milestone framing.
+
+### User-Control Implication
+
+User control remains explicit:
+
+- mutating workflow operations still require approve/reject decisions,
+- proposal cards increase transparency of agent intent and parameters,
+- timeline filters make auditability easier during debugging and study instrumentation.
+
+### Evidence Captured In Code/Logs
+
+- Consolidated branch/PR:
+  - branch: `feat/codex-wave-integration`
+  - draft PR: `#165` (to `main`)
+- Implemented in this wave:
+  - workflow hotspots + impact preview,
+  - workflow metrics endpoint,
+  - workflow export-bundle endpoint,
+  - workflow evidence utility module and research export doc,
+  - chat lifecycle observability summary logging,
+  - timeline actor/event filters,
+  - richer pending proposal cards with approve/reject.
+- Deferred intentionally:
+  - CAVE integration spike scaffolds/docs remain deferred backlog work (not merged as product behavior).
+- Consolidation hygiene:
+  - codex source draft PRs `#139`-`#164` closed with redirect to `#165`.
+
+### Open Paper Question
+
+Decide whether to expose workflow metrics/export-bundle endpoints in the paper as “evaluation instrumentation implemented” or keep them described as internal research support infrastructure, depending on how much of their output is used in the final user-study analysis.
+
+## 2026-04-27 - Editable Project Role Confirmation Checkpoint
+
+### Design Decision
+
+Project mounting now separates indexing from workflow registration. The app
+infers likely project roles from the mounted directory, then asks the user to
+confirm or edit image, mask/label, prediction, checkpoint, and optional config
+paths before writing workflow state.
+
+### Research Rationale
+
+This makes the prototype more project-agnostic and aligns with the paper's
+human-controlled agent framing. Auto-detection is useful, but silently treating
+detected files as workflow facts makes the system brittle and hard to explain
+in a study. Confirmation creates an auditable handoff from file management to
+the segmentation loop.
+
+### User-Control Implication
+
+Image volume is the only required role. Biologists can start with image-only
+data, add masks later, or override incorrect auto-detected files without typing
+full paths. The agent should treat unconfirmed role guesses as suggestions and
+confirmed roles as workflow context.
+
+### Evidence Captured In Code/Logs
+
+- Added confirmed-role workflow patch generation utilities.
+- Updated File Management so suggested and manually mounted directories open a
+  role-confirmation modal before `dataset.loaded`.
+- `dataset.loaded` now records confirmed roles, profile mode, mounted root, and
+  workflow patch source metadata.
+- Added frontend tests for suggested project confirmation, edited/cleared roles,
+  image-only setup, and canceling manual mount confirmation.
+
+### Open Paper Question
+
+Decide how much of this setup handoff appears in the paper figures: it may be
+important evidence for bounded autonomy, but it should not distract from the
+main segmentation-loop contribution.
+
+## 2026-04-27 - Config Lineage and Durable Evidence Bundle Pass
+
+### Design Decision
+
+Confirmed project configs are now persisted as first-class workflow state, and
+workflow evidence export writes a durable local bundle directory in addition to
+returning JSON through the API.
+
+### Research Rationale
+
+The paper-ready prototype needs artifact lineage that survives beyond the live
+UI session. A config path is part of the model/run decision, not just a UI
+detail. Likewise, a bundle response that only exists in memory is insufficient
+for case-study audit, figure preparation, or claim calibration.
+
+### User-Control Implication
+
+The agent can prefer the confirmed config when staging training defaults, but
+runtime launch remains approval-gated. Evidence export now creates a local
+directory with `workflow-bundle.json`, `artifact-paths.json`, `README.md`, and
+small copied artifacts while referencing large files by path.
+
+### Evidence Captured In Code/Logs
+
+- Added `WorkflowSession.config_path`, update/response serialization, SQLite
+  compatibility column creation, and frontend role-confirmation propagation.
+- Agent training defaults now prefer the confirmed workflow config path before
+  falling back to data-derived bundled presets.
+- `export-bundle` now records `bundle_directory`, `bundle_manifest_path`, copied
+  artifact count, skipped artifact count, and missing path count in the audit
+  event.
+
+### Open Paper Question
+
+Decide whether final study exports should copy large image/mask/checkpoint
+files into a removable bundle or keep the current safer manifest-plus-small-
+artifact approach for local case-study machines.
+
+## 2026-04-28 - Directory-Aware Project Ingest Pass
+
+### Design Decision
+
+Project setup now treats a mounted project as a directory structure first, not
+as one image/mask/config tuple. Backend profiling reports role directories and
+detected image/label volume sets. The frontend defaults to folder-level roles
+when multiple image/label volumes are detected, while preserving single-file
+defaults for small smoke projects.
+
+### Research Rationale
+
+Practitioner project folders often contain batches, train/test splits, or
+multiple crops. A one-file confirmation modal misrepresents that workflow and
+weakens the paper claim that the agent can help with realistic iterative
+segmentation. Directory-aware confirmation makes the human-agent handoff more
+honest: the agent infers likely structure, then the user quickly corrects it.
+
+### User-Control Implication
+
+The user can now type a short biological/project-context note during setup and
+confirm folders or files for image, label, prediction, checkpoint, and config
+roles. Workflow state still changes only after `Start project`; the
+`dataset.loaded` event records confirmed roles, detected directories, detected
+volume sets, and project context.
+
+### Evidence Captured In Code/Logs
+
+- Added backend role-directory summaries, generic `.zarr`/`.n5` directory
+  recognition, and `volume_sets` inference.
+- Updated project setup defaults to prefer folders only for multi-volume
+  projects.
+- Updated File Management confirmation UI to capture concise natural-language
+  project context and show detected batch structure.
+- Refined the confirmation UI to remove stage/readiness chips, avoid full
+  absolute paths in role fields, and present the detected project structure as
+  a compact agent-style sentence asking the user to confirm or correct it.
+- Added an in-modal setup feedback loop: pressing Enter submits the user's
+  question/correction, returns a compact local agent response, applies simple
+  detected split corrections such as "use val split", records a client app log
+  event, and appends a `dataset.setup_feedback` workflow event when a workflow
+  is active.
+- Fixed the feedback loop to support repeated correction turns. The submit path
+  now reads the latest draft setup state through a ref and does not block local
+  correction updates while workflow-event logging is still in flight.
+- Added backend and frontend tests for multi-volume folder defaults and event
+  payloads.
+
+## 2026-04-28 - Project Context First Confirmation Pass
+
+### Design Decision
+
+The confirmation flow now asks for broad biological/project context before it
+shows detected structure and before it accepts mapping corrections. The earlier
+single text box conflated "what is this dataset?" with "fix my file mapping,"
+which made the agent context ambiguous and made the UI feel like a technical
+manifest rather than a project handoff.
+
+### User-Control Implication
+
+The user can describe the directory in their own words first. The app then
+shows what it inferred, lets the user correct image/label/prediction/checkpoint
+roles separately, and only writes workflow state after `Start project`.
+Mapping correction turns are no longer folded into project context.
+
+### Evidence Captured In Code/Logs
+
+- Added a dedicated `projectDescription` field before detected structure.
+- Added a separate `mappingFeedback` field for the Enter-to-ask/apply loop.
+- Project descriptions are stored in `metadata.project_context` when supplied,
+  with lightweight inferred fields for modality, target structure, and
+  speed/accuracy preference.
+- `dataset.loaded` now carries both `project_description` and structured
+  `project_context`; `dataset.setup_feedback` remains the audit trail for file
+  mapping correction turns.
+- Focused frontend tests passed:
+  `CI=true npm test -- --runInBand src/views/FilesManager.test.js src/utils/projectSuggestions.test.js`
+  with 13 tests passing.
+
+### Open Risk
+
+The context parser is intentionally lightweight. It is good enough for common
+terms such as EM, micro-CT, mitochondria, nuclei, and speed/accuracy, but the
+agent still needs a richer context extraction pass or explicit follow-up
+questions for uncommon modalities, structures, and lab-specific naming.
+
+## 2026-04-28 - Staged Project Initialization and Hidden Agent Memory
+
+### Design Decision
+
+Project initialization is now a partitioned subworkflow. The app asks for
+semantic project context first, requires a deterministic completeness check,
+then moves to mechanistic file/folder mapping, and only then allows final
+workflow registration. This keeps biological intent and directory-role mapping
+separate while still making both available to the agent.
+
+### Perturbations From The Proposed Plan
+
+- The hidden project file is not the source of truth for audit. It is a compact
+  agent memory/profile layer; workflow DB records and events remain the
+  authoritative evidence trail.
+- The context threshold is deterministic rather than LLM-confidence-based:
+  modality, target structure, task goal, data organization, and speed/accuracy
+  preference are required unless the user explicitly chooses conservative
+  defaults.
+- A `Use defaults` escape hatch exists for smoke tests and ambiguous folders.
+  It is recorded in project context as `use_defaults: true` so the agent knows
+  it should be cautious later.
+
+### Evidence Captured In Code/Logs
+
+- Added backend read/write routes for `.pytc_project_context.json`.
+- Hid `.pytc_project_context.json` from project mounting and file listings.
+- Added staged modal states: `Describe project`, `Confirm file mapping`, and
+  `Start project`.
+- Added deterministic project-context parsing/completeness helpers.
+- On confirmation, the app writes workflow metadata, `dataset.loaded`, and the
+  hidden project memory file containing semantic context, mechanistic mapping,
+  workflow-memory summary, and setup turns.
+- Empty root file-management state now shows a project-initialization card
+  instead of a generic empty-folder state.
+- Focused frontend tests passed with 14 tests; backend file-workspace route
+  tests passed with 9 tests.
+
+### Open Risk
+
+The hidden memory file is written best-effort from the client through the API.
+Read-only mounted directories should surface a clearer user-facing warning if
+profile persistence fails; for now the workflow still starts and logs the
+failure.
+
+### Related Multi-Set Risk
+
+The app still chooses one active image/label root per workflow. True multi-set
+operation needs an active-set selector, batch actions, and agent actions that
+can iterate over several confirmed sets without hiding artifact provenance.
+
+## 2026-04-28 - Project Context Modal UI Trim
+
+### Decision
+
+The project-description step should collect semantic context without exposing
+the internal completeness rubric as visible UI. The modal now keeps only the
+plain-language prompt and text area. The deterministic parser, setup-turn
+recording, hidden `.pytc_project_context.json` profile, and workflow metadata
+are unchanged.
+
+### Rationale
+
+The visible "I still need..." diagnostic and the gray "Required..." footer made
+the setup feel like an implementation checklist rather than a normal project
+intake. The rubric remains useful for agent memory, but it should not be
+presented as primary biologist-facing UI.
+
+### Follow-Up Fix
+
+After hiding the rubric, `Continue` appeared broken whenever the description did
+not satisfy every deterministic context field because the modal stayed on the
+same step with no visible explanation. The setup flow now advances after any
+non-empty project description and records incomplete/missing context internally
+for the agent to resolve later. Empty descriptions still require either text or
+the explicit defaults path.
+
+### Correction To Match Intended Loop
+
+The intended interaction is not "any text advances"; it is: user gives a first
+description, the agent asks one follow-up question if context is incomplete, the
+user adds more detail, and the loop repeats until enough context exists. The UI
+now shows only the next natural-language follow-up question, never the internal
+missing-field checklist. `Use defaults` remains the explicit escape hatch.
+
+### Loop State Fix
+
+Runtime logs showed project-context review events with no frontend exception.
+The issue was local state: the text box was acting as both the current answer
+and the accumulated project description. Short follow-up answers such as `EM!`
+could therefore erase earlier context and make the loop appear stalled. The
+modal now keeps accumulated context separately, clears the answer box after each
+follow-up prompt, and appends each answer into hidden project memory. The parser
+also recognizes punctuated modality answers such as `EM!`.
+
+### Project Brief Upgrade
+
+The confirmation step now renders a derived project brief instead of a raw
+transcript/chip dump. The brief summarizes biological intent, extracted context
+fields, how the agent will use the confirmed paths/config, and the first
+uncertainty to watch. The same `project_brief` object is saved into the hidden
+project context profile and the `dataset.loaded` workflow event so this display
+also becomes agent-usable state.
+
+### Context Loop Stalling Fix
+
+Runtime `project_context_reviewed` events showed the modal was receiving
+`Continue` clicks, but missing fields were not shrinking on some projects. The
+loop was too dependent on what the user typed and ignored information already
+available from the profiled directory. A temporary implementation used
+name/path-derived defaults; that was later corrected below because it overfit
+semantically lucky demo names. App event logs still include the inferred context
+and next question so future stalls are diagnosable.
+
+### Content-Based Context Correction
+
+Name/path-based biological defaults were too brittle and too demo-specific.
+The profiler now separates mechanistic role classification from semantic
+project context. File and folder names may still classify roles such as image,
+label, prediction, config, and checkpoint, but modality/target/task hints come
+from lightweight content spot checks: manifest/config/readme snippets, HDF5
+dataset keys/shapes, TIFF headers, and extension counts. The frontend now
+consumes only explicit backend `context_hints` for biological defaults.
+
+The large File Management project-setup banner was removed. Suggested projects
+remain available through the normal `Open suggested project` button, keeping
+the file screen less visually noisy.
+
+## 2026-04-29 - Agent Action Card Robustness Fix
+
+### Diagnosis
+
+The screenshot query was routed as `status` because the status intent matched
+the term `ready` inside the word `already`. The agent then produced a next-step
+recommendation that said "Proofread this data" while the returned cards were
+generic status/setup actions. The app could render Run-in-app cards, but the
+backend selected the wrong card set.
+
+### Changes
+
+- Replaced raw substring status matching with token/phrase-aware `_query_has`.
+- Added explicit visualization intent handling for requests like "can you
+  visualize these volumes?".
+- Added visualization client effects so agent-run `View data` populates the
+  image/label fields before switching to the viewer.
+- Made setup-stage recommendations prefer `Proofread this data` when the
+  workflow already has a source volume plus mask/label/prediction.
+- Added proofreading blockers. If image or mask-like data are missing, the agent
+  now says exactly what is missing and offers `Choose data` rather than a fake
+  proofreading command.
+- Expanded workflow-agent backend logs with action ids, labels, command ids,
+  recommendation decision, next stage, and proofreading blockers.
+
+### Test Evidence
+
+- `/opt/homebrew/bin/uv run pytest tests/test_workflow_routes.py -q`: 26 passed.
+- `CI=true npm test -- --runInBand src/contexts/WorkflowContext.test.js src/components/Chatbot.test.js`: 16 passed.
+- `npm run build`: compiled successfully with existing warnings.
+
+### Remaining Risk
+
+The visualization card currently fills paths and opens the tab; it does not
+auto-click the Neuroglancer `Visualize` button. That is safer for now, but a
+future controlled `start_visualization` runtime action could make it fully
+hands-free.
+
+## 2026-04-29 - Proofreading Context Leak Diagnosis
+
+Runtime logs showed two separate failures after the agent was asked to visualize
+an image/segmentation pair. First, the visualization action populated the
+current `prepilot_nucmm_mouse` image and label directories, then Neuroglancer
+returned 400 because it was handed a directory path instead of a directly
+readable volume file. Second, the subsequent proofreading page showed
+`mito25-paper-loop-smoke` because `DatasetLoader` queried global
+`/files/project-suggestions` whenever no EHTool session was loaded.
+
+The latter was a real context leak: proofreading was advertising an unrelated
+suggested project independent of mounted/current workflow state. The loader now
+uses only the current workflow's confirmed image/mask paths, or falls back to
+the manual loader with no global suggestion card.
+
+The same log window showed duplicate `/eh/detection/load` attempts from one
+assistant proofreading action. A small one-shot guard was added around
+assistant-triggered proofreading runtime actions so React effect re-entry cannot
+submit the same load twice.
+
+## 2026-04-29 - Raw Tool Call Leak Fix
+
+The chat screenshot showed the general LLM path returning raw JSON:
+`{"name":"visualize_volume_pair", ...}`. Logs confirmed the request went through
+`/chat/query` rather than the workflow-agent endpoint, so the app displayed the
+local LLM's pseudo tool call as normal assistant text.
+
+Fixes: visualization/volume-pair requests now route to the workflow agent, which
+can return app actions/cards, and both frontend and backend chat sanitizers
+replace raw JSON tool-call-shaped responses with a plain-language recovery
+message. This protects current rendering and persisted chat history.
+
+## 2026-04-29 - Train/Run Model Label Pass
+
+Renamed the user-facing top navigation and major stage copy from `Train`/`Infer`
+and `Model Training`/`Model Inference` to `Train Model` and `Run Model`.
+Internal route keys, workflow stages, PyTC command flags, and persisted event
+types remain `training`/`inference` for compatibility.
+
+## 2026-04-29 - Visualization Folder-Pair Resolver
+
+A visualization run failed because the workflow stored folder-level roles
+(`Image/train` and `Label/train`) and `/neuroglancer` tried to read the image
+folder as a volume file. The backend now resolves folder-level visualization
+inputs to a concrete readable image/label pair before loading Neuroglancer. For
+folders with matching names like `img_000_604_576.h5` and `seg_000_604_576.h5`,
+it selects the matched pair, updates workflow paths to the concrete files, and
+logs the resolution as `neuroglancer_volume_path_resolved`.
+
+Also removed the duplicate workflow-agent command block for visualization
+requests. The assistant should now show one primary `View data` app action
+instead of both `View data` and `View data in app` for the same operation.
+
+## 2026-04-29 - Directory Pair Discovery for Visualization Agent
+
+Refined the visualization fix so directory roles are treated as candidate
+image/segmentation pair sets instead of just a folder to silently coerce into
+one file. Added shared volume-pair discovery logic that normalizes common
+image/label prefixes (`img_`, `seg_`, `label_`, `mask_`, etc.) and returns all
+clear matches. The workflow agent now detects these pairs before offering a
+`View data` action, points the action at the first concrete matched pair, and
+asks the user whether more folders or pairs should be included.
+
+The `/neuroglancer` endpoint now logs `neuroglancer_volume_pairs_detected`,
+returns the selected pair plus the detected pair set, and records
+`active_volume_pair` / `volume_pair_discovery` in workflow metadata when a
+directory-level request reaches the endpoint. The Visualization UI accepts this
+richer response shape, updates its local fields to the resolved concrete pair,
+and surfaces the "more pairs?" prompt as a lightweight message. The workflow
+agent also falls back to the stored discovery metadata after an active concrete
+pair has replaced folder-level fields, so it can keep continuity across later
+queries.
+
+Test evidence:
+
+- `python -m py_compile server_api/main.py server_api/workflows/router.py server_api/workflows/volume_pairs.py`
+- `/opt/homebrew/bin/uv run pytest tests/test_neuroglancer_volume_normalization.py -q`: 11 passed.
+- `/opt/homebrew/bin/uv run pytest tests/test_workflow_routes.py -q`: 27 passed.
+- `CI=true npm test -- --runInBand src/components/Chatbot.test.js`: 9 passed.
+- `npm run build`: passed with existing ESLint warnings.
+
+## 2026-04-29 - Visualization Scale Context and Agent Reload
+
+The scale-correction screenshot exposed another agent routing gap: "reload with
+1-1-1" was not a first-class workflow action, so the generic chat path could
+return tool-call-shaped JSON instead of a useful app action. The fix treats
+voxel scale updates as workflow state, not explanatory chat.
+
+Implemented a `set_visualization_scales` workflow-agent intent. It parses
+z,y,x values from natural language, stores them as `visualization_scales` and
+`project_context.voxel_size_nm`, appends a `visualization.scales_updated`
+workflow event, and offers one `Reload viewer` action that routes the UI to
+Visualization with `runtime_action: load_visualization`. The Visualization
+screen now reads persisted scale context and agent-triggered reloads use the
+current image/label fields when workflow paths are not enough.
+
+Also hardened chat rendering against embedded JSON tool-call leaks such as
+"Here is the revised function call..." followed by a JSON object.
+
+Test evidence:
+
+- `python -m py_compile server_api/main.py server_api/workflows/router.py server_api/workflows/volume_pairs.py`
+- `/opt/homebrew/bin/uv run pytest tests/test_workflow_routes.py -q`: 29 passed.
+- `CI=true npm test -- --runInBand src/components/Chatbot.test.js src/contexts/WorkflowContext.test.js`: 20 passed.
+- `npm run build`: passed with existing nonblocking lint warnings outside this scale-change path.
diff --git a/docs/codex-working-memory/third-finish-line-lit-and-task-taxonomy.md b/docs/codex-working-memory/third-finish-line-lit-and-task-taxonomy.md
new file mode 100644
index 00000000..dd5521b4
--- /dev/null
+++ b/docs/codex-working-memory/third-finish-line-lit-and-task-taxonomy.md
@@ -0,0 +1,114 @@
+# Third Finish-Line Heuristic: Literature-Informed Task Taxonomy
+
+Last updated: 2026-06-04
+
+This note captures the third finish-line pass for the Yixiao / TapeReader XRI
+case-study prototype. It combines a lightweight literature scan with a local
+app-readiness sweep, then maps the remaining work into parallel implementation
+tracks.
+
+## Recent Literature Signals To Incorporate
+
+The newest useful thread is not "make the chatbot smarter." It is: make the
+human and agent maintain explicit common ground while working through bounded
+workflow actions.
+
+Relevant recent signals:
+
+- **Human-AI common ground:** recent HCI/human-factors work emphasizes that
+  collaborative agents need shared goals, relevant context, breakdown detection,
+  and repair. Product implication: project facts should be visible,
+  confirmable, and correctable, not hidden inside chat state.
+- **Interaction / process / infrastructure framing:** recent human-agent
+  collaboration framing separates conversational interaction, durable process,
+  and infrastructure. Product implication: chat should be a surface over project
+  memory, action cards, and the evidence ledger, not the source of truth.
+- **Visual analytics agents:** recent VIS/VA work on multimodal agents and
+  visual-analytics workflows suggests agents need to interact with and reason
+  over coordinated views, not just answer from text. Product implication:
+  browser-level workflow tests and visible workflow-state surfaces are part of
+  the technical contribution, not polish.
+- **Formal workflow representation:** emerging workflow-language work for visual
+  analytics reinforces that reusable workflow state should be explicit.
+  Product implication: our export bundle and readiness gates should encode
+  enough structure to compare, replay, and audit runs.
+- **Agent safety indices / deployed agent audits:** current agent-system audits
+  repeatedly track approval requirements, auditability, and capability
+  disclosure. Product implication: every mutating/expensive action needs a
+  policy reason, stale-context status, and approval trail.
+
+### Source Anchors From This Pass
+
+These are not exhaustive paper citations. They are the specific recent sources
+that motivated this pass and should be folded into the manuscript/background
+review if they remain relevant after a deeper bibliography check.
+
+| Source                                                                                                                                                                                                                                                  | Why It Matters For seg.bio                                                                                                                                                                                                |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Chen et al., **ThinkFlow / From Conversation to Human-AI Common Ground** (CHI 2026, Adobe Research), https://research.adobe.com/publication/from-conversation-to-human-ai-common-ground-extracting-cognitive-workflows-for-reuse-in-sense-making-tasks/ | Argues that conversational AI needs dynamic common ground and reusable workflow schemas rather than only preferences or rigid workflows. This supports explicit project facts and reusable case-study workflow state.     |
+| Dhanoa et al., **Agentic Visualization** (arXiv/IEEE CG&A 2025), https://arxiv.org/abs/2505.19101                                                                                                                                                       | Extracts agent role, communication, coordination, progress-indicator, and provenance-log patterns for visualization systems. This supports specialist workflow agents, operation traces, and evidence logs.               |
+| Chen et al., **InterChat** (arXiv 2025), https://arxiv.org/abs/2503.04110                                                                                                                                                                               | Shows that natural language alone is imprecise for visual analytics and should be paired with direct manipulation/contextual interaction linking. This supports editable proposal fields and visible app-state grounding. |
+| Sharma et al., **Feedback by Design** (arXiv 2026), https://arxiv.org/abs/2602.01405                                                                                                                                                                    | Identifies Common Ground, Verifiability, Communication, and Informativeness as feedback barriers. This supports fact cards, source-backed traces, and clear correction affordances.                                       |
+| Gomez et al., **Human-AI collaboration is not very collaborative yet** (Frontiers in Computer Science, 2025), https://www.frontiersin.org/articles/10.3389/fcomp.2024.1521066/full                                                                      | Provides a vocabulary for different human-AI interaction patterns and reinforces that timing/sequence of AI suggestions matters. This supports action-card lifecycle and approval timing as design claims.                |
+
+## Local Readiness Sweep: Remaining Gaps
+
+The current prototype is much stronger than the earlier branch, but the gaps
+that still matter for a strong first case study are:
+
+1. **Common-ground UI is still implicit.**
+   The agent can inspect project context, but the user does not yet have a
+   compact "these are the facts we are both using" panel that is easy to
+   confirm, edit, and reference during the study.
+
+2. **Agent operations are not fully visible as a workflow trace.**
+   We have proposal cards and some traces, but the user should be able to see a
+   concise sequence: inspected facts -> proposed action -> approval decision ->
+   execution -> project-memory update.
+
+3. **Action policy and freshness are still partly convention-based.**
+   The backend has strong proposal behavior, but it should expose machine-
+   checkable reasons when an action is blocked, stale, or approval-required.
+
+4. **Evidence export is useful but not yet a strict contract.**
+   Current exports include richer provenance, but response models are still too
+   generic and proposal-to-approval linkage is inferred from payloads.
+
+5. **Browser-level workflow certification is not yet part of the standard gate.**
+   The Playwright harness exists, but dependency/install flow and CI/operator
+   instructions need to be robust enough that a case-study facilitator can run
+   it.
+
+6. **Real closed-loop claim remains gated.**
+   The rehearsal path is strong, but the paper must not imply training,
+   inference, and evaluation performance until a real app-launched run is
+   recorded and exported.
+
+7. **Deployment observability needs one more hardening pass.**
+   The new demo manager works. The remaining gap is making runtime configuration
+   and health warnings clear enough that a non-original developer can triage the
+   demo quickly.
+
+## Task Taxonomy For Parallel Work
+
+| Track                                  | Goal                                                                                 | Primary Write Scope                                                                                                                          | Done When                                                                                                                                                   |
+| -------------------------------------- | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| A. Common-ground project facts         | Turn project context into a visible, editable, confirmable shared-state object.      | `client/src/views/FilesManager.js`, `client/src/contexts/WorkflowContext.js`, project-memory backend/tests if needed, docs.                  | Yixiao fact cards show modality, target, voxel size, volume split, training policy; edits persist and are visible to the agent/readiness gate.              |
+| B. Agent operation trace               | Make the chat/timeline show concise operational traces without raw hidden reasoning. | `client/src/components/Chatbot.js`, `client/src/components/chat/*`, `client/src/components/WorkflowTimeline.js`, CSS/tests.                  | A user can expand a proposal/result to see inspected facts, policy decision, action status, and affected artifacts.                                         |
+| C. Backend action policy and freshness | Expose stricter action readiness, stale-context blockers, and approval reasons.      | `server_api/workflows/router.py`, `service.py`, workflow tests, route docs.                                                                  | Action responses include `freshness`, `policy_decision`, `blocking_reasons`, and tests cover stale/missing context.                                         |
+| D. Evidence contract and export schema | Make paper-grade evidence bundles more contract-like.                                | `server_api/workflows/bundle_export.py`, `evidence_export.py`, response models/tests/docs.                                                   | Export response has typed fields for proposal/approval/action/run/progress links; withheld-copy policy remains enforced.                                    |
+| E. Browser certification and demo QA   | Make the browser smoke runnable and part of the operator gate.                       | `scripts/browser_yixiao_case_study_smoke.py`, `tests/test_browser_yixiao_case_study_smoke.py`, package/dev dependency docs, manual demo doc. | One documented command either runs Playwright or gives a deterministic skip with install instructions; smoke checks cover progress, chat, proposal editing. |
+| F. Runtime/deploy observability        | Clarify demo health, runtime config, and log checks.                                 | `scripts/manage_demo_instance.py`, `scripts/inspect_demo_instance.py`, docs/tests.                                                           | Inspector reports configured ports/public bases clearly and avoids false failures during expected load; restart/status docs are complete.                   |
+
+## Claim Boundary After This Pass
+
+If these tracks pass, the Yixiao case study can claim:
+
+- visible shared project understanding,
+- approval-gated mixed-initiative workflow coordination,
+- durable project-state updates,
+- exportable provenance for the coordination loop,
+- repeatable demo health/browser readiness checks.
+
+It still cannot claim model improvement until a real training -> inference ->
+evaluation run is completed and entered into the evidence ledger.
diff --git a/docs/codex-working-memory/tochi-writing-synthesis.md b/docs/codex-working-memory/tochi-writing-synthesis.md
new file mode 100644
index 00000000..40855175
--- /dev/null
+++ b/docs/codex-working-memory/tochi-writing-synthesis.md
@@ -0,0 +1,61 @@
+# TOCHI Writing Synthesis (2026-04-13)
+
+Corpus reviewed from local PDFs:
+
+- `3769675.pdf`
+- `3771924.pdf`
+- `3770583.pdf`
+- `3762808.pdf`
+- `3778354.pdf`
+- `3771935.pdf`
+- `3769680.pdf`
+- `3772068.pdf`
+- `3777906.pdf`
+
+## Recurrent Writing Patterns
+
+1. Open with scoped problem framing plus concrete context; avoid broad generic motivation.
+2. State explicit research/design questions early (often in intro or method framing).
+3. Present contributions as a short, concrete list with specific artifacts or outcomes.
+4. Use a clear traceability chain from observations to design goals/requirements/tasks.
+5. Keep related work sectioned by conceptual overlap and end with a precise gap statement.
+6. In discussion, separate:
+   - what findings imply for design/interaction,
+   - methodological/validity limits,
+   - future work.
+7. Calibrate claims carefully; avoid implying completed evaluation when reporting design/prototype work.
+8. Tie evaluation sections to explicit questions and measurable evidence sources.
+
+## Actions Applied To Manuscript
+
+File: `/Users/adamg/seg.bio/_toCHI__Human_Agent_collaboration_for_biomed_image_segmentation/sample-manuscript.tex`
+
+- Added formative questions (`FQ1`, `FQ2`) in Section 3.
+- Added a new Goal→Requirement→Task traceability table (`tab:grt-traceability`).
+- Reframed Section 4 architecture with explicit layered model (`L1` state, `L2` mediation, `L3` controlled execution).
+- Renamed feature subsection to emphasize design realization.
+- Replaced placeholder Evaluation bullets with a structured protocol:
+  - evaluation questions (`EQ1`--`EQ3`),
+  - planned study phases,
+  - metrics and evidence,
+  - analysis plan.
+- Recompiled PDF after text edits.
+
+## Internal Implementation Reality (Not For Manuscript Text)
+
+Implemented in project codebase (current evidence in tests/logs):
+
+- Workflow state/event backbone and APIs.
+- Proofreading/inference/workflow event integration.
+- Approval-gated proposal flow.
+- Chat timeline/state grounding.
+- LLM configuration hardening + backend observability improvements.
+
+Design ideation / planned extensions:
+
+- Failure hotspot prioritization.
+- Correction impact preview.
+- Project-level autonomous run manager.
+- Versioned experiment bundles.
+- External CAVE-compatible integration flow.
+- Autonomous plan simulation UI.
diff --git a/docs/codex-working-memory/workflow-spine-spec.md b/docs/codex-working-memory/workflow-spine-spec.md
new file mode 100644
index 00000000..246516ae
--- /dev/null
+++ b/docs/codex-working-memory/workflow-spine-spec.md
@@ -0,0 +1,126 @@
+# Workflow Spine Spec
+
+Local architecture handoff for the Workflow Spine milestone.
+
+## Scope
+
+The implemented spine supports:
+
+`load data -> visualize/infer -> proofread -> export corrected masks -> stage retraining -> record evidence`
+
+Retraining is staged, not required to complete. Evaluation is represented as a stage value but is not implemented as a real comparison workflow yet.
+
+## Backend
+
+### Tables
+
+`workflow_sessions`
+
+- `id`
+- `user_id`
+- `title`
+- `stage`
+- `dataset_path`
+- `image_path`
+- `label_path`
+- `mask_path`
+- `neuroglancer_url`
+- `inference_output_path`
+- `checkpoint_path`
+- `proofreading_session_id`
+- `corrected_mask_path`
+- `training_output_path`
+- `metadata_json`
+- `created_at`
+- `updated_at`
+
+`workflow_events`
+
+- `id`
+- `workflow_id`
+- `actor`
+- `event_type`
+- `stage`
+- `summary`
+- `payload_json`
+- `approval_status`
+- `created_at`
+
+### API
+
+- `GET /api/workflows/current`
+- `PATCH /api/workflows/{id}`
+- `GET /api/workflows/{id}/events`
+- `POST /api/workflows/{id}/events`
+- `POST /api/workflows/{id}/agent-actions`
+- `POST /api/workflows/{id}/agent-actions/{event_id}/approve`
+- `POST /api/workflows/{id}/agent-actions/{event_id}/reject`
+- `POST /api/workflows/{id}/agent/query`
+
+### Initial Allowlisted Agent Action
+
+`stage_retraining_from_corrections`
+
+Approval requirements:
+
+- A `corrected_mask_path`, `written_path`, existing workflow `corrected_mask_path`, or latest `proofreading.masks_exported` event artifact must exist.
+- Approval updates workflow stage to `retraining_staged`.
+- Approval logs `agent.proposal_approved` and `retraining.staged`.
+- Approval returns client effects:
+  - `navigate_to: "training"`
+  - `set_training_label_path: corrected_mask_path`
+
+## Frontend
+
+### Context
+
+`WorkflowProvider` loads `GET /api/workflows/current` on startup and exposes:
+
+- `workflow`
+- `events`
+- `refreshWorkflow`
+- `refreshEvents`
+- `updateWorkflow`
+- `appendEvent`
+- `proposeAgentAction`
+- `approveAgentAction`
+- `rejectAgentAction`
+- `queryAgent`
+- `lastClientEffects`
+- `consumeClientEffects`
+
+### Timeline
+
+`WorkflowTimeline` displays the current workflow stage and latest events. Pending `agent.proposal_created` events expose Approve and Reject controls.
+
+### Module Wiring
+
+- Visualization passes `workflow_id` to `/neuroglancer`.
+- Inference passes `workflow_id` to `/start_model_inference` and logs terminal completion/failure from polling.
+- Training passes `workflow_id` to `/start_model_training`.
+- Mask Proofreading renders EHTool and passes active `workflow_id`.
+- EHTool dataset load sends `workflow_id` to `/eh/detection/load`.
+- EHTool export records latest corrected mask path and exposes "Stage for retraining."
+
+## Tests
+
+Backend coverage:
+
+- Workflow creation/current behavior.
+- Workflow patch, event append, and event list.
+- Agent proposal approve/reject flow.
+- EHTool load/classify/save/export workflow event linkage.
+
+Frontend coverage:
+
+- Mask Proofreading renders EHTool with workflow id.
+- Workflow timeline renders events and approve/reject buttons.
+- Workflow provider loads current workflow and applies approval client effects.
+
+## Known Limits
+
+- No Alembic migration yet; SQLite compatibility uses `create_all` plus a narrow column patch for `ehtool_sessions.workflow_id`.
+- No model-version artifact table yet.
+- No evaluation/comparison artifact yet.
+- The workflow-aware agent is deterministic fallback logic, not a full LLM planner.
+- Inference completion/failure logging depends on frontend polling observing terminal status.
diff --git a/docs/codex-working-memory/yixiao-finish-line-task-taxonomy.md b/docs/codex-working-memory/yixiao-finish-line-task-taxonomy.md
new file mode 100644
index 00000000..f16aebbd
--- /dev/null
+++ b/docs/codex-working-memory/yixiao-finish-line-task-taxonomy.md
@@ -0,0 +1,147 @@
+# Yixiao Finish-Line Technical Taxonomy
+
+Last updated: 2026-06-04
+
+This document defines the acceptance gates for the Yixiao / TapeReader XRI case
+study and maps each gate to what the prototype can claim during a one-hour
+walkthrough versus what requires a full closed-loop run.
+
+## Current Claim Tiering
+
+### Claim Tier A (today, safe for talk demos)
+
+The prototype can claim workflow coordination on this fixture:
+
+- mounted-project inspection and grounded context,
+- grounded volume-state accounting (ground-truth / draft / image-only),
+- bounded agent proposal behavior with explicit approval gating.
+
+Current evidence comes from:
+
+- 10-volume fixture mount (`6` ground-truth, `2` draft, `2` image-only),
+- stable context (`tapereader_xri_fiber`, `data/raw`, `data/seg`,
+  `TapeReader-Fiber-BCS-AppCompat-Sanity.yaml`),
+- proposal flow from user asks like "train on fully good masks,"
+- smoke-based restoration and promotion checks.
+
+### Claim Tier B (not yet supported as a paper result)
+
+The system should not claim model-quality or closed-loop performance until
+all of the following are evidenced by app-executed artifacts:
+
+1. training run completion record,
+2. checkpoint/model version registration,
+3. post-training inference on image-only targets,
+4. evaluation against held-out truth,
+5. exported evidence linking these steps end-to-end.
+
+## One-Hour Go/No-Go Acceptance Matrix (Yixiao)
+
+For a live one-hour session, the protocol is `GO` only if every row is green.
+`NO-GO` means the facilitator must pause and reset claim language.
+
+| Gate                                         | Explicit Pass Condition                                                                                                                             | Evidence Check                                                     |
+| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
+| Baseline project state                       | Baseline is exactly 10 volumes, `6/2/2` split, correct roots/config, project identified as Yixiao/XRI/CytoTape.                                     | `--prepare-live`; project profile and progress assertions          |
+| Agent context                                | Assistant summary uses mounted workflow context, not stale dataset names or defaults.                                                               | `--prepare-live`; project context assertions; agent recommendation |
+| Approval-gated training proposal             | Training request creates a reviewable proposal, not auto-launch.                                                                                    | `--prepare-live`; recommendation/`agent-proposal` logs             |
+| Proofread promotion                          | Draft volume can be promoted and reflected in progress state.                                                                                       | `--exercise-promotion`; volume-status transition assertions        |
+| Closed-loop rehearsal                        | Rehearsal path can pair `6_1` / `6_2` predictions with withheld targets without in-project leakage.                                                 | `--closed-loop-rehearsal`                                          |
+| Real training/inference/evaluation artifacts | Terminal training/inference completion + checkpoint/version + evaluation entries exist.                                                             | model runs, model versions, evaluation results, bundle export      |
+| Export bundle                                | Evidence bundle returns with schema, artifact manifests, and copy-policy summary (including size-safe defaults).                                    | `/api/workflows/{id}/export-bundle`                                |
+| Live demo health                             | API/worker/Neuroglancer/worker routing/app log health checks are clean enough for launch, with temporary-load transients treated as WARN, not FAIL. | `inspect_demo_instance.py --json`                                  |
+
+### Acceptance interpretation
+
+- `GO` requires the first six rows and rows 7 and 8 to pass for the live path.
+- For row 8, treat `WARN` as expected operational noise (e.g., transient load or missing optional logs) and `FAIL` as a hard blocker.
+- If `Real training/inference/evaluation artifacts` is `NO-GO`, the walkthrough stays at
+  coordination-level claims and must explicitly state this limitation.
+- If any health check is hard-fail (`api.health` down, `worker.url_mismatch`, critical
+  app errors), treat as `NO-GO`.
+
+## Case-Study Evidence Mapping
+
+| Claim                                                | Can claim today                  | Requires closed-loop evidence                              |
+| ---------------------------------------------------- | -------------------------------- | ---------------------------------------------------------- |
+| "workflow coordination"                              | yes                              | no                                                         |
+| "approval-gated training proposal"                   | yes                              | no                                                         |
+| "proofread promotion affects training readiness"     | partial (status transition only) | full browser proofread edit/save/replay loop               |
+| "model converges/improves on TapeReader targets"     | no                               | training + inference + evaluation artifacts                |
+| "closed-loop quality is measured on withheld labels" | no                               | rehearsal + real infer/eval records tied to model versions |
+
+## Ready/Not-Ready Task Taxonomy
+
+### Must be ready for the one-hour session
+
+- smoke harness passes baseline and restore,
+- promotion drill validates fixture state transitions,
+- readiness and export checks are non-empty and pass smoke-level requirements,
+- live health checks are non-blocking,
+- runtime deployment observability is captured as expected values (worker URL, Neuroglancer port, public base) in one command:
+
+```bash
+.venv/bin/python scripts/inspect_demo_instance.py --api-base https://demo.seg.bio --json
+```
+
+- facilitator follows the claim boundary in the script.
+
+### Must be explicit caveats (not blockers)
+
+- no TapeReader barcode checkpoint in this fixture,
+- no browser-level proofread edit quality claim from the current app loop,
+- no full performance claim without real train/infer/eval evidence.
+
+## 2026-06-04 Follow-Up Workstreams
+
+This is the current subagent split for the second finish-line pass.
+
+| Workstream               | Owner    | Scope                                                                                                     | Success Condition                                                                                                                                             |
+| ------------------------ | -------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Closed-loop execution    | Worker A | Operator-safe train/infer/evaluate runbook/helper, explicit holdout truth, short-run override scaffolding | A facilitator can see the exact commands or app steps required for a real short run, and the helper refuses accidental use of mounted labels for `6_1`/`6_2`. |
+| Browser QA               | Worker B | Browser-level smoke or documented automation gap                                                          | We can validate the user-visible path, including refresh/reopen and proposal readability, with a repeatable command or documented manual fallback.            |
+| Agent proposal UX        | Worker C | Editable proposal-card fields, terminal state clarity, specialist agent visual labels                     | Users can adjust agent-filled values before approval and agent role labels/icons do not clip.                                                                 |
+| Memory/provenance        | Worker D | Export completeness, artifact links, external holdout evidence                                            | Evidence bundles contain the records needed to support workflow claims without relying on hidden chat state.                                                  |
+| Deployment survivability | Worker E | Demo2 API restart/start/stop helper and health validation                                                 | The live demo can be restarted without brittle shell behavior or accidentally affecting other deployments.                                                    |
+| Study readiness          | Worker F | Go/no-go checklist and paper claim acceptance criteria                                                    | The team has a crisp matrix for what is demo-ready, what is caveated, and what remains before a stronger paper result.                                        |
+
+## Current Hard Gaps
+
+These are the gaps still expected to remain after the second pass unless a worker
+specifically closes them:
+
+- **Real training runtime:** no completed Yixiao app-launched training run has
+  been captured in the current evidence ledger.
+- **Real inference runtime:** no checkpoint-backed inference outputs for `6_1`
+  and `6_2` are registered as completed workflow runs.
+- **Real evaluation record:** rehearsal validates the wiring, but real
+  prediction-vs-holdout metrics still need a model/version-backed evaluation.
+- **Browser proofread edit quality:** status promotion works, but the case study
+  does not yet prove manual edits in the proofreading editor are biologically
+  meaningful.
+- **Commit hygiene:** the working tree is large and dirty; before paper/demo
+  freeze, changes should be split into coherent commits.
+
+## P0/P1 Alignment
+
+P0 items are now acceptance gates in the matrix above and are required for
+release gating of the Yixiao walk-through.
+
+- **P0**
+  - baseline restore and smoke health,
+  - context fidelity and bounded assistant behavior,
+  - proposal approvals,
+  - promotion and continuity checks,
+  - export copy policy enforcement,
+  - operator visibility.
+
+- **P1**
+  - real train/infer/eval closure,
+  - browser proofread edit/save loop with durable corrected artifacts,
+  - scheduler-level production hardening and multi-user safety.
+
+## Go / No-Go Summary
+
+Go for the session if all one-hour gates pass and the presenter uses only
+Tier A claims.
+No-go if any hard gate fails or if Tier B claims are described as achieved results.
diff --git a/docs/manual-bulk-test-checklist.md b/docs/manual-bulk-test-checklist.md
new file mode 100644
index 00000000..39fd3fbe
--- /dev/null
+++ b/docs/manual-bulk-test-checklist.md
@@ -0,0 +1,105 @@
+# Manual Bulk Test Checklist
+
+Use this after large prototype checkpoints when you want to verify the current
+TOCHI-facing workflow without running full PyTC training.
+
+## Startup
+
+- From `/Users/adamg/seg.bio/pytc-client`, run `scripts/start.sh`.
+- Confirm Electron opens and all three backend services report ready.
+- Ignore `.zshrc` `pyenv` warnings for this app unless they block Python.
+
+## File Management
+
+- Open File Management.
+- Confirm the suggested smoke project card appears.
+- Confirm it reports image, label, prediction, config, and checkpoint roles.
+- Click `Mount Test Project` or `Open Test Project`.
+- Confirm `mito25-paper-loop-smoke` opens without manual path browsing.
+- Confirm `data/image`, `data/seg`, `configs`, `checkpoints`, and `predictions`
+  are present.
+- Ask the assistant `what should I do next?` after mounting.
+- Confirm the workflow no longer behaves like no data is mounted: it should
+  recommend inference/visualization instead of asking you to mount data.
+- Right-click the mounted root and confirm `Unmount Project` is available.
+
+## File Selection
+
+- In Train Model or Run Model, click the folder icon inside a path field and confirm the
+  file picker opens.
+- Click a folder row/name to navigate into it.
+- Use `Use folder` or `Select Current Directory` when the folder itself is the
+  intended input/output.
+- Confirm manual path typing still works, but does not feel like the primary
+  file-selection path.
+
+## Evidence Panel
+
+- Open the assistant drawer and click `Status`.
+- Confirm the assistant drawer opens with workflow context visible.
+- Open TensorBoard from Train Model runtime details.
+- Confirm `Review status` is visible.
+- Confirm the `Loop progress` map is visible.
+- Confirm the panel shows the next incomplete gate if the loop is not complete.
+- Confirm previous result, new result, your saved edits, and reference-mask rows
+  use short user-facing labels.
+- Confirm `Compare results` is disabled with a useful missing-input message when
+  previous result, new result, or reference mask paths are absent.
+- Click `Metric options` only when dataset keys/channels need manual override.
+
+## Metric Computation
+
+- For HDF5/PyTC outputs, enter dataset key `vol0` for baseline/candidate.
+- Use channel `0` for PyTC `result_xy.h5` probability maps when applicable.
+- Use ground-truth dataset `data` for the curated mito25 segmentation file.
+- Click `Compare results` only after previous-result, new-result, and reference paths are
+  recorded in workflow evidence.
+- Confirm metric deltas render for Dice, IoU, and voxel accuracy.
+- Confirm the latest comparison report path appears.
+
+## Bundle Export
+
+- Click `Export report`.
+- Confirm the UI reports file/run/comparison counts and missing path count.
+- Refresh evidence or open the workflow timeline/context panel.
+- Confirm a `workflow.bundle_exported` event exists.
+
+## Proofreading Provenance
+
+- Open Mask Proofreading on a small loaded volume.
+- Confirm the editor exposes a visible `Save mask` control, not only a keyboard
+  shortcut.
+- Paint or erase a small region and confirm an `unsaved edits` indicator appears.
+- Save at least two mask edits in distinct instances/regions.
+- Export masks.
+- Confirm the workflow evidence panel shows a corrected-mask path.
+- Confirm the correction set reports nonzero edits and regions once evidence is
+  refreshed.
+
+## Agent Controls
+
+- Ask the assistant: `what should I do next?`
+- Confirm the reply uses a compact `Do this` / `Why` / `Ready` style rather than
+  a long explanation.
+- Ask the assistant gibberish such as `mmajkf,ansdjs`.
+- Confirm it does not produce workflow action cards for that gibberish.
+- From inference stage with no prediction output, ask for the next step and
+  confirm the assistant action card is `Run model`.
+- From a mounted project with an image/mask pair, click `Proofread this data`
+  and confirm the app opens Proofread and starts loading that pair without
+  manual path entry.
+- From proofreading after a mask export, ask for the next step and confirm the
+  assistant action card is `Use edits for training`.
+- Click `Use edits for training` and confirm a pending agent proposal appears
+  in workflow context/timeline instead of silently staging retraining.
+- Approve the proposal and confirm the workflow moves to `retraining_staged` and
+  the corrected-mask path is loaded into training labels.
+
+## Known Boundaries
+
+- This checklist does not prove full training quality.
+- This checklist does not prove long-running cancellation/retry/recovery.
+- This checklist does not prove browser-level proofreading at scale.
+- A paper-ready case-study loop still needs a fresh app-launched baseline
+  inference, correction export, retraining/fine-tuning, candidate inference, and
+  before/after evaluation over those fresh outputs.
diff --git a/docs/manual-yixiao-case-study-demo.md b/docs/manual-yixiao-case-study-demo.md
new file mode 100644
index 00000000..5793fd5e
--- /dev/null
+++ b/docs/manual-yixiao-case-study-demo.md
@@ -0,0 +1,600 @@
+# Yixiao TapeReader XRI Case Study Demo
+
+## Purpose
+
+This walkthrough locks the current demo around the Yixiao / TapeReader XRI fibre segmentation case study. It is meant for a facilitator or developer preparing `https://demo.seg.bio`, not as a participant-facing protocol.
+
+The case study should demonstrate a workflow-aware agent that understands mounted project state, summarizes volume progress, opens data, proposes bounded training actions, and keeps proofread/training/inference roles separate.
+
+## One-Hour Case-Study Acceptance Gates
+
+Use this for launch decision:
+
+- **Baseline fixture state**: baseline mount must show `10` volumes and `6/2/2` status split.
+- **Agent context**: assistant context must mention `Yixiao TapeReader XRI Case Study`, `40 × 16.3 × 16.3`, and the `6/2/2` split.
+- **Approval-gated training proposal**: “train on the fully good masks” must create a reviewable proposal.
+- **Proofread promotion**: `5_1` or `5_2` can be promoted through the progress API and that change is visible.
+- **Closed-loop rehearsal**: `6_1` and `6_2` can be paired with external holdout masks without leakage.
+- **Real training/inference/evaluation artifacts**: before final claim, confirm terminal training, checkpoint/version, inference, and evaluation entries exist in workflow records.
+- **Export bundle**: export returns `workflow-bundle.json` plus copy summary and required fields.
+- **Live health**: `inspect_demo_instance.py --json` key checks are healthy or expected warnings are documented.
+
+### Claim Boundary (important for facilitator)
+
+- `GO` claim for this setup today:
+  - workflow grounding and coordination, bounded approvals, projection of proofread and image-only roles.
+- `NO` claim today:
+  - TapeReader-level reproduction/accuracy claims without app-backed train/infer/eval evidence.
+  - browser-level edit-quality claims beyond what the current editor actually returns.
+
+## Known Project State
+
+Project root:
+
+```text
+/home/weidf/demo_data/yixiao_tapereader_xri_case_study
+```
+
+Reference pipeline and paper:
+
+- TapeReader: `https://github.com/LinghuLab/TapeReader`
+- Paper: `https://www.biorxiv.org/content/10.1101/2025.05.10.653182v1`
+
+Expected app state:
+
+| Item                    | Expected Value                                       |
+| ----------------------- | ---------------------------------------------------- |
+| Project title           | `Yixiao TapeReader XRI Case Study`                   |
+| Imaging modality        | X-ray / XRI volumetric microscopy                    |
+| Target                  | CytoTape fibres                                      |
+| Voxel size              | `40,16.3,16.3` nm in z,y,x                           |
+| Active image root       | `data/raw`                                           |
+| Active label root       | `data/seg`                                           |
+| Active config           | `configs/TapeReader-Fiber-BCS-AppCompat-Sanity.yaml` |
+| Total volumes           | `10`                                                 |
+| Fully good ground truth | `6`                                                  |
+| Needs proofreading      | `2`                                                  |
+| No segmentation yet     | `2`                                                  |
+
+Volume split:
+
+- Ground truth: `1`, `2`, `3`, `4_1`, `4_2`, `4_3`
+- Draft masks needing proofreading: `5_1`, `5_2`
+- Image-only inference targets: `6_1`, `6_2`
+
+The withheld masks for image-only targets live outside the mounted project at:
+
+```text
+/home/weidf/demo_data/yixiao_tapereader_xri_case_study_holdout_masks
+```
+
+Do not use withheld masks during demo training/inference setup.
+
+## Reset And Smoke Test
+
+Before a demo, run the live smoke harness:
+
+```bash
+cd /home/weidf/deploy/pytc-client-demo2
+.venv/bin/python scripts/run_yixiao_case_study_smoke.py \
+  --prepare-live \
+  --report /tmp/yixiao-case-study-smoke-report.json
+```
+
+What `--prepare-live` does:
+
+- resets the indexed app workspace;
+- mounts the Yixiao project;
+- creates a fresh workflow;
+- patches that workflow with Yixiao context;
+- verifies project profile, progress counts, memory, Neuroglancer, and agent proposals.
+
+What it does not do:
+
+- it does not regenerate fixture data;
+- it does not launch a GPU training job;
+- it does not run inference.
+
+Only regenerate the fixture data when you intentionally want to reset the case-study files:
+
+```bash
+cd /home/weidf/deploy/pytc-client-demo2
+.venv/bin/python scripts/run_yixiao_case_study_smoke.py \
+  --reset-fixture \
+  --prepare-live \
+  --report /tmp/yixiao-case-study-smoke-report.json
+```
+
+The fixture reset can take longer because it rebuilds CLAHE PyTC training inputs.
+
+## Operator Diagnostics (Recommended Pre-Case-Study)
+
+Before final checks, run the operator diagnostics script for a fast live sanity readout:
+
+```bash
+cd /home/weidf/deploy/pytc-client-demo2
+.venv/bin/python scripts/inspect_demo_instance.py \
+  --api-base https://demo.seg.bio \
+  --json
+```
+
+For a single-command go/no-go gate before launch (exit non-zero on hard-fail only):
+
+```bash
+cd /home/weidf/deploy/pytc-client-demo2
+.venv/bin/python scripts/inspect_demo_instance.py \
+  --api-base https://demo.seg.bio \
+  --worker-url localhost:4243 \
+  --neuroglancer-port 4244 \
+  --json \
+  | python3 - <<'PY'
+import json
+import sys
+
+report = json.load(sys.stdin)
+hard_fail = [row["name"] for row in report if row["status"] == "fail"]
+if hard_fail:
+    print("DEMO HEALTH HARD-FAIL:", hard_fail, file=sys.stderr)
+    raise SystemExit(1)
+print("DEMO HEALTH: GO")
+PY
+```
+
+Useful defaults are also inferred from env:
+
+- `PYTC_API_BASE`
+- `PYTC_WORKER_PROTOCOL`
+- `PYTC_WORKER_URL`
+- `PYTC_NEUROGLANCER_PORT`
+- `PYTC_NEUROGLANCER_PUBLIC_BASE`
+- `PYTC_WORKFLOW_BUNDLE_DIR`
+
+Key failures to scan for:
+
+- `api.health` fails (`FAIL`) means the API endpoint is not healthy.
+- `api.runtime_config` (`PASS`/`WARN`) shows matched/mismatched operator expectations for worker URL, configured Neuroglancer port, and Neuroglancer public base.
+- `worker.hello` `WARN` means the configured worker address is not reachable directly.
+- `worker.url_mismatch` `FAIL` means API requests are reaching a different worker URL than the configured `PYTC_WORKER_URL` (this was a known case-study outage class).
+- `api.proxy_log` `WARN` means no matching proxy events were found in the recent app-log tail.
+- `neuroglancer.port` `WARN` means the configured Neuroglancer bind port is not reachable from the operator node.
+- `neuroglancer.public_base` `WARN` means `PYTC_NEUROGLANCER_PUBLIC_BASE` is absent or not an absolute URL.
+- `neuroglancer.url_match` `WARN` means workflow’s stored Neuroglancer URL does not match the configured base.
+- `app_error_events` `WARN` indicates recent ERROR rows in the app log; check the same log via `.logs/app/app-events.jsonl`.
+- `workflow_bundles_disk` `WARN` indicates the workflow bundle directory is unavailable or unreadable.
+
+This script is read-only and does not alter API/workflow state.
+
+## Browser-Level UX Smoke (Optional)
+
+After the API-side checks pass, you can run the browser-level smoke directly against the frontend:
+
+```bash
+cd /home/weidf/deploy/pytc-client-demo2
+.venv/bin/python3 scripts/browser_yixiao_case_study_smoke.py \
+  --base-url http://127.0.0.1:3000 \
+  --report /tmp/yixiao-browser-smoke-report.json
+```
+
+For the production host:
+
+```bash
+.venv/bin/python3 scripts/browser_yixiao_case_study_smoke.py \
+  --base-url https://demo.seg.bio \
+  --report /tmp/yixiao-browser-smoke-report.json
+```
+
+Recommended flags for pre-demo smoke:
+
+- add `--no-headless` when visually monitoring checks.
+- add `--skip-assistant` if the assistant backend is intentionally unavailable.
+- add `--skip-reload` to avoid a continuity round-trip check.
+
+If Playwright is not installed, the script exits with a clear remediation message and does not attempt a partial run. Install exactly with:
+
+```bash
+cd /home/weidf/deploy/pytc-client-demo2
+.venv/bin/python3 -m pip install playwright
+.venv/bin/python3 -m playwright install chromium
+```
+
+The script prints the full remediation block with the interpreter it is running
+under, so this install command is deterministic even when multiple Python
+environments are present.
+
+The smoke verifies:
+
+- app boots at the target URL,
+- Files shows the Yixiao project and required top-level entries,
+- Workflow progress snapshot is `10/6/2/2` with `60%` completion and `80%` segmentation coverage,
+- assistant panel can open and answer a project-context query (unless skipped),
+- training proposal card generation plus editable proposal fields,
+- training proposal card is not obviously clipped at the default viewport,
+- reload/reopen continuity for the same active UI state.
+
+## Demo2 API Runtime Control
+
+Use this helper instead of manual `nohup`/`setsid` invocations:
+
+```bash
+cd /home/weidf/deploy/pytc-client-demo2
+.venv/bin/python scripts/manage_demo_instance.py restart \
+  --api-port 4342 \
+  --force \
+  --health-timeout 90 \
+  --log-file .logs/start/demo2-api-server.log
+```
+
+What this command does:
+
+- finds and stops only demo2 API processes running from this checkout (`server_api.main`) on port `4342`,
+- starts the API with `nohup` + `setsid` so it persists after shell exit,
+- writes startup output to `.logs/start/demo2-api-server.log`,
+- verifies persistence via `/health`,
+- prints the last log lines plus shutdown hints on failure.
+
+Behavior safeguards:
+
+- it matches `server_api.main` processes by repo path and `PYTC_API_PORT`,
+- it does not stop sibling demo services (`demo3` / `user-seg-bio`) because they use different checkout roots and/or ports,
+- restart and stop are idempotent when no matching process exists.
+
+To exercise the closed-loop promotion path without launching GPU training:
+
+```bash
+cd /home/weidf/deploy/pytc-client-demo2
+.venv/bin/python scripts/run_yixiao_case_study_smoke.py \
+  --prepare-live \
+  --exercise-promotion \
+  --report /tmp/yixiao-case-study-smoke-promotion-report.json
+```
+
+This promotes one draft mask from `Needs proofreading` to `Fully good`, verifies project memory records the canonical `proofread_ground_truth` status, and verifies the next training proposal updates from `6` to `7` training volumes. Rerun the normal `--prepare-live` smoke afterward to restore the public demo to the initial 6/2/2 state.
+
+## Manual Demo Flow
+
+### 1. Open The Demo
+
+Open:
+
+```text
+https://demo.seg.bio
+```
+
+Expected:
+
+- the app loads without health/toast errors;
+- the `Files` tab shows `Yixiao TapeReader XRI Case Study` mounted;
+- the folder tree includes `data`, `configs`, `notes`, `outputs`, `snapshots`, and `project_manifest.json`.
+
+### 2. Check Files / Project Inspection
+
+Stay on `Files`.
+
+Expected:
+
+- opening the project triggers a compact project-context confirmation card showing:
+  - modality, target, voxel size, task family, training policy, and volume split;
+  - the card should show `6/2/2` as `(6 ground-truth, 2 draft masks, 2 image-only)` text (or equivalent);
+- if any fact is wrong, use the controls in the same modal to correct it before starting.
+- the suggested project button opens the Yixiao project if it is not already mounted;
+- file roles should be driven by `project_manifest.json`;
+- raw image root should be `data/raw`, not `data/pytc_train`;
+- label root should be `data/seg`;
+- active config should be `TapeReader-Fiber-BCS-AppCompat-Sanity.yaml`.
+
+If the file tree is stale or wrong, rerun:
+
+```bash
+cd /home/weidf/deploy/pytc-client-demo2
+.venv/bin/python scripts/run_yixiao_case_study_smoke.py --prepare-live
+```
+
+### 3. Open Progress
+
+Go to `Progress`.
+
+Expected summary:
+
+- `10` tracked volumes;
+- `6` fully good;
+- `2` needs proofreading;
+- `2` no segmentation;
+- completion is `60%`;
+- segmentation coverage is `80%`.
+
+Expected interpretation:
+
+- fully good volumes are training-ready;
+- needs-proofreading volumes should be reviewed before promotion;
+- no-segmentation volumes are inference targets after a model/checkpoint exists.
+
+### 4. Ask The Agent What This Project Is
+
+Open the assistant and ask:
+
+```text
+what project are we looking at?
+```
+
+Expected response should mention:
+
+- `Yixiao TapeReader XRI Case Study`;
+- XRI / X-ray volumetric microscopy;
+- CytoTape fibres;
+- `40 x 16.3 x 16.3 nm`;
+- `10` tracked volumes;
+- `6` fully good, `2` needing proofreading, `2` without segmentation.
+
+The agent should not describe this as mitochondria or Lucchi/MitoEM.
+
+### 5. Visualize The First Pair
+
+Ask the agent:
+
+```text
+can we look at some data?
+```
+
+Or go to `Visualize` directly.
+
+Expected:
+
+- image path: `data/raw/1/1-xri_raw.tif`;
+- label path: `data/seg/1/1-mask.tif`;
+- scales: `40,16.3,16.3`;
+- Neuroglancer opens through an HTTPS `/neuroglancer/v/...` URL;
+- the viewer should show XRI fibre-like structures and mask overlay.
+
+Known visual caveat:
+
+- These XRI volumes can look banded/wavy compared with EM. That is expected for this fixture and should not be presented as mitochondria-like EM.
+
+### 6. Propose Training From Ground Truth
+
+Ask:
+
+```text
+train on the fully good masks to segment the image-only volumes
+```
+
+Expected:
+
+- the agent should stage a `Train model` action;
+- the card should say it found `6` fully good ground-truth volumes;
+- it should leave `2` draft masks out of training;
+- it should identify `2` image-only volumes as later inference targets;
+- the action should be review/approval gated, not silently launched.
+
+Expected staged training details:
+
+- training image path is a generated subset directory under:
+
+```text
+/home/weidf/demo_data/.pytc_training_subsets/yixiao_tapereader_xri_case_study/
+```
+
+- training label path is the sibling `seg` subset directory;
+- output/log path is under:
+
+```text
+/home/weidf/demo_data/yixiao_tapereader_xri_case_study/outputs/training/
+```
+
+- subset manifest exists and lists:
+  - `6` train pairs;
+  - `2` review pairs;
+  - `2` target images.
+
+### 7. Review Training Form
+
+Click the training card's review/run affordance.
+
+Expected:
+
+- app navigates to `Train Model`;
+- Input Image is populated with the generated subset `image` directory;
+- Input Label is populated with the generated subset `seg` directory;
+- Output Path is populated;
+- Log Path is populated;
+- config preset points to `TapeReader-Fiber-BCS-AppCompat-Sanity.yaml`.
+
+Do not start a long training job during a timed walkthrough unless the facilitator intends to show runtime behavior.
+
+The smoke harness verifies that the worker-side PyTC path resolver can turn the subset directories into six concrete image/label files and validate a staged config. That is not the same as a full GPU training success.
+
+### 8. Proofreading Story
+
+Go to `Proofread`.
+
+Use this narrative:
+
+- `5_1` and `5_2` are draft masks that should be proofread before becoming training ground truth;
+- after edits are saved and a volume is promoted, Progress should move it from `Needs proofreading` to `Fully good`;
+- once promoted, the agent should include it in future training proposals.
+
+Current caveat:
+
+- If the browser proofreading editor does not yet provide a fully realistic edit/save/promote loop for this fixture, present this as the next closed-loop hardening task rather than claiming it is complete.
+
+### 9. Inference Story
+
+Use this narrative:
+
+- `6_1` and `6_2` are image-only targets;
+- the agent should not infer until a checkpoint exists;
+- after training creates or registers a checkpoint, Run Model should target `6_1` and `6_2`;
+- prediction artifacts should be written back into project memory and change Progress coverage.
+
+Current caveat:
+
+- There is no paper-faithful TapeReader checkpoint wired into the fixture yet. The app-compatible config is for workflow validation and sanity runs; the original barcode target is preserved separately because it requires TapeReader-specific branch semantics.
+
+## Developer Smoke Contract
+
+The automated harness currently checks:
+
+- backend health;
+- manifest has 10 volumes and the 6/2/2 split;
+- project can be mounted;
+- project suggestion/profile uses manifest roots;
+- audit sees 8 image/mask pairs with matching shapes;
+- workflow is patched to Yixiao context;
+- project progress reports 10/6/2/2;
+- canonical project memory uses `tapereader_xri_fiber`;
+- Neuroglancer route returns a viewer URL and no false unpaired entries;
+- agent can summarize project context;
+- agent stages a review-gated training card;
+- PyTC worker-side subset resolver accepts the staged training subset.
+
+### Export Bundle Hygiene (Case-Study Runs)
+
+Evidence exports can be large if raw image paths are copied. For repeated case-study
+demonstrations, prefer manifest-only mode:
+
+```bash
+cd /home/weidf/deploy/pytc-client-demo2
+python - <<'PY'
+import requests
+
+workflow_id = <WORKFLOW_ID>
+requests.post(f"https://demo.seg.bio/api/workflows/{workflow_id}/export-bundle",
+              params={"copy_manifest_only": True})
+PY
+```
+
+The endpoint also supports:
+
+- `copy_max_bytes` for general artifact copy cap;
+- `raw_copy_max_bytes` for raw-like image paths (default `0`);
+- `copy_manifest_only=true` to disable all artifact file copies while still emitting
+  `artifact-paths.json`, `workflow-bundle.json`, and a copy summary.
+
+With `--exercise-promotion`, it also checks:
+
+- a draft volume can be promoted through the progress API;
+- project memory exposes both legacy app status and canonical paper-facing status;
+- progress changes to `7` fully good, `1` needs proofreading, `2` missing segmentation;
+- the agent's next training proposal uses seven ground-truth training pairs.
+
+For a fast pre-demo gate, run once:
+
+```bash
+cd /home/weidf/deploy/pytc-client-demo2
+.venv/bin/python scripts/run_yixiao_case_study_smoke.py \
+  --pre-demo-gate \
+  --report /tmp/yixiao-case-study-pre-demo-gate-report.json
+```
+
+This runs:
+
+- normal smoke (`--prepare-live`) with all baseline assertions,
+- one promotion dry-run (`--exercise-promotion`),
+- one final restore smoke to return the public workflow to the baseline `6/2/2` state.
+
+By default it also runs lightweight endpoint checks on the restored workflow:
+
+- `GET /api/workflows/{workflow_id}/case-study-readiness`,
+- `POST /api/workflows/{workflow_id}/export-bundle`.
+
+Disable those checks with:
+
+```bash
+.venv/bin/python scripts/run_yixiao_case_study_smoke.py \
+  --pre-demo-gate \
+  --skip-readiness-check \
+  --skip-export-check
+```
+
+The command writes a single composite JSON report including step pass/fail and residual caveats (for example, readiness not yet met when no training/evaluation loop has been run).
+
+If you only want a single smoke run, keep the legacy pattern:
+
+```bash
+cd /home/weidf/deploy/pytc-client-demo2
+.venv/bin/python scripts/run_yixiao_case_study_smoke.py --prepare-live --verbose
+```
+
+### Closed-Loop Rehearsal With Withheld Masks
+
+To verify the evidence/evaluation wiring for the two image-only targets without
+launching GPU jobs, run:
+
+```bash
+cd /home/weidf/deploy/pytc-client-demo2
+.venv/bin/python scripts/run_yixiao_case_study_smoke.py \
+  --closed-loop-rehearsal \
+  --closed-loop-training-iterations 2 \
+  --closed-loop-inference-iterations 1 \
+  --report /tmp/yixiao-closed-loop-rehearsal-report.json
+```
+
+This uses:
+
+- image targets `6_1` and `6_2` from the mounted manifest;
+- explicit withheld masks from `/home/weidf/demo_data/yixiao_tapereader_xri_case_study_holdout_masks`;
+- a small crop by default: `0:8,0:128,0:128`;
+- the existing `run_closed_loop_smoke.py` evidence harness, which now verifies:
+  - training using explicit withheld target masks,
+  - captured training checkpoints and inferred runtime model-version linkage,
+  - inference runtime synchronization for each target inference pass,
+  - metric evaluation against explicit withheld ground truth.
+
+It deliberately refuses to use mounted project labels as truth for `6_1` or `6_2`.
+Those volumes must remain image-only in the app-facing project. The withheld masks
+are for operator-only evaluation/rehearsal after predictions exist. Rehearsal
+fails if an explicit path is inside the mounted project root or resolves to the
+mounted segmentation path.
+
+Use a different crop for a bigger rehearsal:
+
+```bash
+.venv/bin/python scripts/run_yixiao_case_study_smoke.py \
+  --closed-loop-rehearsal \
+  --closed-loop-training-iterations 12 \
+  --closed-loop-inference-iterations 8 \
+  --closed-loop-crop "0:16,0:256,0:256"
+```
+
+Use full volumes only when you actually need it:
+
+```bash
+.venv/bin/python scripts/run_yixiao_case_study_smoke.py \
+  --closed-loop-rehearsal \
+  --closed-loop-crop ""
+```
+
+This rehearsal proves:
+
+- the image-only targets have external ground-truth masks available for later evaluation;
+- evaluation evidence can be produced with explicit withheld truth paths and explicit
+  iteration overrides;
+- target-level reports include `runtime_overrides`, `runtime_checkpoints`, and
+  `runtime_sync` fields;
+- export/readiness plumbing can represent before/after comparisons.
+
+It does not prove:
+
+- real TapeReader/PyTC training convergence;
+- real inference quality on `6_1` or `6_2`;
+- paper-faithful barcode-target reproduction.
+
+## Known Gaps To Avoid Overclaiming
+
+- The harness does not prove full GPU training convergence.
+- The harness does not prove inference produces scientifically meaningful predictions.
+- The harness does not prove browser-level proofreading edit quality.
+- The app-compatible config is not identical to the original TapeReader barcode-target config.
+- The case study currently proves workflow coordination, not segmentation accuracy.
+
+## Good Paper Claim From This Demo
+
+This case study can support a claim like:
+
+> The system maintains a grounded project state for an XRI fibre segmentation workflow, distinguishes ground truth, draft masks, and image-only volumes, and turns a natural-language training request into an approval-gated, reproducible multi-volume training proposal.
+
+For publication-level model claims, the claim boundary is:
+
+- **Can claim now:** coordination behavior, grounded context, approval-gating.
+- **Can claim after run evidence:** closed-loop training, post-training inference on `6_1` and `6_2`, and holdout-based evaluation.
+
+Avoid claiming that the system has already reproduced TapeReader's model performance unless a separate evaluation run proves it.
diff --git a/docs/proofreading-redesign-notes.md b/docs/proofreading-redesign-notes.md
new file mode 100644
index 00000000..40debd38
--- /dev/null
+++ b/docs/proofreading-redesign-notes.md
@@ -0,0 +1,131 @@
+# Proofreading Redesign Notes
+
+Updated: 2026-04-25
+
+## Log Findings From Latest Run
+
+- The largest runtime defect was not Electron rendering. The app log showed
+  `proofreading_instance_filmstrip_served` for `kind=mask_all`, `axis=xy`,
+  `z_start=48`, `z_count=12`, `max_dim=384` taking `25774.6 ms`, with nearly
+  all time reported inside the resize/render path.
+- The root cause was `labels_to_rgba` assigning colors by looping over every
+  unique label and then scanning the full slice for each label. On dense
+  connectomics labels, this turns all-label overlays into a pathological
+  `unique_labels x pixels` operation.
+- Mask save itself completed and wrote an artifact:
+  `/Users/adamg/seg.bio/testing_data/snemi/seg/.pytc_instance_labels.tif`.
+  The save request took about `946 ms`, changed 86 pixels, and recorded 2622
+  blocked pixels.
+- `/app/log-event` request bookkeeping was flooding the JSONL app log. Keeping
+  client events is useful; duplicating every client-log POST start/finish is
+  not. The middleware should suppress normal bookkeeping for that endpoint while
+  still logging slow or failed log submissions.
+
+## SOTA UI/Workflow Takeaways
+
+- CAVE frames connectomics proofreading as collaborative, versioned,
+  time-travelable annotation infrastructure rather than a static post-hoc edit
+  tool. Prototype implication: save/export state must be explicit and visible,
+  not hidden behind a transient canvas. Source:
+  https://www.nature.com/articles/s41592-024-02426-z
+- CAVEclient describes CAVE as microservices for versioning connectomics data,
+  annotations, metadata, and segmentations. Prototype implication: our local
+  app should model persistent artifacts, corrections, and review decisions as
+  first-class records even before becoming CAVE-scale. Source:
+  https://www.caveconnecto.me/CAVEclient/
+- WEBKNOSSOS presents the expected connectomics flow as upload, preprocessing,
+  collaborative annotation, data management, segmentation, proofreading, and
+  connectome viewing. Prototype implication: the proofreading screen should make
+  queue, canvas, review decision, and export/persistence adjacent. Source:
+  https://home.webknossos.org/use-cases/connectomics
+- Neuroglancer is the reference WebGL volumetric viewer, with an ecosystem
+  around precomputed format, CloudVolume, TensorStore, meshes, and scalable
+  downsampling. Prototype implication: PyTC Client should avoid pretending a
+  React canvas can become a petascale viewer; instead, optimize the local editor
+  and leave a clear future path to Neuroglancer-compatible data services.
+  Source: https://github.com/google/neuroglancer
+- Guided proofreading work identifies visual search as a bottleneck and treats
+  proofreading as correcting split/merge errors while generating training data.
+  Prototype implication: a review queue and fast slice navigation matter more
+  than generic file-browser controls inside proofreading. Source:
+  https://openaccess.thecvf.com/content_cvpr_2018/papers/Haehn_Guided_Proofreading_of_CVPR_2018_paper.pdf
+- MONAI Label treats annotation as an AI-assisted service with active learning,
+  3D Slicer/OHIF frontends, and incremental model improvement. Prototype
+  implication: the right product loop is annotate/proofread, persist, retrain,
+  evaluate, then pick the next useful sample or region. Source:
+  https://www.sciencedirect.com/science/article/pii/S1361841524001324
+- Human-AI interaction guidance emphasizes conveying local uncertainty and
+  setting expectations at the instance level. Prototype implication: agent and
+  UI language should be short, local, and action-oriented, with uncertainty
+  exposed near the item being reviewed. Source:
+  https://www.microsoft.com/en-us/research/articles/how-to-build-effective-human-ai-interaction-considerations-for-machine-learning-and-software-engineering/
+- micro-SAM shows current microscopy annotation tools moving toward interactive
+  2D/3D segmentation and tracking through napari. Prototype implication:
+  prompt-based correction is a good later feature, but the current priority is a
+  reliable edit/save/export loop. Source:
+  https://github.com/computational-cell-analytics/micro-sam
+
+## Current Redesign Decisions
+
+- Replace drawer/collapse navigation with a stable workbench:
+  review queue left, editor center, current action/save/export panel right.
+- Keep case-study/researcher controls out of the participant proofreading UI.
+- Treat "save mask" as a persistence operation with visible artifact/export
+  state, not just a canvas action.
+- Use fast image-only previews during aggressive slider scrubbing, then fetch
+  richer overlays only when the slice is committed or the UI is idle.
+- Vectorize label-to-color rendering so all-label context overlays are not
+  catastrophically slow on real segmentation volumes.
+- Keep app-event logging dense around real proofreading actions, but avoid
+  self-noise from logging the log endpoint itself.
+
+## 2026-04-25 Canvas-First UI Reset
+
+- The screenshot from the Mito25 smoke project showed the workbench becoming a
+  nested form UI instead of a proofreading viewer: large header card, separate
+  slice rail, duplicate embedded layer toolbar, left queue, right action panel,
+  and a small canvas boxed inside all of it.
+- The redesign now treats the central image as the primary object. Review
+  decisions, axis selection, active instance metadata, mask readiness, and export
+  access sit in the viewer header.
+- The slice scrubber remains crucial, but it is now attached to the viewer
+  surface as a bottom dimension control with tick marks and a visible current
+  slice label. The always-open black tooltip was removed because it visually
+  fought the image.
+- The embedded editor's own layer toolbar is hidden in workbench mode so there
+  is one slice-navigation source of truth.
+- The queue no longer shows a redundant "Load dataset" button during an active
+  session. Dataset switching is promoted to the workbench header instead.
+- The right panel is now secondary "Details" material: active object, saved
+  output, opacity controls, and export/staging. It should not carry the main
+  review decision loop.
+- A follow-up compression fix made the canvas fit the available stage and
+  clamps zoom/pan so the image cannot collapse into a tiny off-canvas thumbnail
+  after resizing or scrolling. The queue also collapses sooner on narrower
+  windows.
+- Research rationale and source links are recorded in
+  `docs/research/agentic-ui-design-pass.md`.
+
+## Remaining Follow-Up
+
+- Add a tile/chunk-backed viewer path for large volumes instead of repeatedly
+  encoding full PNG slices.
+- Add explicit split/merge proofreading tools; current paint/erase is only a
+  useful local correction primitive.
+- Add a hotspot/review queue populated by model uncertainty and error evidence,
+  not just instance IDs.
+- Add export adapters for OME-Zarr/NGFF and Neuroglancer precomputed when moving
+  beyond the local TIFF prototype.
+- Add browser-level manual tests that measure scrub latency, save latency, and
+  artifact persistence on the Mito25 and SNEMI sample projects.
+
+## 2026-04-25 Agent-Orchestrated Proofreading Entry
+
+- The global agent can now emit a `start_proofreading` runtime action with
+  image, mask, and review-name overrides. The proofreading tab consumes that
+  action and calls the same loader endpoint used by the manual form.
+- The loader language now starts from "What should I proofread?" and offers a
+  one-click "Start proofreading this pair" path for detected image/mask pairs.
+- The active workbench uses "Change data", "Focus view", "Review details",
+  "Saved edits", and "Use edits for training" so the screen reads like an
+  editing task rather than backend provenance management.
diff --git a/docs/prototype-completion-roadmap.md b/docs/prototype-completion-roadmap.md
new file mode 100644
index 00000000..f47e15f7
--- /dev/null
+++ b/docs/prototype-completion-roadmap.md
@@ -0,0 +1,309 @@
+# Prototype Completion Roadmap
+
+This is the long-term project memory for moving from the current PyTC Client
+toward the paper-implied prototype: an agent-mediated, human-controlled,
+closed-loop biomedical segmentation workflow.
+
+## Current Verdict
+
+The project is not yet a paper-ready prototype of the system described by the
+paper. The evidence substrate is now real enough to support structured smoke
+walkthroughs: real mito25 image/seg data can enter the path, supplied PyTC
+prediction files can be evaluated, completed app/PyTC inference runtimes can be
+synced into workflow records, correction exports become correction-set records,
+and the participant UI exposes the closed-loop pipeline, evidence artifacts,
+metric controls, and bundle export. The remaining gap is still the full fresh
+closed loop: app-launched baseline inference, real proofreading edit/export,
+actual retraining/fine-tuning, post-training inference, and before/after
+evaluation over fresh app-generated outputs.
+
+## Prototype Boundary
+
+- Participant UI should expose biomedical workflow state and controls, not
+  case-study protocol controls.
+- Case-study readiness, protocol planning, and study gates stay researcher-only
+  in docs, backend routes, tests, and exported evidence bundles.
+- Do not reintroduce case-study readiness bars or protocol-plan cards into the
+  participant-facing app.
+
+## Implemented Checkpoints
+
+- Typed workflow evidence records exist for events, artifacts, model runs, model
+  versions, correction sets, evaluation results, hotspots, agent plans, and
+  agent steps.
+- Workflow bundle export exists for researcher/paper evidence capture.
+- Researcher-only readiness gates exist and are covered by backend tests.
+- Synthetic closed-loop smoke exists in `scripts/run_closed_loop_smoke.py`.
+- Real-pair smoke exists for mito25 HDF5 image/seg pairs, using HDF5 dataset
+  keys and crop support.
+- Real prediction input mode exists for supplied baseline/candidate prediction
+  artifacts.
+- PyTC channel-first/channel-last prediction outputs can be selected with
+  explicit baseline/candidate channels in the smoke harness.
+- Completed PyTC worker inference runtimes can be synchronized into workflow
+  `inference.completed` events, `ModelRun` records, and prediction artifacts.
+- Closed-loop evidence is visible in the participant UI: baseline prediction,
+  candidate prediction, corrected mask, reference label/ground truth, latest
+  evaluation report, and metric deltas.
+- The participant UI can compute before/after evaluation metrics from recorded
+  baseline, candidate, and reference volume paths when all required evidence is
+  present.
+- The participant UI exposes dataset key, crop, and channel controls for HDF5
+  and PyTC-style predictions that cannot be safely auto-detected.
+- The participant UI shows an explicit closed-loop pipeline map with the next
+  incomplete gate.
+- Evidence bundle export is available from the participant workflow evidence
+  panel and logs a `workflow.bundle_exported` event for auditability.
+- A workflow-agent recommendation endpoint now returns a stage-aware decision,
+  readiness checklist, blockers, top hotspot, impact preview, app actions, and
+  command blocks from the typed workflow evidence substrate.
+- The participant UI now has a compact workflow-agent control strip across
+  modules. Its primary button can navigate, start safe runtime handoffs, propose
+  retraining staging from corrected masks, refresh insights, and open the
+  assistant evidence/context drawer.
+- Workflow chat now uses the same recommendation substrate for "what next"
+  questions and keeps answers compact: `Do this`, `Why`, `Ready`, and at most
+  one blocker.
+- Workflow-agent chat now carries typed intent, permission-mode, risk metadata,
+  and a structured loop checklist. Slash-style workflow commands are supported
+  for status, inference, proofreading, training, comparison, and export.
+- Assistant chat routing now distinguishes workflow intents from general chat:
+  workflow-like requests go to the deterministic orchestrator, while unrelated
+  or nonsensical text goes through the general assistant path instead of
+  producing workflow action cards.
+- The workflow-agent router now clarifies unknown requests without app action
+  cards, preventing gibberish from being interpreted as a next-step command.
+- Main chat now has direct guardrails for low-signal gibberish, meta questions
+  about whether a job actually ran, and biologist-facing parameter delegation.
+  These responses persist to chat history without invoking the docs RAG path.
+- The local assistant default model is now `llama3.1:8b` instead of
+  `llama3.2:1b`; current local-model evaluation notes live in
+  `docs/research/on-device-llm-options-2026-04-26.md`.
+- Assistant command details are collapsed behind a route disclosure so the
+  visible UI stays domain-oriented rather than command-oriented.
+- Agent-triggered training now stages an inferred preset, current image path,
+  corrected mask path, output/log directory, and conservative default runtime
+  parameters before the user approves the run.
+- Proofreading mask exports materialize correction sets with edit and region
+  counts derived from preceding proofreading events.
+- File Management has a one-click suggested mito25 smoke-project mount.
+- Suggested project mounting profiles local folders for likely image, label,
+  prediction, config, checkpoint, and pair roles before the user has to browse
+  manually.
+- Suggested project mounting now registers detected workflow paths: dataset,
+  image, label/mask, prediction, and checkpoint paths are pushed into the
+  workflow session and logged as a `dataset.loaded` event.
+- Suggested project mounting is now project-agnostic through
+  `pytc-project-profile/v1`: folders can be `image_only`, `image_mask_pair`, or
+  `closed_loop_ready`, and image-only volume folders count as valid workflow
+  starts.
+- Workflow preflight now exposes the current runnable state for setup,
+  visualization, inference, proofreading, training, and evaluation from typed
+  workflow records. It treats config/YAML as an agent-inferred implementation
+  detail rather than a first-order biologist blocker.
+- A stable app-shell `What next?` button now opens the assistant and asks the
+  workflow agent for the next action from current preflight/evidence state,
+  preserving the response and action cards in chat history.
+- The app now opens directly to the main module shell. The startup
+  session-intake/splash gate was removed because the user goal is always the
+  same closed-loop segmentation task.
+- The workflow agent now gathers biological project context at action time:
+  before inference, training, or proofreading triage it asks for missing
+  modality, target structure, and speed/accuracy preference, then stores that
+  as `metadata.project_context`.
+- Suggested project mounting no longer depends on a startup goal. SNEMI/TIFF
+  and raw HDF5 smoke-data fixtures remain available as realistic alternate
+  starts alongside the mito smoke project.
+- A fresh workflow reset path now creates a clean `setup` workflow session
+  while preserving old workflow evidence for audit/history.
+- File Management now keeps the suggested project setup card on the root
+  project view only, reducing repeated clutter once the user is inside a
+  mounted project.
+- File path inputs now open the mounted-project picker from the folder icon as
+  well as the Browse button, so manual path typing is a fallback rather than
+  the apparent primary flow.
+- Inline field help now returns compact, field-specific guidance for common file
+  selectors instead of raw local-doc excerpts.
+- The proofreading editor exposes a visible `Save mask` control, tracks unsaved
+  edits, and caps undo history to reduce memory churn.
+- HDF5/Zarr/NumPy volume loading can select prediction channels while applying
+  crops, avoiding unnecessary full channel-stack reads for PyTC outputs.
+- Shared voxel loading exists for TIFF/OME-TIFF, HDF5, NumPy, Zarr/N5, common
+  2D image formats, and optional NIfTI/MRC parser packages.
+- Evaluation can compute before/after metrics across supported voxel formats.
+- Participant-facing case-study UI has been ablated.
+
+## Next Priority
+
+Run the first fresh app-generated before/after loop:
+
+- Launch baseline PyTC inference from the app on a mito25 crop and sync the
+  completed runtime.
+- Perform a real proofreading edit/export that creates a correction set from
+  the browser/editor path.
+- Run retraining or a bounded fine-tuning smoke from that correction set.
+- Launch post-training inference, sync the completed runtime, and compute
+  before/after metrics over the two app-generated outputs.
+
+## Major Workstreams
+
+1. Evidence substrate
+   - Keep workflow records typed and queryable.
+   - Keep artifact lineage explicit.
+   - Keep evidence bundle export deterministic and paper-friendly.
+
+2. Real data ingestion
+   - Continue broad voxel-format support.
+   - Add OME-Zarr/NGFF and Neuroglancer-precomputed details when the workflow
+     needs lab-scale interoperability.
+   - Preserve crop/key support so large volumes are testable without loading
+     full datasets.
+
+3. Real closed-loop smoke
+   - Synthetic smoke is complete.
+   - Real image/seg smoke with derived predictions is complete.
+   - Real prediction input smoke is complete for externally supplied
+     predictions.
+   - Existing app-generated PyTC prediction files can be ingested as real
+     prediction artifacts.
+   - Fresh app-launched PyTC inference smoke is next.
+
+4. Actual PyTC inference/training loop
+   - Launch inference on real data.
+   - Capture inference output as a `ModelRun`.
+   - Proofread or edit a mask and persist a `CorrectionSet`.
+   - Stage corrections for retraining.
+   - Run retraining or fine-tuning.
+   - Register the candidate checkpoint as a `ModelVersion`.
+   - Run post-training inference.
+   - Compare before/after outputs with real metrics.
+
+5. Workflow UI, not case-study UI
+   - Expose workflow stage, artifacts, runs, corrections, evaluation metrics,
+     and agent proposals.
+   - Implemented UI hardening: direct evaluation-compute controls, closed-loop
+     pipeline map, evidence bundle export, and suggested smoke-project mounting
+     without adding researcher case-study protocol gates.
+   - Implemented agent continuity: the assistant drawer/status entry exposes
+     the next recommended workflow action and a one-click evidence/context view
+     without requiring a persistent canvas strip.
+   - Next UI hardening: expose model versions/config lineage as secondary
+     provenance, make file-role assignment editable when auto-detection guesses
+     wrong, and continue reducing the generic file-browser feel.
+   - Keep approval/rejection controls for risky agent actions.
+   - Refine workflow rail placement and visibility.
+   - Do not expose researcher protocol gates to participants.
+
+6. Agentic bounded autonomy
+   - Agent proposes actions; it does not silently execute risky steps.
+   - Agent role is formalized in `docs/agent-role-spec.md`.
+   - Claude Code pattern notes live in
+     `docs/research/claude-code-agent-patterns.md`.
+   - Implemented agent recommendation substrate: stage-aware decision, blockers,
+     readiness, top hotspot, impact preview, and app-executable actions.
+   - Implemented cross-module agent controls: open files, launch inference from
+     current settings, open proofreading, propose retraining handoff, prime
+     training labels, launch staged training, and open evidence context.
+   - UI simplification pass ablated visible per-module agent nudges and the
+     persistent next-step strip. The agent remains accessible through the chat
+     drawer and normal module buttons where needed.
+   - All chatbot agents should default to short, biologist-skimmable answers:
+     next action first, three bullets or fewer, and no internal implementation
+     details unless explicitly requested.
+   - Approval, rejection, interruption, and resume decisions must be auditable.
+   - Use LangGraph where durable state-machine behavior, checkpoints, and
+     interrupt/resume semantics become real execution requirements.
+   - Use LangChain only for model/tool wrappers and simple retrieval glue.
+   - Next agentic-system hardening: durable job/task state, approval modes,
+     workflow hooks/gates, focused biomedical subagents, and context compaction
+     for long assistant sessions.
+   - Implemented preflight backend/context: training and inference readiness can
+     now say "ready", "missing X", or "agent can run this with inferred
+     defaults" without exposing raw YAML by default.
+   - Next UI integration: surface preflight only at decision points, not as
+     persistent clutter.
+
+7. Evaluation and provenance
+   - Compute before/after segmentation metrics over real outputs.
+   - Link metrics to exact prediction, ground-truth, checkpoint, correction, and
+     config artifacts.
+   - Dataset key, crop, and prediction-channel selectors are implemented in the
+     workflow evidence panel.
+   - Bundle export is auditable through a workflow event, but a persisted
+     downloadable bundle directory/zip is still needed for paper artifact
+     packaging.
+   - Export paper-ready bundles with events, artifacts, runs, versions,
+     corrections, metrics, and figure inputs.
+
+8. Interop and SOTA relevance
+   - Align with connectomics/bioimage formats and workflows: HDF5, OME-Zarr/NGFF,
+     N5/Zarr, Neuroglancer-compatible artifacts, and eventual CAVE/Neuroglancer
+     relevance.
+   - Evaluate relevant model ecosystems when needed: PyTorch Connectomics,
+     MONAI, nnU-Net, Cellpose/Cellpose-SAM, micro-SAM, MedSAM/SAM2 variants,
+     StarDist, PlantSeg, DeepCell/Mesmer.
+
+9. Engineering hardening
+   - Replace process-global runtime state with durable job records.
+   - Add a real job queue for long-running inference/training.
+   - Add cancellation, retries, failure recovery, and resumable execution.
+   - Link TensorBoard, MLflow, W&B, or equivalent run tracking to workflow
+     records where useful.
+   - Make file management and project mounting substantially more user-friendly:
+     guided project setup, obvious mounted roots, automatic image/seg/config/
+     checkpoint detection, duplicate/stale mount cleanup, better picker labels,
+     one-click test-project mounting for smoke workflows, and editable role
+     confirmation when auto-detected project roles are wrong. Current progress:
+     suggested and manually mounted projects are profiled first, then routed
+     through a compact role-confirmation modal before workflow registration.
+     Confirmed config paths are persisted as workflow state and used as the
+     preferred agent training preset. The profiler now reports role directories
+     and detected image/label volume sets; multi-volume projects default to
+     folder-level confirmation instead of one arbitrary file. The confirmation
+     modal now captures broad project context first, stores it in workflow
+     metadata for downstream agent use, then separately supports
+     natural-language mapping corrections before `Start project`. The setup
+     flow is now staged: semantic context must pass a deterministic completeness
+     gate, then the user confirms mechanistic file/folder roles, then the app
+     writes workflow state and a hidden `.pytc_project_context.json` memory file
+     in the project directory. Remaining hardening is true multi-set active-set
+     selection, batch operations across sets, and browser-level blank-state
+     rehearsal on non-mito data. Biological context defaults are now only taken
+     from backend content spot checks such as manifest/config snippets and
+     HDF5/TIFF container metadata, not from semantically lucky project names.
+     The workflow agent now has a stricter action consistency path: status
+     detection no longer uses unsafe raw substring matching, visualization
+     requests can populate viewer paths, proofreading requests from setup can
+     expose a runnable `start-proofreading` card when image/mask data exist, and
+     blocked requests now state the missing artifact instead of silently falling
+     back to generic cards.
+     Visualization scale corrections are now tracked as workflow/project
+     context: the agent can parse z,y,x scale updates from natural language,
+     persist them, and trigger a viewer reload. Remaining hardening is broader
+     unit handling and surfacing current scale context consistently across all
+     model/proofreading screens.
+
+10. Paper alignment
+
+- Maintain the paper-claim-vs-implementation matrix.
+- Maintain a paper/prototype additions matrix.
+- Keep paper claims honest until the real closed loop works.
+- Refresh the claim wording after each prototype milestone.
+
+## Paper-Claim Risk Register
+
+| Claim Area                        | Current Status                                                                                          | Overclaim Risk | Required Evidence                                                                                        |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------- | -------------- | -------------------------------------------------------------------------------------------------------- |
+| Closed-loop improvement           | Backend/evaluation path and external prediction input mode exist, real app-generated model loop missing | High           | Real app-generated baseline inference, correction, retraining, candidate inference, before/after metrics |
+| Human-controlled agent workflow   | Proposal/approval substrate exists                                                                      | Medium         | Visible participant workflow controls and auditable approvals over real actions                          |
+| Biomedical/connectomics relevance | Mito25 data ingestion works                                                                             | Medium         | Real inference/proofreading/retraining on mito/connectomics artifacts                                    |
+| Bounded autonomy                  | Researcher-only plan/proposal records exist                                                             | Medium         | Durable interrupt/resume execution if claimed as operational                                             |
+| Reproducible evidence export      | Bundle exists                                                                                           | Low/Medium     | Bundle generated from real workflow artifacts and paper figures                                          |
+| SOTA alignment                    | Research notes/plans exist                                                                              | Medium         | Explicit comparison/baseline or clear positioning against relevant systems                               |
+
+## Researcher-Only Notes
+
+- Case-study protocol details live in `docs/case-study-prototype-readiness.md`.
+- Smoke execution details live in `docs/closed-loop-smoke.md`.
+- Manual bulk-test steps live in `docs/manual-bulk-test-checklist.md`.
+- Evidence export details live in `docs/research/workflow-evidence-export.md`.
diff --git a/docs/remote-codex-handoff.md b/docs/remote-codex-handoff.md
new file mode 100644
index 00000000..8fdfeee0
--- /dev/null
+++ b/docs/remote-codex-handoff.md
@@ -0,0 +1,319 @@
+# Remote Codex Handoff: PyTC Client Agentic Prototype
+
+Use this file to port the current local Codex context to a remote Codex session.
+The remote goal is practical: keep the case-study demo moving, fix obvious
+workflow breaks quickly, and preserve the prototype direction.
+
+## Current Branch
+
+- Repo: `https://github.com/PytorchConnectomics/pytc-client.git`
+- Branch: `checkpoint/tochi-agentic-prototype`
+- Latest pushed commit: `ac940e4 fix(agent): recognize training requests`
+
+On the remote machine:
+
+```bash
+git fetch origin
+git checkout checkpoint/tochi-agentic-prototype
+git pull --ff-only origin checkpoint/tochi-agentic-prototype
+```
+
+If the remote is intentionally on another branch, cherry-pick the latest fix:
+
+```bash
+git fetch origin
+git cherry-pick ac940e4
+```
+
+## Prototype Goal
+
+This is not just a PyTC GUI. The target prototype is an agent-orchestrated,
+human-controlled biomedical segmentation loop:
+
+1. User mounts a project folder.
+2. App inspects contents and asks for semantic project context.
+3. User confirms image/label/prediction/checkpoint/config roles.
+4. Agent can route the user through visualization, model running, proofreading,
+   training, comparison, and evidence export.
+5. Every agent action should be explicit, logged, approval-gated if risky, and
+   phrased for a biologist rather than as a terminal/config explanation.
+
+The core user goal is always: go from initial image volumes to proofread
+segmentations, with model runs and retraining as needed.
+
+## Most Important Recent Work
+
+### Project-Agnostic Setup
+
+- File setup moved away from the hardcoded mito-only path.
+- Suggested/mounted project folders now go through a confirmation flow.
+- The app attempts to infer:
+  - image data
+  - mask/label data
+  - existing predictions
+  - checkpoints
+  - config presets
+- The user can correct mappings before the workflow state is written.
+- Project context is intended to persist as hidden project memory, not as noisy
+  UI text.
+
+Relevant files:
+
+- `client/src/views/FilesManager.js`
+- `client/src/utils/projectSuggestions.js`
+- `server_api/auth/router.py`
+- `tests/test_file_workspace_routes.py`
+- `client/src/views/FilesManager.test.js`
+
+### Workflow Agent
+
+- The agent is meant to be an orchestrator, not a documentation chatbot.
+- It should answer with short “do this / why / blocker” language.
+- It should return app action cards for runnable tasks.
+- It should name blockers when it cannot act.
+- It should not leak JSON tool calls or internal prompts.
+
+Recent critical fix:
+
+- `train`, `train a model`, `train on saved edits`, and similar phrases now hit
+  the workflow-agent training path instead of “did not understand”.
+
+Relevant files:
+
+- `server_api/workflows/router.py`
+- `client/src/components/Chatbot.js`
+- `client/src/contexts/WorkflowContext.js`
+- `tests/test_workflow_routes.py`
+- `client/src/components/Chatbot.test.js`
+
+### Visualization and Volume Pair Handling
+
+- Directory-level image/label roles are valid project context.
+- Neuroglancer cannot directly load a directory as a volume, so the backend now
+  tries to find clear image-to-seg file pairs inside directories.
+- The agent should ask if there are more pairs/folders instead of pretending one
+  file is the whole project.
+- Visualization scale changes are now workflow context:
+  - “reload with 1-1-1” should store z,y,x scale as `visualization_scales`
+  - it should also update `project_context.voxel_size_nm`
+  - the agent should offer `Reload viewer`
+
+Relevant files:
+
+- `server_api/workflows/volume_pairs.py`
+- `server_api/main.py`
+- `server_api/workflows/router.py`
+- `client/src/views/Visualization.js`
+- `tests/test_neuroglancer_volume_normalization.py`
+
+### Proofreading Context
+
+- Proofreading should use current workflow image/mask paths.
+- It should not show global project suggestions from unrelated projects.
+- Assistant-triggered proofreading load has a one-shot guard to avoid duplicate
+  loads from React effect re-entry.
+
+Relevant files:
+
+- `client/src/views/ehtool/DatasetLoader.js`
+- `client/src/views/ehtool/DatasetLoader.test.js`
+- `client/src/views/ehtool/DetectionWorkflow.js`
+
+## Current Remote Screenshot Diagnosis
+
+The screenshot showing repeated:
+
+> I did not understand that as a workflow job...
+
+for training requests means the remote is missing `ac940e4` or equivalent. Pull
+the branch or cherry-pick that commit. After it lands:
+
+- `train` should ask for missing project context if needed.
+- `can we train a model for this?` should either return `Train model` or name
+  missing image/label inputs.
+- `train on saved edits` should name missing labels/saved edits instead of
+  falling to unknown.
+
+## Case-Study Demo Path
+
+For a prepilot, use a small real dataset project, not a synthetic-only smoke
+path. Current likely remote target from screenshot:
+
+- Mounted folder: `prepilot_lucchi_pp`
+- Expected purpose: mitochondria / EM segmentation stress test
+- Demo target: show whether the app can ingest a practitioner-style folder,
+  infer image/label roles, visualize a pair, and let the agent route to
+  proofreading/training without user config spelunking.
+
+Suggested short script:
+
+1. Start from Files with one mounted project.
+2. Open or mount `prepilot_lucchi_pp`.
+3. Confirm project context in plain language:
+   `EM mitochondria dataset; segment mitochondria; prioritize accuracy.`
+4. Confirm image/label roles.
+5. Ask agent:
+   `what should I do next?`
+6. Ask:
+   `can we visualize my existing segs?`
+7. Run the `View data` / `Reload viewer` action.
+8. If visualization works, ask:
+   `proofread this data`
+9. If labels or edits exist, ask:
+   `can we train a model for this?`
+10. If blocked, confirm the agent names exactly what is missing.
+
+## Remote Debug Runbook
+
+If no server logs are accessible, use endpoint probes and browser behavior.
+
+### Check Current Workflow
+
+```bash
+curl -s https://demo.seg.bio/api/api/workflows/current | python -m json.tool | head -80
+```
+
+If the frontend is configured differently, also try:
+
+```bash
+curl -s https://demo.seg.bio/api/workflows/current | python -m json.tool | head -80
+```
+
+### Query Workflow Agent Directly
+
+Replace `1` with the workflow id from the current-workflow response:
+
+```bash
+curl -s -X POST https://demo.seg.bio/api/api/workflows/1/agent/query \
+  -H 'Content-Type: application/json' \
+  -d '{"query":"can we train a model for this?"}' | python -m json.tool
+```
+
+Expected after `ac940e4`:
+
+- `intent` is `collect_project_context` or `start_training`
+- response does not say `did not understand`
+- actions either contain `start-training` or a setup blocker action
+
+### Check Visualization Pair Handling
+
+```bash
+curl -s -X POST https://demo.seg.bio/api/api/workflows/1/agent/query \
+  -H 'Content-Type: application/json' \
+  -d '{"query":"can we visualize my existing segs?"}' | python -m json.tool
+```
+
+Expected:
+
+- `intent` is `view_data`
+- action id is usually `open-visualization`
+- if directories contain matched files, response mentions clear image/seg pairs
+
+### Check Scale Correction
+
+```bash
+curl -s -X POST https://demo.seg.bio/api/api/workflows/1/agent/query \
+  -H 'Content-Type: application/json' \
+  -d '{"query":"the scales are off; reload with 1-1-1"}' | python -m json.tool
+```
+
+Expected:
+
+- `intent` is `set_visualization_scales`
+- action id is `reload-visualization-scales`
+- workflow metadata stores `visualization_scales: [1.0, 1.0, 1.0]`
+
+## Tests To Run Remotely When Possible
+
+Fast targeted backend:
+
+```bash
+/opt/homebrew/bin/uv run pytest tests/test_workflow_routes.py -q
+```
+
+If `uv` path differs:
+
+```bash
+uv run pytest tests/test_workflow_routes.py -q
+```
+
+Frontend targeted:
+
+```bash
+cd client
+CI=true npm test -- --runInBand src/components/Chatbot.test.js
+```
+
+Production build:
+
+```bash
+cd client
+npm run build
+```
+
+Known build warnings exist in older files. Do not block case-study progress on
+non-new ESLint warnings unless they are directly related to the bug at hand.
+
+## Known Wonkiness To Preserve In Context
+
+- The UI is still too busy in places. Do not add more persistent explanatory
+  panels unless absolutely necessary.
+- Agent replies should be short. Avoid long documentation-style answers.
+- Biologists should not have to manually tune config details unless they ask.
+  The agent should infer safe defaults and expose an approval-gated app action.
+- The project can contain many volumes, not one volume. Do not force a single
+  image path as the full mental model.
+- Directory names may be semantically weak. Infer roles from extensions,
+  structure, manifests/configs, and lightweight file inspection, not only names.
+- If an agent action cannot run, say the blocker plainly and provide the nearest
+  useful action.
+- Remote `demo.seg.bio` may have path prefix quirks. Recent remote note says the
+  frontend should call `https://demo.seg.bio/api/files` and
+  `https://demo.seg.bio/api/api/workflows/current` depending on deployed base
+  config. Verify with curl before assuming.
+
+## Implementation Principles For Remote Codex
+
+- Prefer narrow fixes over large redesigns during case-study prep.
+- Keep app actions typed through `client_effects`.
+- Risky actions still require a user click:
+  - model run
+  - training
+  - proofreading editor load
+  - evidence export
+  - metric computation
+- Record every meaningful agent/workflow action in backend events when possible.
+- If touching chat behavior, update both:
+  - `server_api/workflows/router.py`
+  - `client/src/components/Chatbot.test.js` or `tests/test_workflow_routes.py`
+- If touching project ingest, update:
+  - `client/src/views/FilesManager.test.js`
+  - `client/src/utils/projectSuggestions.test.js`
+  - `tests/test_file_workspace_routes.py`
+
+## Memory Docs Worth Reading
+
+- `docs/codex-working-memory/README.md`
+- `docs/codex-working-memory/research-log.md`
+- `docs/codex-working-memory/backlog.md`
+- `docs/codex-working-memory/progress-log.md`
+- `docs/prototype-completion-roadmap.md`
+- `docs/agent-role-spec.md`
+- `docs/case-study-prototype-readiness.md`
+- `docs/manual-bulk-test-checklist.md`
+- `docs/research/pytc-prepilot-dataset-stress-test.md`
+
+The `docs/codex-working-memory/` files are vendored from the local Mac's
+external Codex notes so remote Codex can operate with the same progress log and
+backlog context.
+
+## Current High-Level Priority
+
+For the remote case-study sprint, the priority is not architectural perfection.
+It is:
+
+1. Make project ingest feel sane for a real folder.
+2. Make the agent answer and act on obvious workflow requests.
+3. Make visualization/proofreading/training blockers explicit.
+4. Avoid UI clutter and long agent prose.
+5. Capture enough evidence to know where the prototype still breaks.
diff --git a/docs/research/agentic-ui-design-pass.md b/docs/research/agentic-ui-design-pass.md
new file mode 100644
index 00000000..e6a9ec96
--- /dev/null
+++ b/docs/research/agentic-ui-design-pass.md
@@ -0,0 +1,93 @@
+# Agentic UI Design Pass
+
+Updated: 2026-04-25
+
+## Scope
+
+This note records the design pass behind the mask proofreading reset. The goal
+is not to make PyTC Client look like a generic AI chat app. The goal is to make
+the biologist-facing workflow behave like a scientific image viewer with bounded
+agent assistance layered around the work, not competing with it.
+
+## Sources Checked
+
+- Microsoft Guidelines for Human-AI Interaction:
+  https://www.microsoft.com/en-us/research/project/guidelines-for-human-ai-interaction/2025-1-31/
+- Magentic-UI human-in-the-loop agentic systems:
+  https://arxiv.org/abs/2507.22358
+- WEBKNOSSOS proofreading workflows:
+  https://docs.webknossos.org/webknossos/proofreading/index.html
+- WEBKNOSSOS connectomics workflow positioning:
+  https://home.webknossos.org/use-cases/connectomics
+- Neuroglancer/PyTorch Connectomics viewer integration notes:
+  https://connectomics.readthedocs.io/en/latest/external/neuroglancer.html
+- 3D Slicer Segment Editor:
+  https://slicer.readthedocs.io/en/5.8/user_guide/modules/segmenteditor.html
+- napari viewer layout and dimension slider pattern:
+  https://napari.org/stable/tutorials/fundamentals/viewer.html
+- Nature 2025 connectomic reconstruction manual proofreading workflow:
+  https://www.nature.com/articles/s41586-025-08985-1
+
+## Design Principles For This App
+
+- Canvas first. The active image/mask view is the work object; controls should
+  orbit it rather than push it into a small nested card.
+- One navigation source of truth. A volume viewer should not show duplicate
+  layer headers, duplicate slice controls, and duplicate next/previous controls
+  in competing places.
+- Keep state local to the action. The current slice, active instance, edit
+  readiness, save state, and review decision should be visible next to the
+  canvas, not hidden in a generic side panel.
+- Use progressive disclosure. Export paths, provenance details, and staging
+  controls matter, but they are secondary to inspect/edit/review/save.
+- Preserve expert imaging patterns. napari and Slicer both keep slice navigation
+  tightly coupled to the image view; Slicer also treats keyboard-driven slice
+  movement and tool switching as core editing affordances.
+- Bound agent behavior. Agent help should surface short, local suggestions and
+  never obscure the segmentation canvas or overload the user with long prose.
+- Avoid case-study-specific participant UI. Study instrumentation belongs in
+  logs/research exports, not as participant-facing controls in the prototype.
+
+## Current Proofreading UI Reset Decisions
+
+- Replace the heavy top card with a compact workbench header.
+- Keep the left review queue, but remove the redundant "Load dataset" action
+  from inside the active proofreading queue.
+- Move review decisions into the viewer header so the user can inspect and
+  classify without moving attention to a separate panel.
+- Hide the embedded editor's duplicate layer toolbar when used inside the
+  proofreading workbench.
+- Attach the slice slider directly to the viewer surface and keep tick marks and
+  an explicit current-slice label.
+- Keep export, overlay opacity, and artifact paths in a narrower details panel
+  rather than making them the primary workflow.
+
+## Remaining UI/Agent Work
+
+- Agent messages need a short "biologist skim" format: conclusion first,
+  1-3 bullets, explicit action or no action.
+- File/project mounting needs a separate flow redesign. The current path-based
+  mounting flow is still too manual and error-prone.
+- The editor still needs a more complete split/merge-oriented tool model; paint
+  and erase are local correction primitives, not connectomics-grade proofreading.
+- The canvas should eventually move toward tiled/chunked rendering for large
+  volumes rather than repeated full-slice PNG transfer.
+
+## 2026-04-25 Product-Language/Orchestrator Update
+
+- The UI problem is broader than density: the app was exposing research/backend
+  bookkeeping ("evidence", "artifacts", "candidate", "correction set") where a
+  biologist expects task language ("previous result", "new result", "your
+  edits", "reference mask").
+- The agent strip should be a workflow orchestrator, not a second dashboard.
+  It now emphasizes one next action plus a small status drawer; readiness counts
+  and path details should not compete with the user's image/mask task.
+- "Proofread this data" is now an executable client effect, not just navigation:
+  the backend emits a `start_proofreading` runtime action and the frontend loads
+  the current image/mask pair into the proofreading workbench when available.
+- Advanced metric dataset/channel fields are hidden behind "Metric options".
+  This follows progressive disclosure: common user action first, technical
+  disambiguation only when HDF5/channel details are required.
+- Remaining design debt: turn the whole app into an intent ladder
+  (`choose data -> run model -> proofread -> train on edits -> compare`) rather
+  than separate modules that happen to share workflow state.
diff --git a/docs/research/agentic-workflow-formalization-report.md b/docs/research/agentic-workflow-formalization-report.md
new file mode 100644
index 00000000..48e97c68
--- /dev/null
+++ b/docs/research/agentic-workflow-formalization-report.md
@@ -0,0 +1,613 @@
+# Agentic Workflow Formalization Report
+
+Date: 2026-05-27
+
+## 1. Executive Summary
+
+Build the seg.bio / PyTC Client assistant as a **workflow-aware, approval-gated project operator** for volumetric biomedical segmentation. The central abstraction should not be chat history. It should be **project memory plus action proposals**. Chat is the conversational surface; project memory is the shared source of truth; action cards bridge intent to bounded app routines; evidence events are the provenance layer that makes the system credible for engineering, science, and a TOCHI-style systems paper.
+
+The paper should call the system a **mixed-initiative workflow agent for iterative biomedical image segmentation**. This is more precise than "chatbot" and more defensible than "autonomous scientist." The product can call it the **Workflow Assistant** or **Segmentation Workflow Assistant**.
+
+The current prototype already has important pieces: workflow sessions, event logs, artifacts, volume states, model runs, correction sets, evaluation records, agent proposals, approval events, action cards, command records, project scanning, and evidence bundle export. The brittle part is that these pieces do not yet form one canonical contract. Project state is spread across `WorkflowSession` columns, `metadata_json.project_context`, `metadata_json.project_observation`, `metadata_json.project_progress_snapshot`, `WorkflowVolumeState`, browser session chat, mounted file records, runtime form state, and inferred project-progress scans. The assistant sometimes answers from a useful but stale synthesis rather than from a documented inspection boundary.
+
+Recommended architecture:
+
+1. Introduce a normalized `ProjectMemory` object as the canonical read model.
+2. Make per-volume state first-class and more expressive than the current `ground_truth / needs_proofreading / missing_segmentation` labels.
+3. Replace fragmented assistant actions with one typed `WorkflowActionProposal` envelope.
+4. Require approval for mutating, expensive, editor-launching, export, and runtime actions.
+5. Log every proposal, approval/rejection, execution attempt, artifact mutation, status transition, and evidence basis.
+6. Add deterministic invalidation and reinspection rules so the agent knows when memory is fresh enough.
+7. Move onboarding from a blank text box to inspect-first guided context elicitation.
+
+This direction is backed by mixed-initiative UI principles: automation should add real value, ask at the right time, expose uncertainty, and leave users in control. Horvitz's mixed-initiative work warns about poor guesses, poor timing, and inadequate user steering; Amershi et al.'s Human-AI Interaction Guidelines emphasize clear system capability, timely updates, efficient correction, and graceful recovery; interactive ML work argues that end-users must participate throughout training and refinement, not merely label data once. In biomedical image analysis, ilastik demonstrates guided interactive learning for non-ML experts, CellProfiler demonstrates modular reproducible pipelines for biologists, OME-Zarr and REMBI show that metadata is not optional, and CAVE / WEBKNOSSOS / VAST show that proofreading and annotation need versioned, queryable state rather than ad hoc edits.
+
+The strongest paper claim is not that the assistant improves segmentation accuracy. The defensible claim is that it improves **workflow coordination** across inspection, volume triage, proofreading, training, inference, evaluation, and evidence capture by making state, proposals, approvals, and provenance explicit.
+
+## 2. Current Prototype Diagnosis
+
+### What exists now
+
+Backend:
+
+- `server_api/workflows/db_models.py` defines useful workflow tables: `WorkflowSession`, `WorkflowEvent`, `WorkflowCommand`, `WorkflowArtifact`, `WorkflowVolumeState`, `WorkflowModelRun`, `WorkflowModelVersion`, `WorkflowCorrectionSet`, `WorkflowEvaluationResult`, `WorkflowRegionHotspot`, `WorkflowAgentPlan`, and `WorkflowAgentStep`.
+- `server_api/workflows/router.py` exposes workflow detail, project progress, volume state, overview, recommendations, agent query, proposal approval/rejection, plan approval, evidence export, and evaluation endpoints.
+- `_observe_workflow_project()` scans mounted roots using `_scan_project_profile()` and persists a compact `metadata_json.project_observation`.
+- `_build_workflow_project_progress()` derives volume rows, writes `metadata_json.project_progress_snapshot`, and syncs `WorkflowVolumeState`.
+- `_requires_action_approval()` and `_infer_action_risk()` already classify actions into read-only, form-prefill, editor, runtime, workflow-record, workspace, and export risk classes.
+- `bundle_export.py` exports events, artifacts, model runs, model versions, correction sets, evaluations, hotspots, volume states, agent plans, and discovered paths.
+
+Frontend:
+
+- `client/src/components/Chatbot.js` routes workflow-like messages to the workflow agent, renders assistant action cards, command cards, proposal cards, traces, and sanitizes stale workflow cards.
+- `client/src/contexts/WorkflowContext.js` centralizes workflow refreshes, action effects, proposal approval, evidence refresh, progress refresh, and runtime handoff.
+- `client/src/views/ProjectProgress.js` provides the current volume tracker and manual status updates.
+- Files, Visualize, Train Model, Run Model, Proofread, and Progress are already recognizable workflow stages.
+
+### Where it is strong
+
+- It has an approval-gated path for significant proposals.
+- It has an append-only event model and typed artifact/run/correction/evaluation tables.
+- It can inspect mounted project roots and parse `project_manifest.json`.
+- It can derive volume-level progress for the MitoEM2 and TapeReader fixtures.
+- It has started separating visible chat from traces/action cards.
+- It has durable command records for approved training, which is the right direction for long-running work.
+- It already avoids arbitrary shell execution as the primary assistant execution model.
+
+### Where it is brittle
+
+- **No canonical memory contract.** Project facts live in multiple mutable places: workflow columns, `metadata_json.project_context`, `project_observation`, `project_progress_snapshot`, persisted `WorkflowVolumeState`, mounted file records, and UI state.
+- **Progress terms are too coarse and inconsistent.** Backend uses `ground_truth`, `needs_proofreading`, `missing_segmentation`, `ignored`; the target model needs `image_only`, `draft_segmentation`, `proofread_ground_truth`, `queued_for_inference`, `prediction_ready`, etc.
+- **Action semantics are split.** There are `AgentChatAction`, `AgentCommandBlock`, `agent.proposal_created` events, `WorkflowCommand`, direct client effects, and runtime actions. The user sees cards, but engineering has several execution paths.
+- **Freshness is implicit.** `_observe_workflow_project()` records `observed_at`, and progress records `generated_at`, but there is no shared invalidation policy or "fresh enough for this answer" test.
+- **The semantic router is heuristic plus optional local LLM classification.** It is useful, but the prompt and routing code are a large handwritten policy surface that can drift from action preconditions.
+- **Training and inference still select from paths/forms, not a canonical volume set.** This makes it easy to accidentally train on draft masks or forget image-only targets.
+- **Approval records do not always produce complete provenance.** Approval is logged, but cards need to record the evidence basis, selected volumes, expected outputs, user-visible risks, command id, resulting artifacts, and postcondition checks.
+- **Onboarding still depends too much on chat.** The scanner finds useful facts, but the first-run experience should be a guided correction form backed by detected facts.
+
+### Fix first
+
+1. Define `ProjectMemory` and populate it from existing tables/scans.
+2. Make `WorkflowVolumeState` the canonical volume state source, with derived scans only proposing updates.
+3. Introduce one `WorkflowActionProposal` schema and map existing cards to it.
+4. Add invalidation rules and visible freshness markers.
+5. Make Progress row actions drive Train/Run/Proofread selections.
+
+## 3. Literature-Backed Design Principles
+
+| Principle                                                 | Evidence                                                                                                                                                                                                                                                                                                                                                                                                                         | App Implication                                                                                                                                                              | Priority |
+| --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
+| Use mixed initiative, not hidden autonomy                 | Horvitz identifies common agent failures: poor goal guesses, poor timing, weak user guidance, and weak recovery; effective systems combine direct manipulation and automated services. [Horvitz 1999](https://www.microsoft.com/en-us/research/wp-content/uploads/2016/11/chi99horvitz.pdf)                                                                                                                                      | The assistant proposes bounded actions and asks for approval when cost or mutation matters. Users can edit facts and reject proposals.                                       | High     |
+| Show capabilities, uncertainty, and recovery              | Amershi et al. organize Human-AI Interaction Guidelines around initial expectations, interaction, errors, and long-term adaptation. [Amershi et al. 2019](https://www.microsoft.com/en-us/research/publication/guidelines-for-human-ai-interaction/)                                                                                                                                                                             | Each answer should include one concrete next move, uncertainty when facts are inferred, and correction controls for wrong project facts.                                     | High     |
+| Keep humans inside the learning loop                      | Interactive ML research argues end-users shape systems through iterative interaction, not just one-time labeling. [Amershi et al. 2014](https://ojs.aaai.org/aimagazine/index.php/aimagazine/article/view/2513/0)                                                                                                                                                                                                                | Proofreading, promotion to ground truth, retraining, and evaluation should be explicit loop stages with visible evidence.                                                    | High     |
+| Ask concrete questions instead of blank prompts           | Mixed-initiative and HAI guidelines both favor timely, bounded clarification over vague handoff.                                                                                                                                                                                                                                                                                                                                 | First-run intake should display detected facts and ask short editable questions: modality, target, label type, voxel size, which masks are trusted.                          | High     |
+| Reproducible workflows need durable provenance            | W3C PROV models entities, activities, agents, and derivation. [PROV-DM](https://www.w3.org/TR/prov-dm/); CWLProv distinguishes prospective and retrospective provenance. [CWLProv review](https://academic.oup.com/gigascience/article/doi/10.1093/gigascience/giz095/5611001)                                                                                                                                                   | Use an append-only evidence ledger for observations, proposals, approvals, executions, artifacts, metrics, and status transitions.                                           | High     |
+| Bioimage data needs metadata, not just files              | REMBI recommends metadata sufficient for reuse of biological images. [REMBI](https://www.nature.com/articles/s41592-021-01166-8); OME-Zarr stores scalable image arrays with multiscale metadata. [OME-Zarr paper](https://pmc.ncbi.nlm.nih.gov/articles/PMC9980008/) and [spec](https://ngff.openmicroscopy.org/0.5/index.html)                                                                                                 | Project memory should store modality, voxel size, axes, dtype, shape, channel/label semantics, and metadata source/confidence.                                               | High     |
+| Biologists adopt guided workflow tools                    | ilastik emphasizes interactive labeling and immediate feedback for non-ML experts. [ilastik](https://www.ilastik.org/); CellProfiler emphasizes modular reproducible pipelines designed for biologists. [CellProfiler 3.0](https://pmc.ncbi.nlm.nih.gov/articles/PMC6029841/)                                                                                                                                                    | The assistant should feel like guided workflow software, not a command-line agent in a chat drawer.                                                                          | High     |
+| Proofreading is stateful and versioned                    | CAVE supports reproducible analysis while proofreading changes segmentation state. [CAVE](https://pmc.ncbi.nlm.nih.gov/articles/PMC12074985/); WEBKNOSSOS supports merge/split and voxel relabeling workflows. [WEBKNOSSOS](https://docs.webknossos.org/webknossos/proofreading/index.html); VAST targets large-volume annotation and segmentation editing. [VAST](https://pmc.ncbi.nlm.nih.gov/articles/PMC6198149/)            | Proofread masks should become versioned correction artifacts with edited regions, source masks, and promotion decisions.                                                     | High     |
+| Agentic coding patterns transfer only as control patterns | Codex and Claude Code-style tools inspect project context, plan, call typed tools, require approvals, and preserve traces. [Codex help](https://help.openai.com/en/articles/11096431), [Claude Code subagents](https://code.claude.com/docs/en/sub-agents), [GitHub Copilot coding agent](https://github.blog/developer-skills/github/less-todo-more-done-the-difference-between-coding-agent-and-agent-mode-in-github-copilot/) | Transfer inspect-plan-act, typed tools, approval gates, traces, and resumability. Do not transfer arbitrary shell execution or code-diff metaphors as the main user surface. | Medium   |
+| Experiment tracking needs lineage and versioning          | MLflow model registry tracks model lineage and stage transitions. [MLflow](https://mlflow.org/docs/2.4.1/model-registry.html); DVC emphasizes data, code, params, metrics, and artifacts for reproducibility. [DVC](https://dvc.org/doc/use-cases/experiment-tracking)                                                                                                                                                           | Training/inference/evaluation records should capture configs, inputs, outputs, checkpoints, metrics, code/library versions when available, and data membership.              | Medium   |
+
+## 4. Proposed Agent Architecture
+
+```mermaid
+flowchart TD
+  U[User] --> Chat[Assistant chat surface]
+  U --> App[Workflow UI: Files / Visualize / Train / Run / Proofread / Progress]
+
+  FS[Mounted project filesystem] --> Inspector[Project inspector]
+  Manifest[project_manifest.json / configs / metadata] --> Inspector
+  Runtime[Training, inference, proofreading events] --> Evidence[Evidence ledger]
+  App --> Evidence
+
+  Inspector --> Memory[Canonical ProjectMemory]
+  Evidence --> Memory
+  VolumeDB[WorkflowVolumeState table] --> Memory
+  Artifacts[Artifacts, runs, corrections, evaluations] --> Memory
+
+  Memory --> Retrieval[Context builder and freshness policy]
+  Retrieval --> Assistant[Assistant response layer]
+  Retrieval --> ProposalGen[Action proposal generator]
+
+  Assistant --> Chat
+  ProposalGen --> Policy[Approval policy]
+  Policy --> Cards[Action cards]
+  Cards --> U
+  U --> Approval[Approve / reject / edit]
+  Approval --> Evidence
+  Approval --> Executor[Bounded workflow executor]
+  Executor --> App
+  Executor --> Jobs[Durable workflow commands / jobs]
+  Jobs --> Evidence
+  Evidence --> Invalidate[Invalidation and reinspection loop]
+  Invalidate --> Inspector
+```
+
+### Components
+
+- **Project inspector:** read-only scanner for mounted roots, manifests, configs, dimensions, dtypes, axes, voxel sizes, checkpoints, predictions, logs, metrics, and proofreading exports.
+- **Project memory:** normalized read model assembled from tables and scans. It is the source of truth for assistant answers.
+- **Retrieval/context layer:** selects only facts relevant to the user query and records freshness. It should never dump raw JSON into chat.
+- **Assistant response layer:** writes short, normal answers with one next move and uncertainty when needed.
+- **Trace/evidence layer:** expandable "What I checked" records: scan time, paths, manifest fields, volume counts, status evidence, blockers.
+- **Action proposal generator:** emits typed cards with scope, affected volumes, inputs, outputs, risk/cost, evidence basis, preconditions, and postconditions.
+- **Approval policy:** read-only navigation can run directly; editor, mutating, export, stop, train, inference, and state transitions need approval.
+- **Bounded workflow executor:** calls app routines only: mount, view, prefill form, open proofread, start/stop training, start/stop inference, compute evaluation, export bundle, update volume status.
+- **Artifact/provenance ledger:** append-only event stream plus typed tables for artifacts, runs, correction sets, model versions, evaluations, and volume transitions.
+- **Invalidation loop:** file changes, status edits, job events, proofread saves, app resume, and freshness-sensitive queries mark memory stale and trigger targeted reinspection.
+
+## 5. Project Memory Schema
+
+```json
+{
+  "schema_version": "seg-workflow-project-memory/v1",
+  "project": {
+    "workflow_id": 123,
+    "title": "Yixiao TapeReader XRI Case Study",
+    "roots": [
+      {
+        "path": "/home/weidf/demo_data/yixiao_tapereader_xri_case_study",
+        "mounted_root_id": 7,
+        "source": "mounted_files",
+        "last_scanned_at": "2026-05-27T..."
+      }
+    ],
+    "dataset_family": "TapeReader / PT37_round2",
+    "task_family": "xri_fibre_instance_segmentation",
+    "imaging_modality": {
+      "value": "X-ray / XRI volumetric microscopy",
+      "source": "project_manifest.json",
+      "confirmed_by_user": false
+    },
+    "target_structure": {
+      "value": "CytoTape fibres",
+      "source": "project_manifest.json",
+      "confirmed_by_user": false
+    },
+    "voxel_size_zyx_nm": {
+      "value": [40, 16.3, 16.3],
+      "source": "project_manifest.json",
+      "confirmed_by_user": false
+    },
+    "label_semantics": {
+      "kind": "instance_labels",
+      "background_value": 0,
+      "partial_annotation_policy": "unknown"
+    }
+  },
+  "task_preset": {
+    "id": "xri_tapereader_fibre",
+    "expected_inputs": ["raw_volume", "instance_mask", "pytc_config"],
+    "expected_outputs": [
+      "prediction_mask",
+      "correction_set",
+      "trained_checkpoint"
+    ],
+    "evaluation_metrics": [
+      "instance_count_delta",
+      "mask_iou",
+      "object_precision_recall"
+    ],
+    "safe_defaults_profile": "app_compatible_sanity"
+  },
+  "volumes": [
+    {
+      "volume_id": "5_1",
+      "name": "PT37_round2_5_1",
+      "image_path": "data/raw/5_1/5_1-xri-raw.tif",
+      "label_path": "data/seg/5_1/5_1-mask.tif",
+      "prediction_path": null,
+      "corrected_mask_path": null,
+      "status": "needs_proofreading",
+      "status_source": "project_manifest",
+      "status_confidence": 1.0,
+      "eligible_for_training": false,
+      "eligible_for_inference": false,
+      "shape_zyx": [40, 500, 500],
+      "dtype": { "image": "uint16", "label": "int64" },
+      "label_stats": { "instance_label_count": 134 },
+      "regions": [
+        {
+          "region_id": "bbox:z0-39_y0-499_x0-499",
+          "proofreading_status": "unreviewed",
+          "valid_mask_path": null
+        }
+      ],
+      "last_verified_at": "2026-05-27T...",
+      "evidence_event_ids": [501, 502]
+    }
+  ],
+  "artifact_index": [
+    {
+      "artifact_id": 21,
+      "type": "config",
+      "role": "app_compatible_training_config",
+      "path": "configs/TapeReader-Fiber-BCS-AppCompat-Sanity.yaml",
+      "checksum": "sha256:...",
+      "exists": true,
+      "source_event_id": 77
+    }
+  ],
+  "run_history": [
+    {
+      "run_id": "train-20260527-001",
+      "type": "training",
+      "status": "completed",
+      "input_volume_ids": ["1", "2", "3", "4_1", "4_2", "4_3"],
+      "config_artifact_id": 21,
+      "output_artifact_ids": [31],
+      "checkpoint_artifact_id": 32,
+      "metrics": {},
+      "started_at": "...",
+      "completed_at": "..."
+    }
+  ],
+  "proofreading_history": [
+    {
+      "correction_set_id": 9,
+      "source_volume_id": "5_1",
+      "source_mask_path": "data/seg/5_1/5_1-mask.tif",
+      "corrected_mask_path": "outputs/corrections/5_1-corrected.tif",
+      "edit_count": 14,
+      "region_count": 3,
+      "promoted_to_ground_truth": false,
+      "source_event_id": 184
+    }
+  ],
+  "evaluation_history": [
+    {
+      "evaluation_id": 4,
+      "baseline_run_id": 12,
+      "candidate_run_id": 15,
+      "reference_artifact_id": 40,
+      "metrics": { "mask_iou": 0.81 },
+      "report_path": "outputs/evaluation/report.json"
+    }
+  ],
+  "user_confirmations": [
+    {
+      "field": "training_policy",
+      "value": "train only on proofread_ground_truth",
+      "confirmed_by": "user",
+      "event_id": 210,
+      "confirmed_at": "..."
+    }
+  ],
+  "evidence_events": [
+    {
+      "event_id": 501,
+      "event_type": "project.observed",
+      "actor": "system",
+      "summary": "Read project manifest and found 10 tracked XRI volumes.",
+      "created_at": "..."
+    }
+  ],
+  "freshness": {
+    "project_tree": {
+      "state": "fresh",
+      "observed_at": "...",
+      "invalidated_by": null
+    },
+    "volume_states": { "state": "fresh", "observed_at": "..." },
+    "runtime": { "state": "stale", "reason": "training job completed" },
+    "assistant_context": {
+      "built_at": "...",
+      "source_event_high_watermark": 501
+    }
+  }
+}
+```
+
+## 6. Volume And Workflow State Machine
+
+Use the following canonical states. Keep legacy labels as aliases during migration:
+
+| Canonical state          | Meaning                                                                   | Legacy alias           |
+| ------------------------ | ------------------------------------------------------------------------- | ---------------------- |
+| `image_only`             | Image exists; no usable label/prediction registered.                      | `missing_segmentation` |
+| `draft_segmentation`     | Segmentation exists but trust status is unknown or imported from a model. | none                   |
+| `needs_proofreading`     | Draft or prediction is explicitly queued for human review.                | `needs_proofreading`   |
+| `proofread_ground_truth` | Human-confirmed training/evaluation reference.                            | `ground_truth`         |
+| `training_candidate`     | Selected for a training run but not necessarily all project ground truth. | none                   |
+| `queued_for_inference`   | Selected target for inference.                                            | none                   |
+| `prediction_ready`       | Inference output exists and can be viewed/proofread/evaluated.            | none                   |
+| `ignored`                | Intentionally excluded.                                                   | `ignored`              |
+
+### Transition policy
+
+| From                     | To                       | Actor                  | Evidence required                                    | Approval                                   |
+| ------------------------ | ------------------------ | ---------------------- | ---------------------------------------------------- | ------------------------------------------ |
+| unknown                  | `image_only`             | inspector              | readable image artifact, no matching mask/prediction | no                                         |
+| unknown                  | `draft_segmentation`     | inspector              | image plus mask/prediction, source not confirmed     | no                                         |
+| unknown                  | `proofread_ground_truth` | manifest/importer/user | manifest status, path marker, or user confirmation   | user confirmation recommended              |
+| `draft_segmentation`     | `needs_proofreading`     | agent/user             | draft mask path and image path                       | no if just queueing; yes if writing status |
+| `needs_proofreading`     | `proofread_ground_truth` | user                   | saved correction set or explicit "mark fully good"   | yes                                        |
+| `image_only`             | `queued_for_inference`   | user/agent             | selected image, checkpoint/config readiness          | yes                                        |
+| `queued_for_inference`   | `prediction_ready`       | executor               | completed inference run and output artifact          | no, system postcondition                   |
+| `prediction_ready`       | `needs_proofreading`     | agent/user             | prediction artifact exists                           | no if queueing; yes if writing status      |
+| `proofread_ground_truth` | `training_candidate`     | agent/user             | selected training set, config, training policy       | yes                                        |
+| any                      | `ignored`                | user                   | explicit user exclusion reason                       | yes                                        |
+| `ignored`                | previous state           | user                   | undo event or selected new status                    | yes                                        |
+
+Partial proofreading should be represented as region-level state, not by pretending the whole volume is fully good. Add `volume_regions` or metadata entries with `bbox_zyx`, `valid_mask_path`, `proofreading_status`, `reviewer`, `source_event_id`, and `promoted_at`. Training eligibility for partially proofread volumes requires a valid mask or an explicit region list.
+
+## 7. Action Card Specification
+
+All cards should use one envelope:
+
+```json
+{
+  "proposal_id": "uuid",
+  "action_type": "start_training",
+  "plain_language_summary": "Train on 6 confirmed XRI fibre masks.",
+  "affected_volume_ids": ["1", "2", "3", "4_1", "4_2", "4_3"],
+  "inputs": [
+    {
+      "role": "config",
+      "path": "configs/TapeReader-Fiber-BCS-AppCompat-Sanity.yaml"
+    }
+  ],
+  "outputs": [{ "role": "checkpoint", "planned_path": "outputs/training/..." }],
+  "risk_level": "runs_job",
+  "requires_approval": true,
+  "estimated_duration": "unknown",
+  "cost_notes": ["uses GPU if available", "writes training outputs"],
+  "preconditions": [{ "id": "training_set", "status": "passed" }],
+  "evidence_basis": [{ "event_id": 501, "label": "manifest volume split" }],
+  "review_details": { "config_diff": null, "selected_volume_count": 6 },
+  "on_approve": { "executor": "workflow.start_training" },
+  "on_reject": { "write_event": "agent.proposal_rejected" },
+  "postconditions": [
+    "model_run row",
+    "checkpoint artifact",
+    "training completed/failed event"
+  ]
+}
+```
+
+Required card types:
+
+| Type                       | Required fields                                                                                       | Approval behavior                                                   |
+| -------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
+| `visualize_data`           | image path, optional label/prediction path, voxel scale, source volume                                | no approval unless it changes saved project state                   |
+| `choose_change_data`       | proposed image/label/config paths, source evidence, fields to change                                  | approval if it writes workflow memory; no approval for form prefill |
+| `open_progress`            | summary counts, stale/fresh marker                                                                    | no approval                                                         |
+| `start_training`           | training volumes, excluded volumes, config, labels/corrections, output/log paths, expected checkpoint | approval required                                                   |
+| `start_inference`          | target volumes, checkpoint, config, output registration plan                                          | approval required                                                   |
+| `queue_proofreading`       | volumes, masks/predictions, priority/evidence                                                         | approval if status is written; no approval for opening view         |
+| `mark_volume_status`       | old/new state, volume ids, reason, reversibility                                                      | approval required                                                   |
+| `export_corrected_masks`   | source session, output path, selected volumes/regions                                                 | approval required                                                   |
+| `evaluate_compare_results` | baseline, candidate, reference, metrics, report path                                                  | approval required if it writes metrics/artifacts                    |
+| `export_evidence_bundle`   | included tables/artifacts, copy limit, output path                                                    | approval required                                                   |
+
+Cards should show a short summary and compact affected-volume list. Long paths, full volume arrays, config snippets, and logs belong behind "Review details." Every approval/rejection/execution must write a workflow event.
+
+## 8. Guided Context Elicitation
+
+After mounting a project:
+
+1. Inspect project tree, manifest, configs, checkpoints, image/mask/prediction roles, and basic metadata.
+2. Show detected facts as editable rows: project title, modality, target structure, voxel size, label type, volume count, trusted masks, draft masks, image-only targets, candidate config.
+3. Ask only concrete unresolved questions.
+4. Persist corrections into project memory as user confirmations.
+5. Generate first recommended actions from the resulting memory.
+
+Example first-run questions:
+
+- "I found 10 XRI volumes: 6 marked ground truth, 2 draft masks, 2 image-only. Is that split correct?"
+- "Are masks in `data/seg` instance labels, binary masks, affinities, or something else?"
+- "Should training use only confirmed/proofread masks?"
+- "Voxel size appears to be z,y,x = 40,16.3,16.3 nm. Confirm or edit?"
+
+Workflow-family prompts:
+
+| Family                             | Ask                                                                                                                              |
+| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| mitochondria semantic segmentation | target class, binary/semantic label convention, voxel size, trusted labels, expected metric such as Dice/IoU                     |
+| mitochondria instance segmentation | instance id semantics, touching-object handling, AP/object metrics, proofread versus draft masks                                 |
+| XRI fibre / TapeReader             | paper-faithful config versus app-compatible config, instance mask semantics, preprocessing/tiled CLAHE status, inference targets |
+| affinity-heavy neuron segmentation | affinity target axes, watershed/agglomeration outputs, valid masks/partial labels, split/merge proofreading policy               |
+| synapse/cleft segmentation         | cleft versus pre/post labels, class imbalance strategy, evaluation reference, region-level review                                |
+
+Voice input should map to the same bounded questions and cards. Corrections should be stored as `user_confirmations`, not just chat text.
+
+## 9. Case Study-Specific Requirements
+
+### Case 1: MitoEM2-style progress workflow
+
+Local fixture: `/home/weidf/demo_data/mitoem2_progress_demo`.
+
+Expected initial state from `project_manifest.json`:
+
+- 6 HDF5 smoke volumes.
+- 2 `ground_truth` / `proofread_ground_truth`.
+- 2 `needs_proofreading`.
+- 2 `missing_segmentation` / `image_only`.
+- Voxel size z,y,x = 30,8,8 nm.
+- Config: `configs/MitoEM2-Pyra-Demo-BC.yaml`.
+
+Agent requirements:
+
+- Know that curated masks can train.
+- Know draft masks must not silently train.
+- Propose proofreading for the two draft volumes.
+- Propose inference for the two image-only targets after a checkpoint exists.
+- Use MitoEM/MitoEM2 literature to explain complex 3D mitochondria instance segmentation and object-level evaluation, without claiming this smoke fixture is the full benchmark. MitoEM introduced a large-scale 3D mitochondria instance dataset and AP-style evaluation for complex mitochondria. [MitoEM](https://pmc.ncbi.nlm.nih.gov/articles/PMC7713709/). MitoEM2.0 expands challenging 3D mitochondria instance segmentation settings. [MitoEM2.0](https://pmc.ncbi.nlm.nih.gov/articles/PMC12927526/).
+
+Paper evidence:
+
+- Volume-state transition timeline.
+- Training-set membership from confirmed masks.
+- Proofreading promotion events.
+- Inference target selection and output registration.
+
+### Case 2: Yixiao / TapeReader XRI fibre workflow
+
+Local fixture: `/home/weidf/demo_data/yixiao_tapereader_xri_case_study`.
+
+Expected initial state:
+
+- 10 tracked XRI volumes.
+- 6 confirmed ground-truth masks: `1`, `2`, `3`, `4_1`, `4_2`, `4_3`.
+- 2 draft masks needing proofreading: `5_1`, `5_2`.
+- 2 image-only inference targets: `6_1`, `6_2`.
+- Voxel size z,y,x = 40,16.3,16.3 nm.
+- App-compatible config: `configs/TapeReader-Fiber-BCS-AppCompat-Sanity.yaml`.
+- Paper-faithful config: `configs/TapeReader-Fiber-BCS-Original-Barcode.yaml`.
+- Reference pipeline: [TapeReader](https://github.com/LinghuLab/TapeReader), preprint DOI [10.1101/2025.05.10.653182](https://www.biorxiv.org/content/10.1101/2025.05.10.653182v1).
+
+Agent requirements:
+
+- Preserve distinction between paper-faithful TapeReader semantics and current PyTC app-compatible fallback.
+- Train only on the 6 confirmed masks unless the user explicitly promotes proofread drafts.
+- Queue `5_1` and `5_2` for proofreading.
+- Queue `6_1` and `6_2` for inference after a model is available.
+- Explain what it has inspected: manifest, active paths, config choice, volume split, voxel size.
+
+Paper evidence:
+
+- Demonstrates non-EM, non-mitochondria workflow adaptation.
+- Shows project-memory value because the training set is not simply "all masks in folder."
+- Shows why domain-specific presets matter.
+
+### Case 3 recommendation: CREMI affinity-heavy neuron segmentation
+
+Recommend **CREMI-style affinity-heavy neuron segmentation** as the third paper case, with a smaller local fixture for reliability. Lucchi++ is useful as an onboarding demo, but it overlaps too much with the mitochondria story. CREMI stresses different agent capabilities:
+
+- affinity labels rather than simple binary/instance masks;
+- partial annotations and valid-mask supervision;
+- split/merge proofreading semantics;
+- anisotropic volume metadata;
+- evaluation that depends on connectomics-style topology, not just pixel IoU;
+- need to distinguish raw image, affinity prediction, watershed/agglomeration, and proofread segmentation artifacts.
+
+This case lets the paper show that the assistant is a workflow formalization layer, not a filename heuristic for masks. It also connects to PyTorch Connectomics' broader scope: EM connectomics, semantic and instance segmentation, multi-task and semi-supervised learning. [PyTorch Connectomics docs](https://connectomics.readthedocs.io/) and [paper](https://arxiv.org/abs/2112.05754).
+
+Minimum fixture:
+
+- 3 to 5 small CREMI/SNEMI-like HDF5 or Zarr volumes.
+- At least one confirmed ground-truth/valid-mask region.
+- One predicted affinity/segmentation output needing split/merge proofreading.
+- One image-only target.
+- Config with affinity outputs and valid-mask support.
+
+Agent behaviors it exercises:
+
+- asks label-semantics questions;
+- blocks training when valid masks are missing for partial labels;
+- explains that `prediction_ready` may be affinities plus postprocessed segmentation;
+- proposes split/merge proofreading instead of generic mask painting;
+- records region-level proofreading and valid-mask provenance.
+
+## 10. Evaluation Plan For The Paper
+
+Participant profile:
+
+- 8 to 12 biomedical image analysts, connectomics researchers, or biologists with segmentation experience.
+- Include both PyTC-experienced and PyTC-naive users if possible.
+
+Study design:
+
+- Within-subject comparison between current manual UI workflow and workflow-assistant condition, or between baseline assistant and formalized project-memory/action-card assistant.
+- Use MitoEM2 and TapeReader tasks; reserve CREMI-style task for transfer/generalization if the fixture is stable.
+
+Tasks:
+
+1. Mount an unfamiliar project and identify usable training masks.
+2. Open a draft segmentation for review.
+3. Mark/proofread/promote a corrected mask.
+4. Configure training from confirmed masks only.
+5. Run or stage inference on image-only volumes.
+6. Compute or inspect before/after evidence.
+7. Export an evidence bundle.
+
+Data to log:
+
+- time to correct project understanding;
+- number of wrong volume-status decisions;
+- number of manual path selections;
+- proposal approval/rejection rate;
+- cards edited before approval;
+- recovery from wrong assistant suggestion;
+- event completeness: inputs, outputs, artifacts, config, selected volumes;
+- subjective NASA-TLX or lightweight workload rating;
+- interview-coded themes: trust, orientation, controllability, scientific confidence.
+
+Success criteria:
+
+- Users can correctly identify training/proofreading/inference sets faster or with fewer errors.
+- Users understand why an action is proposed and what it will affect.
+- Evidence bundles reconstruct the workflow without relying on chat memory.
+- Users can correct wrong auto-detected facts and see those corrections persist.
+
+Defensible claims:
+
+- Improves coordination and visibility in iterative segmentation workflows.
+- Reduces manual translation between file organization, UI forms, and workflow stages.
+- Provides approval-gated bounded routines with provenance.
+- Supports paper-grade reconstruction of workflow decisions.
+
+Claims to avoid without stronger evidence:
+
+- Improves biological segmentation accuracy.
+- Fully automates expert proofreading.
+- Generalizes to all microscopy modalities.
+- Guarantees scientific validity.
+- Safely runs arbitrary pipelines.
+
+## 11. Engineering Roadmap
+
+### Immediate fixes
+
+| Item                                      | User value                       | Backend                                                                           | Frontend                                 | Verification                                   | Paper relevance        |
+| ----------------------------------------- | -------------------------------- | --------------------------------------------------------------------------------- | ---------------------------------------- | ---------------------------------------------- | ---------------------- |
+| Add `ProjectMemory` read endpoint         | assistant answers from one state | compose workflow, events, volume states, artifacts, runs, observations, freshness | show memory/debug panel and trace source | unit tests with MitoEM2/TapeReader manifests   | core architecture      |
+| Migrate volume states to canonical labels | avoids training on drafts        | add aliases/migration from `ground_truth`/`missing_segmentation`                  | update Progress labels and filters       | fixture tests for 2/2/2 and 6/2/2 splits       | case-study correctness |
+| One action proposal envelope              | simpler approval model           | add `workflow_action_proposals` or typed event payload schema                     | render one card component by type        | tests for approve/reject/execution event chain | HAI/provenance claim   |
+| Freshness policy                          | fewer stale answers              | add invalidation markers for scan, progress, runtime, proofreading                | show stale badge and refresh action      | tests for job complete/edit save/app resume    | credibility            |
+| Guided intake from detected facts         | less blank-page anxiety          | expose detected facts and confirmation writes                                     | first-run checklist/editor               | Cypress/manual demo script                     | user study task        |
+
+### Paper-demo requirements
+
+| Item                               | User value                | Backend                                                   | Frontend                                 | Verification        | Paper relevance   |
+| ---------------------------------- | ------------------------- | --------------------------------------------------------- | ---------------------------------------- | ------------------- | ----------------- |
+| Training set from volume states    | correct data selection    | action preflight selects `proofread_ground_truth` only    | card shows included/excluded volumes     | fixture tests       | central demo      |
+| Inference queue from volume states | clear targets             | action preflight selects `image_only` or selected targets | Run Model shows target volume list       | fixture tests       | progress workflow |
+| Proofreading promotion             | trustworthy labels        | correction-set to status transition with approval         | Proofread/Progress "promote" action      | event/artifact test | HITL loop         |
+| Evidence bundle completeness check | reconstructable workflows | post-export validator                                     | export result card                       | bundle schema test  | paper artifact    |
+| TapeReader preset                  | domain-specific behavior  | preset metadata and config distinction                    | intake card and training/inference cards | fixture test        | second case       |
+
+### Production-quality requirements
+
+| Item                                    | User value                | Backend                                               | Frontend                   | Verification                | Paper relevance  |
+| --------------------------------------- | ------------------------- | ----------------------------------------------------- | -------------------------- | --------------------------- | ---------------- |
+| Durable job runner for train/infer      | reliable long jobs        | command leases, status polling, retries, cancellation | status near Train/Run tabs | integration tests           | robustness       |
+| Artifact checksums and dimension probes | reproducibility           | checksum/shape/dtype jobs                             | details disclosure         | sample HDF5/TIFF/Zarr tests | provenance       |
+| Region-level proofreading               | partial-label correctness | `WorkflowVolumeRegionState` or equivalent             | region queue UI            | proofread fixture           | CREMI case       |
+| Config/run manifest writer              | reproducible ML           | save exact config, data membership, environment hints | review details             | golden manifest tests       | scientific rigor |
+| Role-specific permission modes          | safer autonomy            | policy table in backend                               | card labels and settings   | approval tests              | mixed initiative |
+
+### Future/research extensions
+
+- viewer-derived observations or screenshots, explicitly marked as user/viewer-derived rather than filesystem truth;
+- active-learning queues based on uncertainty/hotspot metrics;
+- integration with OME-Zarr metadata and REMBI export templates;
+- collaboration/multi-user review state;
+- model registry aliases for accepted checkpoints;
+- CAVE/WEBKNOSSOS-style versioned segmentation backends for large connectomics datasets.
+
+## 12. Open Questions
+
+- What database shape should `ProjectMemory` take: materialized table, view endpoint, or versioned JSON snapshot plus normalized child tables?
+- Should `ProjectMemory` be persisted after every event or rebuilt on demand with cache invalidation?
+- What volume state vocabulary should be exposed to biologists versus stored internally?
+- What is the minimum reliable dimension/dtype probe set for HDF5, TIFF, NIfTI, N5, and OME-Zarr?
+- How should app-compatible PyTC configs represent multi-volume training without fragile symlink directories?
+- What proofread edit granularity is feasible in the current Proofread implementation: mask save count, instance decisions, voxel edits, or region bounding boxes?
+- Should the third paper case be CREMI now, or should CREMI be scoped as future work while Lucchi++ serves as the stable third demo?
+- What runtime environment metadata can be captured reliably on demo.seg.bio without overpromising reproducibility?
+- How much of the evidence bundle should copy artifacts versus record paths, checksums, and missing-file status?
+
+## Final Recommendation
+
+Build the assistant as a workflow-aware, approval-gated project operator. The central abstraction is not chat history; it is project memory plus action proposals. Chat is the conversational surface. Project memory is the source of truth. Action cards are the bridge from intent to bounded execution. Evidence events are the paper-grade provenance layer.
diff --git a/docs/research/claude-code-agent-patterns.md b/docs/research/claude-code-agent-patterns.md
new file mode 100644
index 00000000..7516f674
--- /dev/null
+++ b/docs/research/claude-code-agent-patterns.md
@@ -0,0 +1,130 @@
+# Claude Code Agent Pattern Pass
+
+Date: 2026-04-25
+
+This note records what is useful for PyTC Client from the Claude Code source
+inspection plus a quick literature/blog/documentation pass. The goal is not to
+clone a coding CLI. The goal is to borrow agent-system patterns that make the
+assistant a real biomedical segmentation workflow orchestrator.
+
+## Sources Reviewed
+
+- Local source inspection of `https://github.com/tanbiralam/claude-code/tree/main/src`.
+  Treat this repo as architectural inspiration only; do not copy large code or
+  user-facing strings.
+- Anthropic Claude Code overview: agentic tool can read, edit, run commands,
+  integrate tools, use MCP, customize instructions, run subagents, schedule
+  tasks, and work across surfaces.
+- Anthropic best practices: verify work, explore before plan before execution,
+  keep context small, use skills for reusable workflows, hooks for deterministic
+  checks, subagents for investigation, and permission allowlists/sandboxing for
+  safety.
+- Claude Code permissions docs: tools are tiered by risk; read-only actions need
+  no approval while shell/file-changing actions do, and modes such as `plan`,
+  `auto`, and `dontAsk` define execution boundaries.
+- Claude Code subagents docs and blog: use focused agents when a side task
+  would flood the main conversation; restrict their tools; return summaries
+  rather than raw logs; use hooks for lifecycle gates.
+- Jason Liu context-engineering note: slash commands keep recurring workflows
+  focused; subagents keep verbose side work out of the main context.
+- Liu et al. 2026 arXiv tech report on Claude Code design space: the simple
+  model-tool loop is only the center; the important system work lives in
+  permissions, compaction, extensibility, subagents, isolation, and append-only
+  session storage.
+
+## Source-Level Patterns Worth Copying
+
+1. Tool-first orchestration
+   - Claude Code models actions as typed tools with input/output schemas,
+     permission checks, concurrency rules, progress state, and result mapping.
+   - PyTC equivalent: every app action from chat should be typed as a workflow
+     action with risk metadata: navigation, form prefill, editor load, model
+     run, training run, metric computation, export, retraining proposal.
+
+2. Permission and risk are first-class data
+   - Claude Code separates read-only tools from risky tools and routes each
+     through a permission layer.
+   - PyTC equivalent: show whether an agent action is `view only`, `opens
+editor`, `runs job`, `writes record`, or `exports`; never hide the approval
+     boundary.
+
+3. Slash commands are compact workflow entrypoints
+   - Claude Code uses slash commands and skills for repeatable work.
+   - PyTC equivalent: support `/status`, `/infer`, `/proofread`, `/train`,
+     `/compare`, `/export`, and `/help` as deterministic workflow commands.
+
+4. Task/checklist substrate beats free-form progress prose
+   - Claude Code has task/todo tools and structured background task state.
+   - PyTC equivalent: the workflow agent should expose a machine-readable loop
+     checklist from readiness gates and record actions as workflow events.
+
+5. Ask structured questions when intent is ambiguous
+   - Claude Code has an `AskUserQuestion` tool with short labels and bounded
+     options.
+   - PyTC equivalent: vague prompts like "I wanna..." should offer 2-4 concrete
+     app actions, not a lecture or hidden prompt scaffolding.
+
+6. Context hygiene is a runtime feature, not just prompt discipline
+   - Claude Code has compaction, tool-result budgeting, summaries, and
+     subagents/forks to prevent context floods.
+   - PyTC equivalent: agent responses stay short; heavy evidence stays in the
+     evidence panel/bundle; raw paths and logs should be expandable details.
+
+7. Verification gates matter
+   - Claude Code’s verification-agent pattern is adversarial: run checks, do not
+     merely read code.
+   - PyTC equivalent: after model/proofread/train/evaluate steps, the app needs
+     acceptance checks over artifacts, metrics, and workflow events.
+
+## Immediate Prototype Changes From This Pass
+
+- Add workflow-agent response metadata: `intent`, `permission_mode`, and
+  structured `tasks`.
+- Add action/command risk metadata: `read_only`, `prefills_form`,
+  `loads_editor`, `runs_job`, `writes_workflow_record`, `exports_evidence`.
+- Keep command pseudo-code collapsed behind a `Route` disclosure so biologists
+  see the app action first, not implementation text.
+- Add deterministic slash aliases in the server and UI logging path:
+  `/status`, `/next`, `/help`, `/infer`, `/segment`, `/proofread`, `/train`,
+  `/compare`, `/metrics`, `/export`.
+
+## Next Agent-System Work
+
+- Add a real workflow task table or durable job table for long-running
+  inference/training instead of relying on transient runtime action state.
+- Add explicit approval modes: `ask`, `auto_read_only`, `plan_only`, and
+  `blocked`, mapped to the biomedical workflow rather than copied literally
+  from coding.
+- Add hooks/gates:
+  - Before training: require corrected mask path and correction-set record.
+  - Before evaluation: require baseline, candidate, and reference volumes.
+  - Before claiming improvement: require metrics and artifact lineage.
+  - Before export: verify bundle contains workflow events and key artifacts.
+- Add focused biomedical subagents only when they become real:
+  - `data-curator`: inspect mounted project and identify image/mask/checkpoint
+    roles.
+  - `model-runner`: prepare and launch inference/training jobs.
+  - `proofreading-triage`: rank likely failure regions and produce review queue.
+  - `evidence-auditor`: verify artifact lineage before paper figures/export.
+- Add context compaction for the assistant drawer: summarize old chat turns and
+  keep workflow state/event evidence as structured context.
+
+## Design Constraint For PyTC
+
+Claude Code’s user is a developer who can read commands. PyTC’s user is a
+biologist or biomedical-image researcher trying to complete a segmentation
+loop. Therefore the visible surface should say "Run model", "Proofread this
+data", "Use edits for training", and "Compare results"; command-like details
+belong behind a disclosure or in logs.
+
+## References
+
+- [Claude Code overview](https://code.claude.com/docs/en/overview)
+- [Claude Code best practices](https://code.claude.com/docs/en/best-practices)
+- [Claude Code permissions](https://code.claude.com/docs/en/permissions)
+- [Claude Code subagents](https://code.claude.com/docs/en/sub-agents)
+- [Claude Code hooks](https://code.claude.com/docs/en/hooks)
+- [Claude Code skills/slash commands](https://code.claude.com/docs/en/slash-commands)
+- [How and when to use subagents in Claude Code](https://claude.com/blog/subagents-in-claude-code)
+- [Slash Commands vs Subagents](https://jxnl.co/writing/2025/08/29/context-engineering-slash-commands-subagents/)
+- [Dive into Claude Code: The Design Space of Today's and Future AI Agent Systems](https://arxiv.org/abs/2604.14228)
diff --git a/docs/research/deep-research-agentic-bioimage-segmentation.md b/docs/research/deep-research-agentic-bioimage-segmentation.md
new file mode 100644
index 00000000..8cc511f0
--- /dev/null
+++ b/docs/research/deep-research-agentic-bioimage-segmentation.md
@@ -0,0 +1,308 @@
+# Deep Research Task: Agentic Bioimage Segmentation Workflow Assistant
+
+## Purpose
+
+Prepare a literature and systems review for an agentic workflow assistant inside PyTC Client / seg.bio. The goal is not to implement code. The goal is to gather high-quality context that can be fed back into an engineering agent to synthesize product, architecture, and paper-writing decisions.
+
+The research should answer: what should this app become, what prior work should it cite or learn from, and what implementation patterns are proven enough to borrow?
+
+## Project Context
+
+We are building an interactive client for biomedical/connectomics image segmentation workflows. The app wraps PyTorch Connectomics-style model training, inference, visualization, proofreading, evaluation, and project tracking behind a guided UI and a workflow-aware chat assistant.
+
+The current prototype is served at:
+
+- Demo: `https://demo.seg.bio`
+- Main app repository: `https://github.com/PytorchConnectomics/pytc-client`
+- Upstream PyTorch Connectomics repository: `https://github.com/PytorchConnectomics/pytorch_connectomics`
+
+Current local demo checkout:
+
+- `/home/weidf/deploy/pytc-client-demo2`
+
+The intended user is a biologist or neuroscience lab user who has volumetric microscopy data and needs to train, run, inspect, proofread, and evaluate segmentation models without being forced to understand every software/configuration detail upfront.
+
+## What The Prototype Currently Does
+
+The app has modules for:
+
+- Files: mount and inspect a project directory.
+- Visualize: open image and label volumes in Neuroglancer.
+- Train Model: configure and launch PyTorch Connectomics training.
+- Run Model: configure and launch inference.
+- Progress: track volume-level status across ground-truth, draft/unproofread segmentation, and missing segmentation.
+- Proofread: inspect and correct mask instances.
+- Assistant: chat with a workflow-aware agent that can propose direct app actions.
+
+The Monitor tab has been sunset for now; runtime status/log links should live with Train Model or Run Model.
+
+Recent project direction:
+
+- The assistant should feel like a normal helpful chatbot on the surface, not an internal planner.
+- Mechanical details should be available in expandable traces like “What I checked,” not front-loaded in every chat answer.
+- The agent should continually update its understanding of the mounted project by inspecting files, manifests, progress state, workflow metadata, and user corrections.
+- The initial project setup should not strand biologists in a blank text box. It should guide them through context with concrete questions and auto-detected facts.
+- The app should distinguish volumes that are:
+  - fully good ground truth,
+  - segmented but still needing proofreading,
+  - image-only with no segmentation yet,
+  - ignored or out of scope.
+- Training should be able to use multiple confirmed ground-truth volumes and then segment remaining image-only volumes.
+
+## Current Demo Project Content
+
+The active demo project is a MitoEM2.0-style progress fixture:
+
+- Local path: `/home/weidf/demo_data/mitoem2_progress_demo`
+- Title: `MitoEM2.0 Progress Demo`
+- Dataset family: MitoEM2.0 / ssSEM mitochondria segmentation.
+- Context currently used by the app:
+  - imaging modality: EM / ssSEM
+  - target structure: mitochondria
+  - preferred optimization: accuracy
+  - voxel size: roughly `30 x 8 x 8 nm` in z,y,x
+- Structure:
+  - `data/image/`: 6 image volumes
+  - `data/seg/`: 4 segmentation volumes
+  - `configs/MitoEM2-Pyra-Demo-BC.yaml`
+  - `project_manifest.json`
+  - `notes/`
+  - `snapshots/`
+- Initial progress state:
+  - 2 volumes are curated/ground-truth quality
+  - 2 volumes have draft segmentation needing proofreading
+  - 2 volumes have no segmentation yet
+
+The desired workflow is:
+
+1. Mount a project.
+2. App mechanically inspects what is present.
+3. User confirms biological/project context with minimal typing.
+4. User views/proofreads available labels.
+5. User marks good volumes as ground truth.
+6. Agent proposes training from ground-truth volumes.
+7. App trains/runs model on remaining image-only volumes.
+8. User reviews/proofreads new predictions.
+9. Progress tracker updates continuously.
+
+## Repositories And Artifacts To Inspect
+
+### Primary repositories
+
+- `https://github.com/PytorchConnectomics/pytc-client`
+  - Look for: workflow agent implementation, project mounting, Neuroglancer integration, progress tracker, proofreading UI, training/inference orchestration, evidence logs.
+- `https://github.com/PytorchConnectomics/pytorch_connectomics`
+  - Look for: training/inference config patterns, supported datasets, metrics, model tasks, docs/tutorials, current v2 direction.
+
+### Relevant docs in this repo
+
+Inspect these first if available:
+
+- `docs/agent-role-spec.md`
+- `docs/prototype-completion-roadmap.md`
+- `docs/research/pytc-prepilot-dataset-stress-test.md`
+- `docs/research/tochi-hci-prototype-takeaways.md`
+- `docs/research/claude-code-agent-patterns.md`
+- `docs/codex-working-memory/research-log.md`
+- `docs/codex-working-memory/progress-log.md`
+- `docs/codex-working-memory/workflow-spine-spec.md`
+
+### Dataset/reference ecosystems to inspect
+
+- MitoEM and MitoEM2.0:
+  - Hugging Face datasets under `pytc/MitoEM` and `pytc/MitoEM2.0`
+  - PyTorch Connectomics configs/tutorials for mitochondria segmentation
+- Lucchi / Lucchi++:
+  - classic mitochondria EM segmentation benchmark
+  - PyTC tutorial datasets/configs
+- SNEMI3D:
+  - neuron segmentation benchmark
+  - affinity output and postprocessing patterns
+- CREMI:
+  - synaptic cleft/neuron/synapse benchmark
+  - multi-volume HDF5 workflows
+- NucMM:
+  - nuclei segmentation across mouse/zebrafish
+  - tests project generality beyond mitochondria/connectomics
+
+## Core Research Questions
+
+### 1. Human-agent interaction for scientific workflows
+
+Find literature on:
+
+- agentic interfaces for domain experts,
+- human-in-the-loop scientific workflows,
+- mixed-initiative systems,
+- LLM agents for data analysis or laboratory work,
+- how to expose agent reasoning without overwhelming users,
+- how to avoid “blank page” onboarding for nontechnical experts.
+
+Specific angle: how should a system elicit project context from a biologist who knows the science but may not know what the software needs?
+
+### 2. Bioimage segmentation UX and workflow tools
+
+Find relevant tools and papers around:
+
+- ilastik
+- CellProfiler
+- napari and napari plugins
+- Fiji/ImageJ segmentation workflows
+- Neuroglancer use in connectomics
+- webKnossos
+- VAST / proofreading tools
+- MoBIE / BigDataViewer if relevant
+- other interactive segmentation/proofreading systems
+
+Focus on:
+
+- how users import projects,
+- how tools represent datasets and labels,
+- how proofreading status is tracked,
+- how model training/inference loops are made understandable.
+
+### 3. Connectomics and volumetric segmentation workflows
+
+Review PyTorch Connectomics and related connectomics workflows:
+
+- semantic segmentation vs affinity/instance segmentation,
+- common model outputs,
+- expected file formats and folder layouts,
+- training/inference/evaluation lifecycle,
+- metrics used for mitochondria, nuclei, neurons, synapses,
+- how proofread labels become new training data.
+
+Output should clearly distinguish what is universal vs connectomics-specific.
+
+### 4. Agent architecture and project-context memory
+
+Find patterns for:
+
+- tool-using agents that inspect local files/project state,
+- persistent project memory,
+- retrieval over project artifacts,
+- structured context/state graphs,
+- durable action proposals and approval cards,
+- separation between visible response and hidden trace,
+- agent plans vs direct app actions.
+
+Compare:
+
+- Claude Code / Codex-style expandable thinking traces,
+- Cursor/Copilot-style coding assistants,
+- data-analysis agents,
+- domain workflow copilots.
+
+Specific question: what is the canonical pattern for keeping an agent’s project context fresh as files and user decisions change?
+
+### 5. Benchmarks and datasets for evaluating this prototype
+
+Identify benchmark/project fixtures we can use to test the workflow:
+
+- small enough to run or stage locally,
+- has raw data and masks,
+- can simulate partially proofread, draft, and missing segmentations,
+- representative of real PyTC workflows.
+
+For each candidate dataset, report:
+
+- source URL,
+- license/access constraints,
+- expected file format,
+- ground-truth availability,
+- segmentation task,
+- recommended PyTC config if known,
+- whether it is useful for a demo, a paper case study, or a stress test.
+
+### 6. Paper positioning
+
+Find likely paper framing:
+
+- HCI / CHI / UIST-style human-agent collaboration for scientific software?
+- Bioimage analysis tool paper?
+- Connectomics workflow systems paper?
+- Demo/prototype paper?
+
+The app’s central claim is not “new segmentation model.” It is closer to:
+
+- agent-guided segmentation workflow orchestration,
+- project-context-aware biomedical image segmentation client,
+- human-in-the-loop proofreading/training loop with persistent workflow memory,
+- reducing software/configuration burden for biology users.
+
+Find prior work and gaps supporting or challenging that claim.
+
+## Output Required From The Research Agent
+
+Produce a single markdown report with these sections:
+
+1. **Executive Summary**
+   - 10-15 bullet points with the most actionable findings.
+
+2. **Related Work Map**
+   - Cluster papers/tools by theme.
+   - Include citations, links, and 1-3 sentence relevance notes for each.
+
+3. **Product Implications**
+   - Concrete design recommendations for this app.
+   - Separate “do now,” “later,” and “avoid.”
+
+4. **Agent Architecture Implications**
+   - Recommended pattern for project context ingestion, memory, tool use, traces, and action proposals.
+   - Call out which patterns are established vs speculative.
+
+5. **Bioimage Workflow Implications**
+   - What the app must support for mitochondria, nuclei, neuron/synapse, and general volumetric segmentation workflows.
+
+6. **Dataset / Benchmark Recommendations**
+   - Table of candidate datasets.
+   - Include which ones best support:
+     - demo reliability,
+     - paper case study,
+     - stress testing,
+     - partial-label progress workflow.
+
+7. **Paper Positioning**
+   - Candidate paper thesis.
+   - Best venue categories.
+   - Related-work outline.
+   - Claims that are defensible vs claims to avoid.
+
+8. **Open Questions For The Engineering Agent**
+   - Questions that need implementation judgment, not more literature.
+
+9. **Annotated Bibliography**
+   - Full citations or stable links.
+   - Short annotation for each source.
+
+## Research Quality Bar
+
+- Prefer primary sources: papers, official docs, benchmark pages, official GitHub repositories.
+- Include URLs for every important source.
+- Separate facts from interpretation.
+- Avoid generic “LLM agents are useful” summaries; tie every point back to this app.
+- When citing tools, describe their actual workflow model, not just their feature list.
+- Note if a source is outdated or if a tool is no longer maintained.
+- Call out contradictions or tradeoffs.
+
+## Known Current Pain Points To Keep In Mind
+
+- The assistant has often sounded too robotic or planner-like.
+- The assistant previously failed to inspect mounted project files deeply enough before answering.
+- Blank project-context text boxes are intimidating for biology users.
+- Biologists may know the relevant experimental context but may not know how to express it in software terms.
+- The app needs to continuously reconcile:
+  - what files exist,
+  - what the user says,
+  - what has been proofread,
+  - what is eligible for training,
+  - what has already been inferred,
+  - what evidence is stored for reproducibility.
+- The agent should propose direct app routines, but not silently mutate artifacts or run expensive jobs without approval.
+- The workflow needs to support multi-volume training, not just single image/label pairs.
+
+## Deliverable Style
+
+Write for an engineering + HCI synthesis reader. The final report should be precise enough that another agent can turn it into implementation tasks, but broad enough to include literature and design framing.
+
+Do not write marketing copy. Do not overclaim. Be concrete.
diff --git a/docs/research/deep-research-agentic-workflow-formalization-2026-05-27.md b/docs/research/deep-research-agentic-workflow-formalization-2026-05-27.md
new file mode 100644
index 00000000..628e2604
--- /dev/null
+++ b/docs/research/deep-research-agentic-workflow-formalization-2026-05-27.md
@@ -0,0 +1,580 @@
+# Deep Research Task: Formalizing The Agentic Segmentation Workflow
+
+## Purpose
+
+Investigate how the seg.bio / PyTC Client assistant should evolve from a useful prototype into a rigorous workflow-aware agent for biomedical image segmentation.
+
+The research target is not "add a chatbot." The target is a system closer to Codex or Claude Code, but specialized for volumetric biomedical segmentation: it should inspect a mounted project, maintain grounded project memory, propose bounded app actions, ask concrete context questions when needed, execute approved routines, and keep the user oriented across visualization, proofreading, training, inference, and evaluation.
+
+The output should give the engineering team a concrete architecture, implementation roadmap, and literature-backed design rationale for improving the current agentic implementation.
+
+## Local Project Context
+
+Primary working checkout on this machine:
+
+- `/home/weidf/deploy/pytc-client-demo2`
+
+Public/demo deployment:
+
+- `https://demo.seg.bio`
+
+Primary repositories:
+
+- PyTC Client / seg.bio app: `https://github.com/PytorchConnectomics/pytc-client`
+- PyTorch Connectomics backend library: `https://github.com/PytorchConnectomics/pytorch_connectomics`
+- TapeReader reference pipeline for the Yixiao/XRI case study: `https://github.com/LinghuLab/TapeReader`
+
+The current prototype includes:
+
+- `Files`: mount and inspect project folders.
+- `Visualize`: open image/mask volumes in Neuroglancer.
+- `Train Model`: configure and launch PyTorch Connectomics training.
+- `Run Model`: configure and launch inference.
+- `Progress`: volume-level workflow tracking.
+- `Proofread`: review and correct segmentation masks.
+- `Assistant`: workflow-aware chat plus action cards.
+
+The `Monitor` tab has been intentionally sunset. Runtime status should live near the relevant action surface: training state in Train Model, inference state in Run Model, proofreading state in Proofread, and project state in Progress / workflow overview.
+
+## Current Case Studies
+
+Treat these as the three paper/prototype cases. Fill in missing details as you inspect local folders and repo docs.
+
+### Case Study 1: MitoEM / MitoEM2-Style Progress Workflow
+
+Likely local fixture:
+
+- `/home/weidf/demo_data/mitoem2_progress_demo`
+
+Core workflow:
+
+- EM/ssSEM mitochondria instance segmentation.
+- Some volumes are confirmed ground truth.
+- Some volumes have draft segmentations needing proofreading.
+- Some volumes are image-only targets.
+- The agent should train from confirmed/proofread ground truth and propose inference for image-only volumes.
+
+### Case Study 2: Yixiao / TapeReader XRI Fibre Workflow
+
+Current local fixture:
+
+- `/home/weidf/demo_data/yixiao_tapereader_xri_case_study`
+
+Reference project:
+
+- TapeReader pipeline: `https://github.com/LinghuLab/TapeReader`
+- Paper: `https://www.biorxiv.org/content/10.1101/2025.05.10.653182v1`
+
+Current split:
+
+- 10 tracked XRI volumes.
+- 6 confirmed ground-truth masks.
+- 2 draft masks needing proofreading.
+- 2 image-only inference targets.
+- Active voxel spacing: `40 x 16.3 x 16.3 nm` in z,y,x.
+- Active app-compatible config: `configs/TapeReader-Fiber-BCS-AppCompat-Sanity.yaml`.
+
+Core workflow:
+
+- XRI/CytoTape fibre instance segmentation.
+- Use confirmed masks for training.
+- Use draft masks for proofreading and later promotion.
+- Use image-only volumes as inference targets.
+- Preserve the distinction between paper-faithful TapeReader config semantics and current app-compatible PyTC fallback config semantics.
+
+### Case Study 3: Placeholder
+
+Identify what the third case should be and what agentic capabilities it should stress.
+
+Candidate families:
+
+- Lucchi++ for reliable onboarding/demo.
+- SNEMI3D or CREMI for affinity-heavy connectomics.
+- NucMM or another non-mitochondria volumetric segmentation workflow.
+
+The research output should recommend the strongest third case for the paper and explain which agent/workflow behaviors it exercises.
+
+## Current Engineering Problem
+
+The assistant has improved, but the agentic architecture is still not formal enough.
+
+Known pain points:
+
+- The agent sometimes answers from stale or incomplete project context.
+- Project context is assembled from multiple places: scanned files, manifests, workflow state, progress state, user chat, and runtime events.
+- There is not yet one canonical project-memory contract that all app modules and the agent treat as the shared source of truth.
+- Action cards exist, but the policy for when to propose, ask, approve, execute, or refuse needs to be formalized.
+- The initial setup experience can still strand biologists in blank text boxes instead of guiding them through concrete project facts.
+- The agent should be able to inspect project state and ask targeted questions, but it should not pretend to see or validate things it cannot actually inspect.
+- The visible chat voice should feel like a normal helpful assistant, while inspection details should be available through progressive disclosure.
+- Training/inference/proofreading actions should be bounded app routines, not arbitrary shell execution.
+- Long-running jobs and artifact mutations need durable provenance.
+- The paper needs a defensible explanation of why this is a coherent human-agent workflow system, not just a UI wrapped around an LLM.
+
+## Research Questions
+
+Answer these in concrete, implementation-oriented terms.
+
+1. What is the right formal model for the agent?
+   - Should it be framed as a workflow orchestration agent, mixed-initiative assistant, scientific workflow manager, interactive ML collaborator, or something else?
+   - What should the paper call it?
+   - What should the product call it?
+
+2. What is the right project-memory schema?
+   - Required dataset-level facts.
+   - Required per-volume state.
+   - Required artifact index.
+   - Required run history.
+   - Required proofreading/edit history.
+   - Required evidence/provenance ledger.
+   - Required user/context confirmations.
+   - Required invalidation or refresh timestamps.
+
+3. What should the agent be allowed to inspect?
+   - Mounted filesystem tree.
+   - `project_manifest.json`.
+   - PyTC configs.
+   - volume dimensions/dtypes/metadata.
+   - available labels/predictions/checkpoints.
+   - progress statuses.
+   - workflow events.
+   - logs and metrics.
+   - proofreading edits.
+   - screenshots or viewer-derived observations, if feasible.
+
+4. When should the agent re-inspect instead of trusting cached memory?
+   - File watcher events.
+   - user changes status.
+   - workflow changes stage.
+   - training/inference job starts/completes/fails.
+   - edits are saved.
+   - app resumes from idle.
+   - user asks a question requiring fresh state.
+
+5. What should the action model look like?
+   - Read-only actions.
+   - Navigation actions.
+   - Form-populating actions.
+   - Approval-gated runtime actions.
+   - Mutating project-state actions.
+   - Expensive training/inference actions.
+   - Refusals/blockers when preconditions are missing.
+
+6. What makes an action proposal understandable to biologists?
+   - Minimal fields for a training card.
+   - Minimal fields for an inference card.
+   - Minimal fields for proofreading queue actions.
+   - Minimal fields for status changes.
+   - How to show affected volumes without dumping huge JSON.
+   - How to expose details only when the user wants them.
+
+7. How should context elicitation work?
+   - What questions should the app ask after mounting a project?
+   - How can auto-detected facts reduce blank-page anxiety?
+   - How should voice/speech input fit?
+   - How should the user correct wrong guesses?
+   - How should corrections persist back into project memory?
+
+8. What should "Codex/Claude Code for segmentation workflows" mean here?
+   - Which coding-agent patterns transfer cleanly?
+   - Which patterns do not transfer because biomedical workflows involve data, compute, provenance, and scientific interpretation?
+   - How should the product show plans, traces, approvals, and recoverability?
+
+9. What safety and provenance guarantees are necessary?
+   - Human approval for expensive/mutating actions.
+   - Reproducible configs and run manifests.
+   - Undo/versioning for project status changes.
+   - Evidence trail for why the agent made a suggestion.
+   - Avoiding hidden arbitrary shell execution.
+
+10. How should the system be evaluated for a paper?
+
+- What claims are defensible?
+- What study tasks should participants perform?
+- What metrics or qualitative evidence would show that the agent improves coordination?
+- What claims should be avoided unless there is stronger evidence?
+
+## Code Areas To Inspect
+
+Start with these files and neighboring modules. Names may drift; use `rg` if needed.
+
+Backend:
+
+- `server_api/workflows/router.py`
+- `server_api/workflows/service.py`
+- `server_api/workflows/db_models.py`
+- `server_api/workflows/bundle_export.py`
+- `server_api/workflows/volume_pairs.py`
+- `server_api/auth/router.py`
+- `server_api/auth/models.py`
+- `server_api/main.py`
+
+Frontend:
+
+- `client/src/components/Chatbot.js`
+- `client/src/contexts/WorkflowContext.js`
+- `client/src/contexts/GlobalContext.js`
+- `client/src/views/FilesManager.js`
+- `client/src/views/Visualization.js`
+- `client/src/views/ModelTraining.js`
+- `client/src/views/RunModel.js`
+- `client/src/views/ProjectProgress.js`
+- `client/src/views/Proofread.js`
+- `client/src/views/Views.js`
+
+Project docs:
+
+- `docs/codex-working-memory/progress-log.md`
+- `docs/codex-working-memory/backlog.md`
+- `docs/codex-working-memory/paper-readiness-production-plan.md`
+- `docs/research/deep-research-agentic-bioimage-segmentation.md`
+- `docs/research/deep-research-engineering-synthesis-2026-05-24.md`
+- `docs/research/internal-technical-audit-2026-05-24.md`
+- `docs/research/claude-code-agent-patterns.md`
+
+Local data fixtures:
+
+- `/home/weidf/demo_data/mitoem2_progress_demo`
+- `/home/weidf/demo_data/yixiao_tapereader_xri_case_study`
+- `/home/weidf/demo_data/yixiao_tapereader_xri_case_study_holdout_masks`
+
+## Literature And Systems Areas To Review
+
+Use current web search and primary sources where possible. The output must include links/citations.
+
+### Human-Agent And Mixed-Initiative Interaction
+
+Look for work on:
+
+- mixed-initiative user interfaces;
+- interactive machine learning;
+- human-AI interaction guidelines;
+- intent elicitation;
+- progressive disclosure;
+- explanation as support for correction, not raw chain-of-thought dumping;
+- approval-gated autonomy;
+- recoverability and user control.
+
+Seed references and keywords:
+
+- Eric Horvitz, "Principles of Mixed-Initiative User Interfaces"
+- Saleema Amershi et al., "Guidelines for Human-AI Interaction"
+- Amershi et al., "The Role of Humans in Interactive Machine Learning"
+- intent elicitation in mixed-initiative systems
+- domain knowledge elicitation in applied ML
+- human-centered AI workflow systems
+
+### Agentic Developer Tools
+
+Review product/system patterns from:
+
+- Codex
+- Claude Code
+- GitHub Copilot agent mode
+- Cursor / Windsurf-style coding agents
+- any recent papers or docs on agentic coding tools
+
+Do not treat these as scientific proof. Treat them as design-pattern references.
+
+Pay attention to:
+
+- inspect-plan-act loops;
+- tool calling;
+- approval gates;
+- diffs and patches as reviewable artifacts;
+- long-running task progress;
+- traces/logs;
+- context compaction and memory;
+- filesystem/project understanding;
+- bounded execution environments;
+- user interruption and resume behavior.
+
+### Bioimage Workflow Tools
+
+Review tools that biologists actually use:
+
+- ilastik
+- CellProfiler
+- Fiji/ImageJ
+- napari
+- napari-imagej
+- Neuroglancer
+- WEBKNOSSOS
+- VAST
+- BigDataViewer
+- MoBIE
+- OMERO
+- OME-Zarr / REMBI
+
+Focus on what they teach about:
+
+- guided setup;
+- workflow recipes;
+- project metadata;
+- annotation/proofreading state;
+- volume visualization;
+- collaboration;
+- reproducibility;
+- non-programmer usability.
+
+### Connectomics And Segmentation Infrastructure
+
+Review:
+
+- PyTorch Connectomics tutorials/configs;
+- MitoEM and MitoEM2.0;
+- Lucchi++;
+- SNEMI3D;
+- CREMI;
+- CAVE / Connectome Annotation Versioning Engine;
+- proofreading and versioned annotation systems.
+
+Focus on:
+
+- data representations;
+- semantic masks vs instance labels vs affinities;
+- train/infer/evaluate loops;
+- proofreading loops;
+- valid masks / partially annotated supervision;
+- provenance and reproducibility.
+
+### Scientific Workflow And Provenance
+
+Review systems/literature around:
+
+- scientific workflow management;
+- provenance graphs;
+- experiment tracking;
+- reproducible computational pipelines;
+- workflow provenance in image analysis;
+- human-in-the-loop ML experiment management.
+
+The question: what is the minimum provenance model this product needs to be credible in a biomedical setting?
+
+## Expected Output
+
+Write the final research report as a markdown file in:
+
+- `docs/research/agentic-workflow-formalization-report.md`
+
+The report should include these sections.
+
+### 1. Executive Summary
+
+One to two pages max. State the recommended agent architecture and why.
+
+### 2. Current Prototype Diagnosis
+
+Grounded in code inspection:
+
+- what exists now;
+- where the agent is already strong;
+- where the current implementation is brittle;
+- where state is duplicated or stale;
+- where UI/action semantics are unclear;
+- what should be fixed first.
+
+### 3. Literature-Backed Design Principles
+
+For each principle:
+
+- cite the relevant literature/systems;
+- state the design implication;
+- map it to this app.
+
+Example format:
+
+| Principle                                       | Evidence | App Implication              | Priority |
+| ----------------------------------------------- | -------- | ---------------------------- | -------- |
+| Ask concrete questions instead of blank prompts | ...      | Guided project intake wizard | High     |
+
+### 4. Proposed Agent Architecture
+
+Include a diagram, preferably Mermaid.
+
+At minimum, specify:
+
+- project inspector;
+- normalized project memory;
+- retrieval/context layer;
+- assistant response layer;
+- trace/evidence layer;
+- action proposal generator;
+- approval policy;
+- bounded workflow executor;
+- artifact/provenance ledger;
+- invalidation/reinspection loop.
+
+### 5. Project Memory Schema
+
+Propose a concrete schema in JSON-like form.
+
+It should cover:
+
+- dataset/project facts;
+- task family preset;
+- volume states;
+- artifact index;
+- run history;
+- proofreading/edit history;
+- metrics/evaluation history;
+- user confirmations;
+- evidence events;
+- stale/freshness markers.
+
+### 6. Volume And Workflow State Machine
+
+Define volume states and transitions.
+
+Minimum states:
+
+- `image_only`
+- `draft_segmentation`
+- `needs_proofreading`
+- `proofread_ground_truth`
+- `training_candidate`
+- `queued_for_inference`
+- `prediction_ready`
+- `ignored`
+
+Include:
+
+- who/what can transition each state;
+- what evidence is required;
+- which transitions require approval;
+- how partial or region-level proofreading should be represented.
+
+### 7. Action Card Specification
+
+Define card types, required fields, and approval behavior for:
+
+- visualize data;
+- choose/change data;
+- open progress;
+- start training;
+- start inference;
+- queue proofreading;
+- mark volume status;
+- export corrected masks;
+- evaluate/compare results.
+
+Specify:
+
+- plain-language summary;
+- affected volumes;
+- inputs;
+- outputs;
+- risks/costs;
+- expected duration if knowable;
+- review details;
+- approval/reject behavior;
+- how resulting events are written.
+
+### 8. Guided Context Elicitation
+
+Design the first-run flow after mounting a project.
+
+It should avoid blank boxes by using:
+
+- auto-detected facts;
+- checkable/editable suggestions;
+- concrete short questions;
+- examples;
+- "I don't know" options;
+- voice-friendly prompts if applicable.
+
+Specify what the app should ask for each workflow family:
+
+- mitochondria semantic segmentation;
+- mitochondria instance segmentation;
+- XRI fibre / TapeReader;
+- affinity-heavy neuron segmentation;
+- synapse/cleft segmentation.
+
+### 9. Case Study-Specific Requirements
+
+For each case study:
+
+- expected files;
+- expected labels;
+- expected configs;
+- workflow loop;
+- progress states;
+- what the agent should know;
+- what the agent should not assume;
+- demo tasks;
+- paper evidence it can generate.
+
+Include concrete recommendations for the third case study.
+
+### 10. Evaluation Plan For The Paper
+
+Propose a realistic study plan.
+
+Include:
+
+- participant profile;
+- tasks;
+- conditions or comparison baselines;
+- data to log;
+- interview prompts;
+- success criteria;
+- risks to claims;
+- defensible claims;
+- claims to avoid.
+
+### 11. Engineering Roadmap
+
+Prioritize implementation into:
+
+- immediate fixes for the current prototype;
+- paper-demo requirements;
+- production-quality requirements;
+- future/research extensions.
+
+Each item should include:
+
+- user value;
+- affected code areas;
+- required backend changes;
+- required frontend changes;
+- test/verification plan;
+- paper relevance.
+
+### 12. Open Questions
+
+List unresolved questions that require user/team decisions, not just engineering execution.
+
+## Quality Bar
+
+The final report must be actionable. It should not be a generic LLM-agent essay.
+
+A good report will:
+
+- cite specific papers, systems, and documentation;
+- inspect the actual codebase and name concrete implementation gaps;
+- distinguish established design patterns from speculative ideas;
+- propose a schema detailed enough for engineers to implement;
+- propose action-card behavior detailed enough for UI implementation;
+- explain how the design supports a TOCHI-style systems/HCI paper;
+- identify what evidence the app should log to support the paper;
+- warn clearly about overclaims.
+
+A bad report will:
+
+- say "use RAG" without specifying what gets retrieved and when;
+- say "make the agent more autonomous" without approval boundaries;
+- propose arbitrary shell execution as the core agent model;
+- ignore project progress and per-volume state;
+- ignore biological user onboarding;
+- ignore provenance and reproducibility;
+- treat all segmentation workflows as generic binary masks;
+- recommend showing hidden chain-of-thought as the main transparency mechanism.
+
+## Suggested Final Recommendation Shape
+
+The report should end with a concise recommendation like:
+
+> Build the assistant as a workflow-aware, approval-gated project operator. The central abstraction is not chat history; it is project memory plus action proposals. Chat is the conversational surface. Project memory is the source of truth. Action cards are the bridge from intent to bounded execution. Evidence events are the paper-grade provenance layer.
+
+The exact wording can change, but the final answer should make the architecture and product direction this concrete.
diff --git a/docs/research/deep-research-agentic-workflow-formalization-chatgpt-prompt-2026-05-27.md b/docs/research/deep-research-agentic-workflow-formalization-chatgpt-prompt-2026-05-27.md
new file mode 100644
index 00000000..bce3aa7d
--- /dev/null
+++ b/docs/research/deep-research-agentic-workflow-formalization-chatgpt-prompt-2026-05-27.md
@@ -0,0 +1,634 @@
+# ChatGPT Deep Research Task: Verify And Strengthen The Agentic Segmentation Workflow Formalization
+
+## Role
+
+Act as a rigorous external research agent reviewing and extending an engineering report for seg.bio / PyTC Client, a web app for volumetric biomedical image segmentation workflows.
+
+Your goal is **not** to produce a generic LLM-agent essay. Your goal is to independently verify, critique, and strengthen the proposed architecture for a workflow-aware assistant specialized for biomedical image segmentation.
+
+The target system should be closer to Codex / Claude Code in workflow discipline, but specialized for segmentation projects: inspect a mounted project, maintain grounded project memory, propose bounded app actions, ask concrete context questions, execute approved routines, and keep the user oriented across visualization, proofreading, training, inference, evaluation, and evidence export.
+
+## Primary Output
+
+Write a final markdown research report that can replace or substantially improve:
+
+`docs/research/agentic-workflow-formalization-report.md`
+
+The report should be actionable for engineers and defensible for a systems/HCI paper.
+
+## Important Limitation
+
+You may not have direct access to the local filesystem. If local files are unavailable, do **not** pretend to inspect them. Use:
+
+- public repository URLs;
+- any code excerpts pasted into this prompt/session;
+- uploaded files, if provided;
+- web-accessible documentation and papers;
+- explicit uncertainty labels where local verification is missing.
+
+When local code inspection is unavailable, mark findings as:
+
+- `Verified from public source`;
+- `Verified from provided excerpt`;
+- `Inferred from project description`;
+- `Needs local verification`.
+
+## Project Context
+
+Primary public/demo deployment:
+
+- https://demo.seg.bio
+
+Primary repositories:
+
+- PyTC Client / seg.bio app: https://github.com/PytorchConnectomics/pytc-client
+- PyTorch Connectomics backend library: https://github.com/PytorchConnectomics/pytorch_connectomics
+- TapeReader reference pipeline: https://github.com/LinghuLab/TapeReader
+
+Current app modules:
+
+- Files: mount and inspect project folders.
+- Visualize: open image/mask volumes in Neuroglancer.
+- Train Model: configure and launch PyTorch Connectomics training.
+- Run Model: configure and launch inference.
+- Progress: volume-level workflow tracking.
+- Proofread: review and correct segmentation masks.
+- Assistant: workflow-aware chat plus action cards.
+
+The `Monitor` tab has been sunset. Runtime status should live near relevant action surfaces:
+
+- training state in Train Model;
+- inference state in Run Model;
+- proofreading state in Proofread;
+- project state in Progress / workflow overview.
+
+## Current Engineering Problem
+
+The assistant prototype is useful but not formal enough.
+
+Known pain points:
+
+- The agent sometimes answers from stale or incomplete project context.
+- Project context is assembled from scanned files, manifests, workflow state, progress state, user chat, and runtime events.
+- There is not yet one canonical project-memory contract shared by all app modules and the agent.
+- Action cards exist, but the policy for proposing, asking, approving, executing, or refusing actions needs formalization.
+- Initial setup can strand biologists in blank text boxes instead of guiding them through concrete detected project facts.
+- The agent should inspect project state and ask targeted questions, but should not pretend to validate facts it cannot inspect.
+- Visible chat should feel normal and concise, while inspection details should be available through progressive disclosure.
+- Training, inference, and proofreading actions should be bounded app routines, not arbitrary shell execution.
+- Long-running jobs and artifact mutations need durable provenance.
+- The paper needs a defensible explanation of why this is a coherent human-agent workflow system, not a UI wrapped around an LLM.
+
+## Case Studies
+
+### Case Study 1: MitoEM / MitoEM2-Style Progress Workflow
+
+Likely local fixture:
+
+- `/home/weidf/demo_data/mitoem2_progress_demo`
+
+Known/project-described workflow:
+
+- EM/ssSEM mitochondria instance segmentation.
+- Some volumes are confirmed ground truth.
+- Some volumes have draft segmentations needing proofreading.
+- Some volumes are image-only targets.
+- The agent should train from confirmed/proofread ground truth and propose inference for image-only volumes.
+
+Known fixture facts from a local manifest excerpt:
+
+- 6 HDF5 smoke volumes.
+- Initial split: 2 ground-truth, 2 needs-proofreading, 2 missing-segmentation/image-only.
+- Voxel size: z,y,x = 30,8,8 nm.
+- Config: `configs/MitoEM2-Pyra-Demo-BC.yaml`.
+- Source links include:
+  - https://huggingface.co/datasets/pytc/MitoEM2.0/tree/main
+  - https://connectomics.readthedocs.io/en/latest/tutorials/mito.html
+
+### Case Study 2: Yixiao / TapeReader XRI Fibre Workflow
+
+Likely local fixture:
+
+- `/home/weidf/demo_data/yixiao_tapereader_xri_case_study`
+
+Reference:
+
+- TapeReader: https://github.com/LinghuLab/TapeReader
+- Preprint: https://www.biorxiv.org/content/10.1101/2025.05.10.653182v1
+
+Known fixture facts from a local manifest excerpt:
+
+- 10 tracked XRI volumes.
+- 6 confirmed ground-truth masks: `1`, `2`, `3`, `4_1`, `4_2`, `4_3`.
+- 2 draft masks needing proofreading: `5_1`, `5_2`.
+- 2 image-only inference targets: `6_1`, `6_2`.
+- Active voxel spacing: z,y,x = 40,16.3,16.3 nm.
+- App-compatible config: `configs/TapeReader-Fiber-BCS-AppCompat-Sanity.yaml`.
+- Paper-faithful config: `configs/TapeReader-Fiber-BCS-Original-Barcode.yaml`.
+- Important requirement: preserve the distinction between paper-faithful TapeReader pipeline semantics and current app-compatible PyTC fallback config semantics.
+
+### Case Study 3: To Recommend
+
+Recommend the strongest third case for the paper and explain what agent/workflow behavior it exercises.
+
+Candidate families:
+
+- Lucchi++ for reliable onboarding/demo.
+- SNEMI3D or CREMI for affinity-heavy connectomics.
+- NucMM or another non-mitochondria volumetric segmentation workflow.
+
+The recommendation should balance:
+
+- paper value;
+- implementation risk;
+- diversity from MitoEM and TapeReader;
+- ability to stress the project-memory/action/provenance model.
+
+## Local Code Areas To Investigate If Accessible
+
+If you can access the repo, inspect these areas and neighboring modules:
+
+Backend:
+
+- `server_api/workflows/router.py`
+- `server_api/workflows/service.py`
+- `server_api/workflows/db_models.py`
+- `server_api/workflows/bundle_export.py`
+- `server_api/workflows/volume_pairs.py`
+- `server_api/auth/router.py`
+- `server_api/auth/models.py`
+- `server_api/main.py`
+
+Frontend:
+
+- `client/src/components/Chatbot.js`
+- `client/src/components/chat/AssistantActionCard.js`
+- `client/src/components/chat/AgentProposalCard.js`
+- `client/src/contexts/WorkflowContext.js`
+- `client/src/contexts/GlobalContext.js`
+- `client/src/views/FilesManager.js`
+- `client/src/views/Visualization.js`
+- `client/src/views/ModelTraining.js`
+- `client/src/views/RunModel.js`
+- `client/src/views/ProjectProgress.js`
+- `client/src/views/Proofread.js`
+- `client/src/views/Views.js`
+
+Local docs to inspect if uploaded or accessible:
+
+- `docs/research/agentic-workflow-formalization-report.md`
+- `docs/research/deep-research-agentic-bioimage-segmentation.md`
+- `docs/research/deep-research-engineering-synthesis-2026-05-24.md`
+- `docs/research/internal-technical-audit-2026-05-24.md`
+- `docs/research/claude-code-agent-patterns.md`
+- `docs/codex-working-memory/progress-log.md`
+- `docs/codex-working-memory/backlog.md`
+- `docs/codex-working-memory/paper-readiness-production-plan.md`
+
+## Existing Report Claims To Audit
+
+Audit these claims carefully:
+
+1. The system should be framed as a **mixed-initiative workflow agent for iterative biomedical image segmentation**.
+2. Product term should be **Workflow Assistant** or **Segmentation Workflow Assistant**.
+3. The central abstraction should be **project memory plus action proposals**, not chat history.
+4. Project memory should cover:
+   - project facts;
+   - task-family preset;
+   - per-volume state;
+   - artifact index;
+   - run history;
+   - proofreading/edit history;
+   - evaluation history;
+   - user confirmations;
+   - evidence events;
+   - freshness/invalidation markers.
+5. Actions should be typed and bounded:
+   - read-only actions;
+   - navigation actions;
+   - form-populating actions;
+   - approval-gated runtime actions;
+   - mutating project-state actions;
+   - expensive training/inference actions;
+   - refusals/blockers.
+6. Per-volume states should include:
+   - `image_only`
+   - `draft_segmentation`
+   - `needs_proofreading`
+   - `proofread_ground_truth`
+   - `training_candidate`
+   - `queued_for_inference`
+   - `prediction_ready`
+   - `ignored`
+7. The strongest third case may be CREMI-style affinity-heavy connectomics, but this must be challenged against Lucchi++ and SNEMI3D.
+8. The defensible paper claim is workflow coordination/provenance, not accuracy improvement.
+
+## Research Questions
+
+Answer in concrete, implementation-oriented terms.
+
+1. What is the right formal model for the agent?
+   - workflow orchestration agent;
+   - mixed-initiative assistant;
+   - scientific workflow manager;
+   - interactive ML collaborator;
+   - or another framing?
+   - What should the paper call it?
+   - What should the product call it?
+
+2. What is the right project-memory schema?
+   - required dataset-level facts;
+   - per-volume state;
+   - artifact index;
+   - run history;
+   - proofreading/edit history;
+   - evidence/provenance ledger;
+   - user/context confirmations;
+   - invalidation or refresh timestamps.
+
+3. What should the agent be allowed to inspect?
+   - mounted filesystem tree;
+   - `project_manifest.json`;
+   - PyTC configs;
+   - volume dimensions/dtypes/metadata;
+   - labels/predictions/checkpoints;
+   - progress statuses;
+   - workflow events;
+   - logs and metrics;
+   - proofreading edits;
+   - screenshots or viewer-derived observations if feasible.
+
+4. When should the agent re-inspect instead of trusting cached memory?
+   - file watcher events;
+   - user status changes;
+   - workflow stage changes;
+   - training/inference job lifecycle;
+   - proofread edit saves;
+   - app resume after idle;
+   - user asks freshness-sensitive questions.
+
+5. What should the action model look like?
+   - card schema;
+   - required fields;
+   - approval behavior;
+   - execution routing;
+   - result/provenance logging;
+   - refusal/blocker behavior.
+
+6. What makes an action proposal understandable to biologists?
+   - minimal training card fields;
+   - minimal inference card fields;
+   - proofreading queue fields;
+   - status-change fields;
+   - affected-volume presentation;
+   - progressive disclosure.
+
+7. How should context elicitation work?
+   - first-run flow after mounting a project;
+   - auto-detected facts;
+   - checkable/editable suggestions;
+   - short questions;
+   - "I don't know" options;
+   - voice-friendly prompts;
+   - correction persistence.
+
+8. What should "Codex/Claude Code for segmentation workflows" mean?
+   - which coding-agent patterns transfer;
+   - which do not transfer;
+   - how to show plans, traces, approvals, interruption, resume, and recoverability.
+
+9. What safety and provenance guarantees are necessary?
+   - human approval;
+   - reproducible configs;
+   - run manifests;
+   - undo/versioning;
+   - evidence trail;
+   - no hidden arbitrary shell execution.
+
+10. How should the system be evaluated for a paper?
+
+- defensible claims;
+- participant tasks;
+- baselines;
+- metrics;
+- qualitative evidence;
+- claims to avoid.
+
+## Literature And Systems Areas To Review
+
+Use current web search and prefer primary sources where possible. Include links/citations.
+
+### Human-Agent And Mixed-Initiative Interaction
+
+Review:
+
+- Eric Horvitz, "Principles of Mixed-Initiative User Interfaces";
+- Saleema Amershi et al., "Guidelines for Human-AI Interaction";
+- Amershi et al., "The Role of Humans in Interactive Machine Learning";
+- intent elicitation in mixed-initiative systems;
+- progressive disclosure;
+- explanation for correction, not raw chain-of-thought;
+- approval-gated autonomy;
+- recoverability and user control.
+
+### Agentic Developer Tools
+
+Review product/system patterns from:
+
+- OpenAI Codex;
+- Claude Code;
+- GitHub Copilot agent mode / coding agent;
+- Cursor / Windsurf-style coding agents.
+
+Treat these as design-pattern references, not scientific proof. Focus on:
+
+- inspect-plan-act loops;
+- tool calling;
+- approval gates;
+- reviewable diffs or reviewable action artifacts;
+- long-running task progress;
+- traces/logs;
+- context compaction and memory;
+- project understanding;
+- bounded execution environments;
+- user interruption and resume.
+
+### Bioimage Workflow Tools
+
+Review:
+
+- ilastik;
+- CellProfiler;
+- Fiji/ImageJ;
+- napari;
+- napari-imagej;
+- Neuroglancer;
+- WEBKNOSSOS;
+- VAST;
+- BigDataViewer;
+- MoBIE;
+- OMERO;
+- OME-Zarr;
+- REMBI.
+
+Focus on:
+
+- guided setup;
+- workflow recipes;
+- project metadata;
+- annotation/proofreading state;
+- volume visualization;
+- collaboration;
+- reproducibility;
+- non-programmer usability.
+
+### Connectomics And Segmentation Infrastructure
+
+Review:
+
+- PyTorch Connectomics tutorials/configs;
+- MitoEM and MitoEM2.0;
+- Lucchi++;
+- SNEMI3D;
+- CREMI;
+- CAVE / Connectome Annotation Versioning Engine;
+- proofreading and versioned annotation systems.
+
+Focus on:
+
+- data representations;
+- semantic masks vs instance labels vs affinities;
+- train/infer/evaluate loops;
+- proofreading loops;
+- valid masks / partially annotated supervision;
+- provenance and reproducibility.
+
+### Scientific Workflow And Provenance
+
+Review:
+
+- W3C PROV;
+- scientific workflow provenance;
+- experiment tracking;
+- MLflow / DVC-style lineage;
+- reproducible computational pipelines;
+- workflow provenance in image analysis;
+- human-in-the-loop ML experiment management.
+
+The key question: what is the **minimum provenance model** this product needs to be credible in a biomedical setting?
+
+## Required Report Sections
+
+### 1. Executive Summary
+
+One to two pages max. State the recommended agent architecture and why.
+
+### 2. Current Prototype Diagnosis
+
+Ground this in public code or provided excerpts. Explicitly mark anything needing local verification.
+
+Cover:
+
+- what exists now;
+- where the agent is strong;
+- where implementation is brittle;
+- where state is duplicated or stale;
+- where UI/action semantics are unclear;
+- what should be fixed first.
+
+### 3. Literature-Backed Design Principles
+
+Use a table:
+
+| Principle | Evidence | App Implication | Priority |
+| --------- | -------- | --------------- | -------- |
+
+Each row must cite real papers/docs/systems.
+
+### 4. Proposed Agent Architecture
+
+Include a Mermaid diagram.
+
+Specify:
+
+- project inspector;
+- normalized project memory;
+- retrieval/context layer;
+- assistant response layer;
+- trace/evidence layer;
+- action proposal generator;
+- approval policy;
+- bounded workflow executor;
+- artifact/provenance ledger;
+- invalidation/reinspection loop.
+
+### 5. Project Memory Schema
+
+Provide JSON-like schema covering:
+
+- dataset/project facts;
+- task-family preset;
+- volume states;
+- artifact index;
+- run history;
+- proofreading/edit history;
+- metrics/evaluation history;
+- user confirmations;
+- evidence events;
+- stale/freshness markers.
+
+### 6. Volume And Workflow State Machine
+
+Define volume states and transitions.
+
+Minimum states:
+
+- `image_only`
+- `draft_segmentation`
+- `needs_proofreading`
+- `proofread_ground_truth`
+- `training_candidate`
+- `queued_for_inference`
+- `prediction_ready`
+- `ignored`
+
+Include:
+
+- actor allowed to transition;
+- evidence required;
+- approval requirement;
+- representation of partial or region-level proofreading.
+
+### 7. Action Card Specification
+
+Define card types, required fields, and approval behavior for:
+
+- visualize data;
+- choose/change data;
+- open progress;
+- start training;
+- start inference;
+- queue proofreading;
+- mark volume status;
+- export corrected masks;
+- evaluate/compare results;
+- export evidence bundle.
+
+Specify:
+
+- plain-language summary;
+- affected volumes;
+- inputs;
+- outputs;
+- risks/costs;
+- expected duration if knowable;
+- review details;
+- approval/reject behavior;
+- resulting events.
+
+### 8. Guided Context Elicitation
+
+Design first-run flow after mounting a project.
+
+Avoid blank boxes by using:
+
+- auto-detected facts;
+- checkable/editable suggestions;
+- concrete short questions;
+- examples;
+- "I don't know" options;
+- voice-friendly prompts if applicable.
+
+Specify questions for:
+
+- mitochondria semantic segmentation;
+- mitochondria instance segmentation;
+- XRI fibre / TapeReader;
+- affinity-heavy neuron segmentation;
+- synapse/cleft segmentation.
+
+### 9. Case Study-Specific Requirements
+
+For each case:
+
+- expected files;
+- expected labels;
+- expected configs;
+- workflow loop;
+- progress states;
+- what the agent should know;
+- what the agent should not assume;
+- demo tasks;
+- paper evidence it can generate.
+
+Include a clear recommendation for the third case study and alternatives considered.
+
+### 10. Evaluation Plan For The Paper
+
+Include:
+
+- participant profile;
+- tasks;
+- conditions or baselines;
+- data to log;
+- interview prompts;
+- success criteria;
+- risks to claims;
+- defensible claims;
+- claims to avoid.
+
+### 11. Engineering Roadmap
+
+Prioritize into:
+
+- immediate fixes for current prototype;
+- paper-demo requirements;
+- production-quality requirements;
+- future/research extensions.
+
+Each item should include:
+
+- user value;
+- affected code areas;
+- required backend changes;
+- required frontend changes;
+- test/verification plan;
+- paper relevance.
+
+### 12. Open Questions
+
+List unresolved questions requiring team decisions, not just engineering execution.
+
+## Quality Bar
+
+A good report will:
+
+- cite specific papers, systems, and documentation;
+- distinguish verified facts from assumptions;
+- inspect public/local code where possible;
+- name concrete implementation gaps;
+- propose a project-memory schema detailed enough to implement;
+- propose action-card behavior detailed enough for UI implementation;
+- explain how the design supports a systems/HCI paper;
+- identify what evidence the app should log;
+- warn clearly about overclaims.
+
+A bad report will:
+
+- say "use RAG" without specifying what is retrieved and when;
+- say "make the agent autonomous" without approval boundaries;
+- propose arbitrary shell execution as the core agent model;
+- ignore project progress and per-volume state;
+- ignore biological onboarding;
+- ignore provenance and reproducibility;
+- treat all segmentation workflows as generic binary masks;
+- recommend showing hidden chain-of-thought as the transparency mechanism;
+- claim local code inspection when it did not happen.
+
+## Final Recommendation Shape
+
+End with a concise recommendation like:
+
+> Build the assistant as a workflow-aware, approval-gated project operator. The central abstraction is not chat history; it is project memory plus action proposals. Chat is the conversational surface. Project memory is the source of truth. Action cards are the bridge from intent to bounded execution. Evidence events are the paper-grade provenance layer.
+
+The exact wording can change, but the final answer should make the architecture and product direction this concrete.
diff --git a/docs/research/deep-research-agentic-workflow-lit-review-chatgpt-prompt-2026-05-27.md b/docs/research/deep-research-agentic-workflow-lit-review-chatgpt-prompt-2026-05-27.md
new file mode 100644
index 00000000..eee89910
--- /dev/null
+++ b/docs/research/deep-research-agentic-workflow-lit-review-chatgpt-prompt-2026-05-27.md
@@ -0,0 +1,607 @@
+# ChatGPT Deep Research Task: Literature Review For A Workflow-Aware Biomedical Segmentation Agent
+
+## Role
+
+Act as an external HCI / human-agent interaction / scientific workflow research agent.
+
+Your job is to perform a **current literature and systems review** and synthesize concrete design improvements for an existing prototype: a workflow-aware assistant for biomedical volume segmentation in seg.bio / PyTC Client.
+
+You are **not** expected to access the local prototype, local filesystem, or private development state. You should not claim to inspect code unless code is explicitly uploaded or pasted. This task is primarily a literature review and design synthesis task.
+
+## Core Question
+
+How should a biomedical image-segmentation assistant evolve from a useful chat/action prototype into a rigorous, workflow-aware, mixed-initiative agent?
+
+The target is not "add a chatbot." The target is closer to Codex / Claude Code in workflow discipline, but specialized for volumetric biomedical segmentation: it should inspect a mounted project, maintain grounded project memory, propose bounded app actions, ask concrete context questions, execute approved app routines, and keep the user oriented across visualization, proofreading, training, inference, evaluation, and evidence export.
+
+## Important Constraints
+
+- Do **not** assume access to the local repository or machine.
+- Do **not** over-index on implementation details unless they are included below.
+- Do **not** recommend arbitrary shell execution as the agent model.
+- Do **not** recommend exposing hidden chain-of-thought as the transparency mechanism.
+- Do **not** make unsupported claims that the assistant improves segmentation accuracy.
+- Focus on HCI, human-agent collaboration, interactive ML, scientific workflow/provenance, and bioimage-analysis workflow systems.
+
+## Prototype Context You Should Assume
+
+The prototype is a web app for biomedical image segmentation workflows. It is public-facing as:
+
+- https://demo.seg.bio
+
+Most up-to-date code context, if web-accessible:
+
+- Repository: https://github.com/PytorchConnectomics/pytc-client
+- Target branch: `checkpoint/tochi-agentic-prototype`
+- Branch URL: https://github.com/PytorchConnectomics/pytc-client/tree/checkpoint/tochi-agentic-prototype
+
+If this branch is unavailable or not fully accessible from your environment, do **not** infer code details from the default branch alone. Use the prototype context in this prompt as the authoritative current-state description, and cite public/default-branch code only as broader context with a note that it may lag the prototype.
+
+The app is built around PyTC Client / seg.bio and PyTorch Connectomics concepts, but you should treat this prompt as the source of truth if you cannot inspect the code.
+
+### Current Product Modules
+
+The app has these workflow surfaces:
+
+- **Files:** mount and inspect project folders.
+- **Visualize:** open image/mask volumes in Neuroglancer.
+- **Train Model:** configure and launch PyTorch Connectomics training.
+- **Run Model:** configure and launch inference.
+- **Progress:** track volume-level workflow status.
+- **Proofread:** review and correct segmentation masks.
+- **Assistant:** workflow-aware chat with action cards.
+
+The old `Monitor` tab has been intentionally sunset. Runtime status should live near the action surface:
+
+- training state in Train Model;
+- inference state in Run Model;
+- proofreading state in Proofread;
+- project state in Progress / workflow overview.
+
+### Current Assistant Behavior
+
+The assistant currently:
+
+- answers workflow questions in chat;
+- can suggest app actions such as opening a view, choosing data, training, inference, proofreading, evaluation, or evidence export;
+- shows action cards;
+- has approval gates for consequential actions;
+- can maintain some workflow events, artifacts, model runs, correction sets, evaluations, and volume states;
+- can scan mounted folders and infer file roles;
+- can read project manifests if present;
+- can derive volume-level progress for demo fixtures;
+- can export evidence bundles containing workflow events and artifacts.
+
+### Current Pain Points
+
+The architecture is useful but not yet formal enough:
+
+- The assistant can answer from stale or incomplete project context.
+- Project context is assembled from several places: scanned files, manifests, workflow state, progress state, user chat, and runtime events.
+- There is no single canonical project-memory contract shared by all app modules and the assistant.
+- Action cards exist, but policy for when to propose, ask, approve, execute, or refuse needs stronger formalization.
+- Initial setup can strand biologists in blank text boxes instead of guiding them through concrete detected project facts.
+- The assistant should inspect project state and ask targeted questions, but should not pretend to validate facts it cannot inspect.
+- Visible chat should feel like a normal helpful assistant; inspection details should be available through progressive disclosure.
+- Training, inference, and proofreading actions should be bounded app routines, not arbitrary shell execution.
+- Long-running jobs and artifact mutations need durable provenance.
+- The paper needs a defensible explanation of why this is a coherent human-agent workflow system, not just a UI wrapped around an LLM.
+
+## Proposed Direction To Critique And Improve
+
+The current internal recommendation is:
+
+> Build the assistant as a workflow-aware, approval-gated project operator. The central abstraction is not chat history; it is project memory plus action proposals. Chat is the conversational surface. Project memory is the source of truth. Action cards are the bridge from intent to bounded execution. Evidence events are the paper-grade provenance layer.
+
+Please critique, validate, and improve this recommendation using literature and systems evidence.
+
+### Candidate Framing
+
+Possible paper framing:
+
+- **mixed-initiative workflow agent for iterative biomedical image segmentation**
+
+Possible product framing:
+
+- **Workflow Assistant**
+- **Segmentation Workflow Assistant**
+
+Please evaluate whether this is the strongest framing. Compare against:
+
+- workflow orchestration agent;
+- mixed-initiative assistant;
+- scientific workflow manager;
+- interactive ML collaborator;
+- human-AI workflow coordinator;
+- AI copilot for bioimage segmentation;
+- agentic project operator.
+
+## Candidate Architecture To Evaluate
+
+Assume the app could be restructured around:
+
+1. **Project inspector**
+   - Reads mounted filesystem tree, project manifest, configs, image metadata, label/prediction/checkpoint availability, logs, metrics, and proofreading exports.
+
+2. **Canonical project memory**
+   - Shared state model for project facts, per-volume status, artifacts, runs, proofreading history, evaluations, user confirmations, evidence events, and freshness markers.
+
+3. **Context/retrieval layer**
+   - Builds concise, current assistant context from project memory and re-inspects when needed.
+
+4. **Assistant response layer**
+   - Produces short, normal, biologist-facing chat responses.
+
+5. **Trace/evidence layer**
+   - Provides expandable details: what was inspected, when, which files or statuses supported the answer, and uncertainty.
+
+6. **Action proposal generator**
+   - Creates typed cards for bounded app actions.
+
+7. **Approval policy**
+   - Lets read-only/navigation/form-prefill actions run with low friction; requires human approval for mutating, expensive, runtime, editor-launching, status-changing, or export actions.
+
+8. **Bounded workflow executor**
+   - Executes only app-defined routines: mount project, open viewer, prefill training/inference forms, launch training/inference, queue proofreading, mark status, export masks, compute metrics, export evidence.
+
+9. **Artifact/provenance ledger**
+   - Records observations, user confirmations, proposals, approvals/rejections, executions, artifacts, volume transitions, job statuses, metrics, and exported evidence.
+
+10. **Invalidation/reinspection loop**
+
+- Refreshes memory when files change, statuses change, jobs start/complete/fail, proofread edits are saved, app resumes, or a user asks a freshness-sensitive question.
+
+Please assess this architecture against HCI/agent/workflow/provenance literature.
+
+## Candidate Project Memory Schema To Evaluate
+
+Assume the project memory should include:
+
+- dataset/project facts:
+  - title;
+  - project roots;
+  - imaging modality;
+  - target structure;
+  - voxel size;
+  - axes;
+  - dtype;
+  - label semantics;
+  - task family;
+  - source and confirmation status for each fact.
+- task-family preset:
+  - expected inputs;
+  - expected outputs;
+  - model/config family;
+  - proofreading expectations;
+  - evaluation metrics;
+  - safe defaults.
+- per-volume state:
+  - volume id/name;
+  - image path;
+  - label path;
+  - prediction path;
+  - corrected mask path;
+  - state;
+  - state source;
+  - confidence;
+  - training/inference eligibility;
+  - shape/dtype/stats;
+  - partial-region status if relevant.
+- artifact index:
+  - configs;
+  - raw images;
+  - masks;
+  - predictions;
+  - checkpoints;
+  - logs;
+  - metrics;
+  - evidence bundles;
+  - checksums if feasible.
+- run history:
+  - training, inference, evaluation, proofreading sessions;
+  - inputs;
+  - outputs;
+  - configs;
+  - status;
+  - timestamps;
+  - metrics.
+- proofreading/edit history:
+  - source mask;
+  - corrected mask;
+  - edited regions/instances where feasible;
+  - reviewer;
+  - promotion decision.
+- user confirmations:
+  - facts corrected by user;
+  - trusted masks;
+  - training policy;
+  - task-family choice.
+- evidence events:
+  - observations;
+  - proposals;
+  - approvals/rejections;
+  - actions;
+  - status transitions;
+  - artifacts created;
+  - errors.
+- freshness/invalidation markers:
+  - last scanned;
+  - invalidated by;
+  - stale domains;
+  - reinspection need.
+
+Please improve this schema from the literature. Identify missing fields, unnecessary fields, and how to keep it minimal but credible.
+
+## Candidate Volume States To Evaluate
+
+Internal recommendation:
+
+- `image_only`
+- `draft_segmentation`
+- `needs_proofreading`
+- `proofread_ground_truth`
+- `training_candidate`
+- `queued_for_inference`
+- `prediction_ready`
+- `ignored`
+
+Please evaluate whether these states are adequate for:
+
+- mitochondria semantic segmentation;
+- mitochondria instance segmentation;
+- XRI fibre instance segmentation;
+- affinity-heavy neuron segmentation;
+- synapse/cleft segmentation;
+- partial or region-level proofreading.
+
+Suggest state names, transitions, evidence requirements, and approval requirements.
+
+## Case Study Context
+
+### Case Study 1: MitoEM / MitoEM2-Style Progress Workflow
+
+Assume a demo fixture modeled on MitoEM/MitoEM2:
+
+- EM/ssSEM mitochondria instance segmentation.
+- 6 small HDF5 smoke volumes.
+- Initial split:
+  - 2 confirmed/proofread ground truth;
+  - 2 draft segmentations needing proofreading;
+  - 2 image-only targets.
+- Voxel size: z,y,x = 30,8,8 nm.
+- Core workflow:
+  - train from confirmed/proofread ground truth;
+  - proofread draft masks;
+  - run inference on image-only volumes;
+  - evaluate with withheld ground truth where available.
+
+What the assistant should know:
+
+- not all masks are safe for training;
+- ground truth and draft segmentations are different states;
+- image-only targets should not be treated as labeled data;
+- MitoEM/MitoEM2 are about challenging 3D mitochondria instance segmentation, not just binary masks.
+
+### Case Study 2: Yixiao / TapeReader XRI Fibre Workflow
+
+Assume a demo fixture modeled on a TapeReader XRI fibre workflow:
+
+- 10 tracked XRI volumes.
+- 6 confirmed ground-truth masks: `1`, `2`, `3`, `4_1`, `4_2`, `4_3`.
+- 2 draft masks needing proofreading: `5_1`, `5_2`.
+- 2 image-only inference targets: `6_1`, `6_2`.
+- Voxel spacing: z,y,x = 40,16.3,16.3 nm.
+- Active app-compatible config: `configs/TapeReader-Fiber-BCS-AppCompat-Sanity.yaml`.
+- Paper-faithful config: `configs/TapeReader-Fiber-BCS-Original-Barcode.yaml`.
+- Reference project: https://github.com/LinghuLab/TapeReader
+- Paper/preprint: https://www.biorxiv.org/content/10.1101/2025.05.10.653182v1
+
+Core workflow:
+
+- XRI/CytoTape fibre instance segmentation.
+- Use confirmed masks for training.
+- Use draft masks for proofreading and later promotion.
+- Use image-only volumes as inference targets.
+- Preserve distinction between paper-faithful TapeReader config semantics and app-compatible PyTC fallback semantics.
+
+What the assistant should know:
+
+- training set is not "all masks in folder";
+- proofread status controls training eligibility;
+- image-only volumes are inference targets;
+- app-compatible config may be a practical fallback, not a reproduction of the paper.
+
+### Case Study 3: To Recommend
+
+Recommend the strongest third case study.
+
+Candidates:
+
+- **Lucchi++**:
+  - reliable onboarding/demo;
+  - mitochondria semantic/instance segmentation;
+  - easier for users;
+  - may overlap with MitoEM.
+- **SNEMI3D or CREMI**:
+  - affinity-heavy connectomics;
+  - stresses valid masks, partial labels, split/merge proofreading, topology-aware evaluation;
+  - likely harder to implement/demo.
+- **NucMM / Nuc3D / other non-mitochondria volumetric segmentation**:
+  - broadens biological scope;
+  - may stress nuclei instance labels rather than connectomics affinities.
+
+Please recommend the strongest third case for:
+
+- a paper prototype;
+- a reliable public demo;
+- long-term research value.
+
+These may be different recommendations.
+
+## Literature Areas To Review
+
+Use current web search and cite primary sources where possible.
+
+### 1. Human-Agent And Mixed-Initiative Interaction
+
+Review and synthesize:
+
+- mixed-initiative user interfaces;
+- intent elicitation;
+- user control and recoverability;
+- approval-gated autonomy;
+- progressive disclosure;
+- explanation as support for correction, not chain-of-thought dumping;
+- human-AI interaction guidelines.
+
+Seed references:
+
+- Eric Horvitz, "Principles of Mixed-Initiative User Interfaces";
+- Saleema Amershi et al., "Guidelines for Human-AI Interaction";
+- Amershi et al., "The Role of Humans in Interactive Machine Learning";
+- recent HCI work on human-agent collaboration, AI copilots, or workflow agents.
+
+### 2. Agentic AI / Developer Agent Systems
+
+Review design patterns from:
+
+- OpenAI Codex;
+- Claude Code;
+- GitHub Copilot agent mode / coding agent;
+- Cursor / Windsurf-like agents;
+- recent papers or technical reports on agentic coding tools;
+- tool-calling agent architectures.
+
+Treat these as systems/design references rather than scientific proof.
+
+Focus on:
+
+- inspect-plan-act loops;
+- tool calling;
+- approval gates;
+- reviewable artifacts;
+- long-running task progress;
+- traces/logs;
+- memory/context management;
+- project understanding;
+- bounded execution;
+- interruption/resume;
+- permission models.
+
+Translate carefully to biomedical workflows. Explain what transfers and what does not.
+
+### 3. Interactive Machine Learning And Human-In-The-Loop ML
+
+Review:
+
+- interactive ML;
+- active learning interfaces;
+- human correction loops;
+- human control over training data;
+- model update provenance;
+- error correction and trust calibration.
+
+Map to:
+
+- proofread masks;
+- promote corrected masks to ground truth;
+- train from confirmed data;
+- infer image-only volumes;
+- evaluate before/after results.
+
+### 4. Bioimage Workflow Tools
+
+Review:
+
+- ilastik;
+- CellProfiler;
+- Fiji/ImageJ;
+- napari;
+- napari-imagej;
+- Neuroglancer;
+- WEBKNOSSOS;
+- VAST;
+- BigDataViewer;
+- MoBIE;
+- OMERO;
+- OME-Zarr;
+- REMBI.
+
+Focus on lessons for:
+
+- guided setup;
+- non-programmer usability;
+- workflow recipes;
+- metadata;
+- project/session state;
+- annotation/proofreading;
+- volume visualization;
+- collaboration;
+- reproducibility.
+
+### 5. Connectomics And Segmentation Infrastructure
+
+Review:
+
+- PyTorch Connectomics;
+- MitoEM;
+- MitoEM2.0;
+- Lucchi++;
+- SNEMI3D;
+- CREMI;
+- CAVE / Connectome Annotation Versioning Engine;
+- proofreading/versioned annotation systems.
+
+Focus on:
+
+- semantic masks vs instance labels vs affinities;
+- train/infer/evaluate loops;
+- proofreading loops;
+- valid masks and partial annotation;
+- segmentation provenance.
+
+### 6. Scientific Workflow And Provenance
+
+Review:
+
+- W3C PROV;
+- scientific workflow management;
+- workflow provenance models;
+- experiment tracking;
+- DVC / MLflow-style lineage;
+- reproducible computational pipelines;
+- image-analysis reproducibility and metadata standards.
+
+Answer:
+
+- What is the minimum provenance model this app needs?
+- Which provenance concepts are necessary and which are overkill for the prototype?
+
+## Required Final Report Structure
+
+### 1. Executive Summary
+
+State the recommended conceptual model, architecture, and strongest paper framing.
+
+### 2. Literature Map
+
+Create a structured map of the literature/systems reviewed:
+
+| Area | Key sources | Core lesson | Relevance to seg.bio |
+| ---- | ----------- | ----------- | -------------------- |
+
+### 3. Design Principles
+
+Use a table:
+
+| Principle | Evidence | Design implication | Priority |
+| --------- | -------- | ------------------ | -------- |
+
+Principles should be specific enough to implement.
+
+### 4. Agent Model Recommendation
+
+Answer:
+
+- what the paper should call the agent;
+- what product should call it;
+- what it is not;
+- what transfers from coding agents;
+- what does not transfer.
+
+### 5. Project Memory Recommendation
+
+Propose a minimal but credible schema and explain why each part matters.
+
+### 6. Inspection And Freshness Policy
+
+Define what the agent may inspect and when it must re-inspect.
+
+### 7. Action And Approval Model
+
+Specify action categories, card fields, approval gates, execution boundaries, and refusal/blocker behavior.
+
+### 8. Context Elicitation And Onboarding
+
+Design a first-run guided intake flow for biologists.
+
+Include example questions and "I don't know" / correction flows.
+
+### 9. Volume State Machine
+
+Critique and improve the candidate states.
+
+Include transitions, evidence, approval requirements, and partial-region handling.
+
+### 10. Case Study Recommendations
+
+For MitoEM/MitoEM2 and TapeReader:
+
+- say what the assistant should know;
+- what it should ask;
+- what it should not assume;
+- what evidence it should generate.
+
+For the third case:
+
+- recommend one for paper prototype;
+- one for reliable demo if different;
+- one for long-term research if different;
+- explain tradeoffs.
+
+### 11. Evaluation Plan
+
+Propose a realistic HCI/systems evaluation:
+
+- participant profile;
+- tasks;
+- conditions/baselines;
+- instrumentation/logging;
+- quantitative metrics;
+- qualitative interview prompts;
+- defensible claims;
+- claims to avoid.
+
+### 12. Implementation Roadmap From Literature
+
+Prioritize improvements:
+
+- immediate prototype improvements;
+- paper-demo requirements;
+- production requirements;
+- research extensions.
+
+For each, include:
+
+- user value;
+- system change;
+- what evidence/logging it needs;
+- how to evaluate it.
+
+### 13. Open Questions
+
+List decisions the team must make.
+
+## Citation Requirements
+
+- Include links for every cited paper/system.
+- Prefer peer-reviewed papers, official docs, and primary project docs.
+- For product references such as Codex/Claude Code/Copilot/Cursor, treat them as design-pattern examples, not scientific validation.
+- Be careful with publication dates and versions.
+- If a source is uncertain, say so.
+
+## Output Style
+
+- Be concrete and implementation-oriented.
+- Avoid generic phrases like "use RAG" unless you specify what gets retrieved, when, and how freshness is handled.
+- Do not dump huge JSON unless it helps implementation.
+- Use markdown tables where they improve clarity.
+- End with a concise recommendation paragraph.
+
+## Final Recommendation Shape
+
+End with a recommendation similar in concreteness to:
+
+> Build the assistant as a workflow-aware, approval-gated project operator. The central abstraction is not chat history; it is project memory plus action proposals. Chat is the conversational surface. Project memory is the source of truth. Action cards are the bridge from intent to bounded execution. Evidence events are the paper-grade provenance layer.
+
+You may change the wording if your literature review suggests a better framing, but the final recommendation must be equally concrete.
diff --git a/docs/research/deep-research-engineering-synthesis-2026-05-24.md b/docs/research/deep-research-engineering-synthesis-2026-05-24.md
new file mode 100644
index 00000000..f111e483
--- /dev/null
+++ b/docs/research/deep-research-engineering-synthesis-2026-05-24.md
@@ -0,0 +1,189 @@
+# Deep Research Engineering Synthesis
+
+Date: 2026-05-24
+
+Source: user-provided deep research report, "Designing Human-Agent Collaboration for Iterative Biomedical Image Segmentation."
+
+This note translates the research output into engineering and product choices for the current PyTC Client / seg.bio prototype. It is intentionally implementation-facing: what to build, what to simplify, and what claims the app should support.
+
+## Core Interpretation
+
+The strongest product direction is not "chatbot next to PyTC." It is a workflow-aware coordination layer for iterative biomedical segmentation. The assistant should help users move through inspection, visualization, proofreading, training, inference, and evaluation while keeping project state and artifact provenance legible.
+
+The research strongly reinforces several issues already found in the local technical audit:
+
+- project context needs to be structured and continuously refreshed;
+- agent actions need one approval-gated execution model;
+- visible chat should be natural and short, with details behind "What I checked";
+- project onboarding should start with mechanical inspection and guided questions, not a blank prompt;
+- volume state should be a core object, not inferred repeatedly from filenames;
+- task-family presets matter because semantic masks, instance labels, affinities, proofreading, and evaluation metrics differ across PyTC workflows.
+
+## Product Decisions To Adopt
+
+### 1. Treat Project Memory As The Center
+
+The canonical system object should be a structured project memory, not the chat transcript and not the current form fields.
+
+Minimum schema:
+
+- `project_facts`: modality, target structure, voxel size, task family, dataset family, optimization preference.
+- `artifact_index`: raw images, labels, predictions, configs, checkpoints, logs, metrics, screenshots, evidence bundles.
+- `volumes`: one row per volume or subvolume with image path, segmentation path, prediction path, status, status source, and provenance.
+- `runs`: training, inference, evaluation, proofreading sessions, and their output artifacts.
+- `evidence_events`: facts observed, user confirmations, agent suggestions, approvals, failures, and artifact mutations.
+
+Design consequence: the assistant should answer from this memory plus fresh targeted probes, not from stale summaries or unstructured chat history.
+
+### 2. Keep Chat Human, Keep Mechanics Expandable
+
+User-facing assistant responses should read like a normal collaborator:
+
+- short summary first;
+- one concrete next move;
+- no "Current read / Why this fits / Blocker" boilerplate in normal speech;
+- no dumped JSON, config fragments, or internal decision fields in the visible answer.
+
+Mechanical details belong in expandable traces:
+
+- files checked;
+- volume counts;
+- manifest/config matched;
+- exact reason a volume entered a training set;
+- runtime/log status;
+- warnings and uncertainty.
+
+Design consequence: the agent response object should separate `message`, `trace`, `proposal`, and `state_update`. The renderer should never have to infer which parts are human-facing.
+
+### 3. Use Action Cards As The Only Consequential Execution Path
+
+Every consequential action should use the same lifecycle:
+
+1. observe current project state;
+2. propose a bounded app routine;
+3. show scope, inputs, outputs, expected cost, and why now;
+4. wait for explicit approval when the action mutates artifacts or starts compute;
+5. execute through a typed app routine;
+6. write events/artifacts back to project memory;
+7. update the visible chat with success/failure.
+
+This should replace the current split between ad hoc actions, commands, durable proposals, runtime actions, and client effects.
+
+### 4. Make Per-Volume State First-Class
+
+The progress table should become the canonical user's-eye state of the project:
+
+- `ground_truth`: curated and training-ready;
+- `needs_proofreading`: segmentation exists but should not be used as ground truth yet;
+- `image_only`: raw image exists, no segmentation/prediction yet;
+- `predicted`: model output exists and needs review;
+- `ignored`: intentionally out of scope.
+
+Each status needs provenance:
+
+- detected from file naming;
+- imported from manifest;
+- marked by user;
+- produced by inference;
+- promoted from proofreading;
+- overridden by agent/user.
+
+Design consequence: training/inference/proofreading actions should select volumes from this state table, not re-derive their own private volume sets.
+
+### 5. Guided Onboarding Should Be Inspect-First
+
+The first project flow should be:
+
+1. mount directory;
+2. inspect files/configs/checkpoints/metadata;
+3. show what was detected;
+4. ask two or three concrete questions only when needed;
+5. let the user correct individual facts;
+6. save context as project memory.
+
+Avoid asking a biologist to start with a blank "describe project" box. Optional notes can remain, but they should not be the main gate.
+
+### 6. Task Families Need Presets
+
+The app should not treat all segmentation as the same. At minimum:
+
+- mitochondria semantic segmentation, e.g. Lucchi++;
+- mitochondria instance segmentation, e.g. MitoEM / MitoEM2;
+- neuron affinity segmentation, e.g. SNEMI3D;
+- synaptic cleft segmentation, e.g. CREMI;
+- nuclei instance segmentation, e.g. NucMM.
+
+Each preset should define expected inputs, output heads, proofreading expectations, evaluation metrics, and safe default run settings.
+
+## Near-Term Engineering Backlog
+
+### P0: Fix Agent Intent And Action Reliability
+
+- Keep semantic intent prompt and validation from one source of truth.
+- Add tests for prompt-listed intents.
+- Replace fragmented action/proposal execution with one `ActionExecution` envelope.
+- Ensure approval always produces a visible status update and either a form prefill, started job, or actionable failure.
+
+### P0: Resume, Do Not Reset, Workflow State
+
+- Hydrate the continuous big chat and mounted project state from server workflow records.
+- Stop page reloads from creating fresh workflows unless the user explicitly starts a new project.
+- Keep browser storage as cache only.
+
+### P1: Build Structured Project Memory
+
+- Promote current `project_context`, `project_observation`, `project_progress_snapshot`, and sidecar artifacts into a normalized project-memory shape.
+- Add invalidation rules: re-scan only affected folders/artifacts when files, statuses, or run outputs change.
+- Add a "Project memory" inspection panel for debugging and study evidence.
+
+### P1: Make Training Sets Real Artifacts
+
+- Replace directory-of-symlinks training subsets with a PyTC-compatible manifest, combined volume, or explicit supported file list.
+- Dry-run the staged config by constructing the dataset before launching expensive training.
+- Show selected training volumes and excluded volumes on the approval card and Train Model form.
+
+### P1: Strengthen Proofreading-To-Training Provenance
+
+- Treat proofread masks as versioned artifacts.
+- Store which instances/regions were edited.
+- Support promotion from prediction/draft to ground truth only through explicit user action.
+- Plan for `valid_mask` support so partially annotated regions can become training-ready without pretending the whole volume is complete.
+
+### P2: Evaluation And Evidence Export
+
+- Add evaluation as a real stage: baseline prediction, proofread correction, retraining run, candidate prediction, metrics, evidence bundle.
+- Export logs/events/configs/metrics/status transitions as a case-study evidence package.
+
+## UI Streamlining Implications
+
+- Files should focus on mounted project inspection and detected roles, not just a file-browser clone.
+- Progress should become the project control surface: row actions for view, proofread, mark ground truth, ignore, train on selected, infer missing.
+- Train Model should show training set membership, not just one image path and one label path.
+- Run Model should show target volumes and output registration into project progress.
+- Proofread should expose "use edits for training" as a status transition with artifact provenance.
+- The assistant panel should render one primary proposal card at a time, with an obvious execution state.
+
+## Paper Positioning Notes
+
+The strongest manuscript claim is:
+
+> Iterative biomedical image segmentation is bottlenecked by workflow coordination across inspection, inference, proofreading, retraining, and evaluation. This prototype contributes a workflow-aware, approval-gated human-agent interface that keeps project context visible and helps users move through that loop.
+
+Safe claims:
+
+- integrates fragmented workflow stages;
+- keeps per-volume workflow state visible;
+- uses approval-gated actions;
+- supports closed-loop correction and retraining as an interaction design;
+- reduces manual translation between software-specific steps.
+
+Avoid until backed by study data:
+
+- improves segmentation accuracy;
+- reduces effort for all bioimage domains;
+- safely automates scientific workflows;
+- generalizes across all biomedical imaging tasks.
+
+## Immediate Code Change From This Synthesis
+
+The semantic intent prompt/validator mismatch was fixed in the same pass that created this synthesis. This is a small but important example of the larger principle: agent semantics need typed contracts, not duplicated prompt prose and code allowlists.
diff --git a/docs/research/internal-technical-audit-2026-05-24.md b/docs/research/internal-technical-audit-2026-05-24.md
new file mode 100644
index 00000000..761f5c18
--- /dev/null
+++ b/docs/research/internal-technical-audit-2026-05-24.md
@@ -0,0 +1,845 @@
+# Internal Technical Audit - Agentic PyTC Client
+
+Date: 2026-05-24
+
+Repo: `/home/weidf/deploy/pytc-client-demo2`
+
+Branch: `checkpoint/tochi-agentic-prototype`
+
+This report is an internal engineering pass over the current app state after the MitoEM2 progress demo, project progress tracker, guided project context flow, continuous workflow chat, Monitor-tab sunset, and agent action-card work. It focuses on bugs, technical incongruities, UI streamlining, and ways to expand the agent into a more useful workflow collaborator.
+
+## What I Inspected
+
+Primary files and systems:
+
+- Frontend shell and state: `client/src/App.js`, `client/src/contexts/GlobalContext.js`, `client/src/contexts/WorkflowContext.js`, `client/src/api.js`
+- Main workflow UI: `client/src/views/Views.js`, `FilesManager.js`, `Visualization.js`, `ModelTraining.js`, `ModelInference.js`, `ProjectProgress.js`, `MaskProofreading.js`
+- Chat UI: `client/src/components/Chatbot.js`, `AssistantTrace`, action/proposal card handling
+- Runtime config/client launch: `client/src/runtime/modelLaunch.js`, `client/src/configSchema.js`
+- Backend app: `server_api/main.py`, `runtime_settings.py`, `app_event_logger.py`
+- Workflow agent/backend orchestration: `server_api/workflows/router.py`, `service.py`, `db_models.py`, `agent_plan.py`, `volume_io.py`
+- File/project mounting and context scan: `server_api/auth/router.py`
+- Worker runtime: `server_pytc/services/model.py`
+- Proofreading backend/frontend: `server_api/ehtool/router.py`, `server_api/ehtool/data_manager.py`, `client/src/views/ehtool/DetectionWorkflow.js`, `ProofreadingEditor.js`
+- Tests and docs touched by recent work: `tests/test_workflow_routes.py`, `tests/test_file_workspace_routes.py`, `client/src/components/Chatbot.test.js`, `client/src/views/FilesManager.test.js`, `docs/codex-working-memory/progress-log.md`
+
+Validation run during this audit:
+
+- `.venv/bin/python -m py_compile server_api/workflows/router.py server_api/auth/router.py server_api/main.py server_pytc/services/model.py server_api/ehtool/router.py server_api/ehtool/data_manager.py runtime_settings.py app_event_logger.py`
+- `CI=true npm test -- --runInBand src/views/Views.test.js src/components/Chatbot.test.js src/views/FilesManager.test.js src/utils/projectSuggestions.test.js`
+  - Passed: 55 tests
+  - Existing warning: FilesManager async state updates are not wrapped in `act(...)` in tests
+- `CI=true npm run build`
+  - Passed with existing EHTool hook dependency warnings and large bundle warning
+- `.venv/bin/python -m pytest tests/test_workflow_routes.py tests/test_file_workspace_routes.py -q`
+  - Passed: 61 tests, 12 dependency/deprecation warnings
+
+## Executive Readout
+
+The prototype now has many of the right ingredients: mounted-project scanning, volume-pair discovery, project context memory, progress snapshots, proofread artifacts, durable workflow commands, action cards, runtime logs, and a broad app-event log. The main issue is that these parts are still stitched together by ad hoc metadata, UI side effects, and heuristic routing rather than a single canonical workflow state model.
+
+The two most urgent product-level gaps are:
+
+1. The agent does not yet have a reliable observe-orient-act loop over project state. It observes files and progress, but this is embedded in `server_api/workflows/router.py` and stored in mutable JSON blobs rather than exposed as a small set of typed tools and state records.
+2. User-facing agent actions are too fragile. An action can be a chat item, a proposal, a durable command, a runtime action, a client effect, or some combination. This creates regressions like "Approve does nothing", hidden form prefill failures, stale cards, and confusing training state.
+
+The most concrete bug found in this pass is in the semantic workflow router: the prompt asks the LLM to emit intents that the validation set rejects. That means the LLM can make the right semantic decision and the app will discard it.
+
+## Highest Priority Bugs And Risks
+
+### 1. Semantic Router Rejects Its Own Prompted Intents
+
+Evidence:
+
+- `server_api/workflows/router.py` `SEMANTIC_WORKFLOW_INTENTS` omits `style_feedback`, `project_files`, and `project_progress`.
+- `_semantic_intent_payload()` prompt lists all three as valid intents.
+- If the LLM returns one of these prompt-listed intents, the backend rejects it with:
+  - `if intent not in SEMANTIC_WORKFLOW_INTENTS: return {}`
+
+Why it matters:
+
+- This directly undermines the recent work to make the agent understand less explicit user requests.
+- It explains some "robotic" or irrelevant fallback responses even when the semantic model was likely correct.
+- It makes app behavior dependent on whether the regex fallback happens to catch the same wording.
+
+Recommendation:
+
+- Add the missing intents to `SEMANTIC_WORKFLOW_INTENTS`.
+- Add a unit test that asserts every intent listed in the semantic prompt is present in the validation set.
+- Consider defining intents once as structured data and generating both prompt text and validation from it.
+
+### 2. App Boot Still Resets Workflow And File State
+
+Evidence:
+
+- `client/src/App.js` `CacheBootstrapper` calls `resetFileState()` before rendering the workflow provider.
+- `client/src/contexts/WorkflowContext.js` `bootFreshSession()` calls:
+  - `resetFileWorkspace()`
+  - `clearLocalWorkflowInputs()`
+  - `startNewWorkflowApi({ metadata: { created_from: "page_reload" } })`
+
+Why it matters:
+
+- This conflicts with the desired "one continuous big chat/workflow in the same session" model.
+- It can erase mounted file indexes, selected paths, workflow context, and active runtime-facing state on reload.
+- It makes debugging confusing because reloads create fresh workflow records and reset local state even if the user is still in the same browser session.
+
+Recommendation:
+
+- Replace fresh boot with resume-first boot:
+  - call `getCurrentWorkflow()`;
+  - hydrate file/project state from workflow metadata;
+  - only reset when the user explicitly clicks New project or Reset workspace.
+- Keep an explicit `session_generation` or `workflow_generation` field to invalidate stale cards without nuking the workspace.
+
+### 3. "Persisted" App State Is Not Persisted
+
+Evidence:
+
+- `client/src/contexts/GlobalContext.js` imports `localforage`, but `usePersistedState(_key, defaultValue)` is a thin `useState` wrapper.
+- `resetFileState()` removes localforage keys that are not actually written by `usePersistedState`.
+
+Why it matters:
+
+- The code reads as if local state persists, but it does not.
+- This makes chat/workflow state behavior harder to reason about and increases hidden reliance on backend workflow records.
+
+Recommendation:
+
+- Either restore real persisted state for selected fields or rename this helper to make it honest.
+- Prefer workflow-backed hydration for scientific project state, not browser-only caches.
+
+### 4. Main Chat Routing Sends Nearly Every Message To The Workflow Agent
+
+Evidence:
+
+- `client/src/components/Chatbot.js` `shouldUseWorkflowAgent()` returns true for any non-empty query when a workflow exists:
+  - `isWorkflowAgentQuery(...) || isWorkflowFollowUpQuery(...) || query.trim().length > 0`
+
+Why it matters:
+
+- The general RAG chat path is effectively dead in normal workflow sessions.
+- The workflow agent has to answer everything, including ordinary conceptual questions and UI tone feedback.
+- If the workflow agent is over-constrained, every response inherits the same robotic workflow template.
+
+Recommendation:
+
+- Route by intent class:
+  - workflow agent for workflow state, app actions, mounted project state, and run orchestration;
+  - docs/RAG for conceptual PyTC questions;
+  - conversational model path for open-ended explanation or tone feedback.
+- Keep a single visible chat, but allow multiple internal responders behind it.
+
+### 5. Continuous Chat Is Split Between Browser SessionStorage And Server DB
+
+Evidence:
+
+- `Chatbot.js` stores visible messages in `sessionStorage` under `pytc.workflowAssistant.continuousChat.v1`.
+- `server_api/workflows/router.py` persists workflow-agent exchanges to `chat_messages` through `_persist_workflow_agent_chat_exchange()`.
+- The frontend does not hydrate visible chat from the workflow-agent conversation on boot.
+- Legacy `/chat/conversations` endpoints still exist in `server_api/main.py`.
+
+Why it matters:
+
+- Closing and reopening the drawer in the same session works, but reloads and cross-device sessions are fragile.
+- The backend has a richer durable history than the frontend uses.
+- Stale card sanitization exists because old frontend-only cards can outlive their workflow.
+
+Recommendation:
+
+- Make server workflow chat the source of truth.
+- Keep `sessionStorage` only as an optimistic display cache.
+- Hydrate visible chat from `GET /workflow/{id}/agent/conversation` or equivalent.
+- Store card/action state by workflow/action id, not just by serialized frontend messages.
+
+### 6. Agent Action Execution Has Too Many Overlapping Concepts
+
+Current concepts:
+
+- Chat `actions`
+- Chat `commands`
+- Workflow `proposals`
+- Durable `WorkflowCommand`
+- `client_effects`
+- `runtime_action`
+- `pendingRuntimeAction`
+- `lastClientEffects`
+
+Why it matters:
+
+- User-facing regressions have repeatedly appeared around "Approve" and "Run in app".
+- `approveAgentAction()` applies client effects without runtime, runs a durable command, then sets `pendingRuntimeAction` to `monitor_training`, not `start_training`.
+- Some actions execute immediately, some require approval, some create commands, and some only prefill UI.
+- Failure states are not consistently appended to the chat as human-readable messages.
+
+Recommendation:
+
+- Introduce a typed `ActionExecution` state machine:
+  - `proposed`
+  - `approved`
+  - `prefilling`
+  - `ready_to_run`
+  - `starting`
+  - `running`
+  - `completed`
+  - `failed`
+  - `rejected`
+- Use one action envelope for all agent-to-app work:
+  - `kind`
+  - `risk`
+  - `required_inputs`
+  - `client_prefill`
+  - `server_command`
+  - `runtime_watch`
+  - `expected_visible_result`
+- Render that envelope consistently in chat, forms, and runtime panels.
+
+### 7. Training Subset Plan Is Still Fragile
+
+Evidence:
+
+- `server_api/workflows/router.py` `_build_progress_training_subset_plan()` symlinks selected images and labels into:
+  - `/home/weidf/demo_data/.pytc_training_subsets/<project>/<run>/image`
+  - `/home/weidf/demo_data/.pytc_training_subsets/<project>/<run>/seg`
+- `server_pytc/services/model.py` later converts directory inputs into file lists using a subset manifest or direct directory scan.
+- The user already saw `ValueError: unrecognizable file format for .../workflow_.../image`, indicating at least one path reached PyTC as a directory instead of a concrete file/list-compatible input.
+
+Why it matters:
+
+- This is the heart of progress-based training. If it fails, "train on fully good volumes" cannot be trusted.
+- PyTC configs may expect a single H5, a list field, a directory pattern, or a dataset-specific loader. A generic directory of symlinks is not a universal contract.
+
+Recommendation:
+
+- Make "multi-volume training set" a first-class runtime input:
+  - either write a PyTC-compatible manifest that the dataset loader explicitly understands;
+  - or create a combined H5/Zarr stack with matching image/label arrays;
+  - or add a config schema path that is explicitly a list of volume files.
+- Before launching, validate the final staged config by instantiating the dataset or running a dry-run loader check.
+- Show the exact training volumes in the approval card with counts, status filters, and excluded volumes.
+
+### 8. Config Mutation Is Duplicated Across Client And Worker
+
+Evidence:
+
+- `client/src/runtime/modelLaunch.js` mutates YAML for launch defaults and output/input paths.
+- `server_pytc/services/model.py` also applies path overrides, sanitizes numeric values, resolves missing direct volume paths, coerces inference aug count, and applies "agent safe training defaults".
+
+Why it matters:
+
+- Client and worker can drift.
+- Debugging staged configs is harder because multiple layers mutate YAML.
+- The agent approval card may describe one config while the worker launches another.
+
+Recommendation:
+
+- Move all runtime config staging into the backend/worker.
+- Let frontend only display proposed structured fields and call a `stage_config`/`preview_config` endpoint.
+- Store a config diff artifact in workflow evidence for every launch.
+
+### 9. Project Context Memory Is Written Into Mounted Source Directories
+
+Evidence:
+
+- `server_api/auth/router.py` writes `.pytc_project_context.json` into the mounted project directory.
+- `reset_workspace()` deletes that hidden file from mounted roots.
+- EHTool also writes `.pytc_proofreading.json` and `.pytc_instance_labels.tif` alongside source mask/data directories.
+
+Why it matters:
+
+- For real biology projects, writing hidden metadata into source data directories can surprise users.
+- Resetting app workspace should not silently delete project memory unless the user explicitly asks.
+- Multiple app-side hidden files create mixed ownership between source data and app state.
+
+Recommendation:
+
+- Store app-managed project memory in an app workspace keyed by project root hash.
+- If writing sidecars into the project is useful, ask explicitly and show where they live.
+- Split "unmount/reset app index" from "delete project context sidecars".
+
+### 10. File Manager And Workflow Router Are Too Monolithic
+
+Evidence:
+
+- `client/src/views/FilesManager.js` is over 4,000 lines.
+- `server_api/workflows/router.py` is around 7,900 lines.
+- `server_api/main.py` and `server_api/auth/router.py` are also multi-thousand-line modules.
+
+Why it matters:
+
+- Cross-feature changes have high regression risk.
+- The codebase lacks obvious ownership boundaries for:
+  - project scanning;
+  - project memory;
+  - agent intent routing;
+  - action proposal/execution;
+  - progress tracking;
+  - runtime launch;
+  - file tree sync.
+
+Recommendation:
+
+- Split by domain:
+  - `project_observation.py`
+  - `project_progress.py`
+  - `agent_intents.py`
+  - `agent_actions.py`
+  - `runtime_commands.py`
+  - `project_memory.py`
+  - frontend hooks/components for file tree, setup wizard, context audit, and role mapping.
+
+## Agent And Orchestration Findings
+
+### The Agent Needs A Canonical Observe-Orient-Act Loop
+
+The current agent can inspect state, but the inspection is embedded inside `query_workflow_agent()`. A stronger architecture would define explicit tools:
+
+- `list_project_tree(root, depth, filters)`
+- `inspect_volume(path)`
+- `sample_volume_slices(path, count, axes)`
+- `discover_image_label_pairs(root)`
+- `read_project_manifest(root)`
+- `read_progress_tracker(workflow_id)`
+- `update_project_memory(fact, source, confidence)`
+- `stage_visualization(image, label, scales)`
+- `stage_training_run(training_set, config, output)`
+- `inspect_runtime_failure(run_id)`
+
+The agent should call these tools as part of a bounded loop and return:
+
+- a normal human response;
+- an expandable trace of what it checked;
+- one or more typed action proposals.
+
+### Project Memory Should Be Structured, Versioned, And Source-Aware
+
+The app already stores:
+
+- `project_context`
+- `project_observation`
+- `project_progress_snapshot`
+- `active_volume_pair`
+- `volume_pair_discovery`
+- `.pytc_project_context.json`
+- `.pytc_proofreading.json`
+
+But these are not yet one cohesive system. The project memory model should distinguish:
+
+- User-provided facts: "we care about mitochondria", "prioritize accuracy"
+- Mechanically verified facts: H5 shape, dtype, voxel size from metadata, pair shape match
+- Agent inferences: likely image/seg pairing, likely dataset purpose
+- Workflow decisions: selected active pair, selected training subset
+- Runtime outcomes: checkpoint path, prediction path, proofread artifact path
+
+Each memory item should carry:
+
+- `key`
+- `value`
+- `source`
+- `confidence`
+- `observed_at`
+- `valid_for_path`
+- `supersedes`
+- `needs_user_confirmation`
+
+### The Agent Should Be Allowed To Be Human-Facing Without Losing Rigor
+
+The recent `AssistantTrace` pattern is the right direction. The chat should speak normally:
+
+- "I found two clean ground-truth volumes. I can train on those and leave the two draft masks out."
+
+The expandable trace should carry rigor:
+
+- files checked;
+- status counts;
+- exact paths;
+- assumptions;
+- reasons for excluding volumes.
+
+Do not put all mechanical detail in the top-level chat message unless the user asks for it.
+
+### The Agent Currently Offers Too Few Simultaneous Useful Actions
+
+Evidence:
+
+- `_one_app_suggestion()` intentionally reduces actions to a single primary action.
+
+Why it matters:
+
+- For a scientific workflow, the agent often should offer a small set of adjacent actions:
+  - "View first pair"
+  - "Open progress"
+  - "Train on good masks"
+  - "Proofread draft masks"
+- Reducing to one action makes the agent feel less capable and forces additional chat turns.
+
+Recommendation:
+
+- Allow up to 2 or 3 action cards when they are distinct and safe.
+- Group related cards under "I can do these next".
+- Keep destructive or expensive actions approval-gated.
+
+## UI Streamlining Opportunities
+
+### Guided Project Intake Should Replace Blank Free Text
+
+The current guided project setup is an improvement, but the product direction should be:
+
+- Start with "I checked your folder" summary.
+- Ask 3 to 5 concrete questions with selectable choices:
+  - What are we segmenting?
+  - What imaging modality is this?
+  - Which masks are ground truth versus draft?
+  - What should count as done?
+  - Is speed or accuracy more important?
+- Offer "I do not know" and "Use detected default" for each.
+- Allow optional voice/free-text note after structured choices.
+
+Biologists should not have to know what project context is useful to the agent.
+
+### Progress Page Needs Direct Workflow Actions
+
+Current state:
+
+- The Progress page gives counts and manual status dropdowns.
+
+Missing:
+
+- Per-row actions:
+  - View image/mask
+  - Open proofreader
+  - Mark as ground truth with note
+  - Run inference on this volume
+  - Exclude from training
+- Multi-select actions:
+  - Train on selected ground truth
+  - Proofread selected draft masks
+  - Segment selected missing masks
+- Notes/reasons:
+  - "marked ground truth by Adam"
+  - "excluded because shape mismatch"
+
+### Training Approval Card Needs A Compact Summary
+
+The raw path-heavy card is hard to parse. A better training proposal card:
+
+- Title: "Train on 2 ground-truth volumes"
+- Summary chips:
+  - Training set: 2 proofread GT
+  - Targets after training: 2 missing masks
+  - Excluded: 2 draft masks
+  - Config: MitoEM2 Pyra demo
+  - Output: `outputs/training/<run>`
+- Expandable details:
+  - exact paths;
+  - config diff;
+  - manifest path;
+  - runtime defaults.
+- Buttons:
+  - Review in Train Model
+  - Approve and start
+  - Edit selection
+
+### Runtime Pages Need Stronger "What Is Happening" State
+
+Train/Run pages should visually separate:
+
+- Proposed but not approved
+- Prefilled and ready
+- Submitted to worker
+- Running
+- Finished
+- Failed
+
+On failure, the page should offer:
+
+- "Ask agent to inspect failure"
+- "Open log"
+- "Copy diagnostic bundle"
+- "Retry with fixed config"
+
+### File Manager Should Be Less Central To Everything
+
+FilesManager now owns too many workflows:
+
+- mounting;
+- project setup;
+- context editing;
+- audit display;
+- role mapping;
+- file operations;
+- preview;
+- project suggestions;
+- reset/unmount.
+
+Recommended UI split:
+
+- Files page: browsing, preview, mount/unmount
+- Project Setup drawer/page: context, audit, role mapping
+- Progress page: volume status and workflow actions
+- Assistant panel: propose/reroute actions
+
+## Runtime And Data Findings
+
+### Neuroglancer Is Better, But Needs Metadata Spot-Checks
+
+Good:
+
+- Viewer URLs are retained server-side.
+- Mixed-content handling and public base URL are handled.
+- Scales are now required and pulled from workflow/project context.
+- Folder-level inputs can resolve to concrete volume pairs.
+
+Risk:
+
+- Axis/order assumptions are still implicit. Volumes are treated as z,y,x after loading.
+- The weird-looking MitoEM2 dummy data may be a real data-crop choice, an axis rendering issue, or a contrast/shape issue. The app has no first-class "volume sanity check" panel to explain this.
+
+Recommendation:
+
+- Add a volume inspector panel:
+  - shape;
+  - dtype;
+  - min/max/percentiles;
+  - voxel size;
+  - selected dataset key inside H5;
+  - thumbnail slices along z/y/x;
+  - warnings for very small z depth, low dynamic range, wrong-looking axis ratio.
+
+### EHTool Proofreading State Is Useful But Too Hidden
+
+Good:
+
+- `DataManager` persists instance edits to `.pytc_instance_labels.tif`.
+- It persists review state to `.pytc_proofreading.json`.
+- It records workflow events for classification and mask save.
+
+Risks:
+
+- `_data_managers` is an in-memory dict keyed by session id. Process restart reloads from DB paths, but cache behavior and multi-user/process behavior are not robust.
+- Sidecar artifacts live next to source data.
+- Project Progress does not yet directly consume proofreading completion in a first-class way.
+
+Recommendation:
+
+- Register proofread artifacts as workflow artifacts.
+- Link proofread artifacts back to progress volumes.
+- Use proofread completion to update `ground_truth` status automatically only after explicit "Use edits for training" or "Mark good" confirmation.
+
+### Runtime Logging Is Broad But Needs Correlation
+
+Good:
+
+- Client event logging captures console/network/DOM/resource events.
+- Server middleware logs requests and response codes.
+- Worker logs runtime command, config snapshots, subprocess output, TensorBoard status, and artifacts.
+
+Gaps:
+
+- Client logs and server request logs are not consistently tied by a propagated `x-request-id`.
+- Chat query -> proposal -> approval -> command -> worker process -> artifact is not one explicit trace id.
+- Logging is very high volume and may leak paths/config text into app logs.
+
+Recommendation:
+
+- Add `workflow_trace_id` to every action card and propagate it through:
+  - chat query;
+  - proposal event;
+  - command row;
+  - API request;
+  - worker runtime state;
+  - app event log;
+  - generated artifacts.
+- Add redaction controls for paths and full config text when needed.
+
+## File And Project Context Findings
+
+### Project Mounting Can Be Expensive And Noisy
+
+Evidence:
+
+- Mounting recursively indexes source dirs into DB.
+- Project scans skip some ignored names, but mounted tree can still include dot/cache directories.
+- `get_files(parent)` repairs stale mounted entries and prunes uploads on requests.
+
+Risks:
+
+- Large biology projects can have huge folders.
+- Folder refreshes can produce UI stalls or apparent empty folders if backend scans lag or fail.
+
+Recommendation:
+
+- Use lazy tree indexing by folder.
+- Store scan status per folder:
+  - unscanned;
+  - scanning;
+  - scanned;
+  - failed;
+  - stale.
+- Surface scan errors and partial states in the UI.
+
+### File Preview And Properties Are Partial
+
+Evidence:
+
+- File preview supports some image/TIFF paths but not HDF5 previews generally.
+- Properties modal uses placeholder timestamps rather than backend metadata.
+
+Recommendation:
+
+- Use the volume inspector for HDF5/Zarr/N5.
+- Do not show fake created/modified metadata.
+- Add "copy absolute path" and "inspect datasets" for H5.
+
+### Progress Pairing Is Heuristic
+
+Evidence:
+
+- `server_api/workflows/router.py` derives pair keys from file names and token matching.
+- It uses markers like `gt`, `curated`, and `consensus` to infer ground truth.
+- Manual overrides exist, but notes/reasons are not exposed in the UI.
+
+Risks:
+
+- Datasets with nonstandard naming can be mispaired.
+- Draft segmentations can be treated as ground truth or vice versa if names are misleading.
+
+Recommendation:
+
+- Store explicit volume records:
+  - `image_path`
+  - `segmentation_path`
+  - `segmentation_status`
+  - `status_source`
+  - `status_note`
+  - `validated_shape_match`
+  - `last_viewed_at`
+  - `proofread_artifact_path`
+- Let project setup confirm pair mapping once, then stop relying on repeated filename inference.
+
+## Frontend Technical Findings
+
+### API Base Pathing Is Confusing
+
+Evidence:
+
+- `apiClient` baseURL is `${origin}/api` in production.
+- Workflow API methods call paths like `/api/workflows/current`, producing public paths like `/api/api/workflows/current`.
+- Some endpoints use raw `axios` and `BASE_URL`; others use `apiClient`.
+
+Why it matters:
+
+- The app works because deployment routes have been adapted around this, but it is easy to break.
+- Docs already mention both `/api/workflows` and `/api/api/workflows`.
+
+Recommendation:
+
+- Normalize frontend API paths:
+  - baseURL should be origin only, and all paths include `/api`;
+  - or baseURL should be `/api`, and paths must not start with `/api`.
+- Add tests for deployed URL construction.
+
+### Debug Logs Are Still In Production-Built Code
+
+Evidence:
+
+- `client/src/api.js`, `InputSelector.js`, `ModelTraining.js`, `ModelInference.js`, and EHTool router have debug `console.log`/diagnostic prints.
+- `server_api/ehtool/router.py` prints "EHTOOL ROUTER MODULE LOADED - VERSION: DEBUG v2" at import time.
+
+Recommendation:
+
+- Gate debug logs behind a logging helper or env flag.
+- Keep app-event logs structured and avoid duplicate raw console spam.
+
+### Build Warnings Should Be Addressed
+
+Current build warnings:
+
+- EHTool hook dependency warnings in `DetectionWorkflow.js`
+- EHTool hook dependency warnings in `ProofreadingEditor.js`
+- Bundle size warning: main JS around 694 kB gzip
+
+Recommendation:
+
+- Fix hook dependencies deliberately. For canvas-heavy components, move imperative drawing functions into refs/callbacks to avoid stale closures.
+- Code-split EHTool/proofreading and Neuroglancer-heavy paths so the first load is smaller.
+
+## Backend Technical Findings
+
+### Workflow Metadata JSON Is Carrying Too Much Contract
+
+Examples:
+
+- `project_context`
+- `project_observation`
+- `project_progress_snapshot`
+- `project_progress_overrides`
+- `active_volume_pair`
+- `volume_pair_discovery`
+- `neuroglancer_proofreading`
+- runtime-ish fields
+
+Risk:
+
+- Important state has weak validation, weak migrations, and no typed ownership.
+
+Recommendation:
+
+- Keep metadata as an extension field, but move core concepts into typed tables or Pydantic schemas:
+  - project memories;
+  - volume records;
+  - action executions;
+  - runtime runs;
+  - proofread artifacts.
+
+### Legacy Generic Chat Has Process-Global State
+
+Evidence:
+
+- `server_api/main.py` has module-level `_active_convo_id` and `_chat_history` for generic chat.
+
+Risk:
+
+- Multi-user or multi-session chat can leak context or behave unpredictably.
+- This is especially risky if one visible chat remains but routes between workflow and generic chat.
+
+Recommendation:
+
+- Remove process-global chat state.
+- Persist all chat history by conversation id and workflow id.
+
+### Durable Commands Only Support Training
+
+Evidence:
+
+- `/api/workflows/{workflow_id}/commands/{command_id}/run` rejects command types other than `start_training`.
+
+Recommendation:
+
+- Generalize durable commands for:
+  - start training;
+  - start inference;
+  - run evaluation;
+  - export evidence;
+  - run data prep.
+- Make command status the source of truth for action-card progress.
+
+## Suggested Agent Role Expansion
+
+### Near-Term Agent Capabilities
+
+Add the following as typed, tested workflow tools:
+
+- Read project summary
+- List folders/files with filters
+- Inspect H5/Zarr/TIFF volume metadata
+- Discover and confirm image/label pairs
+- Read and update project memory
+- Read project progress
+- Mark volume status with note
+- Stage visualization for a selected pair
+- Stage training from selected progress statuses
+- Stage inference for selected missing volumes
+- Inspect last runtime failure
+
+### Medium-Term Agent Behavior
+
+The agent should behave like:
+
+1. Observe
+   - Refresh project observation and progress.
+   - Inspect relevant files or volume metadata.
+2. Orient
+   - Identify what is known, unknown, and risky.
+   - Update project memory with sourced facts.
+3. Propose
+   - Provide a normal chat response.
+   - Show trace in expandable UI.
+   - Offer 1 to 3 action cards.
+4. Act
+   - Execute only approved or low-risk actions.
+   - Keep visible status synced to command/runtime state.
+5. Learn
+   - Store what worked, what failed, and what the user corrected.
+
+### Long-Term Agent Features
+
+- Voice-guided project intake for biologists.
+- Project "interview" mode that asks one concrete question at a time.
+- Auto-generated project map:
+  - folders;
+  - image volumes;
+  - masks;
+  - checkpoints;
+  - configs;
+  - outputs.
+- Agent-generated run notebook:
+  - what was trained on;
+  - what was excluded;
+  - why;
+  - model config diff;
+  - results and next step.
+- Failure triage:
+  - parse runtime logs;
+  - identify config/data mismatch;
+  - propose specific fix;
+  - generate retry card.
+
+## Suggested Engineering Roadmap
+
+### Immediate Stabilization
+
+1. Fix semantic intent set mismatch.
+2. Stop resetting workflow/file state on ordinary app boot.
+3. Make visible chat hydrate from server workflow conversation.
+4. Normalize API path handling.
+5. Add unknown `navigate_to` validation so bad agent effects cannot blank the UI.
+6. Make proposal approval append a visible chat status message and show action execution state.
+7. Fix training subset launch contract with a dry-run dataset validation.
+
+### Project Memory And Progress
+
+1. Create a `project_memory` backend module with typed schemas.
+2. Create explicit volume records from confirmed mappings.
+3. Move progress tracker from repeated heuristics to stored volume state plus refreshable observations.
+4. Connect proofread artifacts to progress volume statuses.
+5. Add volume notes and row actions.
+
+### Runtime And Agent Execution
+
+1. Introduce `ActionExecution` as a single envelope for all app actions.
+2. Generalize durable commands beyond training.
+3. Centralize config staging and diff generation in backend/worker.
+4. Propagate `workflow_trace_id` across chat, commands, worker logs, and artifacts.
+5. Add "Inspect failure" action for failed runs.
+
+### UI Polish
+
+1. Replace blank/free-text project setup with a guided checklist and optional notes.
+2. Add a persistent project status summary visible outside the Progress tab.
+3. Add compact training/inference proposal cards with expandable technical details.
+4. Add a volume inspector for H5/Zarr/TIFF shape, dtype, metadata, and thumbnails.
+5. Code-split heavy proofread/3D modules.
+
+## Specific Follow-Up Bugs To File
+
+- `SEMANTIC_WORKFLOW_INTENTS` missing prompt-listed intents.
+- `CacheBootstrapper` and `WorkflowProvider` boot reset conflict with continuous workflow sessions.
+- `usePersistedState` name is misleading and unused `localforage` import should be reconciled.
+- `shouldUseWorkflowAgent()` routes every non-empty workflow-session message to workflow agent.
+- Training subset staging can pass directories where PyTC expects concrete volume files or list-compatible config.
+- `approveAgentAction()` durable command branch switches to `monitor_training` after command submission, which hides whether the launch actually happened unless the runtime page watches correctly.
+- `buildRuntimeOverridesFromEffects()` uses `inferenceConfigOriginPath` while most runtime paths expect `configOriginPath`.
+- Project context/proofread sidecars are written into mounted source data directories.
+- `reset_workspace()` deletes `.pytc_project_context.json` from mounted source roots.
+- `server_api/ehtool/router.py` import-time diagnostic print should be removed or gated.
+- `client/src/views/Monitoring.js` remains as dead code after Monitor tab sunset.
+- Production build still contains several debug `console.log` calls.
+- EHTool hook dependency warnings remain.
+- Generic chat has process-global `_chat_history` / `_active_convo_id`.
+
+## Closing Assessment
+
+The app is close to a useful agentic workflow prototype, but the next jump is architectural rather than cosmetic. The right direction is not "more prompt engineering"; it is to give the agent a canonical project memory, typed observation tools, typed action execution, and a progress model that is not reconstructed from path heuristics every time.
+
+Once those exist, the chat can become much more natural because the technical rigor can move into traces, cards, and project state rather than being jammed into every assistant message.
diff --git a/docs/research/on-device-llm-options-2026-04-26.md b/docs/research/on-device-llm-options-2026-04-26.md
new file mode 100644
index 00000000..5d879782
--- /dev/null
+++ b/docs/research/on-device-llm-options-2026-04-26.md
@@ -0,0 +1,38 @@
+# On-Device LLM Options - 2026-04-26
+
+Purpose: keep the PyTC Client assistant local-first while improving workflow
+reasoning beyond the old `llama3.2:1b` default.
+
+## Current Implementation Decision
+
+- Immediate default: `llama3.1:8b`, because it is already installed on this
+  development machine and is a major quality jump over the 1B default.
+- Embeddings remain `nomic-embed-text:latest`.
+- Rebuild the FAISS index after editing `server_api/chatbot/file_summaries/`.
+
+## Models To Evaluate Next
+
+| Model            | Why It Matters                                                                                      | Tradeoff                                                                         | Status                |
+| ---------------- | --------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | --------------------- |
+| `qwen3:4b`       | Ollama lists it at 2.5GB with a 256K context window; useful candidate for fast local workflow chat. | Needs local pull and behavioral testing.                                         | Evaluate              |
+| `qwen3:8b`       | Larger Qwen3 local text model, 5.2GB and 40K context.                                               | More memory/latency than 4B.                                                     | Evaluate              |
+| `gemma3:4b`      | Ollama lists Gemma 3 as multimodal with 128K context; 4B is 3.3GB.                                  | Multimodal support is not yet integrated into PyTC Client.                       | Evaluate              |
+| `phi4-mini`      | Ollama describes it as memory/compute constrained and latency-bound, with 128K context.             | Requires Ollama 0.5.13+ and should be tested for UI-agent instruction following. | Evaluate              |
+| llama.cpp / GGUF | Strong fallback runtime path; official repo supports Metal for Apple Silicon.                       | More integration work than Ollama.                                               | Future runtime option |
+
+## Product Takeaway
+
+Model choice is not enough. The bad interaction came from letting general RAG
+answer workflow/meta questions. The robust fix is layered:
+
+- deterministic workflow router for run/proofread/train/compare/status intents;
+- direct guards for gibberish and meta questions such as "did you run?";
+- documentation that says low-level YAML/stride/blending is advanced-only;
+- stronger local model for the remaining general assistant path.
+
+## Sources
+
+- Ollama Qwen3 model library: https://ollama.com/library/qwen3
+- Ollama Gemma 3 model library: https://ollama.com/library/gemma3
+- Ollama Phi-4 Mini model library: https://ollama.com/library/phi4-mini
+- llama.cpp supported backends: https://github.com/ggml-org/llama.cpp
diff --git a/docs/research/preliminary-agentic-report-triage-2026-05-27.md b/docs/research/preliminary-agentic-report-triage-2026-05-27.md
new file mode 100644
index 00000000..2c8d32d0
--- /dev/null
+++ b/docs/research/preliminary-agentic-report-triage-2026-05-27.md
@@ -0,0 +1,257 @@
+# Preliminary Agentic Workflow Report Triage
+
+Date: 2026-05-27
+
+## What This Is
+
+This is a short engineering triage of `docs/research/agentic-workflow-formalization-report.md` while a fuller ChatGPT Deep Research pass is running.
+
+The preliminary report is useful, but it was produced quickly. Treat it as an implementation-facing hypothesis document, not as final literature support for the paper.
+
+## Bottom Line
+
+The report's main direction is strong enough to act on:
+
+> Build the assistant as a workflow-aware, approval-gated project operator. Chat is the conversational surface. Project memory is the source of truth. Action cards are the bridge from intent to bounded execution. Evidence events are the provenance layer.
+
+This matches what the prototype failures have shown in practice:
+
+- when the agent lacks fresh project state, it becomes generic;
+- when project progress is not canonical, training/proofreading/inference choices drift;
+- when action cards do not fully stage paths/artifacts, approval appears to do nothing;
+- when onboarding starts from a blank prompt, biologists are stranded;
+- when evidence is not recorded, the paper has weak system claims.
+
+## What Is Solid Enough To Implement Now
+
+### 1. Yixiao Harness And Demo Contract
+
+Already started and should continue.
+
+The repo now has:
+
+- `scripts/run_yixiao_case_study_smoke.py`
+- `docs/manual-yixiao-case-study-demo.md`
+
+These directly support the report's recommendation that case studies need repeatable evidence, not vibes.
+
+Next concrete extensions:
+
+- add a proofread/promote smoke path for `5_1` or `5_2`;
+- add a no-checkpoint inference blocker check for `6_1` / `6_2`;
+- add a post-checkpoint inference proposal smoke once a checkpoint exists;
+- add evidence-bundle export validation for the Yixiao workflow.
+
+### 2. Canonical Project Memory Read Model
+
+The preliminary report correctly identifies this as the central technical move.
+
+Current app already has `GET /api/workflows/{workflow_id}/memory`, but it should be hardened into the shared contract used by:
+
+- Assistant;
+- Progress;
+- Train Model;
+- Run Model;
+- Proofread;
+- evidence export.
+
+Immediate implementation target:
+
+- version the memory schema explicitly;
+- include freshness markers for project tree, progress, runtime, proofreading, and assistant context;
+- include source/evidence for each project fact;
+- include canonical active volume set;
+- include selected training/inference candidates derived from volume states;
+- add tests around MitoEM2 and Yixiao fixtures.
+
+### 3. Volume State Vocabulary Migration
+
+The report's proposed vocabulary is more expressive than the current prototype.
+
+Current legacy states:
+
+- `ground_truth`
+- `needs_proofreading`
+- `missing_segmentation`
+- `ignored`
+
+Proposed canonical states:
+
+- `image_only`
+- `draft_segmentation`
+- `needs_proofreading`
+- `proofread_ground_truth`
+- `training_candidate`
+- `queued_for_inference`
+- `prediction_ready`
+- `ignored`
+
+Do not switch the whole UI in one risky pass. Add aliases first:
+
+| Legacy                 | Canonical Alias          |
+| ---------------------- | ------------------------ |
+| `ground_truth`         | `proofread_ground_truth` |
+| `missing_segmentation` | `image_only`             |
+| `needs_proofreading`   | `needs_proofreading`     |
+| `ignored`              | `ignored`                |
+
+Immediate implementation target:
+
+- expose canonical state and display label in project memory;
+- keep legacy fields for compatibility;
+- update agent decision logic to reason in canonical terms;
+- update Progress copy so users see normal wording, not internal enum names.
+
+### 4. Typed Action Proposal Envelope
+
+The report is right that action semantics are split across too many surfaces.
+
+Current sources include:
+
+- chat actions;
+- command blocks;
+- proposal events;
+- direct client effects;
+- runtime actions;
+- workflow commands.
+
+Immediate implementation target:
+
+- define a `WorkflowActionProposal` JSON schema in backend docs/code;
+- make agent-generated cards include a stable `proposal_type`, `risk_level`, `affected_volume_ids`, `inputs`, `outputs`, `preconditions`, `evidence_basis`, and `postconditions`;
+- keep frontend rendering compatible with current cards, but normalize server output.
+
+Do this before large new agent behaviors. It will prevent another "Approve does nothing" regression.
+
+### 5. Guided Context Elicitation
+
+The report's onboarding recommendation is consistent with user feedback.
+
+Immediate Yixiao-specific version:
+
+- after mount, show detected facts:
+  - "I found XRI/CytoTape fibre data";
+  - "10 volumes: 6 GT, 2 draft masks, 2 image-only";
+  - "voxel size 40 x 16.3 x 16.3 nm";
+  - "training policy: use confirmed GT only";
+  - "config: app-compatible TapeReader sanity config";
+- ask short confirmation questions, not one blank textarea;
+- persist corrections as project memory confirmations.
+
+This can be implemented before the full generalized version.
+
+## What Needs Deep Research Validation
+
+Do not treat these as final until the fuller pass returns:
+
+### 1. Third Case Study Choice
+
+The preliminary report recommends CREMI-style affinity-heavy neuron segmentation. That is plausible, but the implementation risk is high.
+
+Deep research should validate whether the paper is better served by:
+
+- CREMI/SNEMI3D for workflow diversity and connectomics realism;
+- Lucchi++ for a stable onboarding case;
+- NucMM or another non-mito case for breadth;
+- keeping the third case as future work.
+
+For tomorrow/prototype stability, do not block Yixiao work on this.
+
+### 2. Literature Completeness
+
+The cited areas are directionally correct:
+
+- Horvitz mixed initiative;
+- Amershi HAI guidelines and interactive ML;
+- ilastik / CellProfiler / napari / Neuroglancer / WEBKNOSSOS / VAST;
+- CAVE / provenance / OME-Zarr / REMBI;
+- Codex / Claude Code / Copilot as product-pattern analogies.
+
+But the quick report should be audited for:
+
+- missing primary HCI sources;
+- overreliance on product docs;
+- exact claims about CAVE/WEBKNOSSOS/VAST;
+- current dates and versions;
+- better workflow/provenance sources.
+
+### 3. Evaluation Design
+
+The proposed participant tasks are good starting points, but deep research should strengthen:
+
+- baselines;
+- measures;
+- study size;
+- what evidence supports TOCHI versus a demo/system paper;
+- how to avoid implying segmentation-accuracy improvements.
+
+## Engineering Work To Do While Deep Research Runs
+
+Prioritized for the Yixiao-only lock-in:
+
+1. **Proofreading roundtrip for Yixiao draft masks**
+   - Open `5_1` or `5_2`.
+   - Save or mock a correction artifact.
+   - Promote to `proofread_ground_truth`.
+   - Verify Progress and agent training subset update from 6 GT to 7 GT.
+
+2. **Inference blocker and target proposal**
+   - Ask agent to segment `6_1` / `6_2` before a checkpoint exists.
+   - It should explain the checkpoint blocker and offer training/checkpoint registration.
+   - Once a checkpoint exists, it should propose inference on exactly `6_1` / `6_2`.
+
+3. **Evidence bundle export for Yixiao**
+   - Export workflow memory, volume states, viewer events, training proposal, approvals, subset manifest, and smoke report path.
+   - Add a validator that confirms these records exist.
+
+4. **Yixiao guided intake card**
+   - Replace any blank project-context textarea for this fixture with detected facts and confirm/edit controls.
+   - Persist confirmations.
+
+5. **Action card cleanup**
+   - Make the training card display:
+     - 6 included GT volumes;
+     - 2 draft masks excluded;
+     - 2 image-only targets after training;
+     - config;
+     - output/log path;
+     - approval behavior.
+   - Hide giant paths behind details.
+
+6. **Project memory hardening**
+   - Add freshness fields.
+   - Add source/evidence for project facts.
+   - Add canonical state aliases.
+   - Add tests that Yixiao memory remains stable after refresh.
+
+## Strong Claims We Can Make After Current Work
+
+If the Yixiao harness and current workflow remain stable, we can safely claim:
+
+- the system can mount and inspect a real XRI/TapeReader project fixture;
+- it tracks volume-level workflow state across GT, draft masks, and image-only targets;
+- it opens selected raw/mask pairs in Neuroglancer with project voxel scale;
+- it turns a natural-language training request into an approval-gated multi-volume training proposal;
+- it preserves excluded draft masks and image-only targets in the proposal;
+- it validates worker-side training subset path resolution before launch.
+
+## Claims To Avoid For Now
+
+Avoid claiming:
+
+- the system reproduces TapeReader performance;
+- the current proofread UI fully supports production-grade fibre correction;
+- the current agent can visually inspect image quality;
+- the current app has complete project-memory invalidation;
+- the workflow generalizes across all bioimage segmentation tasks;
+- the assistant improves segmentation accuracy.
+
+## Recommended Next Engineering Move
+
+Do the Yixiao proofreading roundtrip next.
+
+Reason:
+
+- It directly tests the heart of the paper story: human correction changes project state, and the agent uses that updated state in the next training proposal.
+- It will expose whether Progress, Proofread, Assistant, and Train Model are actually coordinated or just separately plausible.
+- It produces a clean paper/demo moment: 6 GT becomes 7 GT after a human review decision.
diff --git a/docs/research/pytc-prepilot-dataset-stress-test.md b/docs/research/pytc-prepilot-dataset-stress-test.md
new file mode 100644
index 00000000..188175ad
--- /dev/null
+++ b/docs/research/pytc-prepilot-dataset-stress-test.md
@@ -0,0 +1,237 @@
+# PyTC Dataset Prepilot Stress Test
+
+Date: 2026-04-28
+
+## Goal
+
+Run a solo prepilot before external case studies to find where the prototype breaks on realistic PyTorch Connectomics (PyTC) workflows: project setup, role inference, config selection, training/inference launch, proofreading, correction export, retraining, candidate inference, metrics, and evidence export.
+
+The important constraint is that most public PyTC datasets provide data and configs, but not always matching pretrained checkpoints. For a credible stress test, treat "baseline inference" as one of:
+
+- Use an existing local checkpoint if available.
+- Run a short training/fine-tuning pass first, then infer from that checkpoint.
+- Use a published upstream checkpoint only when the checkpoint source, config family, and expected tensor outputs match.
+
+## Source Grounding
+
+- PyTC paper: PyTC is a framework for semantic and instance segmentation of volumetric microscopy data, with benchmark claims across CREMI, MitoEM, and NucMM. Source: [PyTorch Connectomics paper](https://arxiv.org/abs/2112.05754).
+- PyTC docs: The official tutorials map specific config families to Lucchi, MitoEM, SNEMI3D, and CREMI workflows. Sources: [mitochondria tutorial](https://connectomics.readthedocs.io/en/latest/tutorials/mito.html), [neuron tutorial](https://connectomics.readthedocs.io/en/latest/tutorials/neuron.html), [synapse tutorial](https://pytorch-connectomics.readthedocs.io/en/latest/tutorials/synapse.html).
+- Upstream PyTC has moved toward a v2.0 stack with PyTorch Lightning, MONAI, Hydra/OmegaConf, pretrained tutorial checkpoints, and `just` workflows. This is useful precedent, but the current client is wired around the older `scripts/main.py` + YAML configs. Source: [current PyTC GitHub](https://github.com/PytorchConnectomics/pytorch_connectomics).
+
+## Recommended Dataset Ladder
+
+Run the ladder in order. Stop when the prototype fails; log the failure as product evidence rather than forcing the demo through.
+
+| Tier    | Dataset                     | Why this tier matters                                                           | Data source                                                                                                                                                                                                      | Existing local config(s)                                                                                                           | Expected stress point                                                                                                 |
+| ------- | --------------------------- | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| 0       | Local Mito25 / Mito25 smoke | Fastest app-level closed-loop rehearsal using the app's current demo path       | Existing local data under `/Users/adamg/seg.bio/testing_data/mito25` when mounted                                                                                                                                | `configs/MitoEM/Mito25-Local-Smoke-BC.yaml`, `configs/MitoEM/Mito25-Local-BC.yaml`                                                 | End-to-end app state, project setup, proofreading save/export, short training/inference job handling                  |
+| 1       | MitoEM toy crop             | Real PyTC/Hugging Face data, small enough to iterate                            | [pytc/MitoEM](https://huggingface.co/datasets/pytc/MitoEM/tree/main), especially `mitoem_R_train_4um_im.h5` and `mitoem_R_train_4um_seg.h5`                                                                      | Adapt `configs/MitoEM/Mito25-Local-BC.yaml` for direct HDF5 crop, or `MitoEM-R-Base.yaml` + `MitoEM-R-BC.yaml` for full tiled data | HDF5 role inference, small real mitochondria proofreading, model-run artifact lineage                                 |
+| 2       | Lucchi / Lucchi++           | Small classic mitochondria semantic segmentation benchmark with public labels   | PyTC docs link `lucchi.zip`; also [pytc/tutorial](https://huggingface.co/datasets/pytc/tutorial/tree/main) has `lucchi++.zip`; background at [Connectomics Lucchi++](https://sites.google.com/view/connectomics) | `configs/Lucchi-Mitochondria.yaml`                                                                                                 | TIFF stack handling, semantic rather than instance masks, local evaluation with IoU/F1-style metrics                  |
+| 3       | CREMI synaptic clefts       | Multi-volume HDF5 benchmark and synapse task; tests non-mito biology            | [CREMI data page](https://cremi.org/data/) cropped A/B/C volumes or [pytc/tutorial](https://huggingface.co/datasets/pytc/tutorial/tree/main) `cremi.zip`                                                         | `configs/CREMI/CREMI-Base.yaml` + `configs/CREMI/CREMI-Foreground-UNet.yaml`                                                       | Multiple image/label pairs, `@`-separated config paths, HDF5 internal dataset keys, synapse-specific metrics          |
+| 4       | SNEMI3D neurons             | Classic dense neurite segmentation with affinity output and postprocessing      | PyTC docs `snemi.zip`; challenge context at [SNEMI3D](https://snemi3d.grand-challenge.org/)                                                                                                                      | `configs/SNEMI/SNEMI-Base.yaml` + `configs/SNEMI/SNEMI-Affinity-UNet.yaml`                                                         | Affinity maps are not directly editable instance masks; requires waterz/zwatershed postprocessing before proofreading |
+| 5       | NucMM                       | Non-mito, non-synapse nuclei; tests modality generality and project agnosticism | [NucMM project page](https://pytorchconnectomics.github.io/datasets/proj/nucmm/) and [pytc/NucMM](https://huggingface.co/datasets/pytc/NucMM/tree/main)                                                          | `configs/NucMM/NucMM-Mouse-Base.yaml` + `NucMM-Mouse-UNet-BC.yaml`; `NucMM-Zebrafish-Base.yaml` + `NucMM-Zebrafish-UNet-BC.yaml`   | Large-volume nuclei, EM vs micro-CT modality mismatch, non-mito proofreading language                                 |
+| Stretch | JWR15 synapse polarity      | Tests arbitrary-volume synapse inference and semantic synapse masks             | PyTC synapse docs mention `jwr15_synapse.zip`                                                                                                                                                                    | `configs/JWR15/synapse/JWR15-Synapse-Base.yaml` + `JWR15-Synapse-BCE.yaml`                                                         | Pretrained-checkpoint availability, arbitrary-volume inference, non-instance semantic masks                           |
+| Stretch | MitoEM2.0                   | Current PyTC dataset ecosystem and larger modern mitochondrial scope            | [pytc/MitoEM2.0](https://huggingface.co/datasets/pytc/MitoEM2.0/tree/main)                                                                                                                                       | No matching local legacy config yet; evaluate separately                                                                           | 17GB scale, new dataset organization, likely requires schema/config adaptation                                        |
+
+## Project Folder Schema For The Prepilot
+
+For every dataset, stage a project folder under a consistent schema before opening it in the client:
+
+```text
+testing_projects/prepilot_<dataset_slug>/
+  data/
+    image/
+    seg/
+    prediction/
+  configs/
+  checkpoints/
+  outputs/
+  notes/
+    prepilot-log.md
+```
+
+Minimum workable project:
+
+- `data/image`: one image volume, image stack folder, or PyTC JSON/txt list.
+- `data/seg`: optional label/mask volume or stack.
+- `configs`: the PyTC config copied from `pytorch_connectomics/configs/...` with local paths patched or overridden by the app.
+- `checkpoints`: optional. If empty, the prepilot starts with a short training run.
+- `outputs`: runtime artifacts, predictions, checkpoints, exported masks, metrics, and evidence bundle.
+
+The app should infer roles, but the user must explicitly confirm the role mapping before workflow state mutates.
+
+## Solo Prepilot Script
+
+### Pass A: Fast App Loop On Local Mito25
+
+Use this to confirm the app loop before spending time on external data.
+
+1. Reset app workflow state and mount only the local Mito25 project.
+2. Confirm image, label/mask, config, output path, and checkpoint roles.
+3. Ask the agent: "What should I do next?"
+4. Expected agent behavior: it should propose a concrete workflow action, not dump config docs.
+5. Run short baseline inference if a checkpoint exists; otherwise run the smoke training config first.
+6. Open proofreading, inspect 3 objects, mark at least one `needs fix`, draw/edit, save mask.
+7. Export corrected masks.
+8. Stage retraining from corrections.
+9. Run short candidate inference.
+10. Compute before/after metrics.
+11. Export the evidence bundle.
+
+Pass conditions:
+
+- Role confirmation is explicit and editable.
+- Agent can open or propose the next app action with approval.
+- Proofreading save persists to both app state and artifact path.
+- Exported correction is visible to retraining.
+- Metrics compare baseline vs candidate, even if the model is intentionally weak.
+- Evidence bundle contains events, configs, paths, masks/predictions, metric report, and run summaries.
+
+### Pass B: MitoEM Toy Crop
+
+Use this to test project agnosticism while staying small.
+
+1. Download `mitoem_R_train_4um_im.h5` and `mitoem_R_train_4um_seg.h5` from [pytc/MitoEM](https://huggingface.co/datasets/pytc/MitoEM/tree/main).
+2. Stage them as `data/image/..._im.h5` and `data/seg/..._seg.h5`.
+3. Copy `configs/MitoEM/Mito25-Local-BC.yaml` into the project config folder and patch only paths/output names.
+4. Start from blank app state and mount the project folder.
+5. Confirm roles and verify the app does not silently fall back to local mito25 defaults.
+6. Run the same loop as Pass A, but record every place the UI assumes "mito25".
+
+Expected findings:
+
+- The role profiler should detect `_im.h5` as image and `_seg.h5` as label.
+- The proofreader should load slices without manual HDF5-key entry if the file has a simple volume dataset.
+- If HDF5 keys are ambiguous, the app should ask for a key rather than fail silently.
+
+### Pass C: Lucchi / Lucchi++
+
+Use this to stress format generality and semantic segmentation.
+
+1. Download `lucchi.zip` from the PyTC tutorial source or `lucchi++.zip` from [pytc/tutorial](https://huggingface.co/datasets/pytc/tutorial/tree/main).
+2. Arrange files to match `configs/Lucchi-Mitochondria.yaml`: `img/train_im.tif`, `label/train_label.tif`, `img/test_im.tif`.
+3. Mount the project and confirm roles.
+4. Ask the agent to set up the run for "mitochondria semantic segmentation on Lucchi".
+5. Run a very short training smoke, then inference.
+6. Compute semantic metrics against public labels where available.
+
+Expected findings:
+
+- The app should not force an instance-proofreading mental model onto semantic masks.
+- The agent should mention "semantic mitochondria mask" and "threshold/IoU" rather than "instance proofreading queue" unless instance labels are present.
+- Runtime summaries should show training status and useful warnings, not raw terminal logs by default.
+
+### Pass D: CREMI
+
+Use this to test multi-volume HDF5 and synapse-specific workflows.
+
+1. Download cropped CREMI A/B/C data from [CREMI](https://cremi.org/data/) or use the PyTC tutorial `cremi.zip`.
+2. Arrange expected paths for `CREMI-Base.yaml`, or patch config paths:
+   - training images: `corrected/im_A.h5@corrected/im_B.h5@corrected/im_C.h5`
+   - training labels: `corrected/syn_A.h5@corrected/syn_B.h5@corrected/syn_C.h5`
+   - inference images: `corrected/im_A+.h5@corrected/im_B+.h5@corrected/im_C+.h5`
+3. Mount project folder.
+4. Confirm multiple image/label pairs rather than a single pair.
+5. Ask the agent: "Prepare a synaptic cleft detection run."
+6. Observe whether the agent can identify missing label paths, HDF5 keys, and config mismatch before starting.
+
+Expected findings:
+
+- Current project role schema may be too single-pair oriented.
+- The app likely needs first-class support for batches/pair tables.
+- Proofreading may need a synapse-specific review mode rather than object-instance review.
+
+### Pass E: SNEMI3D
+
+Use this only after the app can handle CREMI/MitoEM cleanly.
+
+1. Download SNEMI data using the PyTC neuron tutorial source.
+2. Arrange `image/train-input.tif`, `seg/train-labels.tif`, and `test-input.tif`.
+3. Use `SNEMI-Base.yaml` + `SNEMI-Affinity-UNet.yaml`.
+4. Ask the agent to set up neuron affinity segmentation.
+5. Verify the agent explains that raw model output is an affinity map and needs waterz/zwatershed before it becomes an editable segmentation.
+
+Expected findings:
+
+- This will expose whether the prototype incorrectly assumes model outputs are always direct masks.
+- A robust agent should route the user through postprocessing and not send affinity channels directly into the proofreader.
+
+### Pass F: NucMM
+
+Use this as the "not connectomics mitochondria" generality test.
+
+1. Download `NucMM-M.zip` or `NucMM-Z.zip` from [pytc/NucMM](https://huggingface.co/datasets/pytc/NucMM/tree/main).
+2. Pick one smaller/cropped subset if the zip is too large for an initial run.
+3. Use the matching `NucMM-*` base and `UNet-BC` config.
+4. Mount and confirm roles.
+5. Ask the agent to describe the biological object and run strategy.
+
+Expected findings:
+
+- The agent should adapt language to nuclei segmentation.
+- The app should support non-mito instance masks without hardcoded labels, names, or assumptions.
+- Large volume I/O and slice navigation will likely surface performance bottlenecks.
+
+## What To Record During The Solo Prepilot
+
+Use a table in `notes/prepilot-log.md` for each dataset:
+
+| Check                            | Result    | Evidence path           | Notes                                                |
+| -------------------------------- | --------- | ----------------------- | ---------------------------------------------------- |
+| Project roles inferred correctly | pass/fail | screenshot/log/event id | Was any role wrong or silently defaulted?            |
+| Config selected correctly        | pass/fail | config path             | Did app suggest the right PyTC config family?        |
+| Agent next-step answer useful    | pass/fail | chat id                 | Did it produce action, question, or irrelevant docs? |
+| Agent action approval works      | pass/fail | event id                | Did action mutate app only after approval?           |
+| Runtime starts                   | pass/fail | run id                  | Training/inference job record exists?                |
+| Runtime summary readable         | pass/fail | screenshot              | Was raw log hidden unless requested?                 |
+| Proofreading loads quickly       | pass/fail | timing                  | Slice change target: under 1-2s on small crop.       |
+| Mask save persists               | pass/fail | artifact path           | Reopen and verify edit remains.                      |
+| Export works                     | pass/fail | export path             | Corrected mask usable by training.                   |
+| Candidate metrics computed       | pass/fail | report path             | Baseline/candidate/reference all resolved.           |
+| Evidence bundle exported         | pass/fail | bundle path             | Includes events, configs, artifacts, metrics.        |
+
+## Failure Modes This Prepilot Is Designed To Expose
+
+- The app silently chooses the old mito25 demo project instead of the confirmed project.
+- File role inference works for simple HDF5 names but fails for real HDF5 internal datasets.
+- Project schema supports one image/mask pair but not multiple pairs or config `@` lists.
+- Training/inference jobs start, but the UI exposes terminal logs instead of actionable summaries.
+- The agent gives RAG documentation instead of asking/applying workflow-specific decisions.
+- The agent treats semantic masks, instance masks, affinity maps, contours, and distance transforms as interchangeable.
+- Baseline inference cannot run because checkpoint/config/data tensor shapes are mismatched.
+- Proofreading becomes unusable on larger volumes due to slice loading, canvas state, or save/export bugs.
+- Metrics only work for the local synthetic path and fail on semantic, affinity, or multi-volume datasets.
+- Evidence bundle lacks enough artifact lineage to reconstruct what happened.
+
+## Minimum Prepilot Completion Bar
+
+Before external case studies, the prototype should pass:
+
+1. Local Mito25 closed-loop smoke.
+2. MitoEM toy crop project-agnostic setup and proofreading.
+3. Lucchi or CREMI non-mito25 setup with at least training/inference launch and a useful agent preflight.
+
+If those pass, the app is ready for a controlled prepilot with another person. If SNEMI3D or NucMM also pass, the system has stronger evidence for project agnosticism.
+
+## Ingested Local Projects
+
+On 2026-04-28, `scripts/ingest_prepilot_datasets.py` staged practical prepilot fixtures under `/Users/adamg/seg.bio/testing_projects`.
+
+| Project                   | Status              | Contents                                                                                                                                                                                                                                                         |
+| ------------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `prepilot_mito25_smoke`   | ready               | Symlinked local Mito25 smoke HDF5 image/seg pairs plus `Mito25-Local-Smoke-BC.yaml`.                                                                                                                                                                             |
+| `prepilot_mitoem_toy`     | ready               | Downloaded public MitoEM-R 4um HDF5 image/seg crop from Hugging Face and wrote `MitoEM-Toy-BC-Smoke.yaml`.                                                                                                                                                       |
+| `prepilot_lucchi_pp`      | ready               | Downloaded/extracted `lucchi++.zip`; staged `train_im.h5`, `train_mito.h5`, `test_im.h5`, and `test_mito.h5` with patched Lucchi config.                                                                                                                         |
+| `prepilot_snemi3d_local`  | ready               | Symlinked existing local SNEMI train/test TIFFs and labels with patched SNEMI base config plus affinity UNet config.                                                                                                                                             |
+| `prepilot_cremi_official` | needs preprocessing | Downloaded official CREMI A/B/C HDF5 containers; manifest records raw and cleft-label HDF5 keys. Legacy PyTC configs expect preprocessed `corrected/im_*.h5` and `corrected/syn_*.h5`, so this fixture intentionally exposes the HDF5-key/config-adaptation gap. |
+| `prepilot_nucmm_mouse`    | ready               | Downloaded/extracted public NucMM-Mouse archive; staged train image/seg HDF5 crops and copied NucMM Mouse configs.                                                                                                                                               |
+
+Each project includes:
+
+- `project_manifest.json` with role paths, source URLs, config paths, and HDF5/TIFF inventories.
+- `notes/README.md` with human-readable project guidance.
+- `notes/prepilot-log.md` with a pass/fail table for solo testing.
+
+## Paper-Relevant Takeaway
+
+The prepilot should not be framed as "does PyTC achieve SOTA." It should be framed as "does the prototype make an iterative biomedical segmentation loop controllable, inspectable, and recoverable across realistic PyTC datasets?" The strongest TOCHI evidence will be failure localization: where users need agent help, where the workflow is too technical, and where provenance/evidence prevents confusion across long-running segmentation iterations.
diff --git a/docs/research/subagent-orchestration-integration-2026-05-27.md b/docs/research/subagent-orchestration-integration-2026-05-27.md
new file mode 100644
index 00000000..b225d8b5
--- /dev/null
+++ b/docs/research/subagent-orchestration-integration-2026-05-27.md
@@ -0,0 +1,52 @@
+# Subagent Orchestration Integration - 2026-05-27
+
+## Purpose
+
+This note coordinates the parallel subagent pass for turning seg.bio into a paper-grade mixed-initiative workflow agent for the Yixiao/TapeReader XRI case study.
+
+The integration rule is simple: subagent reports are advisory. The main implementation must converge on one shared orchestration layer where manual UI actions and assistant actions read and write the same project memory, volume state records, action proposals, policy gates, and evidence ledger.
+
+## Active Subagents
+
+| Lane                 | Agent     | Scope                                                      | Expected Output                                            |
+| -------------------- | --------- | ---------------------------------------------------------- | ---------------------------------------------------------- |
+| Backend State        | Turing    | Composite volume state and project memory backend          | Schema/API transition plan, backcompat map, tests          |
+| App Agent Capability | Aristotle | Assistant intent routing, action proposals, response style | Capability matrix, routing gaps, trace/action changes      |
+| Action Policy        | Volta     | Action-card schema, risk tiers, approval gates             | Strict action schema, policy table, approval tests         |
+| Trace/Evidence       | Hume      | Structured traces and provenance bundles                   | Trace schema, ledger/export improvements, tests            |
+| UI Workflow          | Nietzsche | Onboarding, progress, assistant, action cards              | UI streamlining plan for coherent manual-agent handoff     |
+| Yixiao Case Study    | Dirac     | First case-study readiness                                 | Demo arc, negative tests, acceptance checklist             |
+| Reliability/QA       | James     | Prototype release gates                                    | Regression, smoke, stale-state, refresh, failed-run checks |
+
+Reliability/QA was queued after the first wave and wrote `docs/research/subagent-reliability-qa-2026-05-27.md`.
+
+## Integration Acceptance Criteria
+
+The next implementation pass should be considered successful only if all of these are true for the Yixiao case-study path:
+
+1. The project state is represented by canonical records, not chat prose.
+2. Volume readiness separates annotation maturity, workflow role, execution state, and region scope, even if legacy fields remain for UI compatibility.
+3. The assistant answers from project memory and can name the evidence behind important claims.
+4. Consequential assistant actions are typed action cards with inputs, target volumes, outputs, risk, approval policy, blockers, and expected state changes.
+5. Manual UI actions and assistant actions produce the same state transitions and evidence events.
+6. The assistant shows a structured trace, not raw chain-of-thought.
+7. Promoting a draft mask changes project memory, progress, and future training proposals.
+8. Evidence bundle export can reconstruct the inspect -> propose -> approve -> execute -> update story.
+9. The Yixiao smoke harness verifies the happy path plus at least one state-transition roundtrip.
+10. The public demo can be reset to the initial case-study state with one command.
+
+## Candidate Implementation Order
+
+1. Add composite-state helpers behind the existing volume-state API.
+2. Add strict action-card construction helpers and normalize existing agent cards through them.
+3. Add structured trace payload helpers and wire them to the most important Yixiao intents.
+4. Add policy checks for training, inference, promotion, and evidence export.
+5. Add Yixiao negative smoke checks once the state/action contracts are stable.
+6. Tighten frontend rendering only after backend contracts stop moving.
+
+## Non-Goals For This Pass
+
+- Do not expose raw model chain-of-thought.
+- Do not add arbitrary shell execution for the app agent.
+- Do not claim TapeReader model-performance reproduction without a separate evaluation run.
+- Do not replace the current UI wholesale; bridge the existing screens through a shared orchestration layer.
diff --git a/docs/research/subagent-reliability-qa-2026-05-27.md b/docs/research/subagent-reliability-qa-2026-05-27.md
new file mode 100644
index 00000000..59d11804
--- /dev/null
+++ b/docs/research/subagent-reliability-qa-2026-05-27.md
@@ -0,0 +1,211 @@
+# Reliability / QA Plan For Agentic Prototype
+
+Date: 2026-05-27
+
+Scope: verify the agentic PyTC prototype is stable enough for the Yixiao TapeReader XRI demo without overclaiming full GPU training, inference quality, or proofreading-at-scale. This plan is a release gate, not a research-evaluation protocol.
+
+## 1. Regression Suite
+
+Run from repo root:
+
+```bash
+cd /home/weidf/deploy/pytc-client-demo2
+uv run pytest
+cd client && npm test -- --watchAll=false
+cd client && npm run build
+```
+
+Minimum passing expectation:
+
+- `uv run pytest` passes all backend/workflow tests, especially workflow routes, evidence export, volume I/O, Neuroglancer URL contract, runtime settings, file workspace routes, and closed-loop smoke script tests.
+- React/Jest passes workflow context, proposal cards, assistant action/command cards, timeline filters, file manager, project progress, model training/inference, proofreading, and input-selector tests.
+- `npm run build` completes without compile errors.
+
+Fast targeted rerun after workflow/agent edits:
+
+```bash
+uv run pytest \
+  tests/test_workflow_routes.py \
+  tests/test_workflow_artifact_records.py \
+  tests/test_workflow_export_bundle.py \
+  tests/test_workflow_case_study_acceptance.py \
+  tests/test_closed_loop_smoke_script.py
+
+cd client && npm test -- --watchAll=false \
+  src/contexts/WorkflowContext.test.js \
+  src/__tests__/agentProposalCards.test.js \
+  src/components/Chatbot.test.js \
+  src/views/ProjectProgress.test.js \
+  src/views/FilesManager.test.js
+```
+
+## 2. Live Service Smoke
+
+Start local services:
+
+```bash
+cd /home/weidf/deploy/pytc-client-demo2
+scripts/start.sh
+```
+
+Health checks:
+
+```bash
+curl -fsS http://localhost:8000/
+curl -fsS http://localhost:4242/health
+curl -fsS http://localhost:4243/hello
+curl -fsS http://localhost:3000/
+```
+
+Closed-loop workflow smoke:
+
+```bash
+uv run python scripts/run_closed_loop_smoke.py \
+  --output-dir /tmp/pytc-closed-loop-smoke
+cat /tmp/pytc-closed-loop-smoke/smoke-report.json
+```
+
+Expected: smoke report passes and creates `workflow-bundle.json`, `readiness.json`, `evaluation-report.json`, and artifacts. Known exclusions are acceptable only if the report calls them out: real PyTC training, real PyTC inference, browser proofreading interaction, retries/cancellation/recovery.
+
+## 3. Yixiao Live Smoke
+
+Reset and prepare the public demo state:
+
+```bash
+cd /home/weidf/deploy/pytc-client-demo2
+.venv/bin/python scripts/run_yixiao_case_study_smoke.py \
+  --prepare-live \
+  --report /tmp/yixiao-case-study-smoke-report.json \
+  --verbose
+cat /tmp/yixiao-case-study-smoke-report.json
+```
+
+Promotion-path check:
+
+```bash
+.venv/bin/python scripts/run_yixiao_case_study_smoke.py \
+  --prepare-live \
+  --exercise-promotion \
+  --report /tmp/yixiao-case-study-smoke-promotion-report.json
+cat /tmp/yixiao-case-study-smoke-promotion-report.json
+
+.venv/bin/python scripts/run_yixiao_case_study_smoke.py \
+  --prepare-live \
+  --report /tmp/yixiao-case-study-smoke-report.json
+```
+
+Fast pre-demo gate (recommended for final readiness checks):
+
+```bash
+.venv/bin/python scripts/run_yixiao_case_study_smoke.py \
+  --pre-demo-gate \
+  --report /tmp/yixiao-case-study-pre-demo-gate-report.json
+```
+
+When run successfully, this command performs normal smoke + promotion roundtrip + restore, then writes a composite report including readiness/export sanity checks. Readiness may still be incomplete in this fixture context unless closed-loop evidence has been intentionally executed.
+
+Expected:
+
+- Normal run verifies manifest-backed mount, project profile, 10 volumes, 6 fully good, 2 needs proofreading, 2 no segmentation, 60% completion, 80% segmentation coverage, project memory, Neuroglancer URL, agent summary, review-gated training proposal, and PyTC subset resolver.
+- Promotion run verifies a draft mask can become canonical `proofread_ground_truth`, progress changes to 7/1/2, and the next training proposal uses seven training pairs.
+- Final normal run restores the public demo to 6/2/2.
+
+## 4. Stale State Checks
+
+Before any timed demo, remove ambiguity from old runtime state:
+
+```bash
+cd /home/weidf/deploy/pytc-client-demo2
+lsof -tiTCP:8000 -sTCP:LISTEN
+lsof -tiTCP:4242 -sTCP:LISTEN
+lsof -tiTCP:4243 -sTCP:LISTEN
+lsof -tiTCP:3000 -sTCP:LISTEN
+```
+
+If the wrong process owns a port, stop it intentionally, then restart with `scripts/start.sh`.
+
+State assertions:
+
+- Files tab mounts `/home/weidf/demo_data/yixiao_tapereader_xri_case_study`.
+- File tree includes `data`, `configs`, `notes`, `outputs`, `snapshots`, and `project_manifest.json`.
+- Active roots are `data/raw` and `data/seg`; active config is `configs/TapeReader-Fiber-BCS-AppCompat-Sanity.yaml`.
+- The assistant does not describe the project as mitochondria, Lucchi, MitoEM, or mito25 after Yixiao is mounted.
+- No old workflow card silently launches training or inference; all agent-generated training actions remain review/approval gated.
+
+Useful log inspection:
+
+```bash
+tail -n 120 .logs/start/api-server.log
+tail -n 120 .logs/start/pytc-server.log
+tail -n 120 .logs/start/react-dev.log
+```
+
+## 5. Browser Refresh / Session Continuity
+
+Manual browser checks against `http://localhost:3000` or `https://demo.seg.bio`:
+
+1. Mount the Yixiao project, open `Files`, refresh the browser, and confirm the same project remains mounted.
+2. Open `Progress`, refresh, and confirm counts stay 10/6/2/2 with 60% completion and 80% segmentation coverage.
+3. Ask `what project are we looking at?`, refresh, reopen the assistant, and confirm project context is still Yixiao/TapeReader/XRI.
+4. Ask `train on the fully good masks to segment the image-only volumes`, refresh before approval, and confirm the proposal remains review-gated rather than auto-running.
+5. Navigate to `Visualize`, open the first image/mask pair, refresh, and confirm the viewer can be reopened through an HTTPS `/neuroglancer/v/...` URL.
+6. Close and reopen the browser session; repeat `Files`, `Progress`, and assistant context checks.
+
+Fail the gate if refresh drops the mounted project, changes volume counts, loses proposal gating, or resurrects stale non-Yixiao context.
+
+## 6. Failed Run Checks
+
+Simulate and inspect common failures without editing code:
+
+```bash
+cd /home/weidf/deploy/pytc-client-demo2
+.venv/bin/python scripts/run_yixiao_case_study_smoke.py \
+  --prepare-live \
+  --project-root /tmp/not-a-yixiao-project \
+  --report /tmp/yixiao-negative-smoke-report.json || true
+cat /tmp/yixiao-negative-smoke-report.json 2>/dev/null || true
+```
+
+Expected failed-run behavior:
+
+- Failure is explicit and actionable, not a false pass.
+- UI surfaces health or validation errors instead of hanging indefinitely.
+- Failed training/inference attempts do not create completed workflow evidence.
+- A failed or canceled run leaves later agent proposals review-gated.
+- After rerunning `--prepare-live`, the demo state returns to the known 6/2/2 baseline.
+
+When a real PyTC run is intentionally started, record:
+
+- exact config path;
+- input image/label paths;
+- output/log paths;
+- checkpoint path if created;
+- terminal status: completed, failed, canceled, or unknown;
+- whether workflow evidence accurately matches that status.
+
+## 7. Yixiao Demo-Readiness Gates
+
+Go/no-go requires all of the following:
+
+- Regression suite passes or any skipped/failing tests are documented as unrelated to the demo path.
+- `scripts/start.sh` brings all four local services up cleanly.
+- `--pre-demo-gate` command passes and writes a composite report at
+  `/tmp/yixiao-case-study-pre-demo-gate-report.json`.
+- (For manual verification) normal Yixiao smoke passes and report is archived at `/tmp/yixiao-case-study-smoke-report.json`.
+- (For manual verification) promotion smoke passes once, then normal smoke is rerun to restore 6/2/2.
+- Browser refresh/session checks pass on the target demo URL.
+- Assistant correctly states: Yixiao TapeReader XRI Case Study, XRI/X-ray volumetric microscopy, CytoTape fibres, 40 x 16.3 x 16.3 nm, 10 total volumes, 6 fully good, 2 needs proofreading, 2 without segmentation.
+- Training proposal uses only the 6 fully good masks, excludes 5_1 and 5_2 draft masks, targets 6_1 and 6_2 for later inference, and requires approval.
+- Visualize opens `data/raw/1/1-xri_raw.tif` with `data/seg/1/1-mask.tif` and correct scales.
+- Proofreading and inference are presented with the known caveats from `docs/manual-yixiao-case-study-demo.md`.
+- No claim is made that the prototype has reproduced TapeReader model performance unless a separate completed evaluation run proves it.
+
+Demo is blocked if any of these are true:
+
+- services are unhealthy or using unknown stale processes;
+- Yixiao smoke fails;
+- project state is not 6/2/2 before the public walkthrough;
+- assistant uses stale mitochondria/mito25 context;
+- refresh loses mounted project or staged proposals;
+- training/inference can launch silently without review;
+- failed runs appear as successful workflow evidence.
diff --git a/docs/research/tochi-hci-prototype-takeaways.md b/docs/research/tochi-hci-prototype-takeaways.md
new file mode 100644
index 00000000..3c1dbf51
--- /dev/null
+++ b/docs/research/tochi-hci-prototype-takeaways.md
@@ -0,0 +1,81 @@
+# TOCHI/HCI Prototype Takeaways
+
+Purpose: keep implementation-facing notes from a quick TOCHI/HCI systems pass
+while turning PyTC Client into a paper-defensible, human-controlled,
+closed-loop biomedical segmentation prototype.
+
+## Sources Read
+
+- Dow et al., "Parallel Prototyping Leads to Better Design Results, More
+  Divergence, and Increased Self-Efficacy", ACM TOCHI 17(4), 2010.
+  <https://hci.stanford.edu/publications/2010/parallel-prototyping/ParallelPrototyping2010.pdf>
+- Microsoft Research, "Guidelines for Human-AI Interaction" publication page:
+  CHI 2019 guidelines and a TOCHI 2022 follow-up on early assessment.
+  <https://www.microsoft.com/en-us/research/project/guidelines-for-human-ai-interaction/publications/>
+- CHI 2025 Case Studies of HCI in Practice page, including recent examples of
+  practice-facing case studies and pilot case-study framing.
+  <https://chi2025.acm.org/for-authors/case-studies/>
+- CHI 2026 Human-Agent Collaboration workshop call, especially mixed-initiative
+  workflows, transparency, failure recovery, and shared accountability.
+  <https://chi26workshop-human-agent-collaboration.hailab.io/>
+- Adobe Research CHI 2025 summary on compositional structures for human-AI
+  co-creation, emphasizing workflow-spanning prototypes, context, inspection,
+  and control.
+  <https://research.adobe.com/news/an-experimental-new-design-approach-for-human-ai-co-creation/>
+
+## Implementation Takeaways
+
+- A TOCHI-grade prototype should not only "do the task"; it should make the
+  interaction logic inspectable. For this project, that means visible workflow
+  state, artifacts, metrics, agent proposals, approvals, and exported evidence.
+- Parallel-prototyping logic argues against a single opaque model result. The
+  UI should support comparing baseline/candidate predictions and before/after
+  metrics side by side, rather than only showing the latest output.
+- Human-AI interaction guidelines push for calibrated expectations, visible
+  uncertainty/failure, efficient correction, undo/dismissal, and clear handoff.
+  For PyTC Client, the agent must show what it will do, what evidence it used,
+  and whether it is blocked by missing files, long-running jobs, or failed
+  metrics.
+- Human-agent collaboration work stresses mutual awareness and shared
+  accountability. The prototype should preserve an audit trail of agent plans,
+  user approvals/rejections, runtime events, and artifact lineage.
+- Recent workflow-spanning human-AI creation systems treat AI as embedded in
+  multiple structures, not as a chat box bolted onto one screen. Here, the
+  assistant should connect setup, visualization, inference, proofreading,
+  retraining, evaluation, and evidence export through the workflow substrate.
+- Case-study-facing HCI work needs evidence that is reproducible and
+  inspectable. Participant UI should stay focused on the biomedical workflow;
+  researcher case-study gates should remain in docs/tests/export bundles.
+
+## Prototype Implications
+
+- Keep the `Closed-loop Evidence` panel as the central participant-facing
+  evidence surface. It should show baseline/candidate predictions, correction
+  artifacts, reference labels, metric deltas, report paths, and bundle export
+  status.
+- Add explicit controls whenever auto-detection can silently fail. Dataset keys,
+  crop windows, and channel selectors are necessary for HDF5/PyTC outputs.
+- Treat long-running inference/training as accountable jobs, not transient UI
+  state. The next hardening phase should add durable job records, cancellation,
+  retry, and recovery.
+- Make project setup boring. Suggested project mounting and auto-detected data
+  roles reduce demo friction and prevent participants from spending study time
+  debugging paths.
+- Do not claim autonomous closed-loop improvement until the app can perform:
+  baseline inference, proofreading export, retraining/fine-tuning, candidate
+  inference, metric computation, and evidence bundle export using app-generated
+  artifacts.
+
+## Additions To Consider For The Paper
+
+- Frame the system as a workflow evidence substrate plus bounded agentic
+  control layer, not only as a GUI around PyTorch Connectomics.
+- Include a figure that shows artifact lineage: source image/label, baseline
+  prediction, correction set, retraining run, model version, candidate
+  prediction, evaluation result, evidence bundle.
+- Include a design rationale section grounded in human-AI interaction:
+  calibrated autonomy, visible provenance, interruptible/approvable actions,
+  and closed-loop comparison.
+- If case studies are used, separate participant task flow from researcher
+  readiness gates. The latter supports rigor but should not appear as
+  participant-facing protocol UI.
diff --git a/docs/research/workflow-evidence-export.md b/docs/research/workflow-evidence-export.md
index 6ca60b8a..ce9adaed 100644
--- a/docs/research/workflow-evidence-export.md
+++ b/docs/research/workflow-evidence-export.md
@@ -15,14 +15,114 @@ Use the workflow utilities to generate stable evidence summaries for paper notes
 - `workflow_id`
 - `session_snapshot` (current workflow state)
 - `events` (chronologically ordered)
-- `artifact_paths` (`[{ path, exists }]`)
+- `artifact_paths`
+- `bundle_directory` and `bundle_manifest_path` for the durable local export
+- `copied_artifacts` and `skipped_artifacts`
+- `copy_settings` with effective max-size configuration
+- `project_memory_summary`
+
+## Policy-aware artifact metadata
+
+`artifact_paths` entries now include structured policy and reference fields:
+
+- `copy_policy`
+  - `allow_copy`
+  - `reason` (`withheld_reference`, `ground_truth_reference_outside_dataset`,
+    `external_reference_path`, `metadata_restriction`, `size_limit`, etc.)
+  - `policy_code` (`default`, `withheld_reference`,
+    `ground_truth_reference_outside_dataset`, `external_reference_path`, ...)
+- `copy_mode` (for skipped artifacts):
+  - `missing` (path does not exist)
+  - `not_a_file`
+  - `manifest_only`
+  - `policy` (policy-only references)
+  - `size_limit`
+- `reference_scope`
+  - `is_reference_only`
+  - `reference_reason` (`withheld_reference`, `ground_truth_reference_outside_dataset`)
+  - `reference_key`
+- provenance fields:
+  - `source_type` (`session_snapshot`, `event`, `artifact`, ...)
+  - `source_key` / `source_parent_key`
+  - `sources` (all contributing sources for shared paths)
+
+### Policy precedence
+
+When multiple sources emit the same path, path policy reasons merge with this order:
+
+1. `withheld_reference`
+2. `ground_truth_reference_outside_dataset`
+3. `external_reference_path`
+4. metadata restriction / default fallback
+
+This keeps held-out and ground-truth restrictions dominant over generic external-reference tagging.
+
+Reference-only paths are still emitted as skipped artifacts in `skipped_artifacts` with:
+
+- `reason = "reference_only_policy"`
+- `copy_mode = "policy"`
+- `copy_policy` preserving the strongest reason (`withheld_reference` preferred where appropriate)
+
+`artifact_paths` and `skipped_artifacts` are therefore paper-grade enough to recover exact export intent without ad-hoc assumptions.
 
 ## Paper-note utility
 
-`server_api.workflows.evidence_export` provides a deterministic summary shape:
+The durable bundle directory contains:
+
+- `workflow-bundle.json`
+- `artifact-paths.json`
+- `README.md`
+- `files/` (copied payloads)
+
+`copy_manifest_only=true` writes only path metadata and manifest files, skipping bytes.
+
+The same `copy_mode` values above and raw/max-size fields appear in skipped records:
+
+- `size_bytes`
+- `copy_limit_bytes`
+- `raw_copy_max_bytes`
+
+## Evidence export summary shape
+
+`server_api.workflows.evidence_export` now includes stricter, linked summary shapes:
 
 - `stage_progression_summary`
 - `agent_proposal_approval_summary`
+- `agent_proposal_approval_links`
+- `agent_proposal_approval_graph`
+- `user_status_changes`
+- `model_context`
+- `project_memory_summary`
 - `key_event_timeline_snippet`
 
+`agent_proposal_approval_graph` is ordered by proposal creation and is intended to be machine-readable:
+
+- `proposal`: `event_id`, `summary`, `action`, `params`, `stage`, `actor`
+- `approval`: approval event linkage and `approval_payload`
+- `action_events`: proposal→action edges (e.g., `training.run_approved`, `agent.client_effects_approved`, `retraining.staged`)
+- `commands`: command records created from action execution
+- `runs`: model runs linked to proposals/actions with structured `progress_events`
+
+`project_memory_summary` is included as a compact paper-oriented digest with `schema_version` `pytc-project-memory-summary/v1`.
+It includes `workflow_id`, `workflow_stage`, `workflow_title`, `dataset_path`, and
+artifact/run/version/plan/command event counts.
+
+`agent_proposal_approval_links` includes explicit proposal-action-approval links:
+
+- `proposal_event_id`
+- `approval_event_id`
+- `approval_status`
+- `action` (original proposal action)
+- `params` (original proposal params)
+
+`agent_proposal_approval_graph` includes a per-proposal chain:
+
+- `proposal`: `event_id`, `summary`, `action`, `params`, `stage`, `actor`
+- `approval`: `event_id`, `status`, `stage`, `actor`, `approval_payload`
+- `action_events`: event-level progress into action staging
+- `commands`: `command_id`, `command_type`, `status`, `actor`,
+  `source_event_id`, `approval_event_id`, timing fields
+- `runs`: `run_id`, `run_type`, `status`, artifact/config references,
+  `progress_events` (with `event_type`, `run_type`, `run_id`, `actor`, `created_at`, etc.)
+
 Use this when exporting workflow evidence into local research logs for manuscript drafting.
diff --git a/docs/runbooks/demo-health-check.md b/docs/runbooks/demo-health-check.md
new file mode 100644
index 00000000..52790827
--- /dev/null
+++ b/docs/runbooks/demo-health-check.md
@@ -0,0 +1,41 @@
+# demo.seg.bio Health Check Runbook
+
+Run this when updating the public demo build or service stack.
+
+## What this checks
+
+`scripts/check_demo_health.py` verifies:
+
+- Root app returns HTTP 200
+- Canonical workflow endpoint `GET /api/workflows/current` returns HTTP 200
+- Compatibility endpoint `GET /api/api/workflows/current` returns HTTP 200
+- Files root `GET /api/files?parent=root` returns HTTP 200 and JSON list
+- Project suggestions `GET /api/files/project-suggestions` returns HTTP 200 and JSON list
+- App log event ingest `POST /api/app/log-event`
+- Neuroglancer viewer health when either:
+  - a viewer URL is derivable from the current workflow, or
+  - `--neuroglancer-url` is passed
+
+## Deployment components currently involved
+
+- `nginx` fronts `https://demo.seg.bio`
+- Frontend static bundle is deployed to `/var/www/demo.seg.bio`
+- API process runs on port `4342` (service: `pytc-demo@pytc-client-demo2.service`)
+- PyTC worker (behind the API) is configured separately and must be reachable by API
+- Neuroglancer backend is on port `4244`
+- Public tunnel service is `cloudflared-demo-seg-bio.service`
+
+## Run the health check
+
+```bash
+cd /home/weidf/deploy/pytc-client-demo2
+python3 scripts/check_demo_health.py
+```
+
+Optional viewer override:
+
+```bash
+python3 scripts/check_demo_health.py --neuroglancer-url https://demo.seg.bio/neuroglancer/v/<token>/
+```
+
+The script exits with a non-zero status if any required check fails.
diff --git a/pyproject.toml b/pyproject.toml
index 283f740d..3d8a6e7b 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -23,6 +23,7 @@ dependencies = [
     "python-jose>=3.5.0",
     "python-multipart==0.0.20",
     "requests>=2.31",
+    "scikit-image>=0.25",
     "scipy>=1.11",
     "tensorboard==2.20.0",
     "tensorboard-data-server==0.7.2",
@@ -32,6 +33,7 @@ dependencies = [
     "uvicorn==0.38.0",
     "zarr>=2.18",
     "connectomics",
+    "langgraph>=1.0.0",
 ]
 
 [tool.uv.sources]
@@ -39,5 +41,6 @@ dependencies = [
 
 [dependency-groups]
 dev = [
-    "black>=26.1.0",
+    "black==26.5.1",
+    "pytest==9.0.2",
 ]
diff --git a/pytorch_connectomics b/pytorch_connectomics
deleted file mode 160000
index 20ccfde6..00000000
--- a/pytorch_connectomics
+++ /dev/null
@@ -1 +0,0 @@
-Subproject commit 20ccfde6f85868351b00d7b795d4cf89a251d6be
diff --git a/scripts/bootstrap.ps1 b/scripts/bootstrap.ps1
index 9631d34d..fbe1169a 100644
--- a/scripts/bootstrap.ps1
+++ b/scripts/bootstrap.ps1
@@ -4,6 +4,9 @@ $scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
 $rootDir = Split-Path $scriptDir
 $clientDir = Join-Path $rootDir 'client'
 $pytcDir = Join-Path $rootDir 'pytorch_connectomics'
+$targetCommit = '04c2a35e78a1a7ca1138f83a98fc3ef27097abd4'
+$targetRef = 'refs/heads/pytc-client-legacy-runtime'
+$pytcRepository = 'https://github.com/PytorchConnectomics/pytorch_connectomics.git'
 
 function RequireCommand([string]$command, [string]$message) {
     if (-not (Get-Command $command -ErrorAction SilentlyContinue)) {
@@ -18,18 +21,33 @@ RequireCommand 'git' 'git is required to download pytorch_connectomics.'
 Write-Host 'Preparing pytorch_connectomics dependency...'
 if (Test-Path (Join-Path $pytcDir '.git')) {
     Push-Location $pytcDir
-    git fetch origin *> $null
-    $currentCommit = (git rev-parse HEAD) -replace '\s', ''
-    $targetCommit = '0a0dceb'
+    $currentCommit = (git rev-parse --verify HEAD 2> $null) -replace '\s', ''
     if ($currentCommit -ne $targetCommit) {
-        git checkout $targetCommit
+        git fetch --depth 1 origin $targetRef
+        $fetchedCommit = (git rev-parse FETCH_HEAD) -replace '\s', ''
+        if ($fetchedCommit -ne $targetCommit) {
+            throw "$targetRef resolved to $fetchedCommit, expected $targetCommit."
+        }
+        git checkout --detach $targetCommit
     }
     Pop-Location
 } else {
-    git clone 'https://github.com/PytorchConnectomics/pytorch_connectomics.git' $pytcDir
-    Push-Location $pytcDir
-    git checkout '0a0dceb'
-    Pop-Location
+    if (Test-Path $pytcDir) {
+        if ((Get-ChildItem -Force $pytcDir | Measure-Object).Count -ne 0) {
+            throw "$pytcDir exists but is not an empty Git checkout."
+        }
+        Remove-Item $pytcDir
+    }
+
+    New-Item -ItemType Directory -Path $pytcDir | Out-Null
+    git -C $pytcDir init --quiet
+    git -C $pytcDir remote add origin $pytcRepository
+    git -C $pytcDir fetch --depth 1 origin $targetRef
+    $fetchedCommit = (git -C $pytcDir rev-parse FETCH_HEAD) -replace '\s', ''
+    if ($fetchedCommit -ne $targetCommit) {
+        throw "$targetRef resolved to $fetchedCommit, expected $targetCommit."
+    }
+    git -C $pytcDir checkout --detach $targetCommit
 }
 
 Write-Host 'Synchronizing Python environment with uv...'
diff --git a/scripts/browser_yixiao_case_study_smoke.py b/scripts/browser_yixiao_case_study_smoke.py
new file mode 100755
index 00000000..be50f066
--- /dev/null
+++ b/scripts/browser_yixiao_case_study_smoke.py
@@ -0,0 +1,646 @@
+#!/usr/bin/env python3
+"""Browser-level regression smoke for the Yixiao TapeReader XRI case-study UI.
+
+The script exercises the live React UI end-to-end in a browser:
+- application loads
+- Yixiao project appears mounted in Files
+- progress summary reads 10/6/2/2
+- assistant drawer opens and responds to project/training queries
+- training proposal card is editable, and edited fields can be canceled
+- training proposal card text is not obviously clipped at the standard viewport
+- refresh/reopen keeps the app in a continuable state
+
+If Playwright is not installed, the script fails with an explicit install gap
+message so operators know the exact dependency command.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import shlex
+import re
+import time
+import sys
+from typing import Any, Dict, List, Optional, Tuple
+from urllib.parse import urlparse
+
+DEFAULT_BASE_URL = "http://127.0.0.1:3000"
+DEFAULT_REPORT = "/tmp/yixiao-browser-case-study-smoke.json"
+PROJECT_NAME = "Yixiao TapeReader XRI Case Study"
+VIEWPORT_DEFAULT = (1280, 900)
+EXPECTED_PROGRESS = {
+    "Tracked volumes": 10,
+    "Fully good": 6,
+    "Needs proofreading": 2,
+    "No segmentation": 2,
+}
+EXPECTED_COMPLETION_PERCENT = 60
+EXPECTED_SEGMENTATION_COVERAGE_PERCENT = 80
+PROJECT_ROOT_ENTRIES = [
+    "data",
+    "configs",
+    "notes",
+    "outputs",
+    "snapshots",
+    "project_manifest.json",
+]
+PLAYWRIGHT_INSTALL_HINT = """playwright is not installed.
+Install with:
+  {python} -m pip install playwright
+  {python} -m playwright install chromium"""
+
+
+def _playwright_install_hint() -> str:
+    python = shlex.quote(sys.executable or "python3")
+    return PLAYWRIGHT_INSTALL_HINT.format(python=python)
+
+
+def _raise_playwright_error(context: str) -> RuntimeError:
+    return RuntimeError(f"{_playwright_install_hint()}\nObserved issue: {context}")
+
+
+def _normalize_progress_labels(raw: str) -> str:
+    return (raw or "").replace("\n", " ").strip()
+
+
+def _extract_progress_from_text(
+    raw_text: str,
+) -> Tuple[Dict[str, int], Optional[int], Optional[int]]:
+    """Extract summary fields from visible page text.
+
+    Returns:
+        (label->value, completion_pct, segmentation_coverage_pct)
+    """
+
+    text = _normalize_progress_labels(raw_text)
+    values: Dict[str, int] = {}
+    for label, expected in EXPECTED_PROGRESS.items():
+        # Keep this tolerant of layout-specific whitespace/newlines.
+        match = re.search(
+            rf"{re.escape(label)}\s*[^0-9]*?(\"?\d+)?,?", text, re.IGNORECASE
+        )
+        if not match:
+            continue
+        if match.group(1):
+            try:
+                values[label] = int(match.group(1))
+            except ValueError:
+                pass
+
+    completion_match = re.search(r"Completion[^0-9%]{0,40}(\d{1,3})%", text)
+    completion_pct = int(completion_match.group(1)) if completion_match else None
+
+    segcov_match = re.search(
+        r"Segmentation coverage:\s*(\d{1,3})%",
+        text,
+        re.IGNORECASE,
+    )
+    segcov_pct = int(segcov_match.group(1)) if segcov_match else None
+    return values, completion_pct, segcov_pct
+
+
+def _build_arg_parser() -> argparse.ArgumentParser:
+    hint = _playwright_install_hint()
+    parser = argparse.ArgumentParser(
+        description="Browser smoke test for Yixiao TapeReader XRI case-study UI",
+        formatter_class=argparse.RawTextHelpFormatter,
+        epilog=f"If Playwright is missing or missing browsers:\n{hint}",
+    )
+    parser.add_argument(
+        "--base-url",
+        default=DEFAULT_BASE_URL,
+        help=(
+            "Frontend URL to load."
+            " Defaults to local demo frontend (127.0.0.1:3000)."
+            " Pass --base-url https://demo.seg.bio for production-like checks."
+        ),
+    )
+    parser.add_argument(
+        "--timeout-ms",
+        type=int,
+        default=30_000,
+        help=("Timeout in ms for each high-level UI wait step. " "Defaults to 30000."),
+    )
+    parser.add_argument(
+        "--viewport",
+        default=f"{VIEWPORT_DEFAULT[0]}x{VIEWPORT_DEFAULT[1]}",
+        help="Viewport as WIDTHxHEIGHT. Defaults to 1280x900.",
+    )
+    parser.add_argument(
+        "--no-headless",
+        action="store_true",
+        help="Run Playwright with browser UI visible.",
+    )
+    parser.add_argument(
+        "--report",
+        default=DEFAULT_REPORT,
+        help="Optional JSON report path.",
+    )
+    parser.add_argument(
+        "--skip-assistant",
+        action="store_true",
+        help="Skip assistant queries (still validates load, project mount, and progress).",
+    )
+    parser.add_argument(
+        "--skip-reload",
+        action="store_true",
+        help="Skip refresh/reopen continuity checks.",
+    )
+    return parser
+
+
+def _parse_viewport(value: str) -> Tuple[int, int]:
+    if not value:
+        return VIEWPORT_DEFAULT
+    width_height = value.lower().split("x", 1)
+    if len(width_height) != 2:
+        raise argparse.ArgumentTypeError("viewport must be WIDTHxHEIGHT, e.g. 1280x900")
+    width = int(width_height[0])
+    height = int(width_height[1])
+    if width < 320 or height < 320:
+        raise argparse.ArgumentTypeError("viewport dimensions must be >= 320")
+    return width, height
+
+
+def _playwright_import_error() -> Optional[BaseException]:
+    try:
+        from playwright.sync_api import sync_playwright  # type: ignore
+
+        return None
+    except ModuleNotFoundError as exc:
+        return exc
+    except Exception as exc:  # pragma: no cover - defensive for odd envs
+        return exc if isinstance(exc, ImportError) else ImportError(str(exc))
+
+
+def _resolve_browser_playwright(playwright) -> None:
+    browsers = [
+        ("chromium", playwright.chromium),
+        ("firefox", playwright.firefox),
+        ("webkit", playwright.webkit),
+    ]
+    errors: List[str] = []
+    for name, launcher in browsers:
+        try:
+            browser = launcher.launch(headless=True)
+            browser.close()
+            return
+        except Exception as exc:  # pragma: no cover - engine-specific runtime behavior
+            errors.append(f"{name}: {exc}")
+    raise RuntimeError(
+        f"No Playwright browser runtime was available. Attempts: {'; '.join(errors)}"
+    )
+
+
+def _open_tab(page, label: str):
+    menu_item = page.locator(".pytc-top-menu .ant-menu-item").filter(
+        has_text=label,
+    )
+    if not menu_item.count():
+        raise AssertionError(f"Top-level tab '{label}' not found.")
+    menu_item.first.click()
+    # let animation/layout settle
+    page.wait_for_timeout(250)
+
+
+def _is_text_visible(page, text: str) -> bool:
+    locator = page.get_by_text(re.compile(re.escape(text), re.IGNORECASE))
+    return locator.count() > 0 and locator.first.is_visible()
+
+
+def _wait_for_project_mount(page, timeout_ms: int) -> None:
+    if _is_text_visible(page, PROJECT_NAME):
+        return
+
+    suggest_button = page.get_by_role(
+        "button", name=re.compile(r"Use suggested project|Open suggested project", re.I)
+    )
+    if suggest_button.count() > 0 and suggest_button.first.is_enabled():
+        suggest_button.first.click()
+        try:
+            page.get_by_text(re.compile(re.escape(PROJECT_NAME), re.I)).wait_for(
+                timeout=timeout_ms,
+            )
+            return
+        except Exception:
+            pass
+
+    if not _is_text_visible(page, PROJECT_NAME):
+        raise AssertionError(
+            f"Could not find mounted project '{PROJECT_NAME}' on Files page."
+        )
+
+
+def _assert_required_project_entries(page, timeout_ms: int) -> None:
+    for entry in PROJECT_ROOT_ENTRIES:
+        locator = page.get_by_text(re.compile(rf"\b{re.escape(entry)}\b", re.I))
+        if locator.count() == 0:
+            raise AssertionError(
+                f"Required project entry '{entry}' not visible on the page"
+            )
+        try:
+            locator.first.wait_for(timeout=timeout_ms)
+        except Exception as exc:
+            raise AssertionError(
+                f"Required project entry '{entry}' never appeared"
+            ) from exc
+
+
+def _extract_progress_snapshot(page) -> Dict[str, Any]:
+    script = r"""
+    () => {
+      const labels = {
+        "Tracked volumes": "tracked",
+        "Fully good": "good",
+        "Needs proofreading": "proofread",
+        "No segmentation": "missing",
+      };
+      const byLabel = {};
+      const cards = Array.from(document.querySelectorAll('.ant-card'));
+      const parseTextNumber = (value) => {
+        if (typeof value !== 'string') return null;
+        const m = value.match(/([0-9]{1,4})/);
+        return m ? Number(m[1]) : null;
+      };
+      for (const card of cards) {
+        const lines = Array.from(card.querySelectorAll('*'))
+          .map((el) => (el.textContent || '').trim())
+          .flatMap((text) => text.split('\n'))
+          .map((text) => text.trim())
+          .filter(Boolean);
+        for (let i = 0; i < lines.length - 1; i += 1) {
+          const line = lines[i];
+          if (!labels[line]) continue;
+          let j = i + 1;
+          while (j < lines.length && !lines[j].match(/[0-9]/)) j += 1;
+          if (j >= lines.length) continue;
+          const value = parseTextNumber(lines[j]);
+          if (Number.isFinite(value)) {
+            byLabel[labels[line]] = value;
+          }
+        }
+      }
+
+      const text = document.body ? (document.body.innerText || '') : '';
+      const completionMatch = text.match(/Completion[^0-9%]{0,50}(\d{1,3})%/i);
+      const segMatch = text.match(/Segmentation coverage:\s*(\d{1,3})%/i);
+      return {
+        metrics: byLabel,
+        completion_percent: completionMatch ? Number(completionMatch[1]) : null,
+        segmentation_coverage_percent: segMatch ? Number(segMatch[1]) : null,
+      };
+    }
+    """
+    return page.evaluate(script)
+
+
+def _assert_progress(snapshot: Dict[str, Any]) -> None:
+    metrics = snapshot.get("metrics") or {}
+    expected_metric_map = {
+        "tracked": EXPECTED_PROGRESS["Tracked volumes"],
+        "good": EXPECTED_PROGRESS["Fully good"],
+        "proofread": EXPECTED_PROGRESS["Needs proofreading"],
+        "missing": EXPECTED_PROGRESS["No segmentation"],
+    }
+    for key, expected in expected_metric_map.items():
+        actual = metrics.get(key)
+        if actual != expected:
+            raise AssertionError(
+                f"Progress metric '{key}' expected {expected}, got {actual}"
+            )
+
+    completion_pct = snapshot.get("completion_percent")
+    segcov_pct = snapshot.get("segmentation_coverage_percent")
+    if completion_pct != EXPECTED_COMPLETION_PERCENT:
+        raise AssertionError(
+            f"completion_pct expected {EXPECTED_COMPLETION_PERCENT}, got {completion_pct}"
+        )
+    if segcov_pct != EXPECTED_SEGMENTATION_COVERAGE_PERCENT:
+        raise AssertionError(
+            "segmentation_coverage_pct expected "
+            f"{EXPECTED_SEGMENTATION_COVERAGE_PERCENT}, got {segcov_pct}"
+        )
+
+
+def _open_assistant(page) -> None:
+    open_buttons = page.locator(".pytc-top-nav button.ant-btn-circle")
+    if open_buttons.count() < 1:
+        raise AssertionError("Could not find assistant open button on top nav")
+    open_buttons.last.click()
+    close_button = page.locator('button[aria-label="Close assistant"]')
+    close_button.wait_for(state="visible", timeout=8000)
+
+
+def _send_assistant_query(page, query: str, timeout_ms: int) -> str:
+    messages = page.locator(".ant-list-item")
+    before = messages.count()
+
+    input_box = page.get_by_placeholder("Message")
+    input_box.fill("")
+    input_box.type(query)
+    input_box.press("Enter")
+
+    # Wait for at least one new list item (user message + assistant response may still be pending).
+    page.wait_for_function(
+        f"() => document.querySelectorAll('.ant-list-item').length > {before}",
+        timeout=timeout_ms,
+    )
+
+    # Wait for a fresh assistant response containing non-empty text.
+    def _wait_for_reply() -> str:
+        for _ in range(max(1, timeout_ms // 250)):
+            items = messages.all_inner_texts()
+            if len(items) <= before:
+                page.wait_for_timeout(250)
+                continue
+            candidate = items[-1]
+            if candidate and candidate.strip():
+                return candidate
+            page.wait_for_timeout(250)
+        raise AssertionError("No assistant reply text appeared in time")
+
+    reply = _wait_for_reply()
+    return reply
+
+
+def _wait_for_training_proposal(page, timeout_ms: int):
+    locator = page.locator("section[aria-label^='proposal-']").filter(
+        has_text="Approve Training Run"
+    )
+    locator.first.wait_for(timeout=timeout_ms)
+    return locator.first
+
+
+def _check_proposal_editing(page, proposal_locator) -> Dict[str, Any]:
+    edit_button = proposal_locator.locator('button:has-text("Edit details")')
+    if edit_button.count() == 0:
+        raise AssertionError("Training proposal did not expose an edit affordance.")
+    edit_button.first.click()
+
+    editable_fields = proposal_locator.locator('[aria-label^="Edit "]')
+    if editable_fields.count() == 0:
+        raise AssertionError(
+            "Training proposal edit mode did not expose any editable fields."
+        )
+
+    editable_field = editable_fields.first
+    field_label = editable_field.get_attribute("aria-label") or "Edit field"
+    original_value = editable_field.input_value()
+    test_value = f"{original_value} [smoke-edit-check]"
+    editable_field.fill(test_value)
+    page.wait_for_timeout(250)
+
+    approve_button = proposal_locator.locator('button:has-text("Approve with edits")')
+    if approve_button.count() == 0:
+        raise AssertionError(
+            "Proposal edit flow did not flag edited fields as expected."
+        )
+
+    cancel_button = proposal_locator.locator('button:has-text("Cancel edits")')
+    if cancel_button.count() == 0:
+        raise AssertionError("Proposal edit flow did not expose a cancel option.")
+    cancel_button.first.click()
+    page.wait_for_timeout(250)
+
+    if proposal_locator.locator('[aria-label^="Edit "]').count() > 0:
+        raise AssertionError("Proposal edit mode did not close after cancel.")
+    return {
+        "editable_fields": editable_fields.count(),
+        "edited_field_label": field_label,
+        "edit_flow": "passed",
+    }
+
+
+def _check_proposal_card_for_text_clipping(page, proposal_locator) -> Dict[str, Any]:
+    details = page.evaluate(
+        """
+        (el) => {
+          const node = typeof el === 'string' ? document.querySelector(el) : el;
+          if (!node) {
+            return {found: false, overflow: true, reasons: ['proposal element not found']};
+          }
+          const isVisible = (element) => {
+            const rect = element.getBoundingClientRect();
+            const style = getComputedStyle(element);
+            return rect.width > 0 && rect.height > 0 && style.display !== 'none' && style.visibility !== 'hidden';
+          };
+          const offenders = [];
+          const walk = (element) => {
+            const children = Array.from(element.querySelectorAll('*'));
+            for (const child of children) {
+              if (!isVisible(child)) continue;
+              const style = getComputedStyle(child);
+              if (style.overflowX === 'hidden' && child.scrollWidth > child.clientWidth + 1) {
+                offenders.push({
+                  text: (child.textContent || '').slice(0, 140),
+                  clientWidth: child.clientWidth,
+                  scrollWidth: child.scrollWidth,
+                  clientHeight: child.clientHeight,
+                  scrollHeight: child.scrollHeight,
+                  overflowX: style.overflowX,
+                });
+              }
+              if (child.scrollWidth > child.clientWidth + 1) {
+                offenders.push({
+                  text: (child.textContent || '').slice(0, 140),
+                  clientWidth: child.clientWidth,
+                  scrollWidth: child.scrollWidth,
+                  clientHeight: child.clientHeight,
+                  scrollHeight: child.scrollHeight,
+                  overflowX: style.overflowX,
+                });
+              }
+            }
+          };
+          walk(node);
+          const proposalWidth = node.getBoundingClientRect().width;
+          return {
+            found: true,
+            overflow: offenders.length > 0,
+            proposalWidth,
+            count: offenders.length,
+            offenders: offenders.slice(0, 5),
+          };
+        }
+        """,
+        proposal_locator,
+    )
+    if details.get("overflow"):
+        raise AssertionError(
+            f"Proposal card appears horizontally clipped: {json.dumps(details)}"
+        )
+    return details
+
+
+def _refresh_and_reopen_checks(page, timeout_ms: int, skip_assistant: bool) -> None:
+    page.reload(wait_until="networkidle")
+    page.wait_for_load_state("domcontentloaded")
+    _open_tab(page, "Files")
+    page.wait_for_timeout(400)
+    _wait_for_project_mount(page, timeout_ms)
+
+    _open_tab(page, "Workflow")
+    page.wait_for_timeout(300)
+    snapshot = _extract_progress_snapshot(page)
+    _assert_progress(snapshot)
+
+    if skip_assistant:
+        return
+
+    _open_assistant(page)
+    reply = _send_assistant_query(
+        page,
+        "what project are we looking at?",
+        timeout_ms=timeout_ms,
+    )
+    if "yixiao" not in reply.lower():
+        raise AssertionError(
+            f"Assistant did not mention Yixiao after reload. Reply: {reply}"
+        )
+
+
+def run_smoke(
+    base_url: str,
+    timeout_ms: int,
+    viewport: Tuple[int, int],
+    headless: bool,
+    skip_assistant: bool,
+    skip_reload: bool,
+) -> Dict[str, Any]:
+    result = {
+        "passed": True,
+        "base_url": base_url,
+        "checks": [],
+    }
+
+    viewport_config = {"width": viewport[0], "height": viewport[1]}
+    playwright_error = _playwright_import_error()
+    if playwright_error is not None:
+        raise _raise_playwright_error(str(playwright_error))
+
+    from playwright.sync_api import sync_playwright
+
+    with sync_playwright() as p:
+        # Pick a working engine once to avoid launch failures at runtime.
+        try:
+            _resolve_browser_playwright(p)
+        except RuntimeError as exc:
+            raise _raise_playwright_error(str(exc))
+        browser = p.chromium.launch(headless=headless)
+        context = browser.new_context(viewport=viewport_config)
+        page = context.new_page()
+        page.set_default_timeout(timeout_ms)
+
+        try:
+            page.goto(base_url, wait_until="networkidle", timeout=timeout_ms)
+            if "Yixiao" in (page.title() or ""):
+                result["checks"].append("page loaded")
+            else:
+                result["checks"].append(f"page title: {page.title()}")
+
+            _open_tab(page, "Files")
+            page.wait_for_timeout(300)
+
+            _wait_for_project_mount(page, timeout_ms)
+            _assert_required_project_entries(page, timeout_ms)
+            result["checks"].append("project mounted")
+
+            _open_tab(page, "Workflow")
+            page.wait_for_timeout(300)
+            snapshot = _extract_progress_snapshot(page)
+            _assert_progress(snapshot)
+            result["checks"].append("progress counts verified")
+            result["progress_snapshot"] = snapshot
+
+            if not skip_assistant:
+                _open_assistant(page)
+                result["checks"].append("assistant opened")
+
+                project_reply = _send_assistant_query(
+                    page,
+                    "what project are we looking at?",
+                    timeout_ms,
+                )
+                if "yixiao" not in project_reply.lower():
+                    raise AssertionError(
+                        "Assistant did not confirm Yixiao case-study context."
+                    )
+                result["checks"].append("assistant project context check")
+
+                _send_assistant_query(
+                    page,
+                    "train on the fully good masks to segment the image-only volumes",
+                    timeout_ms,
+                )
+                proposal = _wait_for_training_proposal(page, timeout_ms)
+                edit_report = _check_proposal_editing(page, proposal)
+                overflow_report = _check_proposal_card_for_text_clipping(page, proposal)
+                result["checks"].append("assistant proposal editing check")
+                result["proposal_edit_report"] = edit_report
+                result["checks"].append("assistant proposal card text clipping check")
+                result["proposal_card_metrics"] = overflow_report
+
+            if not skip_reload:
+                _refresh_and_reopen_checks(
+                    page, timeout_ms, skip_assistant=skip_assistant
+                )
+                result["checks"].append("refresh/reopen continuity check")
+
+        finally:
+            context.close()
+            browser.close()
+
+    return result
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    parser = _build_arg_parser()
+    args = parser.parse_args(argv)
+
+    base_url = args.base_url.rstrip("/")
+    parsed = urlparse(base_url)
+    if parsed.scheme not in {"http", "https"}:
+        raise ValueError("base-url must include a scheme, e.g. http://127.0.0.1:3000")
+
+    viewport = _parse_viewport(args.viewport)
+    timeout_ms = max(5000, int(args.timeout_ms))
+
+    report: Dict[str, Any] = {
+        "generated_at_unix": time.time(),
+        "script": __file__,
+    }
+
+    try:
+        checks = run_smoke(
+            base_url=base_url,
+            timeout_ms=timeout_ms,
+            viewport=viewport,
+            headless=not args.no_headless,
+            skip_assistant=args.skip_assistant,
+            skip_reload=args.skip_reload,
+        )
+        report.update(checks)
+        report["passed"] = True
+        print("Yixiao browser smoke passed.")
+    except Exception as exc:
+        report.update(
+            {
+                "passed": False,
+                "error": str(exc),
+                "error_type": exc.__class__.__name__,
+            },
+        )
+        print(f"Yixiao browser smoke failed: {exc}")
+
+    with open(args.report, "w", encoding="utf-8") as handle:
+        json.dump(report, handle, indent=2, sort_keys=True)
+    print(f"Report: {args.report}")
+
+    if not report["passed"]:
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/scripts/check_demo_health.py b/scripts/check_demo_health.py
new file mode 100644
index 00000000..07b262f1
--- /dev/null
+++ b/scripts/check_demo_health.py
@@ -0,0 +1,358 @@
+#!/usr/bin/env python3
+"""Lightweight public health checks for demo.seg.bio deployment."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from dataclasses import dataclass
+from typing import Any
+from urllib.parse import urljoin
+
+import requests
+
+DEFAULT_DEMO_BASE = "https://demo.seg.bio"
+DEFAULT_TIMEOUT = 5.0
+
+
+@dataclass(frozen=True)
+class CheckResult:
+    name: str
+    ok: bool
+    message: str
+    critical: bool = True
+
+
+def _build_url(base_url: str, path: str) -> str:
+    return f"{base_url.rstrip('/')}/{path.lstrip('/')}"
+
+
+def _to_json(response: requests.Response) -> Any | None:
+    try:
+        return response.json()
+    except ValueError:
+        return None
+
+
+def _require_status(
+    response: requests.Response, *, expected: int, check_name: str, detail: str
+) -> CheckResult:
+    if response.status_code != expected:
+        return CheckResult(check_name, False, f"{detail}: HTTP {response.status_code}")
+    return CheckResult(check_name, True, f"{detail} (status {response.status_code})")
+
+
+def _check_root(base_url: str, timeout: float) -> CheckResult:
+    response = requests.get(_build_url(base_url, "/"), timeout=timeout)
+    return _require_status(
+        response,
+        expected=200,
+        check_name="root.app",
+        detail="Root app path returned",
+    )
+
+
+def _check_json_dict(
+    response: requests.Response,
+    *,
+    check_name: str,
+    path: str,
+    required_fields: list[str] | None = None,
+) -> tuple[CheckResult, Any | None]:
+    status_check = _require_status(
+        response,
+        expected=200,
+        check_name=check_name,
+        detail=f"{path} returned",
+    )
+    if not status_check.ok:
+        return status_check, None
+
+    payload = _to_json(response)
+    if not isinstance(payload, dict):
+        return (
+            CheckResult(check_name, False, f"{path} returned non-JSON payload"),
+            None,
+        )
+
+    if required_fields:
+        missing = [field for field in required_fields if field not in payload]
+        if missing:
+            return (
+                CheckResult(
+                    check_name,
+                    False,
+                    f"{path} missing required fields: {', '.join(missing)}",
+                ),
+                payload,
+            )
+
+    return CheckResult(check_name, True, f"{path} returned valid JSON"), payload
+
+
+def _check_workflow_routes(
+    base_url: str, timeout: float
+) -> tuple[list[CheckResult], dict[str, Any] | None]:
+    results: list[CheckResult] = []
+
+    canonical_path = "/api/workflows/current"
+    compat_path = "/api/api/workflows/current"
+
+    canonical_response = requests.get(
+        _build_url(base_url, canonical_path), timeout=timeout
+    )
+    canonical_result, canonical_payload = _check_json_dict(
+        canonical_response,
+        check_name="workflow.current",
+        path=canonical_path,
+        required_fields=["workflow", "events"],
+    )
+    results.append(canonical_result)
+
+    compat_response = requests.get(_build_url(base_url, compat_path), timeout=timeout)
+    compat_result, compat_payload = _check_json_dict(
+        compat_response,
+        check_name="workflow.compat",
+        path=compat_path,
+        required_fields=["workflow", "events"],
+    )
+
+    if compat_result.ok and isinstance(compat_payload, dict):
+        workflow = compat_payload.get("workflow")
+        if isinstance(workflow, dict):
+            compat_workflow_id = workflow.get("id")
+            compat_result = CheckResult(
+                "workflow.compat",
+                True,
+                f"{compat_path} returned workflow {compat_workflow_id}",
+            )
+    results.append(compat_result)
+
+    workflow_payload: dict[str, Any] | None = None
+    if canonical_result.ok and isinstance(canonical_payload, dict):
+        workflow_payload = canonical_payload
+    elif compat_result.ok and isinstance(compat_payload, dict):
+        workflow_payload = compat_payload
+
+    return results, workflow_payload
+
+
+def _check_files_root(base_url: str, timeout: float) -> CheckResult:
+    response = requests.get(
+        _build_url(base_url, "/api/files"),
+        params={"parent": "root"},
+        timeout=timeout,
+    )
+    status_result = _require_status(
+        response,
+        expected=200,
+        check_name="files.root",
+        detail="Files root check",
+    )
+    if not status_result.ok:
+        return status_result
+
+    payload = _to_json(response)
+    if not isinstance(payload, list):
+        return CheckResult(
+            "files.root",
+            False,
+            "Files root returned non-list JSON",
+        )
+
+    return CheckResult(
+        "files.root", True, f"Files root returned {len(payload)} entries"
+    )
+
+
+def _check_project_suggestions(base_url: str, timeout: float) -> CheckResult:
+    response = requests.get(
+        _build_url(base_url, "/api/files/project-suggestions"), timeout=timeout
+    )
+    status_result = _require_status(
+        response,
+        expected=200,
+        check_name="files.project_suggestions",
+        detail="Project suggestions",
+    )
+    if not status_result.ok:
+        return status_result
+
+    payload = _to_json(response)
+    if not isinstance(payload, list):
+        return CheckResult(
+            "files.project_suggestions",
+            False,
+            "Project suggestions returned non-list JSON",
+        )
+
+    return CheckResult(
+        "files.project_suggestions",
+        True,
+        f"Project suggestions returned {len(payload)} entries",
+    )
+
+
+def _check_app_log_event(base_url: str, timeout: float) -> CheckResult:
+    response = requests.post(
+        _build_url(base_url, "/api/app/log-event"),
+        json={
+            "event": "demo.health_check",
+            "level": "INFO",
+            "message": "demo health check",
+            "source": "check_demo_health.py",
+            "data": {
+                "check": "public_demo_health",
+            },
+        },
+        timeout=timeout,
+        headers={"Content-Type": "application/json"},
+    )
+    status_result = _require_status(
+        response,
+        expected=200,
+        check_name="app.log_event",
+        detail="App log event endpoint",
+    )
+    if not status_result.ok:
+        return status_result
+
+    payload = _to_json(response)
+    if not isinstance(payload, dict):
+        return CheckResult(
+            "app.log_event", False, "App log event returned non-JSON payload"
+        )
+
+    status_value = str(payload.get("status", "")).lower()
+    if status_value not in {"ok", "success"}:
+        return CheckResult(
+            "app.log_event",
+            False,
+            f"App log event returned unexpected status payload: {payload!r}",
+        )
+
+    return CheckResult("app.log_event", True, "App log event accepted")
+
+
+def _check_viewer_health(
+    base_url: str,
+    timeout: float,
+    *,
+    workflow_payload: dict[str, Any] | None,
+    configured_url: str | None,
+) -> list[CheckResult]:
+    results: list[CheckResult] = []
+    candidate = (configured_url or "").strip()
+
+    if not candidate and workflow_payload:
+        workflow = workflow_payload.get("workflow")
+        if isinstance(workflow, dict):
+            candidate = str(workflow.get("neuroglancer_url", "")).strip()
+
+    if not candidate:
+        return [
+            CheckResult(
+                "viewer.health",
+                False,
+                "No viewer URL available; skipped",
+                critical=False,
+            )
+        ]
+
+    if candidate.startswith("/"):
+        candidate = urljoin(base_url.rstrip("/") + "/", candidate.lstrip("/"))
+
+    response = requests.get(candidate, timeout=timeout)
+    status_result = _require_status(
+        response,
+        expected=200,
+        check_name="viewer.health",
+        detail="Neuroglancer viewer",
+    )
+    if not status_result.ok:
+        return [status_result]
+
+    return [
+        CheckResult(
+            "viewer.health",
+            True,
+            f"Neuroglancer viewer check passed for {candidate}",
+        )
+    ]
+
+
+def _format_result(result: CheckResult) -> str:
+    label = "PASS" if result.ok else "FAIL"
+    if not result.ok and not result.critical:
+        label = "SKIP"
+    return f"[{label}] {result.name}: {result.message}"
+
+
+def run(base_url: str, timeout: float, neuroglancer_url: str | None = None) -> int:
+    checks: list[CheckResult] = []
+
+    checks.append(_check_root(base_url, timeout))
+
+    workflow_results, workflow_payload = _check_workflow_routes(base_url, timeout)
+    checks.extend(workflow_results)
+
+    checks.append(_check_files_root(base_url, timeout))
+    checks.append(_check_project_suggestions(base_url, timeout))
+    checks.append(_check_app_log_event(base_url, timeout))
+    checks.extend(
+        _check_viewer_health(
+            base_url,
+            timeout,
+            workflow_payload=workflow_payload,
+            configured_url=neuroglancer_url,
+        )
+    )
+
+    for result in checks:
+        print(_format_result(result))
+
+    failed = [result for result in checks if result.critical and not result.ok]
+    if failed:
+        print(f"\nHealth check failed ({len(failed)} failing checks)")
+        for check in failed:
+            print(f" - {check.name}: {check.message}")
+        return 1
+
+    return 0
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Run demo.seg.bio health checks")
+    parser.add_argument(
+        "--base",
+        default=os.environ.get("DEMO_BASE_URL", DEFAULT_DEMO_BASE),
+        help=f"Demo base URL (default: {DEFAULT_DEMO_BASE})",
+    )
+    parser.add_argument(
+        "--timeout",
+        type=float,
+        default=DEFAULT_TIMEOUT,
+        help=f"Request timeout in seconds (default: {DEFAULT_TIMEOUT})",
+    )
+    parser.add_argument(
+        "--neuroglancer-url",
+        default=os.environ.get("DEMO_NEUROGLANCER_URL", ""),
+        help="Override Neuroglancer URL to probe for viewer health",
+    )
+    return parser.parse_args()
+
+
+def main() -> None:
+    args = parse_args()
+    sys.exit(
+        run(
+            base_url=args.base,
+            timeout=args.timeout,
+            neuroglancer_url=args.neuroglancer_url,
+        )
+    )
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/dev.sh b/scripts/dev.sh
index 455ed869..1c4b8650 100755
--- a/scripts/dev.sh
+++ b/scripts/dev.sh
@@ -4,8 +4,10 @@ set -euo pipefail
 
 ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 CLIENT_DIR="${ROOT_DIR}/client"
-DEFAULT_OLLAMA_BASE_URL="http://cscigpu08.bc.edu:4443"
-DEFAULT_OLLAMA_MODEL="llama3.1:8b"
+DEFAULT_OLLAMA_BASE_URL="http://127.0.0.1:11434"
+DEFAULT_OLLAMA_MODEL="qwen3.6:27b"
+DEFAULT_OLLAMA_EMBED_MODEL="qwen3-embedding:8b"
+export PYTC_UNLOAD_OLLAMA_BEFORE_TRAINING="${PYTC_UNLOAD_OLLAMA_BEFORE_TRAINING:-0}"
 
 if ! command -v uv >/dev/null 2>&1; then
 	echo "uv is required. Run scripts/bootstrap.sh first." >&2
@@ -44,6 +46,8 @@ DATA_SERVER_PID=$!
 echo "Starting API server (port 4242)..."
 OLLAMA_BASE_URL="${OLLAMA_BASE_URL:-${DEFAULT_OLLAMA_BASE_URL}}" \
 	OLLAMA_MODEL="${OLLAMA_MODEL:-${DEFAULT_OLLAMA_MODEL}}" \
+	PYTC_WORKFLOW_INTENT_MODEL="${PYTC_WORKFLOW_INTENT_MODEL:-${OLLAMA_MODEL:-${DEFAULT_OLLAMA_MODEL}}}" \
+	OLLAMA_EMBED_MODEL="${OLLAMA_EMBED_MODEL:-${DEFAULT_OLLAMA_EMBED_MODEL}}" \
 	PYTHONDONTWRITEBYTECODE=1 uv run --directory "${ROOT_DIR}" python -m server_api.main &
 API_PID=$!
 
diff --git a/scripts/ingest_prepilot_datasets.py b/scripts/ingest_prepilot_datasets.py
new file mode 100644
index 00000000..04b068ce
--- /dev/null
+++ b/scripts/ingest_prepilot_datasets.py
@@ -0,0 +1,762 @@
+#!/usr/bin/env python3
+"""Ingest public PyTC prepilot datasets into project-shaped folders.
+
+The goal is not to mirror every benchmark at full scale. It is to stage realistic
+project folders that exercise the app's setup, agent, runtime, proofreading, and
+evidence-export paths without silently depending on the old mito25 demo state.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shutil
+import subprocess
+import textwrap
+import zipfile
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+SCRIPT_PATH = Path(__file__).resolve()
+REPO_ROOT = SCRIPT_PATH.parents[1]
+SEG_ROOT = REPO_ROOT.parent
+DEFAULT_PROJECT_ROOT = SEG_ROOT / "testing_projects"
+DEFAULT_DATA_ROOT = SEG_ROOT / "testing_data"
+ALLOW_DOWNLOADS = True
+
+
+@dataclass
+class Role:
+    name: str
+    path: Path | None
+    description: str
+    hdf5_key: str | None = None
+
+    def as_json(self, project_dir: Path) -> dict[str, Any]:
+        if self.path is None:
+            value = None
+        else:
+            try:
+                value = str(self.path.resolve().relative_to(project_dir.resolve()))
+            except ValueError:
+                value = str(self.path.resolve())
+        out: dict[str, Any] = {
+            "name": self.name,
+            "path": value,
+            "description": self.description,
+        }
+        if self.hdf5_key:
+            out["hdf5_key"] = self.hdf5_key
+        return out
+
+
+@dataclass
+class ProjectSpec:
+    slug: str
+    title: str
+    task: str
+    source: str
+    notes: list[str] = field(default_factory=list)
+    roles: list[Role] = field(default_factory=list)
+    recommended_configs: list[Path] = field(default_factory=list)
+    source_urls: list[str] = field(default_factory=list)
+    status: str = "ready"
+
+
+def run(cmd: list[str], cwd: Path | None = None) -> None:
+    print("+ " + " ".join(cmd), flush=True)
+    subprocess.run(cmd, cwd=str(cwd) if cwd else None, check=True)
+
+
+def ensure_dir(path: Path) -> Path:
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def safe_unlink(path: Path) -> None:
+    if path.is_symlink() or path.is_file():
+        path.unlink()
+
+
+def symlink_or_keep(src: Path, dst: Path) -> None:
+    if not src.exists():
+        raise FileNotFoundError(src)
+    ensure_dir(dst.parent)
+    if dst.exists() or dst.is_symlink():
+        if dst.is_symlink() and dst.resolve() == src.resolve():
+            return
+        safe_unlink(dst)
+    dst.symlink_to(src)
+
+
+def copy_file(src: Path, dst: Path) -> None:
+    if not src.exists():
+        raise FileNotFoundError(src)
+    ensure_dir(dst.parent)
+    shutil.copy2(src, dst)
+
+
+def download(url: str, dst: Path) -> None:
+    ensure_dir(dst.parent)
+    if dst.exists() and dst.stat().st_size > 0:
+        print(f"Already downloaded: {dst}", flush=True)
+        return
+    if not ALLOW_DOWNLOADS:
+        print(f"Download disabled, missing: {dst}", flush=True)
+        return
+    part = dst.with_suffix(dst.suffix + ".part")
+    cmd = [
+        "curl",
+        "-L",
+        "--fail",
+        "--retry",
+        "3",
+        "--retry-delay",
+        "2",
+        "--continue-at",
+        "-",
+        "--output",
+        str(part),
+        url,
+    ]
+    run(cmd)
+    part.rename(dst)
+
+
+def extract_zip(zip_path: Path, dst: Path, delete_archive: bool = True) -> None:
+    marker = dst / ".extract_complete"
+    if marker.exists():
+        print(f"Already extracted: {dst}", flush=True)
+        if delete_archive and zip_path.exists():
+            zip_path.unlink()
+        return
+    ensure_dir(dst)
+    with zipfile.ZipFile(zip_path) as zf:
+        zf.extractall(dst)
+    marker.write_text("ok\n")
+    if delete_archive:
+        zip_path.unlink()
+
+
+def free_bytes(path: Path) -> int:
+    usage = shutil.disk_usage(path)
+    return usage.free
+
+
+def require_space(path: Path, needed_bytes: int, label: str) -> bool:
+    free = free_bytes(path)
+    if free < needed_bytes:
+        print(
+            f"Skipping {label}: needs about {needed_bytes / 1e9:.2f}GB free, "
+            f"only {free / 1e9:.2f}GB available.",
+            flush=True,
+        )
+        return False
+    return True
+
+
+def rel_or_abs(path: Path, base: Path) -> str:
+    try:
+        return str(path.resolve().relative_to(base.resolve()))
+    except ValueError:
+        return str(path.resolve())
+
+
+def inspect_hdf5(path: Path, limit: int = 40) -> list[dict[str, Any]]:
+    try:
+        import h5py
+    except Exception:
+        return []
+
+    datasets: list[dict[str, Any]] = []
+
+    def visit(name: str, obj: Any) -> None:
+        if len(datasets) >= limit:
+            return
+        if isinstance(obj, h5py.Dataset):
+            datasets.append(
+                {
+                    "key": name,
+                    "shape": list(obj.shape),
+                    "dtype": str(obj.dtype),
+                }
+            )
+
+    try:
+        with h5py.File(path, "r") as handle:
+            handle.visititems(visit)
+    except Exception as exc:
+        datasets.append({"error": repr(exc)})
+    return datasets
+
+
+def inspect_tiff(path: Path) -> dict[str, Any]:
+    try:
+        import tifffile
+
+        with tifffile.TiffFile(path) as tif:
+            series = tif.series[0]
+            return {"shape": list(series.shape), "dtype": str(series.dtype)}
+    except Exception as exc:
+        return {"error": repr(exc)}
+
+
+def write_manifest(project_dir: Path, spec: ProjectSpec) -> None:
+    hdf5: dict[str, list[dict[str, Any]]] = {}
+    tiff: dict[str, dict[str, Any]] = {}
+    for file_path in sorted(project_dir.rglob("*")):
+        if not file_path.is_file():
+            continue
+        suffix = file_path.suffix.lower()
+        rel = rel_or_abs(file_path, project_dir)
+        if suffix in {".h5", ".hdf", ".hdf5"}:
+            hdf5[rel] = inspect_hdf5(file_path)
+        elif suffix in {".tif", ".tiff"}:
+            tiff[rel] = inspect_tiff(file_path)
+
+    manifest = {
+        "schema": "pytc-prepilot-project/v1",
+        "slug": spec.slug,
+        "title": spec.title,
+        "task": spec.task,
+        "source": spec.source,
+        "status": spec.status,
+        "source_urls": spec.source_urls,
+        "roles": [role.as_json(project_dir) for role in spec.roles],
+        "recommended_configs": [
+            rel_or_abs(path, project_dir)
+            for path in spec.recommended_configs
+            if path.exists()
+        ],
+        "notes": spec.notes,
+        "hdf5_inventory": hdf5,
+        "tiff_inventory": tiff,
+    }
+    (project_dir / "project_manifest.json").write_text(
+        json.dumps(manifest, indent=2, sort_keys=True) + "\n"
+    )
+
+    notes_dir = ensure_dir(project_dir / "notes")
+    readme = [
+        f"# {spec.title}",
+        "",
+        f"Task: {spec.task}",
+        f"Status: {spec.status}",
+        f"Source: {spec.source}",
+        "",
+        "## Roles",
+        "",
+    ]
+    for role in spec.roles:
+        path_text = role.as_json(project_dir)["path"]
+        key_text = f" HDF5 key: `{role.hdf5_key}`." if role.hdf5_key else ""
+        readme.append(f"- `{role.name}`: `{path_text}`. {role.description}.{key_text}")
+    readme += [
+        "",
+        "## Recommended Configs",
+        "",
+    ]
+    if spec.recommended_configs:
+        for config in spec.recommended_configs:
+            readme.append(f"- `{rel_or_abs(config, project_dir)}`")
+    else:
+        readme.append("- No runnable config was written yet; see notes below.")
+    readme += [
+        "",
+        "## Notes",
+        "",
+    ]
+    for note in spec.notes:
+        readme.append(f"- {note}")
+    readme.append("")
+    (notes_dir / "README.md").write_text("\n".join(readme))
+    prepilot_log = notes_dir / "prepilot-log.md"
+    if not prepilot_log.exists():
+        prepilot_log.write_text(textwrap.dedent("""\
+                # Prepilot Log
+
+                | Check | Result | Evidence path | Notes |
+                | --- | --- | --- | --- |
+                | Project roles inferred correctly | pending |  |  |
+                | Config selected correctly | pending |  |  |
+                | Agent next-step answer useful | pending |  |  |
+                | Agent action approval works | pending |  |  |
+                | Runtime starts | pending |  |  |
+                | Runtime summary readable | pending |  |  |
+                | Proofreading loads quickly | pending |  |  |
+                | Mask save persists | pending |  |  |
+                | Export works | pending |  |  |
+                | Candidate metrics computed | pending |  |  |
+                | Evidence bundle exported | pending |  |  |
+                """))
+
+
+def patch_yaml_text(src: Path, dst: Path, replacements: dict[str, str]) -> None:
+    text = src.read_text()
+    for old, new in replacements.items():
+        text = text.replace(old, new)
+    ensure_dir(dst.parent)
+    dst.write_text(text)
+
+
+def init_project(project_root: Path, slug: str) -> Path:
+    project_dir = ensure_dir(project_root / slug)
+    for child in [
+        "data/image",
+        "data/seg",
+        "data/prediction",
+        "configs",
+        "checkpoints",
+        "outputs",
+        "notes",
+    ]:
+        ensure_dir(project_dir / child)
+    return project_dir
+
+
+def stage_local_mito25_smoke(project_root: Path, data_root: Path) -> ProjectSpec:
+    slug = "prepilot_mito25_smoke"
+    project_dir = init_project(project_root, slug)
+    source = data_root / "mito25_smoke"
+    symlink_or_keep(source / "image", project_dir / "data/image/source")
+    symlink_or_keep(source / "seg", project_dir / "data/seg/source")
+    config = project_dir / "configs/Mito25-Local-Smoke-BC.yaml"
+    copy_file(
+        REPO_ROOT / "pytorch_connectomics/configs/MitoEM/Mito25-Local-Smoke-BC.yaml",
+        config,
+    )
+    spec = ProjectSpec(
+        slug=slug,
+        title="Prepilot Mito25 Smoke",
+        task="Tiny local mitochondria instance-segmentation smoke loop",
+        source=str(source),
+        roles=[
+            Role("dataset_path", project_dir / "data", "Project data root"),
+            Role(
+                "image_path",
+                project_dir / "data/image/source/512-768_8192-10240_11264-13312_im.h5",
+                "Training/proofreading image volume",
+            ),
+            Role(
+                "label_path",
+                project_dir / "data/seg/source/512-768_8192-10240_11264-13312_seg.h5",
+                "Training/proofreading segmentation labels",
+            ),
+            Role(
+                "inference_image_path",
+                project_dir / "data/image/source/512-768_8192-10240_13312-15360_im.h5",
+                "Held-out image volume for inference smoke",
+            ),
+        ],
+        recommended_configs=[config],
+        notes=[
+            "Use first because it is fast and already aligned with the current app runtime configs.",
+            "This fixture is not a biological generality test; it is an app closed-loop sanity test.",
+        ],
+    )
+    write_manifest(project_dir, spec)
+    return spec
+
+
+def stage_local_snemi(project_root: Path, data_root: Path) -> ProjectSpec:
+    slug = "prepilot_snemi3d_local"
+    project_dir = init_project(project_root, slug)
+    source = data_root / "snemi"
+    symlink_or_keep(source / "image", project_dir / "data/image/source")
+    symlink_or_keep(source / "seg", project_dir / "data/seg/source")
+    config_base = project_dir / "configs/SNEMI-Prepilot-Base.yaml"
+    src_base = REPO_ROOT / "pytorch_connectomics/configs/SNEMI/SNEMI-Base.yaml"
+    text = src_base.read_text()
+    text = text.replace(
+        "INPUT_PATH: datasets/SNEMI3D/ # or your own dataset path",
+        f"INPUT_PATH: {project_dir / 'data'}",
+    )
+    text = text.replace(
+        "OUTPUT_PATH: outputs/SNEMI3D/test",
+        f"OUTPUT_PATH: {project_dir / 'outputs/inference'}",
+    )
+    text = text.replace(
+        "OUTPUT_PATH: outputs/SNEMI3D/", f"OUTPUT_PATH: {project_dir / 'outputs/train'}"
+    )
+    config_base.write_text(text)
+    config_model = project_dir / "configs/SNEMI-Affinity-UNet.yaml"
+    copy_file(
+        REPO_ROOT / "pytorch_connectomics/configs/SNEMI/SNEMI-Affinity-UNet.yaml",
+        config_model,
+    )
+    spec = ProjectSpec(
+        slug=slug,
+        title="Prepilot SNEMI3D Local",
+        task="Dense neurite affinity segmentation and postprocessing stress test",
+        source=str(source),
+        roles=[
+            Role("dataset_path", project_dir / "data", "Project data root"),
+            Role(
+                "image_path",
+                project_dir / "data/image/source/train-input.tif",
+                "Training image volume",
+            ),
+            Role(
+                "label_path",
+                project_dir / "data/seg/source/train-labels.tif",
+                "Training segmentation labels",
+            ),
+            Role(
+                "inference_image_path",
+                project_dir / "data/image/source/test-input.tif",
+                "Inference image volume",
+            ),
+        ],
+        recommended_configs=[config_base, config_model],
+        notes=[
+            "Affinity outputs are not directly editable instance masks; a robust agent should route through waterz/zwatershed.",
+            "This local SNEMI fixture already existed, so it is symlinked rather than duplicated.",
+        ],
+        source_urls=["http://rhoana.rc.fas.harvard.edu/dataset/snemi.zip"],
+    )
+    write_manifest(project_dir, spec)
+    return spec
+
+
+def stage_mitoem_toy(project_root: Path) -> ProjectSpec:
+    slug = "prepilot_mitoem_toy"
+    project_dir = init_project(project_root, slug)
+    image = project_dir / "data/image/mitoem_R_train_4um_im.h5"
+    seg = project_dir / "data/seg/mitoem_R_train_4um_seg.h5"
+    image_url = "https://huggingface.co/datasets/pytc/MitoEM/resolve/main/mitoem_R_train_4um_im.h5?download=true"
+    seg_url = "https://huggingface.co/datasets/pytc/MitoEM/resolve/main/mitoem_R_train_4um_seg.h5?download=true"
+    if require_space(project_root, 60_000_000, slug):
+        download(image_url, image)
+        download(seg_url, seg)
+    config = project_dir / "configs/MitoEM-Toy-BC-Smoke.yaml"
+    src = REPO_ROOT / "pytorch_connectomics/configs/MitoEM/Mito25-Local-Smoke-BC.yaml"
+    text = src.read_text()
+    old_train_im = "/Users/adamg/seg.bio/testing_data/mito25_smoke/image/512-768_8192-10240_11264-13312_im.h5"
+    old_train_seg = "/Users/adamg/seg.bio/testing_data/mito25_smoke/seg/512-768_8192-10240_11264-13312_seg.h5"
+    old_infer_im = "/Users/adamg/seg.bio/testing_data/mito25_smoke/image/512-768_8192-10240_13312-15360_im.h5"
+    old_output = "/Users/adamg/seg.bio/outputs/mito25_local_smoke_bc"
+    text = text.replace(old_train_im, str(image))
+    text = text.replace(old_train_seg, str(seg))
+    text = text.replace(old_infer_im, str(image))
+    text = text.replace(old_output, str(project_dir / "outputs/mitoem_toy_bc"))
+    config.write_text(text)
+    spec = ProjectSpec(
+        slug=slug,
+        title="Prepilot MitoEM Toy Crop",
+        task="Real public mitochondria instance-segmentation crop",
+        source="pytc/MitoEM Hugging Face dataset",
+        roles=[
+            Role("dataset_path", project_dir / "data", "Project data root"),
+            Role("image_path", image, "4um MitoEM-R raw image HDF5 crop"),
+            Role("label_path", seg, "4um MitoEM-R mitochondria instance labels"),
+        ],
+        recommended_configs=[config],
+        source_urls=[image_url, seg_url],
+        notes=[
+            "Use this as the first non-demo project-agnostic role-inference test.",
+            "The smoke config intentionally uses the same image for training and inference so runtime plumbing can be tested quickly.",
+        ],
+    )
+    write_manifest(project_dir, spec)
+    return spec
+
+
+def find_first(root: Path, names: list[str]) -> Path | None:
+    lowered = {name.lower() for name in names}
+    for path in sorted(root.rglob("*")):
+        if path.is_file() and path.name.lower() in lowered:
+            return path
+    return None
+
+
+def stage_lucchi(project_root: Path) -> ProjectSpec:
+    slug = "prepilot_lucchi_pp"
+    project_dir = init_project(project_root, slug)
+    archive = project_dir / ".cache/lucchi_pp.zip"
+    source_dir = project_dir / "data/source"
+    url = "https://huggingface.co/datasets/pytc/tutorial/resolve/main/lucchi%2B%2B.zip?download=true"
+    if require_space(project_root, 800_000_000, slug):
+        if (source_dir / ".extract_complete").exists():
+            print(f"Already extracted: {source_dir}", flush=True)
+        else:
+            download(url, archive)
+            extract_zip(archive, source_dir)
+
+    candidates = {
+        "train_im": find_first(source_dir, ["train_im.tif", "train_im.h5"]),
+        "train_label": find_first(
+            source_dir,
+            ["train_label.tif", "train_label.h5", "train_mito.tif", "train_mito.h5"],
+        ),
+        "test_im": find_first(source_dir, ["test_im.tif", "test_im.h5"]),
+        "test_label": find_first(
+            source_dir,
+            ["test_label.tif", "test_label.h5", "test_mito.tif", "test_mito.h5"],
+        ),
+    }
+    role_paths: dict[str, Path | None] = {
+        "train_im": None,
+        "train_label": None,
+        "test_im": None,
+        "test_label": None,
+    }
+    if candidates["train_im"]:
+        role_paths["train_im"] = (
+            project_dir / f"data/image/{candidates['train_im'].name}"
+        )
+        symlink_or_keep(candidates["train_im"], role_paths["train_im"])
+    if candidates["test_im"]:
+        role_paths["test_im"] = project_dir / f"data/image/{candidates['test_im'].name}"
+        symlink_or_keep(candidates["test_im"], role_paths["test_im"])
+    if candidates["train_label"]:
+        role_paths["train_label"] = (
+            project_dir / f"data/seg/{candidates['train_label'].name}"
+        )
+        symlink_or_keep(candidates["train_label"], role_paths["train_label"])
+    if candidates["test_label"]:
+        role_paths["test_label"] = (
+            project_dir / f"data/seg/{candidates['test_label'].name}"
+        )
+        symlink_or_keep(candidates["test_label"], role_paths["test_label"])
+
+    config = project_dir / "configs/Lucchi-Prepilot-Mitochondria.yaml"
+    src = REPO_ROOT / "pytorch_connectomics/configs/Lucchi-Mitochondria.yaml"
+    text = src.read_text()
+    train_im_name = (
+        role_paths["train_im"].name if role_paths["train_im"] else "train_im.tif"
+    )
+    train_label_name = (
+        role_paths["train_label"].name
+        if role_paths["train_label"]
+        else "train_label.tif"
+    )
+    test_im_name = (
+        role_paths["test_im"].name if role_paths["test_im"] else "test_im.tif"
+    )
+    text = text.replace(
+        "INPUT_PATH: datasets/Lucchi/", f"INPUT_PATH: {project_dir / 'data'}"
+    )
+    text = text.replace(
+        "IMAGE_NAME: img/train_im.tif", f"IMAGE_NAME: image/{train_im_name}"
+    )
+    text = text.replace(
+        "LABEL_NAME: label/train_label.tif", f"LABEL_NAME: seg/{train_label_name}"
+    )
+    text = text.replace(
+        "IMAGE_NAME: img/test_im.tif", f"IMAGE_NAME: image/{test_im_name}"
+    )
+    text = text.replace(
+        "OUTPUT_PATH: outputs/Lucchi_UNet/test",
+        f"OUTPUT_PATH: {project_dir / 'outputs/inference'}",
+    )
+    text = text.replace(
+        "OUTPUT_PATH: outputs/Lucchi_UNet/",
+        f"OUTPUT_PATH: {project_dir / 'outputs/train'}",
+    )
+    config.write_text(text)
+    spec = ProjectSpec(
+        slug=slug,
+        title="Prepilot Lucchi++",
+        task="Mitochondria semantic segmentation benchmark",
+        source="pytc/tutorial Hugging Face dataset",
+        roles=[
+            Role("dataset_path", project_dir / "data", "Project data root"),
+            Role("image_path", role_paths["train_im"], "Training image stack"),
+            Role(
+                "label_path",
+                role_paths["train_label"],
+                "Training semantic mitochondria labels",
+            ),
+            Role("inference_image_path", role_paths["test_im"], "Test image stack"),
+            Role(
+                "reference_label_path",
+                role_paths["test_label"],
+                "Test labels if present",
+            ),
+        ],
+        recommended_configs=[config],
+        source_urls=[url],
+        notes=[
+            "This is a semantic-mask project, not an instance-queue proofreading project.",
+            "If file names differ after upstream archive changes, inspect data/source and update role links.",
+        ],
+    )
+    write_manifest(project_dir, spec)
+    return spec
+
+
+def stage_cremi(project_root: Path) -> ProjectSpec:
+    slug = "prepilot_cremi_official"
+    project_dir = init_project(project_root, slug)
+    urls = {
+        "sample_A_20160501.hdf": "https://cremi.org/static/data/sample_A_20160501.hdf",
+        "sample_B_20160501.hdf": "https://cremi.org/static/data/sample_B_20160501.hdf",
+        "sample_C_20160501.hdf": "https://cremi.org/static/data/sample_C_20160501.hdf",
+    }
+    if require_space(project_root, 700_000_000, slug):
+        for name, url in urls.items():
+            download(url, project_dir / "data/source" / name)
+    config_base = project_dir / "configs/CREMI-Official-Base.yaml"
+    copy_file(
+        REPO_ROOT / "pytorch_connectomics/configs/CREMI/CREMI-Base.yaml", config_base
+    )
+    config_model = project_dir / "configs/CREMI-Foreground-UNet.yaml"
+    copy_file(
+        REPO_ROOT / "pytorch_connectomics/configs/CREMI/CREMI-Foreground-UNet.yaml",
+        config_model,
+    )
+    spec = ProjectSpec(
+        slug=slug,
+        title="Prepilot CREMI Official Crops",
+        task="Synaptic cleft detection and HDF5-key stress test",
+        source="CREMI challenge official cropped datasets",
+        roles=[
+            Role(
+                "dataset_path",
+                project_dir / "data/source",
+                "Official CREMI HDF5 containers",
+            ),
+            Role(
+                "image_path",
+                project_dir / "data/source/sample_A_20160501.hdf",
+                "Sample A raw volume container",
+                hdf5_key="volumes/raw",
+            ),
+            Role(
+                "label_path",
+                project_dir / "data/source/sample_A_20160501.hdf",
+                "Sample A synaptic cleft labels in the same HDF5 container",
+                hdf5_key="volumes/labels/clefts",
+            ),
+        ],
+        recommended_configs=[config_base, config_model],
+        source_urls=list(urls.values()),
+        status="needs-preprocessing",
+        notes=[
+            "Official CREMI data stores raw, clefts, neuron ids, and annotations inside each HDF5 file.",
+            "The legacy local PyTC config expects preprocessed corrected/im_A.h5 and corrected/syn_A.h5 style files, so this project intentionally exposes an HDF5-key/config-adaptation gap.",
+            "Use this fixture to test whether the app asks for HDF5 keys instead of pretending the container is one simple volume.",
+        ],
+    )
+    write_manifest(project_dir, spec)
+    return spec
+
+
+def stage_nucmm_mouse(project_root: Path) -> ProjectSpec:
+    slug = "prepilot_nucmm_mouse"
+    project_dir = init_project(project_root, slug)
+    archive = project_dir / ".cache/NucMM-M.zip"
+    source_dir = project_dir / "data/source"
+    url = "https://huggingface.co/datasets/pytc/NucMM/resolve/main/NucMM-M.zip?download=true"
+    if require_space(project_root, 1_500_000_000, slug):
+        if (source_dir / ".extract_complete").exists():
+            print(f"Already extracted: {source_dir}", flush=True)
+        else:
+            download(url, archive)
+            extract_zip(archive, source_dir)
+    config_base = project_dir / "configs/NucMM-Mouse-Base.yaml"
+    copy_file(
+        REPO_ROOT / "pytorch_connectomics/configs/NucMM/NucMM-Mouse-Base.yaml",
+        config_base,
+    )
+    config_model = project_dir / "configs/NucMM-Mouse-UNet-BC.yaml"
+    copy_file(
+        REPO_ROOT / "pytorch_connectomics/configs/NucMM/NucMM-Mouse-UNet-BC.yaml",
+        config_model,
+    )
+
+    h5_files = sorted(source_dir.rglob("*.h5"))
+    image_guess = next((p for p in h5_files if p.name.startswith(("img", "im_"))), None)
+    seg_guess = next((p for p in h5_files if p.name.startswith(("seg", "nuc"))), None)
+    if image_guess:
+        symlink_or_keep(image_guess, project_dir / f"data/image/{image_guess.name}")
+    if seg_guess:
+        symlink_or_keep(seg_guess, project_dir / f"data/seg/{seg_guess.name}")
+
+    spec = ProjectSpec(
+        slug=slug,
+        title="Prepilot NucMM Mouse",
+        task="Neuronal nuclei instance segmentation generality test",
+        source="pytc/NucMM Hugging Face dataset",
+        roles=[
+            Role("dataset_path", project_dir / "data", "Project data root"),
+            Role(
+                "image_path",
+                project_dir / f"data/image/{image_guess.name}" if image_guess else None,
+                "Guessed mouse nuclei image volume",
+            ),
+            Role(
+                "label_path",
+                project_dir / f"data/seg/{seg_guess.name}" if seg_guess else None,
+                "Guessed mouse nuclei label volume",
+            ),
+        ],
+        recommended_configs=[config_base, config_model],
+        source_urls=[url],
+        status="needs-confirmation" if not image_guess or not seg_guess else "ready",
+        notes=[
+            "Use this to force non-mito language and project-general workflow behavior.",
+            "The manifest records guessed roles; confirm them in the app before mutating workflow state.",
+            "The upstream archive layout may not exactly match the legacy config paths.",
+        ],
+    )
+    write_manifest(project_dir, spec)
+    return spec
+
+
+def write_index(project_root: Path, specs: list[ProjectSpec]) -> None:
+    ensure_dir(project_root)
+    lines = [
+        "# Prepilot Projects",
+        "",
+        "Generated by `pytc-client/scripts/ingest_prepilot_datasets.py`.",
+        "",
+        "| Project | Task | Status | Notes |",
+        "| --- | --- | --- | --- |",
+    ]
+    for spec in specs:
+        note = spec.notes[0] if spec.notes else ""
+        lines.append(f"| `{spec.slug}` | {spec.task} | {spec.status} | {note} |")
+    lines.append("")
+    lines.append(
+        "Large datasets intentionally omitted unless they fit local disk constraints: full MitoEM, MitoEM2.0, padded CREMI, and NucMM-Z."
+    )
+    lines.append("")
+    (project_root / "README.md").write_text("\n".join(lines))
+
+
+def main() -> None:
+    global ALLOW_DOWNLOADS
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--project-root", type=Path, default=DEFAULT_PROJECT_ROOT)
+    parser.add_argument("--data-root", type=Path, default=DEFAULT_DATA_ROOT)
+    parser.add_argument("--skip-downloads", action="store_true")
+    parser.add_argument("--skip-nucmm", action="store_true")
+    parser.add_argument("--skip-cremi", action="store_true")
+    parser.add_argument("--skip-lucchi", action="store_true")
+    args = parser.parse_args()
+    ALLOW_DOWNLOADS = not args.skip_downloads
+
+    project_root = ensure_dir(args.project_root)
+    specs: list[ProjectSpec] = []
+    specs.append(stage_local_mito25_smoke(project_root, args.data_root))
+    specs.append(stage_local_snemi(project_root, args.data_root))
+
+    specs.append(stage_mitoem_toy(project_root))
+    if not args.skip_lucchi:
+        specs.append(stage_lucchi(project_root))
+    if not args.skip_cremi:
+        specs.append(stage_cremi(project_root))
+    if not args.skip_nucmm:
+        specs.append(stage_nucmm_mouse(project_root))
+
+    write_index(project_root, specs)
+    print("\nPrepilot project root:", project_root)
+    for spec in specs:
+        print(f"- {spec.slug}: {spec.status}")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/inspect_demo_instance.py b/scripts/inspect_demo_instance.py
new file mode 100644
index 00000000..647671cb
--- /dev/null
+++ b/scripts/inspect_demo_instance.py
@@ -0,0 +1,1192 @@
+#!/usr/bin/env python3
+"""Operator-focused runtime diagnostics for the demo deployment.
+
+The checks are read-only and designed to answer:
+- Can API and worker be reached?
+- Is the worker URL aligned with expectation and runtime logs?
+- Is Neuroglancer reachable and reasonably configured?
+- Are Ollama/chat endpoints reachable?
+- How big are recent logs/bundles and are there recent ERROR events?
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import socket
+from collections import Counter, deque
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlsplit
+
+import requests
+
+DEMO_SEG_HOSTS = {"demo.seg.bio", "www.demo.seg.bio"}
+DEMO_SEG_PUBLIC_BASE = "https://demo.seg.bio/neuroglancer"
+DEMO_SEG_NEUROGLANCER_PORT = 4244
+DEMO_SEG_LOG_TAIL_LINES = 5000
+
+
+def _demo_seg_defaults(
+    *,
+    api_base: str,
+    neuroglancer_port: int,
+    neuroglancer_public_base: str,
+    log_tail_lines: int,
+) -> tuple[int, str, int]:
+    host = (urlsplit(api_base).hostname or "").lower()
+    if host in DEMO_SEG_HOSTS:
+        resolved_public_base = neuroglancer_public_base.strip() or DEMO_SEG_PUBLIC_BASE
+        resolved_port = neuroglancer_port or DEMO_SEG_NEUROGLANCER_PORT
+        resolved_log_tail_lines = (
+            DEMO_SEG_LOG_TAIL_LINES if log_tail_lines == 120 else log_tail_lines
+        )
+        return resolved_port, resolved_public_base, resolved_log_tail_lines
+    return neuroglancer_port, neuroglancer_public_base, log_tail_lines
+
+
+@dataclass(frozen=True)
+class CheckResult:
+    name: str
+    status: str
+    message: str
+    details: dict[str, Any] | None = None
+
+
+def _safe_json_loads(line: str) -> Any | None:
+    text = (line or "").strip()
+    if not text:
+        return None
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        return None
+
+
+def _normalize_base_url(value: str) -> str:
+    text = (value or "").strip()
+    if not text:
+        return ""
+    parsed = urlsplit(text if "://" in text else f"http://{text}")
+    return f"{parsed.scheme}://{parsed.netloc}".rstrip("/")
+
+
+def _normalize_worker_url(protocol: str, worker_url: str) -> str:
+    text = (worker_url or "").strip().rstrip("/")
+    if not text:
+        return ""
+    parsed = urlsplit(text if "://" in text else f"{(protocol or 'http')}://{text}")
+    return f"{parsed.scheme}://{parsed.netloc}".rstrip("/")
+
+
+def _host_and_port(value: str) -> tuple[str | None, int | None]:
+    parsed = urlsplit(value if "://" in value else f"http://{value}")
+    return parsed.hostname, parsed.port
+
+
+def _tail_json_lines(path: Path, max_lines: int = 200) -> list[dict[str, Any]]:
+    if not path.exists():
+        return []
+    rows: deque[dict[str, Any]] = deque(maxlen=max_lines)
+    with path.open("r", encoding="utf-8") as handle:
+        for line in handle:
+            payload = _safe_json_loads(line)
+            if isinstance(payload, dict):
+                rows.append(payload)
+    return list(rows)
+
+
+def _dir_size_bytes(path: Path) -> int:
+    if not path.exists():
+        return 0
+    total = 0
+    for entry in path.rglob("*"):
+        if entry.is_file():
+            try:
+                total += entry.stat().st_size
+            except OSError:
+                continue
+    return total
+
+
+def _humanize_bytes(value: int) -> str:
+    units = ["B", "KB", "MB", "GB", "TB"]
+    size = float(value)
+    for unit in units:
+        if size < 1024 or unit == "TB":
+            return f"{size:.1f} {unit}"
+        size /= 1024
+    return f"{size:.1f} TB"
+
+
+def _http_request_json(
+    *,
+    base_url: str,
+    path: str,
+    method: str = "GET",
+    timeout: int = 3,
+    json_payload: Any = None,
+    raise_for_status: bool = True,
+) -> tuple[int, Any, requests.Response]:
+    url = f"{base_url.rstrip('/')}{path}"
+    response = requests.request(
+        method=method.upper(),
+        url=url,
+        json=json_payload,
+        timeout=timeout,
+        headers={"Accept": "application/json"},
+    )
+    if raise_for_status:
+        response.raise_for_status()
+    try:
+        body = response.json()
+    except (json.JSONDecodeError, ValueError):
+        text = (response.text or "").strip()
+        body = text or None
+    return response.status_code, body, response
+
+
+def _record_result(
+    checks: list[CheckResult],
+    status: str,
+    name: str,
+    message: str,
+    details: dict[str, Any] | None = None,
+) -> CheckResult:
+    result = CheckResult(name=name, status=status, message=message, details=details)
+    checks.append(result)
+    return result
+
+
+def check_api_health(*, api_base: str, timeout: int) -> CheckResult:
+    try:
+        status, payload, _ = _http_request_json(
+            base_url=api_base,
+            path="/health",
+            timeout=timeout,
+            raise_for_status=False,
+        )
+    except Exception as exc:
+        return CheckResult(
+            name="api.health",
+            status="fail",
+            message="API /health request failed",
+            details={"error": str(exc)},
+        )
+
+    if status != 200:
+        return CheckResult(
+            name="api.health",
+            status="warn",
+            message="API /health returned non-200",
+            details={"status_code": status, "payload": payload},
+        )
+
+    if payload != {"status": "ok"}:
+        return CheckResult(
+            name="api.health",
+            status="warn",
+            message="API /health returned unexpected payload",
+            details={"status_code": status, "payload": payload},
+        )
+
+    return CheckResult(
+        name="api.health",
+        status="pass",
+        message="API /health is OK",
+        details={"status_code": status},
+    )
+
+
+def check_app_log_path(
+    *, api_base: str, timeout: int
+) -> tuple[CheckResult, Path | None]:
+    try:
+        status, payload, _ = _http_request_json(
+            base_url=api_base,
+            path="/app/log-path",
+            timeout=timeout,
+            raise_for_status=False,
+        )
+        if status != 200:
+            return (
+                CheckResult(
+                    name="api.log_path",
+                    status="warn",
+                    message="Could not read /app/log-path",
+                    details={"status_code": status, "payload": payload},
+                ),
+                None,
+            )
+        if not isinstance(payload, dict) or not payload.get("path"):
+            return (
+                CheckResult(
+                    name="api.log_path",
+                    status="warn",
+                    message="Unexpected /app/log-path payload",
+                    details={"payload": payload},
+                ),
+                None,
+            )
+        return (
+            CheckResult(
+                name="api.log_path",
+                status="pass",
+                message="Read API app log path",
+                details={"path": payload.get("path")},
+            ),
+            Path(str(payload.get("path"))),
+        )
+    except Exception as exc:
+        return (
+            CheckResult(
+                name="api.log_path",
+                status="warn",
+                message="Could not read /app/log-path",
+                details={"error": str(exc)},
+            ),
+            None,
+        )
+
+
+def _collect_worker_proxy_urls(
+    *,
+    app_log_rows: list[dict[str, Any]],
+    worker_endpoint: str,
+) -> list[str]:
+    matches = []
+    for row in app_log_rows:
+        if row.get("component") != "server_api":
+            continue
+        event = row.get("event")
+        if event not in {
+            "worker_proxy_request_started",
+            "worker_proxy_request_completed",
+            "worker_proxy_request_failed",
+        }:
+            continue
+        if row.get("path") == worker_endpoint and row.get("worker_url"):
+            matches.append(str(row.get("worker_url")))
+    return matches
+
+
+def check_runtime_events(
+    *,
+    app_log_path: Path | None,
+    timeout_lines: int,
+    expected_worker_url: str,
+    neuroglancer_port: int,
+    neuroglancer_public_base: str | None = None,
+) -> list[CheckResult]:
+    checks: list[CheckResult] = []
+    expected_worker = _normalize_worker_url("http", expected_worker_url)
+    expected_public_base = (neuroglancer_public_base or "").strip().rstrip("/")
+    expected_ng_port = int(neuroglancer_port)
+
+    if not app_log_path:
+        _record_result(
+            checks,
+            "warn",
+            "api.runtime_config_log",
+            "Could not inspect runtime config from logs without /app/log-path",
+            {"reason": "log-path-unavailable"},
+        )
+        return checks
+
+    rows = _tail_json_lines(app_log_path, max_lines=timeout_lines)
+    configured_rows = [
+        row for row in rows if row.get("event") == "api_runtime_configured"
+    ]
+    if not configured_rows:
+        _record_result(
+            checks,
+            "warn",
+            "api.runtime_config_log",
+            "No api_runtime_configured event in recent app log",
+            {"path": str(app_log_path)},
+        )
+        _record_result(
+            checks,
+            "warn",
+            "api.runtime_config",
+            "Could not compare runtime config against expected values",
+            {
+                "expected": {
+                    "worker_url": expected_worker,
+                    "neuroglancer_port": expected_ng_port,
+                    "neuroglancer_public_base": expected_public_base,
+                },
+            },
+        )
+        return checks
+
+    configured = configured_rows[-1]
+    configured_worker_url = _normalize_worker_url(
+        protocol="",
+        worker_url=str(configured.get("worker_url") or ""),
+    )
+    configured_ng_port = configured.get("neuroglancer_port")
+    try:
+        configured_ng_port_int = (
+            int(configured_ng_port) if configured_ng_port is not None else None
+        )
+    except (TypeError, ValueError):
+        configured_ng_port_int = None
+    configured_public_base = (
+        str(configured.get("neuroglancer_public_base", "")).strip().rstrip("/")
+    )
+
+    mismatches: list[str] = []
+    if expected_worker:
+        if configured_worker_url:
+            if configured_worker_url != expected_worker:
+                mismatches.append("worker_url")
+        else:
+            mismatches.append("worker_url")
+    if expected_ng_port and configured_ng_port_int is not None:
+        if configured_ng_port_int != expected_ng_port:
+            mismatches.append("neuroglancer_port")
+    elif expected_ng_port:
+        mismatches.append("neuroglancer_port")
+    if expected_public_base and configured_public_base:
+        if configured_public_base != expected_public_base:
+            mismatches.append("neuroglancer_public_base")
+    elif expected_public_base:
+        mismatches.append("neuroglancer_public_base")
+    _record_result(
+        checks,
+        "pass" if not mismatches else "warn",
+        "api.runtime_config",
+        (
+            "Runtime config in api log matches operator expectations"
+            if not mismatches
+            else "Runtime config in api log differs from operator expectations"
+        ),
+        {
+            "expected": {
+                "worker_url": expected_worker,
+                "neuroglancer_port": expected_ng_port,
+                "neuroglancer_public_base": expected_public_base,
+            },
+            "observed": {
+                "worker_url": configured_worker_url,
+                "neuroglancer_port": configured_ng_port_int,
+                "neuroglancer_public_base": configured_public_base,
+            },
+            "mismatches": mismatches,
+        },
+    )
+
+    _record_result(
+        checks,
+        "pass",
+        "api.runtime_config_log",
+        "Read api_runtime_configured event from app log",
+        {
+            "path": str(app_log_path),
+            "api_host": configured.get("api_host"),
+            "api_port": configured.get("api_port"),
+            "neuroglancer_port": configured.get("neuroglancer_port"),
+            "worker_url": configured.get("worker_url"),
+        },
+    )
+
+    if configured_worker_url and expected_worker:
+        _record_result(
+            checks,
+            "pass" if configured_worker_url == expected_worker else "warn",
+            "api.runtime_config_worker_url",
+            (
+                "Configured worker URL aligns with expected worker URL"
+                if configured_worker_url == expected_worker
+                else "Configured worker URL differs from expected worker URL"
+            ),
+            {
+                "expected_worker_url": expected_worker,
+                "configured_worker_url": configured_worker_url,
+            },
+        )
+
+    configured_ng_port = configured.get("neuroglancer_port")
+    try:
+        configured_ng_port_int = (
+            int(configured_ng_port) if configured_ng_port is not None else None
+        )
+    except (TypeError, ValueError):
+        configured_ng_port_int = None
+    if configured_ng_port_int is not None:
+        _record_result(
+            checks,
+            "pass" if configured_ng_port_int == int(neuroglancer_port) else "warn",
+            "api.runtime_config_neuroglancer_port",
+            (
+                "Configured neuroglancer port aligns with expected value"
+                if configured_ng_port_int == int(neuroglancer_port)
+                else "Configured neuroglancer port differs from expected value"
+            ),
+            {
+                "expected_neuroglancer_port": int(neuroglancer_port),
+                "configured_neuroglancer_port": configured_ng_port_int,
+            },
+        )
+    elif configured_ng_port is not None:
+        _record_result(
+            checks,
+            "warn",
+            "api.runtime_config_neuroglancer_port",
+            "Could not parse configured neuroglancer port from runtime log",
+            {
+                "expected_neuroglancer_port": int(neuroglancer_port),
+                "configured_neuroglancer_port": configured_ng_port,
+            },
+        )
+
+    public_base = (neuroglancer_public_base or "").strip()
+    if public_base:
+        configured_public_base = str(
+            configured.get("neuroglancer_public_base", "")
+        ).strip()
+        if configured_public_base:
+            _record_result(
+                checks,
+                (
+                    "pass"
+                    if configured_public_base.rstrip("/") == public_base.rstrip("/")
+                    else "warn"
+                ),
+                "api.runtime_config_neuroglancer_public_base",
+                (
+                    "Configured neuroglancer public base aligns with expected value"
+                    if configured_public_base.rstrip("/") == public_base.rstrip("/")
+                    else "Configured neuroglancer public base differs from expected value"
+                ),
+                {
+                    "expected_neuroglancer_public_base": public_base,
+                    "configured_neuroglancer_public_base": configured_public_base,
+                },
+            )
+        else:
+            _record_result(
+                checks,
+                "warn",
+                "api.runtime_config_neuroglancer_public_base",
+                "No configured public base found in runtime log",
+                {"reason": "missing_log_field"},
+            )
+
+    return checks
+
+
+def check_worker_path(
+    *,
+    api_base: str,
+    expected_worker_url: str,
+    app_log_path: Path | None,
+    timeout: int,
+) -> list[CheckResult]:
+    checks: list[CheckResult] = []
+
+    worker_url = _normalize_worker_url("http", expected_worker_url)
+
+    try:
+        status, payload, _ = _http_request_json(
+            base_url=worker_url,
+            path="/hello",
+            timeout=timeout,
+            raise_for_status=False,
+        )
+        if status == 200:
+            _record_result(
+                checks,
+                "pass",
+                "worker.hello",
+                "Direct worker hello probe succeeded",
+                {"status_code": status, "url": worker_url, "payload": payload},
+            )
+        else:
+            _record_result(
+                checks,
+                "warn",
+                "worker.hello",
+                "Direct worker hello probe returned non-200",
+                {"status_code": status, "url": worker_url, "payload": payload},
+            )
+    except Exception as exc:
+        _record_result(
+            checks,
+            "warn",
+            "worker.hello",
+            "Direct worker hello probe failed",
+            {"url": worker_url, "error": str(exc)},
+        )
+
+    response_status = None
+    api_training_status = None
+    observed_worker_url: str | None = None
+    try:
+        response_status, api_training_status, _ = _http_request_json(
+            base_url=api_base,
+            path="/training_status",
+            timeout=timeout,
+            raise_for_status=False,
+        )
+
+        if response_status == 200:
+            _record_result(
+                checks,
+                "pass",
+                "api.training_status",
+                "API /training_status reached worker endpoint",
+                {"status_code": response_status, "payload": api_training_status},
+            )
+            if isinstance(api_training_status, dict):
+                observed_worker_url = str(
+                    api_training_status.get("worker_url") or ""
+                ).strip()
+        else:
+            _record_result(
+                checks,
+                "warn",
+                "api.training_status",
+                "API /training_status returned an error",
+                {"status_code": response_status, "payload": api_training_status},
+            )
+            if isinstance(api_training_status, dict):
+                detail = api_training_status.get("detail")
+                if isinstance(detail, dict):
+                    observed_worker_url = str(detail.get("worker_url") or "").strip()
+                else:
+                    observed_worker_url = str(
+                        api_training_status.get("worker_url") or ""
+                    ).strip()
+    except Exception as exc:
+        _record_result(
+            checks,
+            "warn",
+            "api.training_status",
+            "API /training_status request failed",
+            {"error": str(exc)},
+        )
+
+    if app_log_path:
+        log_rows = _tail_json_lines(app_log_path, max_lines=250)
+        worker_urls = _collect_worker_proxy_urls(
+            app_log_rows=log_rows,
+            worker_endpoint="/training_status",
+        )
+        if worker_urls:
+            observed_worker_url = worker_urls[-1]
+            _record_result(
+                checks,
+                "pass",
+                "api.proxy_log",
+                "Read worker target from API proxy log",
+                {
+                    "observed_worker_url": observed_worker_url,
+                    "log_path": str(app_log_path),
+                },
+            )
+        else:
+            _record_result(
+                checks,
+                "warn",
+                "api.proxy_log",
+                "No matching worker proxy events found in app log tail",
+                {"log_path": str(app_log_path)},
+            )
+    else:
+        _record_result(
+            checks,
+            "warn",
+            "api.proxy_log",
+            "No app log path available for worker proxy target check",
+            {"reason": "log-path-unavailable"},
+        )
+
+    if observed_worker_url:
+        observed_normalized = _normalize_worker_url(
+            protocol=(urlsplit(observed_worker_url).scheme or "http"),
+            worker_url=observed_worker_url,
+        )
+        mismatch = observed_normalized != worker_url
+        _record_result(
+            checks,
+            "pass" if not mismatch else "fail",
+            "worker.url_mismatch",
+            (
+                "Worker URL matches API proxy target"
+                if not mismatch
+                else "Worker URL mismatch: API appears to proxy a different target"
+            ),
+            {
+                "expected_worker_url": worker_url,
+                "observed_worker_url": observed_worker_url,
+            },
+        )
+    else:
+        _record_result(
+            checks,
+            "warn",
+            "worker.url_mismatch",
+            "Could not determine API proxy target worker URL",
+            {"expected_worker_url": worker_url},
+        )
+
+    return checks
+
+
+def check_workflow(api_base: str, timeout: int) -> CheckResult:
+    try:
+        status, payload, _ = _http_request_json(
+            base_url=api_base,
+            path="/api/workflows/current",
+            timeout=timeout,
+            raise_for_status=False,
+        )
+    except Exception as exc:
+        return CheckResult(
+            name="workflow.current",
+            status="warn",
+            message="Could not read current workflow",
+            details={"error": str(exc)},
+        )
+
+    if status in {401, 403}:
+        return CheckResult(
+            name="workflow.current",
+            status="warn",
+            message="Current workflow endpoint requires authentication",
+            details={"status_code": status},
+        )
+    if status != 200 or not isinstance(payload, dict):
+        return CheckResult(
+            name="workflow.current",
+            status="warn",
+            message="Current workflow endpoint returned unexpected payload/status",
+            details={"status_code": status, "payload": payload},
+        )
+
+    workflow = payload.get("workflow") if isinstance(payload, dict) else None
+    events = payload.get("events", [])
+    if not isinstance(workflow, dict):
+        return CheckResult(
+            name="workflow.current",
+            status="warn",
+            message="Current workflow payload is missing workflow object",
+            details={"payload": payload},
+        )
+
+    return CheckResult(
+        name="workflow.current",
+        status="pass",
+        message="Current workflow endpoint is reachable",
+        details={
+            "workflow": workflow,
+            "workflow_id": workflow.get("id"),
+            "title": workflow.get("title"),
+            "stage": workflow.get("stage"),
+            "events": len(events) if isinstance(events, list) else 0,
+        },
+    )
+
+
+def check_neuroglancer(
+    *,
+    api_base: str,
+    workflow: dict[str, Any] | None,
+    neuroglancer_port: int,
+    neuroglancer_public_base: str | None,
+) -> list[CheckResult]:
+    checks: list[CheckResult] = []
+
+    if not workflow:
+        _record_result(
+            checks,
+            "warn",
+            "neuroglancer",
+            "Skipping Neuroglancer checks: no workflow available",
+            {"reason": "workflow_not_available"},
+        )
+        return checks
+
+    host, _ = _host_and_port(api_base)
+    if host is None:
+        host = "127.0.0.1"
+
+    if neuroglancer_port <= 0:
+        _record_result(
+            checks,
+            "warn",
+            "neuroglancer.port",
+            "Configured Neuroglancer bind port is not positive",
+            {"port": neuroglancer_port},
+        )
+    else:
+        try:
+            with socket.create_connection((host, neuroglancer_port), timeout=1):
+                pass
+            _record_result(
+                checks,
+                "pass",
+                "neuroglancer.port",
+                "Neuroglancer port is reachable",
+                {
+                    "host": host,
+                    "port": neuroglancer_port,
+                    "reachable": True,
+                },
+            )
+        except Exception:
+            _record_result(
+                checks,
+                "warn",
+                "neuroglancer.port",
+                "Neuroglancer port is not reachable from this operator node",
+                {
+                    "host": host,
+                    "port": neuroglancer_port,
+                    "reachable": False,
+                },
+            )
+
+    public_base = (neuroglancer_public_base or "").strip().rstrip("/")
+    if not public_base:
+        _record_result(
+            checks,
+            "warn",
+            "neuroglancer.public_base",
+            "No Neuroglancer public base provided",
+            {"hint": "set PYTC_NEUROGLANCER_PUBLIC_BASE in operator env"},
+        )
+    else:
+        parsed = urlsplit(public_base)
+        _record_result(
+            checks,
+            "pass" if parsed.scheme else "warn",
+            "neuroglancer.public_base",
+            (
+                "Neuroglancer public base URL format is valid"
+                if parsed.scheme
+                else "Neuroglancer public base is not absolute"
+            ),
+            {
+                "value": public_base,
+                "has_scheme": bool(parsed.scheme),
+            },
+        )
+
+    neuroglancer_url = workflow.get("neuroglancer_url")
+    if neuroglancer_url and public_base:
+        if str(neuroglancer_url).startswith(public_base):
+            _record_result(
+                checks,
+                "pass",
+                "neuroglancer.url_match",
+                "Workflow neuroglancer_url starts with configured public base",
+                {
+                    "neuroglancer_url": neuroglancer_url,
+                    "public_base": public_base,
+                },
+            )
+        else:
+            _record_result(
+                checks,
+                "warn",
+                "neuroglancer.url_match",
+                "Workflow neuroglancer_url does not start with configured public base",
+                {
+                    "neuroglancer_url": neuroglancer_url,
+                    "public_base": public_base,
+                },
+            )
+    elif neuroglancer_url:
+        _record_result(
+            checks,
+            "warn",
+            "neuroglancer.url_match",
+            "Workflow has neuroglancer_url but public base is unset",
+            {"neuroglancer_url": neuroglancer_url},
+        )
+    else:
+        _record_result(
+            checks,
+            "warn",
+            "neuroglancer.url_match",
+            "Current workflow does not expose neuroglancer_url",
+            {"workflow_id": workflow.get("id")},
+        )
+
+    return checks
+
+
+def check_ollama(*, api_base: str, timeout: int) -> list[CheckResult]:
+    checks: list[CheckResult] = []
+
+    ollama_base = (os.environ.get("OLLAMA_BASE_URL") or "").strip()
+    if not ollama_base:
+        _record_result(
+            checks,
+            "warn",
+            "ollama.base",
+            "OLLAMA_BASE_URL is not set",
+            {"note": "Ollama/chat checks are limited"},
+        )
+        return checks
+
+    base = _normalize_base_url(ollama_base)
+    required = [
+        "OLLAMA_MODEL",
+        "PYTC_WORKFLOW_INTENT_MODEL",
+        "OLLAMA_EMBED_MODEL",
+    ]
+    missing_vars = [name for name in required if not os.environ.get(name)]
+    if missing_vars:
+        _record_result(
+            checks,
+            "warn",
+            "ollama.env",
+            "Some Ollama-related model environment variables are unset",
+            {"missing": missing_vars},
+        )
+
+    try:
+        status, payload, _ = _http_request_json(
+            base_url=base,
+            path="/api/tags",
+            timeout=timeout,
+            raise_for_status=False,
+        )
+        if status != 200 or not isinstance(payload, dict):
+            _record_result(
+                checks,
+                "warn",
+                "ollama.models",
+                "Could not query Ollama /api/tags",
+                {"status_code": status, "payload": payload},
+            )
+        else:
+            models = {
+                item.get("name")
+                for item in (payload.get("models") or [])
+                if isinstance(item, dict)
+            }
+            configured = [
+                os.environ.get("OLLAMA_MODEL"),
+                os.environ.get("PYTC_WORKFLOW_INTENT_MODEL")
+                or os.environ.get("OLLAMA_MODEL"),
+                os.environ.get("OLLAMA_EMBED_MODEL"),
+            ]
+            required_models = [value for value in configured if value]
+            missing_models = [
+                name for name in required_models if name and name not in models
+            ]
+            _record_result(
+                checks,
+                "warn" if missing_models else "pass",
+                "ollama.models",
+                (
+                    "Some configured Ollama models are missing from /api/tags"
+                    if missing_models
+                    else "Ollama API is reachable and configured models are present"
+                ),
+                {
+                    "ollama_base": base,
+                    "configured_models": required_models,
+                    "available_models": sorted(models),
+                    "missing_models": missing_models,
+                },
+            )
+    except Exception as exc:
+        _record_result(
+            checks,
+            "warn",
+            "ollama.models",
+            "Could not query Ollama /api/tags",
+            {"ollama_base": base, "error": str(exc)},
+        )
+
+    try:
+        status, payload, _ = _http_request_json(
+            base_url=api_base,
+            path="/chat/status",
+            timeout=timeout,
+            raise_for_status=False,
+        )
+        if status != 200:
+            _record_result(
+                checks,
+                "warn",
+                "ollama.chat_status",
+                "Could not query API /chat/status",
+                {"status_code": status, "payload": payload},
+            )
+        elif isinstance(payload, dict) and payload.get("configured"):
+            _record_result(
+                checks,
+                "pass",
+                "ollama.chat_status",
+                "API chat status reports configured",
+                payload,
+            )
+        else:
+            _record_result(
+                checks,
+                "warn",
+                "ollama.chat_status",
+                "API chat status is not configured",
+                payload,
+            )
+    except Exception as exc:
+        _record_result(
+            checks,
+            "warn",
+            "ollama.chat_status",
+            "Could not query API /chat/status",
+            {"error": str(exc)},
+        )
+
+    return checks
+
+
+def check_disk_and_errors(
+    *,
+    app_log_path: Path | None,
+    workflow_bundle_dir: Path,
+    error_tail_lines: int,
+) -> list[CheckResult]:
+    checks: list[CheckResult] = []
+
+    if app_log_path:
+        log_rows = _tail_json_lines(app_log_path, max_lines=error_tail_lines)
+        errors = [row for row in log_rows if str(row.get("level")).upper() == "ERROR"]
+        counters = Counter(row.get("event") for row in errors if isinstance(row, dict))
+        _record_result(
+            checks,
+            "warn" if errors else "pass",
+            "app_error_events",
+            f"Found {len(errors)} ERROR event rows in recent app log",
+            {
+                "error_count": len(errors),
+                "top_events": counters.most_common(6),
+            },
+        )
+        try:
+            usage = _dir_size_bytes(app_log_path.parent)
+            _record_result(
+                checks,
+                "pass",
+                "app_log_disk",
+                "Computed app log parent directory disk usage",
+                {
+                    "path": str(app_log_path.parent),
+                    "bytes": usage,
+                    "human": _humanize_bytes(usage),
+                },
+            )
+        except OSError as exc:
+            _record_result(
+                checks,
+                "warn",
+                "app_log_disk",
+                "Could not compute app log disk usage",
+                {"path": str(app_log_path.parent), "error": str(exc)},
+            )
+    else:
+        _record_result(
+            checks,
+            "warn",
+            "app_error_events",
+            "No app log path available from /app/log-path",
+            {"reason": "log-path-unavailable"},
+        )
+
+    try:
+        bundle_exists = workflow_bundle_dir.exists()
+        bundle_bytes = _dir_size_bytes(workflow_bundle_dir)
+        _record_result(
+            checks,
+            "pass" if bundle_exists else "warn",
+            "workflow_bundles_disk",
+            "Computed workflow bundle directory disk usage",
+            {
+                "path": str(workflow_bundle_dir),
+                "exists": bundle_exists,
+                "bytes": bundle_bytes,
+                "human": _humanize_bytes(bundle_bytes),
+            },
+        )
+    except OSError as exc:
+        _record_result(
+            checks,
+            "warn",
+            "workflow_bundles_disk",
+            "Could not compute workflow bundle disk usage",
+            {"path": str(workflow_bundle_dir), "error": str(exc)},
+        )
+
+    return checks
+
+
+def run_diagnostics(config: argparse.Namespace) -> list[CheckResult]:
+    checks: list[CheckResult] = []
+
+    api_base = _normalize_base_url(config.api_base)
+    if not api_base:
+        api_base = "http://127.0.0.1:4242"
+
+    (
+        resolved_neuroglancer_port,
+        resolved_neuroglancer_public_base,
+        resolved_log_tail_lines,
+    ) = _demo_seg_defaults(
+        api_base=api_base,
+        neuroglancer_port=int(config.neuroglancer_port),
+        neuroglancer_public_base=config.neuroglancer_public_base,
+        log_tail_lines=config.log_tail_lines,
+    )
+
+    checks.append(check_api_health(api_base=api_base, timeout=config.timeout))
+
+    log_path_result, api_log_path = check_app_log_path(
+        api_base=api_base,
+        timeout=config.timeout,
+    )
+    checks.append(log_path_result)
+
+    worker_url = _normalize_worker_url(config.worker_protocol, config.worker_url)
+    checks.extend(
+        check_runtime_events(
+            app_log_path=api_log_path,
+            timeout_lines=resolved_log_tail_lines,
+            expected_worker_url=worker_url,
+            neuroglancer_port=resolved_neuroglancer_port,
+            neuroglancer_public_base=resolved_neuroglancer_public_base,
+        )
+    )
+    checks.extend(
+        check_worker_path(
+            api_base=api_base,
+            expected_worker_url=worker_url,
+            app_log_path=api_log_path,
+            timeout=config.timeout,
+        )
+    )
+
+    workflow_check = check_workflow(api_base=api_base, timeout=config.timeout)
+    checks.append(workflow_check)
+
+    checks.extend(
+        check_neuroglancer(
+            api_base=api_base,
+            workflow=(
+                (workflow_check.details or {}).get("workflow")
+                if workflow_check.status == "pass"
+                else None
+            ),
+            neuroglancer_port=resolved_neuroglancer_port,
+            neuroglancer_public_base=resolved_neuroglancer_public_base,
+        )
+    )
+
+    checks.extend(check_ollama(api_base=api_base, timeout=config.timeout))
+
+    bundle_dir = Path(config.workflow_bundle_dir).expanduser().resolve()
+    checks.extend(
+        check_disk_and_errors(
+            app_log_path=api_log_path,
+            workflow_bundle_dir=bundle_dir,
+            error_tail_lines=resolved_log_tail_lines,
+        )
+    )
+
+    return checks
+
+
+def render_report(checks: list[CheckResult]) -> list[str]:
+    symbols = {"pass": "PASS", "warn": "WARN", "fail": "FAIL"}
+    lines = []
+    for check in checks:
+        detail = f" | {json.dumps(check.details)}" if check.details else ""
+        lines.append(
+            f"[{symbols.get(check.status, check.status.upper())}] "
+            f"{check.name}: {check.message}{detail}"
+        )
+    return lines
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Inspect PyTC demo-instance runtime health and misconfiguration risks."
+    )
+    parser.add_argument(
+        "--api-base",
+        default=os.environ.get("PYTC_API_BASE", "http://127.0.0.1:4342"),
+        help="API base URL",
+    )
+    parser.add_argument(
+        "--worker-protocol",
+        default=os.environ.get("PYTC_WORKER_PROTOCOL", "http"),
+        help="Worker protocol (default from PYTC_WORKER_PROTOCOL)",
+    )
+    parser.add_argument(
+        "--worker-url",
+        default=os.environ.get("PYTC_WORKER_URL", "localhost:4243"),
+        help="Worker URL (default from PYTC_WORKER_URL)",
+    )
+    parser.add_argument(
+        "--neuroglancer-port",
+        type=int,
+        default=int(os.environ.get("PYTC_NEUROGLANCER_PORT", "4244")),
+        help="Expected Neuroglancer bind port",
+    )
+    parser.add_argument(
+        "--neuroglancer-public-base",
+        default=os.environ.get("PYTC_NEUROGLANCER_PUBLIC_BASE", ""),
+        help="Expected Neuroglancer public base URL",
+    )
+    parser.add_argument(
+        "--workflow-bundle-dir",
+        default=os.environ.get("PYTC_WORKFLOW_BUNDLE_DIR", ".logs/workflow-bundles"),
+        help="Workflow bundle directory",
+    )
+    parser.add_argument(
+        "--timeout",
+        type=int,
+        default=3,
+        help="Request timeout in seconds",
+    )
+    parser.add_argument(
+        "--log-tail-lines",
+        type=int,
+        default=120,
+        help="App log rows to scan for recent events",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Print JSON report output",
+    )
+    args = parser.parse_args()
+
+    checks = run_diagnostics(args)
+
+    if args.json:
+        print(
+            json.dumps(
+                [check.__dict__ for check in checks],
+                ensure_ascii=False,
+                indent=2,
+                sort_keys=True,
+            )
+        )
+    else:
+        for line in render_report(checks):
+            print(line)
+
+    return 1 if any(check.status == "fail" for check in checks) else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/scripts/manage_demo_instance.py b/scripts/manage_demo_instance.py
new file mode 100755
index 00000000..fe4023ff
--- /dev/null
+++ b/scripts/manage_demo_instance.py
@@ -0,0 +1,472 @@
+#!/usr/bin/env python3
+"""Operator-level management for the demo2 API process.
+
+This tool intentionally performs only process orchestration and health verification for
+`server_api.main` in this checkout. It is scoped to the expected demo2 root and
+`PYTC_API_PORT` so restart operations do not cross-kill sibling demo services.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import signal
+import subprocess
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import requests
+
+DEMO_API_ROOT = Path(__file__).resolve().parent.parent
+DEMO2_API_PORT = 4342
+DEMO2_WORKER_URL = "localhost:4243"
+DEMO2_NEUROGLANCER_PORT = 4244
+DEMO2_NEUROGLANCER_PUBLIC_BASE = "https://demo.seg.bio/neuroglancer"
+DEMO2_ALLOWED_ORIGINS = (
+    "https://demo.seg.bio,http://localhost:3000,http://127.0.0.1:3000,null"
+)
+
+
+@dataclass(frozen=True)
+class DemoApiProcess:
+    pid: int
+    command: str
+    cwd: str | None = None
+    env: dict[str, str] | None = None
+
+
+def _demo_api_defaults() -> dict[str, str]:
+    return {
+        "PYTC_API_PORT": str(DEMO2_API_PORT),
+        "PYTC_API_HOST": "127.0.0.1",
+        "PYTC_WORKER_URL": DEMO2_WORKER_URL,
+        "PYTC_NEUROGLANCER_PORT": str(DEMO2_NEUROGLANCER_PORT),
+        "PYTC_NEUROGLANCER_PUBLIC_BASE": DEMO2_NEUROGLANCER_PUBLIC_BASE,
+        "PYTC_ALLOWED_ORIGINS": DEMO2_ALLOWED_ORIGINS,
+    }
+
+
+def _safe_int(value: str | None) -> int | None:
+    if not value:
+        return None
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def _is_descendant_path(candidate: str | None, root: Path) -> bool:
+    if not candidate:
+        return False
+    try:
+        candidate_path = Path(candidate).resolve()
+        resolved_root = root.resolve()
+        return candidate_path == resolved_root or candidate_path.is_relative_to(
+            resolved_root
+        )
+    except Exception:
+        return False
+
+
+def _read_process_cwd(pid: int) -> str | None:
+    try:
+        return os.path.realpath(os.readlink(f"/proc/{pid}/cwd"))
+    except Exception:
+        return None
+
+
+def _read_process_env(pid: int) -> dict[str, str]:
+    env_path = f"/proc/{pid}/environ"
+    env: dict[str, str] = {}
+    try:
+        raw = Path(env_path).read_bytes()
+    except Exception:
+        return env
+
+    for item in raw.split(b"\0"):
+        if b"=" not in item:
+            continue
+        key, value = item.split(b"=", 1)
+        env[key.decode("utf-8", errors="ignore")] = value.decode(
+            "utf-8", errors="ignore"
+        )
+    return env
+
+
+def _extract_pid_from_ps_line(line: str) -> tuple[int, str] | None:
+    text = line.strip()
+    if not text:
+        return None
+    pid_text, _, command = text.partition(" ")
+    if not pid_text.isdigit():
+        return None
+    return int(pid_text), command.strip()
+
+
+def _extract_port_from_command(command: str) -> int | None:
+    for token in command.split():
+        if token.startswith("PYTC_API_PORT="):
+            return _safe_int(token.split("=", 1)[1])
+    return None
+
+
+def discover_demo_api_processes(
+    *,
+    api_port: int,
+    root: Path = DEMO_API_ROOT,
+    run_ps: Any | None = None,
+) -> list[DemoApiProcess]:
+    """Find matching API processes for demo2 in this repo checkout."""
+
+    if run_ps is None:
+        run_ps = subprocess.check_output
+
+    output = run_ps(["ps", "-eo", "pid=,command=", "-ww"], text=True)
+    processes: list[DemoApiProcess] = []
+    for line in str(output).splitlines():
+        parsed = _extract_pid_from_ps_line(line)
+        if not parsed:
+            continue
+
+        pid, command = parsed
+        if "server_api.main" not in command:
+            continue
+
+        cwd = _read_process_cwd(pid)
+        if not _is_descendant_path(cwd, root):
+            continue
+
+        env = _read_process_env(pid)
+        observed_port = _safe_int(env.get("PYTC_API_PORT"))
+        if observed_port is None:
+            observed_port = _extract_port_from_command(command)
+
+        if observed_port is not None and observed_port != api_port:
+            continue
+
+        processes.append(DemoApiProcess(pid=pid, command=command, cwd=cwd, env=env))
+
+    return processes
+
+
+def _build_api_command(
+    *,
+    python_bin: Path,
+    api_port: int = DEMO2_API_PORT,
+) -> tuple[list[str], dict[str, str]]:
+    command = ["nohup", "setsid", str(python_bin), "-m", "server_api.main"]
+    env = os.environ.copy()
+    env.update(_demo_api_defaults())
+    env["PYTC_API_PORT"] = str(api_port)
+    env["PYTC_API_BASE"] = f"http://{env['PYTC_API_HOST']}:{env['PYTC_API_PORT']}"
+    env["PYTC_WORKER_URL"] = env["PYTC_WORKER_URL"]
+    return command, env
+
+
+def _tail_lines(path: Path, max_lines: int = 80) -> str:
+    if not path.exists():
+        return "(log file does not exist)"
+
+    lines: list[str] = []
+    try:
+        with path.open("r", encoding="utf-8", errors="replace") as handle:
+            for raw in handle:
+                lines.append(raw.rstrip("\n"))
+    except Exception as exc:
+        return f"(unable to read log file {path}: {exc})"
+
+    if len(lines) <= max_lines:
+        return "\n".join(lines)
+    return "\n".join(lines[-max_lines:])
+
+
+def _runtime_snapshot_message(env: dict[str, str], *, api_port: int) -> str:
+    return (
+        "Runtime config -> "
+        f"api_port={api_port}, "
+        f"worker_url={env.get('PYTC_WORKER_URL')}, "
+        f"neuroglancer_port={env.get('PYTC_NEUROGLANCER_PORT')}, "
+        f"neuroglancer_public_base={env.get('PYTC_NEUROGLANCER_PUBLIC_BASE')}"
+    )
+
+
+def _wait_for_health(
+    url: str, timeout: int = 30
+) -> tuple[bool, str | dict[str, Any] | None]:
+    deadline = time.time() + timeout
+    last_error = None
+    while time.time() < deadline:
+        try:
+            response = requests.get(url, timeout=2)
+            if response.status_code != 200:
+                last_error = f"HTTP {response.status_code}"
+            else:
+                return True, response.json() if response.text else None
+        except requests.RequestException as exc:
+            last_error = f"{type(exc).__name__}: {exc}"
+        time.sleep(1)
+    return False, last_error
+
+
+def stop_demo_api(
+    *,
+    api_port: int = DEMO2_API_PORT,
+    root: Path = DEMO_API_ROOT,
+    shutdown_timeout: int = 20,
+    poll_interval: float = 0.25,
+) -> int:
+    processes = discover_demo_api_processes(api_port=api_port, root=root)
+    if not processes:
+        print(f"No matching demo API process found on port {api_port} under {root}")
+        return 0
+
+    for process in processes:
+        print(f"Stopping pid {process.pid}: {process.command}")
+        try:
+            os.kill(process.pid, signal.SIGTERM)
+        except ProcessLookupError:
+            continue
+        except Exception as exc:
+            print(f"Failed to signal pid {process.pid}: {exc}")
+            return 1
+
+    deadline = time.time() + shutdown_timeout
+    while time.time() < deadline:
+        alive = [p for p in processes if _is_process_alive(p.pid)]
+        if not alive:
+            print(f"Stopped {len(processes)} demo API process(es)")
+            return 0
+        time.sleep(poll_interval)
+
+    for process in processes:
+        if _is_process_alive(process.pid):
+            try:
+                os.kill(process.pid, signal.SIGKILL)
+            except ProcessLookupError:
+                continue
+            except Exception as exc:
+                print(f"Failed to force-stop pid {process.pid}: {exc}")
+                return 1
+
+    print(f"Forcibly stopped {len(processes)} demo API process(es)")
+    return 0
+
+
+def _is_process_alive(pid: int) -> bool:
+    try:
+        os.kill(pid, 0)
+        return True
+    except ProcessLookupError:
+        return False
+    except Exception:
+        return False
+
+
+def start_demo_api(
+    *,
+    python_bin: Path = DEMO_API_ROOT / ".venv" / "bin" / "python",
+    root: Path = DEMO_API_ROOT,
+    log_file: Path = DEMO_API_ROOT / ".logs" / "start" / "demo2-api-server.log",
+    api_port: int = DEMO2_API_PORT,
+    health_timeout: int = 30,
+    force: bool = False,
+    pid_file: Path = DEMO_API_ROOT / ".logs" / "start" / "demo2-api.pid",
+    extra_env: dict[str, str] | None = None,
+) -> int:
+    if not python_bin.exists():
+        print(f"Python executable not found: {python_bin}")
+        return 1
+
+    processes = discover_demo_api_processes(api_port=api_port, root=root)
+    if processes:
+        if force:
+            print(
+                f"Found {len(processes)} existing process(es) on demo2 port {api_port}; stopping first"
+            )
+            stop_rc = stop_demo_api(api_port=api_port, root=root)
+            if stop_rc != 0:
+                return stop_rc
+        else:
+            details = ", ".join(str(p.pid) for p in processes)
+            print(f"Demo2 API already running on {api_port}: pid(s) {details}")
+            return 0
+
+    log_file.parent.mkdir(parents=True, exist_ok=True)
+    pid_file.parent.mkdir(parents=True, exist_ok=True)
+
+    command, env = _build_api_command(python_bin=python_bin, api_port=api_port)
+    if extra_env:
+        env.update(extra_env)
+    env["PYTC_API_PORT"] = str(api_port)
+
+    with log_file.open("a", encoding="utf-8") as handle:
+        try:
+            process = subprocess.Popen(
+                command,
+                cwd=str(root),
+                stdout=handle,
+                stderr=subprocess.STDOUT,
+                env=env,
+            )
+        except Exception as exc:
+            print(f"Failed to start demo2 API process: {exc}")
+            return 1
+
+    pid_file.write_text(f"{process.pid}\n", encoding="utf-8")
+    print(f"Started demo2 API pid {process.pid}; logs: {log_file}")
+    print(_runtime_snapshot_message(env, api_port=api_port))
+
+    healthy, detail = _wait_for_health(
+        f"http://127.0.0.1:{api_port}/health", timeout=health_timeout
+    )
+    if healthy:
+        print(f"Health check passed: https://127.0.0.1:{api_port}/health -> {detail}")
+        return 0
+
+    print("Health check failed after startup")
+    print(f"Last error: {detail}")
+    print("Recent log output:")
+    print(_tail_lines(log_file))
+    stop_demo_api(api_port=api_port, root=root)
+    return 1
+
+
+def print_status(*, api_port: int, root: Path) -> int:
+    processes = discover_demo_api_processes(api_port=api_port, root=root)
+    if not processes:
+        print("demo2 API: stopped")
+        return 1
+
+    health_ok, detail = _wait_for_health(
+        f"http://127.0.0.1:{api_port}/health", timeout=3
+    )
+    status = "healthy" if health_ok else "unhealthy"
+    for process in processes:
+        print(f"demo2 API pid {process.pid} ({status})")
+    if not health_ok:
+        print(f"Health detail: {detail}")
+        return 1
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Manage the demo2 API runtime process")
+    parser.add_argument(
+        "action",
+        choices=["start", "stop", "restart", "status"],
+        help="Action to run",
+    )
+    parser.add_argument(
+        "--api-port",
+        type=int,
+        default=DEMO2_API_PORT,
+        help=f"Expected PYTC_API_PORT for demo2 (default: {DEMO2_API_PORT})",
+    )
+    parser.add_argument(
+        "--repo-root",
+        default=str(DEMO_API_ROOT),
+        help="Demo repo root to scope process matching",
+    )
+    parser.add_argument(
+        "--python",
+        default=str(DEMO_API_ROOT / ".venv" / "bin" / "python"),
+        help="Python executable for launching server_api.main",
+    )
+    parser.add_argument(
+        "--log-file",
+        default=str(DEMO_API_ROOT / ".logs" / "start" / "demo2-api-server.log"),
+        help="Path for API log output",
+    )
+    parser.add_argument(
+        "--pid-file",
+        default=str(DEMO_API_ROOT / ".logs" / "start" / "demo2-api.pid"),
+        help="Path for pidfile",
+    )
+    parser.add_argument(
+        "--health-timeout",
+        type=int,
+        default=30,
+        help="Seconds to wait for /health before giving up",
+    )
+    parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Restart by stopping matching processes before start",
+    )
+    parser.add_argument(
+        "--extra-env",
+        action="append",
+        default=[],
+        help="Pass extra KEY=VALUE env into the managed process",
+    )
+    return parser
+
+
+def parse_extra_env(values: list[str]) -> dict[str, str]:
+    parsed: dict[str, str] = {}
+    for item in values:
+        if "=" not in item:
+            raise ValueError(f"Invalid --extra-env entry: {item}")
+        key, value = item.split("=", 1)
+        parsed[key.strip()] = value.strip()
+    return parsed
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    root = Path(args.repo_root).resolve()
+    log_file = Path(args.log_file)
+    pid_file = Path(args.pid_file)
+
+    if args.extra_env:
+        try:
+            env_overrides = parse_extra_env(args.extra_env)
+        except ValueError as exc:
+            print(exc)
+            return 1
+    else:
+        env_overrides = {}
+
+    if args.action == "start":
+        return start_demo_api(
+            python_bin=Path(args.python),
+            root=root,
+            log_file=log_file,
+            api_port=args.api_port,
+            health_timeout=args.health_timeout,
+            force=args.force,
+            pid_file=pid_file,
+            extra_env=env_overrides,
+        )
+
+    if args.action == "stop":
+        return stop_demo_api(api_port=args.api_port, root=root)
+
+    if args.action == "restart":
+        stop_rc = stop_demo_api(api_port=args.api_port, root=root)
+        if stop_rc != 0:
+            return stop_rc
+        return start_demo_api(
+            python_bin=Path(args.python),
+            root=root,
+            log_file=log_file,
+            api_port=args.api_port,
+            health_timeout=args.health_timeout,
+            force=False,
+            pid_file=pid_file,
+            extra_env=env_overrides,
+        )
+
+    if args.action == "status":
+        return print_status(api_port=args.api_port, root=root)
+
+    print(f"Unknown action: {args.action}")
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/scripts/run_closed_loop_smoke.py b/scripts/run_closed_loop_smoke.py
new file mode 100644
index 00000000..07912624
--- /dev/null
+++ b/scripts/run_closed_loop_smoke.py
@@ -0,0 +1,946 @@
+#!/usr/bin/env python3
+"""Run a local closed-loop workflow smoke against the FastAPI workflow API.
+
+This harness is deliberately honest about scope: it exercises workflow
+materialization, metrics, bundle export, and researcher-readiness gates with
+synthetic TIFF artifacts. It does not run PyTC training, PyTC inference, or the
+browser proofreading editor.
+"""
+
+from __future__ import annotations
+
+import argparse
+import contextlib
+import json
+import sys
+import tempfile
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+import numpy as np
+import tifffile
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+if str(REPO_ROOT) not in sys.path:
+    sys.path.insert(0, str(REPO_ROOT))
+
+from server_api.workflows.volume_io import (  # noqa: E402
+    SUPPORTED_VOLUME_FORMATS,
+    load_volume,
+    parse_crop,
+)
+
+
+def _write_json(path: Path, payload: Dict[str, Any]) -> None:
+    path.write_text(json.dumps(payload, indent=2, sort_keys=True), encoding="utf-8")
+
+
+def _request_json(response, label: str) -> Dict[str, Any]:
+    if response.status_code >= 400:
+        raise RuntimeError(f"{label} failed: {response.status_code} {response.text}")
+    return response.json()
+
+
+def _post_event(
+    client,
+    *,
+    workflow_id: int,
+    event_type: str,
+    stage: str,
+    summary: str,
+    payload: Optional[Dict[str, Any]] = None,
+    actor: str = "system",
+) -> Dict[str, Any]:
+    return _request_json(
+        client.post(
+            f"/api/workflows/{workflow_id}/events",
+            json={
+                "actor": actor,
+                "event_type": event_type,
+                "stage": stage,
+                "summary": summary,
+                "payload": payload or {},
+            },
+        ),
+        f"post {event_type}",
+    )
+
+
+def generate_smoke_artifacts(output_dir: Path) -> Dict[str, str]:
+    artifact_dir = output_dir / "artifacts"
+    artifact_dir.mkdir(parents=True, exist_ok=True)
+
+    volume_shape = (4, 32, 32)
+    z, y, x = np.indices(volume_shape)
+    image = ((x * 5 + y * 3 + z * 17) % 255).astype(np.uint8)
+
+    ground_truth = np.zeros(volume_shape, dtype=np.uint8)
+    ground_truth[:, 8:22, 9:23] = 1
+    ground_truth[1:3, 18:27, 4:13] = 2
+
+    baseline = np.zeros_like(ground_truth)
+    baseline[:, 10:20, 11:21] = 1
+    baseline[1:3, 20:25, 6:11] = 2
+
+    corrected = ground_truth.copy()
+    candidate = ground_truth.copy()
+
+    paths = {
+        "image": artifact_dir / "image.tif",
+        "initial_mask": artifact_dir / "initial-mask.tif",
+        "corrected_mask": artifact_dir / "corrected-mask.tif",
+        "ground_truth": artifact_dir / "ground-truth.tif",
+        "baseline_prediction": artifact_dir / "baseline-prediction.tif",
+        "candidate_prediction": artifact_dir / "candidate-prediction.tif",
+        "training_output": artifact_dir / "training-output",
+        "checkpoint": artifact_dir / "checkpoint-smoke.pth",
+        "evaluation_report": output_dir / "evaluation-report.json",
+    }
+
+    tifffile.imwrite(str(paths["image"]), image, photometric="minisblack")
+    tifffile.imwrite(str(paths["initial_mask"]), baseline, photometric="minisblack")
+    tifffile.imwrite(str(paths["corrected_mask"]), corrected, photometric="minisblack")
+    tifffile.imwrite(str(paths["ground_truth"]), ground_truth, photometric="minisblack")
+    tifffile.imwrite(
+        str(paths["baseline_prediction"]), baseline, photometric="minisblack"
+    )
+    tifffile.imwrite(
+        str(paths["candidate_prediction"]), candidate, photometric="minisblack"
+    )
+    paths["training_output"].mkdir(parents=True, exist_ok=True)
+    paths["checkpoint"].write_text(
+        "synthetic checkpoint placeholder\n", encoding="utf-8"
+    )
+
+    return {key: str(value) for key, value in paths.items()}
+
+
+def _write_tiff(path: Path, volume: np.ndarray) -> str:
+    tifffile.imwrite(str(path), np.asarray(volume), photometric="minisblack")
+    return str(path)
+
+
+def _apply_crop_to_array(array: np.ndarray, crop: Optional[str]) -> np.ndarray:
+    crop_slices = parse_crop(crop)
+    if crop_slices is None:
+        return np.asarray(array)
+    if len(crop_slices) > array.ndim:
+        raise ValueError(
+            f"Crop has {len(crop_slices)} dimensions but prediction array has "
+            f"{array.ndim}"
+        )
+    key = tuple(list(crop_slices) + [slice(None)] * (array.ndim - len(crop_slices)))
+    return np.asarray(array[key])
+
+
+def _select_prediction_channel(
+    array: np.ndarray,
+    *,
+    channel: Optional[int],
+    reference_ndim: int,
+    label: str,
+) -> np.ndarray:
+    volume = np.asarray(array)
+    if volume.ndim == reference_ndim:
+        if channel is not None:
+            raise ValueError(
+                f"{label} prediction is already {reference_ndim}D; "
+                "do not pass a channel selector for this artifact."
+            )
+        return volume
+    if volume.ndim != reference_ndim + 1:
+        return volume
+
+    if channel is not None and channel < 0:
+        raise ValueError(f"{label} channel must be non-negative")
+
+    if channel is None:
+        if volume.shape[0] <= 16:
+            axis = 0
+        elif volume.shape[-1] <= 16:
+            axis = -1
+        else:
+            raise ValueError(
+                f"{label} prediction has shape {volume.shape}; pass an explicit "
+                "channel because no small channel axis could be inferred."
+            )
+        channel = 0
+    elif volume.shape[0] > channel and volume.shape[0] <= 16:
+        axis = 0
+    elif volume.shape[-1] > channel and volume.shape[-1] <= 16:
+        axis = -1
+    elif volume.shape[0] > channel:
+        axis = 0
+    elif volume.shape[-1] > channel:
+        axis = -1
+    else:
+        raise ValueError(
+            f"{label} channel {channel} is out of bounds for prediction shape "
+            f"{volume.shape}"
+        )
+
+    return np.take(volume, channel, axis=axis)
+
+
+def _load_prediction_volume(
+    path: str,
+    *,
+    dataset_key: Optional[str],
+    crop: Optional[str],
+    channel: Optional[int],
+    reference_ndim: int,
+    label: str,
+) -> np.ndarray:
+    raw = load_volume(str(path), dataset_key=dataset_key)
+    selected = _select_prediction_channel(
+        raw,
+        channel=channel,
+        reference_ndim=reference_ndim,
+        label=label,
+    )
+    return _apply_crop_to_array(selected, crop)
+
+
+def _summarize_model_runs(rows: Any) -> List[Dict[str, Any]]:
+    return [
+        {
+            "id": row.get("id"),
+            "run_type": row.get("run_type"),
+            "status": row.get("status"),
+            "runtime": row.get("metadata", {}).get("runtime"),
+            "output_path": row.get("output_path"),
+            "checkpoint_path": row.get("checkpoint_path"),
+            "config_path": row.get("config_path"),
+        }
+        for row in (rows or [])
+    ]
+
+
+def _latest_row(rows: List[Dict[str, Any]]) -> Optional[Dict[str, Any]]:
+    return rows[-1] if rows else None
+
+
+def _derived_baseline_from_mask(mask: np.ndarray) -> np.ndarray:
+    baseline = np.asarray(mask).copy()
+    if baseline.size == 0:
+        return baseline
+    last_axis = baseline.ndim - 1
+    cutoff = max(1, baseline.shape[last_axis] // 4)
+    index = [slice(None)] * baseline.ndim
+    index[last_axis] = slice(0, cutoff)
+    baseline[tuple(index)] = 0
+    return baseline
+
+
+def generate_real_pair_artifacts(
+    output_dir: Path,
+    *,
+    image_path: str,
+    mask_path: str,
+    image_dataset: Optional[str] = None,
+    mask_dataset: Optional[str] = None,
+    baseline_prediction_path: Optional[str] = None,
+    candidate_prediction_path: Optional[str] = None,
+    baseline_dataset: Optional[str] = None,
+    candidate_dataset: Optional[str] = None,
+    baseline_channel: Optional[int] = None,
+    candidate_channel: Optional[int] = None,
+    ground_truth_path: Optional[str] = None,
+    ground_truth_dataset: Optional[str] = None,
+    crop: Optional[str] = None,
+) -> Dict[str, str]:
+    artifact_dir = output_dir / "artifacts"
+    artifact_dir.mkdir(parents=True, exist_ok=True)
+
+    image = load_volume(image_path, dataset_key=image_dataset, crop=crop)
+    ground_truth_source = ground_truth_path or mask_path
+    ground_truth_key = ground_truth_dataset or mask_dataset
+    ground_truth = load_volume(
+        ground_truth_source,
+        dataset_key=ground_truth_key,
+        crop=crop,
+    )
+    if image.shape != ground_truth.shape:
+        raise ValueError(
+            "Real image/ground-truth pair must resolve to the same shape after crop; "
+            f"got image {image.shape} and ground truth {ground_truth.shape}"
+        )
+
+    using_real_predictions = bool(baseline_prediction_path or candidate_prediction_path)
+    if using_real_predictions and not (
+        baseline_prediction_path and candidate_prediction_path
+    ):
+        raise ValueError(
+            "Real-prediction mode requires both baseline_prediction_path and "
+            "candidate_prediction_path"
+        )
+
+    if using_real_predictions:
+        baseline = _load_prediction_volume(
+            str(baseline_prediction_path),
+            dataset_key=baseline_dataset,
+            crop=crop,
+            channel=baseline_channel,
+            reference_ndim=ground_truth.ndim,
+            label="baseline",
+        )
+        candidate = _load_prediction_volume(
+            str(candidate_prediction_path),
+            dataset_key=candidate_dataset,
+            crop=crop,
+            channel=candidate_channel,
+            reference_ndim=ground_truth.ndim,
+            label="candidate",
+        )
+        shapes = {
+            "ground_truth": ground_truth.shape,
+            "baseline_prediction": baseline.shape,
+            "candidate_prediction": candidate.shape,
+        }
+        if len(set(shapes.values())) != 1:
+            raise ValueError(
+                "Real prediction volumes must match ground truth shape after crop; "
+                f"got {shapes}"
+            )
+    else:
+        baseline = _derived_baseline_from_mask(ground_truth)
+        candidate = np.asarray(ground_truth).copy()
+
+    paths = {
+        "source_image": str(Path(image_path).expanduser()),
+        "source_mask": str(Path(mask_path).expanduser()),
+        "source_ground_truth": str(Path(ground_truth_source).expanduser()),
+        "image": _write_tiff(artifact_dir / "image-crop.tif", image),
+        "initial_mask": _write_tiff(
+            artifact_dir / "initial-mask-derived.tif", baseline
+        ),
+        "corrected_mask": _write_tiff(
+            artifact_dir / "corrected-mask-crop.tif", ground_truth
+        ),
+        "ground_truth": _write_tiff(
+            artifact_dir / "ground-truth-crop.tif", ground_truth
+        ),
+        "baseline_prediction": _write_tiff(
+            artifact_dir
+            / (
+                "baseline-prediction-real.tif"
+                if using_real_predictions
+                else "baseline-prediction-derived.tif"
+            ),
+            baseline,
+        ),
+        "candidate_prediction": _write_tiff(
+            artifact_dir
+            / (
+                "candidate-prediction-real.tif"
+                if using_real_predictions
+                else "candidate-prediction-derived.tif"
+            ),
+            candidate,
+        ),
+        "training_output": str(artifact_dir / "training-output"),
+        "checkpoint": str(artifact_dir / "checkpoint-smoke.pth"),
+        "evaluation_report": str(output_dir / "evaluation-report.json"),
+    }
+    if baseline_prediction_path:
+        paths["source_baseline_prediction"] = str(
+            Path(baseline_prediction_path).expanduser()
+        )
+        if baseline_channel is not None:
+            paths["source_baseline_channel"] = str(baseline_channel)
+    if candidate_prediction_path:
+        paths["source_candidate_prediction"] = str(
+            Path(candidate_prediction_path).expanduser()
+        )
+        if candidate_channel is not None:
+            paths["source_candidate_channel"] = str(candidate_channel)
+
+    Path(paths["training_output"]).mkdir(parents=True, exist_ok=True)
+    Path(paths["checkpoint"]).write_text(
+        "real-pair smoke checkpoint placeholder\n", encoding="utf-8"
+    )
+    return paths
+
+
+def run_closed_loop_smoke(
+    output_dir: Path,
+    *,
+    include_research_plan: bool = True,
+    image_path: Optional[str] = None,
+    mask_path: Optional[str] = None,
+    image_dataset: Optional[str] = None,
+    mask_dataset: Optional[str] = None,
+    baseline_prediction_path: Optional[str] = None,
+    candidate_prediction_path: Optional[str] = None,
+    baseline_dataset: Optional[str] = None,
+    candidate_dataset: Optional[str] = None,
+    baseline_channel: Optional[int] = None,
+    candidate_channel: Optional[int] = None,
+    ground_truth_path: Optional[str] = None,
+    ground_truth_dataset: Optional[str] = None,
+    require_explicit_ground_truth: bool = False,
+    training_iterations: Optional[int] = None,
+    inference_iterations: Optional[int] = None,
+    crop: Optional[str] = None,
+) -> Dict[str, Any]:
+    output_dir.mkdir(parents=True, exist_ok=True)
+    if image_path or mask_path:
+        if not image_path or not mask_path:
+            raise ValueError(
+                "Real-artifact mode requires both image_path and mask_path"
+            )
+        if require_explicit_ground_truth and not ground_truth_path:
+            raise ValueError(
+                "Closed-loop real-artifact mode requires explicit --ground-truth-path for "
+                "evaluation in closed-loop rehearsal mode."
+            )
+        has_prediction_inputs = bool(
+            baseline_prediction_path or candidate_prediction_path
+        )
+        if has_prediction_inputs and not (
+            baseline_prediction_path and candidate_prediction_path
+        ):
+            raise ValueError(
+                "Real-prediction mode requires both baseline_prediction_path and "
+                "candidate_prediction_path"
+            )
+        artifact_mode = (
+            "real_pair_real_predictions"
+            if has_prediction_inputs
+            else "real_pair_derived_predictions"
+        )
+        artifacts = generate_real_pair_artifacts(
+            output_dir,
+            image_path=image_path,
+            mask_path=mask_path,
+            image_dataset=image_dataset,
+            mask_dataset=mask_dataset,
+            baseline_prediction_path=baseline_prediction_path,
+            candidate_prediction_path=candidate_prediction_path,
+            baseline_dataset=baseline_dataset,
+            candidate_dataset=candidate_dataset,
+            baseline_channel=baseline_channel,
+            candidate_channel=candidate_channel,
+            ground_truth_path=ground_truth_path,
+            ground_truth_dataset=ground_truth_dataset,
+            crop=crop,
+        )
+        source_data = {
+            "image_path": image_path,
+            "mask_path": mask_path,
+            "image_dataset": image_dataset,
+            "mask_dataset": mask_dataset,
+            "ground_truth_path": ground_truth_path or mask_path,
+            "ground_truth_dataset": ground_truth_dataset or mask_dataset,
+            "require_explicit_ground_truth": require_explicit_ground_truth,
+            "training_iterations": training_iterations,
+            "inference_iterations": inference_iterations,
+            "baseline_prediction_path": baseline_prediction_path,
+            "candidate_prediction_path": candidate_prediction_path,
+            "baseline_dataset": baseline_dataset,
+            "candidate_dataset": candidate_dataset,
+            "baseline_channel": baseline_channel,
+            "candidate_channel": candidate_channel,
+            "crop": crop,
+        }
+    else:
+        artifact_mode = "synthetic"
+        artifacts = generate_smoke_artifacts(output_dir)
+        source_data = {"synthetic": True}
+
+    from fastapi.testclient import TestClient
+    from sqlalchemy import create_engine
+    from sqlalchemy.orm import sessionmaker
+
+    from server_api.auth import database as auth_database
+    from server_api.auth import models
+
+    with contextlib.redirect_stdout(sys.stderr):
+        from server_api.main import app as server_api_app
+
+    db_path = output_dir / "workflow-smoke.db"
+    engine = create_engine(
+        f"sqlite:///{db_path}", connect_args={"check_same_thread": False}
+    )
+    session_local = sessionmaker(autocommit=False, autoflush=False, bind=engine)
+    models.Base.metadata.create_all(bind=engine)
+
+    def override_get_db():
+        db = session_local()
+        try:
+            yield db
+        finally:
+            db.close()
+
+    previous_override = server_api_app.dependency_overrides.get(auth_database.get_db)
+    server_api_app.dependency_overrides[auth_database.get_db] = override_get_db
+    prediction_runtime = (
+        "external_artifact"
+        if artifact_mode == "real_pair_real_predictions"
+        else "simulated"
+    )
+    baseline_summary = (
+        "Recorded external baseline prediction artifact."
+        if artifact_mode == "real_pair_real_predictions"
+        else "Recorded synthetic baseline inference output."
+    )
+    candidate_summary = (
+        "Recorded external candidate prediction artifact."
+        if artifact_mode == "real_pair_real_predictions"
+        else "Recorded synthetic candidate inference output."
+    )
+
+    try:
+        client = TestClient(server_api_app)
+        current = _request_json(client.get("/api/workflows/current"), "get workflow")
+        workflow_id = current["workflow"]["id"]
+
+        _post_event(
+            client,
+            workflow_id=workflow_id,
+            actor="user",
+            event_type="dataset.loaded",
+            stage="visualization",
+            summary="Loaded synthetic smoke-test image and initial mask.",
+            payload={
+                "image_path": artifacts.get("source_image") or artifacts["image"],
+                "mask_path": artifacts["initial_mask"],
+                "source_mask_path": artifacts.get("source_mask"),
+                "source_ground_truth_path": artifacts.get("source_ground_truth"),
+                "image_dataset": image_dataset,
+                "mask_dataset": mask_dataset,
+                "ground_truth_dataset": ground_truth_dataset,
+                "crop": crop,
+                "artifact_mode": artifact_mode,
+            },
+        )
+        _post_event(
+            client,
+            workflow_id=workflow_id,
+            event_type="inference.completed",
+            stage="inference",
+            summary=baseline_summary,
+            payload={
+                "outputPath": artifacts["baseline_prediction"],
+                "runtime": prediction_runtime,
+                "artifact_mode": artifact_mode,
+                "source_prediction_path": artifacts.get("source_baseline_prediction"),
+                "prediction_dataset": baseline_dataset,
+                "prediction_channel": baseline_channel,
+            },
+        )
+        _post_event(
+            client,
+            workflow_id=workflow_id,
+            actor="user",
+            event_type="proofreading.instance_classified",
+            stage="proofreading",
+            summary="Marked the smoke hotspot as incorrect.",
+            payload={"region_id": "z:1", "classification": "incorrect"},
+        )
+        _post_event(
+            client,
+            workflow_id=workflow_id,
+            actor="user",
+            event_type="proofreading.mask_saved",
+            stage="proofreading",
+            summary="Saved a synthetic corrected mask for the hotspot.",
+            payload={"region_id": "z:1", "instance_id": 42},
+        )
+        _post_event(
+            client,
+            workflow_id=workflow_id,
+            event_type="proofreading.masks_exported",
+            stage="proofreading",
+            summary="Exported synthetic corrected masks.",
+            payload={
+                "written_path": artifacts["corrected_mask"],
+                "region_id": "z:1",
+                "runtime": "simulated",
+                "artifact_mode": artifact_mode,
+            },
+        )
+
+        hotspots = _request_json(
+            client.get(f"/api/workflows/{workflow_id}/hotspots"),
+            "compute hotspots",
+        )
+        proposal = _request_json(
+            client.post(
+                f"/api/workflows/{workflow_id}/agent-actions",
+                json={
+                    "action": "stage_retraining_from_corrections",
+                    "summary": "Stage smoke corrections for retraining.",
+                    "payload": {"corrected_mask_path": artifacts["corrected_mask"]},
+                },
+            ),
+            "create agent proposal",
+        )
+        _request_json(
+            client.post(
+                f"/api/workflows/{workflow_id}/agent-actions/{proposal['id']}/approve"
+            ),
+            "approve agent proposal",
+        )
+        _post_event(
+            client,
+            workflow_id=workflow_id,
+            event_type="training.completed",
+            stage="evaluation",
+            summary="Recorded synthetic retraining completion.",
+            payload={
+                "outputPath": artifacts["training_output"],
+                "checkpointPath": artifacts["checkpoint"],
+                "checkpointName": "checkpoint-smoke.pth",
+                "runtime": "simulated",
+                "iterations": training_iterations,
+                "artifact_mode": artifact_mode,
+            },
+        )
+        _post_event(
+            client,
+            workflow_id=workflow_id,
+            event_type="inference.completed",
+            stage="evaluation",
+            summary=candidate_summary,
+            payload={
+                "outputPath": artifacts["candidate_prediction"],
+                "checkpointPath": artifacts["checkpoint"],
+                "runtime": prediction_runtime,
+                "iterations": inference_iterations,
+                "artifact_mode": artifact_mode,
+                "source_prediction_path": artifacts.get("source_candidate_prediction"),
+                "prediction_dataset": candidate_dataset,
+                "prediction_channel": candidate_channel,
+            },
+        )
+
+        training_runs = _request_json(
+            client.get(
+                f"/api/workflows/{workflow_id}/model-runs",
+                params={"run_type": "training"},
+            ),
+            "list training runs",
+        )
+        inference_runs = _request_json(
+            client.get(
+                f"/api/workflows/{workflow_id}/model-runs",
+                params={"run_type": "inference"},
+            ),
+            "list inference runs",
+        )
+        model_versions = _request_json(
+            client.get(f"/api/workflows/{workflow_id}/model-versions"),
+            "list model versions",
+        )
+        latest_training_run = _latest_row(training_runs)
+        latest_inference_run = _latest_row(inference_runs)
+        latest_model_version = _latest_row(model_versions)
+
+        research_plan: Optional[Dict[str, Any]] = None
+        if include_research_plan:
+            research_plan = _request_json(
+                client.post(
+                    f"/api/workflows/{workflow_id}/agent-plans",
+                    json={
+                        "title": "Researcher-only smoke readiness plan",
+                        "metadata": {"researcher_only": True, "synthetic": True},
+                    },
+                ),
+                "create researcher-only agent plan",
+            )
+            _request_json(
+                client.post(
+                    f"/api/workflows/{workflow_id}/agent-plans/{research_plan['id']}/approve"
+                ),
+                "approve researcher-only agent plan",
+            )
+
+        evaluation = _request_json(
+            client.post(
+                f"/api/workflows/{workflow_id}/evaluation-results/compute",
+                json={
+                    "name": "synthetic-closed-loop-smoke",
+                    "ground_truth_path": artifacts["ground_truth"],
+                    "baseline_prediction_path": artifacts["baseline_prediction"],
+                    "candidate_prediction_path": artifacts["candidate_prediction"],
+                    "report_path": artifacts["evaluation_report"],
+                    "metadata": {
+                        "artifact_mode": artifact_mode,
+                        "source_data": source_data,
+                    },
+                },
+            ),
+            "compute evaluation",
+        )
+        readiness = _request_json(
+            client.get(f"/api/workflows/{workflow_id}/case-study-readiness"),
+            "get researcher readiness",
+        )
+        bundle = _request_json(
+            client.post(f"/api/workflows/{workflow_id}/export-bundle"),
+            "export bundle",
+        )
+
+        _write_json(output_dir / "workflow-bundle.json", bundle)
+        _write_json(output_dir / "readiness.json", readiness)
+
+        report = {
+            "workflow_id": workflow_id,
+            "artifact_mode": artifact_mode,
+            "source_data": source_data,
+            "output_dir": str(output_dir),
+            "db_path": str(db_path),
+            "ready_for_case_study": readiness["ready_for_case_study"],
+            "readiness": {
+                "completed_count": readiness["completed_count"],
+                "total_count": readiness["total_count"],
+                "next_required_items": readiness["next_required_items"],
+            },
+            "metric_summary": evaluation["metrics"]["summary"],
+            "runtime_sync": {
+                "training_runs": _summarize_model_runs(training_runs),
+                "inference_runs": _summarize_model_runs(inference_runs),
+                "model_versions": [
+                    {
+                        "id": item.get("id"),
+                        "version_label": item.get("version_label"),
+                        "status": item.get("status"),
+                        "checkpoint_path": item.get("checkpoint_path"),
+                        "training_run_id": item.get("training_run_id"),
+                    }
+                    for item in (model_versions or [])
+                ],
+            },
+            "runtime_checkpoints": {
+                "checkpoint": artifacts["checkpoint"],
+                "training_run_checkpoint": latest_training_run.get("checkpoint_path"),
+                "inference_run_checkpoint": latest_inference_run.get("checkpoint_path"),
+                "model_version_checkpoint": (
+                    latest_model_version.get("checkpoint_path")
+                    if latest_model_version
+                    else None
+                ),
+            },
+            "runtime_overrides": {
+                "training_iterations": training_iterations,
+                "inference_iterations": inference_iterations,
+            },
+            "bundle_counts": {
+                "events": len(bundle.get("events", [])),
+                "artifacts": len(bundle.get("artifacts", [])),
+                "model_runs": len(bundle.get("model_runs", [])),
+                "model_versions": len(bundle.get("model_versions", [])),
+                "correction_sets": len(bundle.get("correction_sets", [])),
+                "evaluation_results": len(bundle.get("evaluation_results", [])),
+                "persisted_hotspots": len(bundle.get("persisted_hotspots", [])),
+                "agent_plans": len(bundle.get("agent_plans", [])),
+            },
+            "top_hotspot": hotspots.get("hotspots", [{}])[0],
+            "real_checks_exercised": [
+                "FastAPI workflow routes",
+                "SQLite workflow persistence with typed records",
+                "artifact materialization from workflow events",
+                "correction-set materialization",
+                "model-run and model-version materialization",
+                "hotspot ranking from workflow event evidence",
+                "TIFF before/after segmentation metrics",
+                *(
+                    ["real prediction artifacts supplied by caller"]
+                    if artifact_mode == "real_pair_real_predictions"
+                    else []
+                ),
+                "workflow evidence bundle export",
+            ],
+            "simulated_or_not_exercised": [
+                "actual PyTC training subprocess",
+                "actual PyTC inference subprocess",
+                "browser-level proofreading editor interaction",
+                *(
+                    []
+                    if artifact_mode.startswith("real_pair_")
+                    else ["real biomedical/connectomics sample data"]
+                ),
+                *(
+                    [
+                        "baseline/candidate predictions derived from real segmentation labels, not model outputs"
+                    ]
+                    if artifact_mode == "real_pair_derived_predictions"
+                    else []
+                ),
+                "long-running job queue, cancellation, retry, and failure recovery",
+            ],
+            "supported_volume_formats": list(SUPPORTED_VOLUME_FORMATS),
+            "researcher_only_checks": (
+                [
+                    "case-study readiness gate",
+                    "bounded agent plan preview and approval audit",
+                ]
+                if include_research_plan
+                else ["case-study readiness gate without plan approval"]
+            ),
+            "artifacts": artifacts,
+        }
+        _write_json(output_dir / "smoke-report.json", report)
+        return report
+    finally:
+        if previous_override is None:
+            server_api_app.dependency_overrides.pop(auth_database.get_db, None)
+        else:
+            server_api_app.dependency_overrides[auth_database.get_db] = (
+                previous_override
+            )
+        engine.dispose()
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Run a synthetic closed-loop workflow smoke for PyTC workflow evidence."
+    )
+    parser.add_argument(
+        "--output-dir",
+        type=Path,
+        default=None,
+        help="Directory for generated smoke artifacts. Defaults to a temp directory.",
+    )
+    parser.add_argument(
+        "--no-research-plan",
+        action="store_true",
+        help="Skip the researcher-only agent-plan readiness gate.",
+    )
+    parser.add_argument(
+        "--image-path",
+        type=str,
+        default=None,
+        help="Optional real raw image volume path. Enables real-artifact mode.",
+    )
+    parser.add_argument(
+        "--mask-path",
+        type=str,
+        default=None,
+        help="Optional real label/segmentation volume path. Enables real-artifact mode.",
+    )
+    parser.add_argument(
+        "--image-dataset",
+        type=str,
+        default=None,
+        help="Dataset key for HDF5/Zarr/NPZ image volumes, e.g. main.",
+    )
+    parser.add_argument(
+        "--mask-dataset",
+        type=str,
+        default=None,
+        help="Dataset key for HDF5/Zarr/NPZ mask volumes, e.g. data.",
+    )
+    parser.add_argument(
+        "--ground-truth-path",
+        type=str,
+        default=None,
+        help="Optional ground-truth path for evaluation. Defaults to --mask-path.",
+    )
+    parser.add_argument(
+        "--ground-truth-required",
+        action="store_true",
+        help=(
+            "Require explicit ground-truth path for evaluation; do not infer from "
+            "--mask-path for rehearsal runs."
+        ),
+    )
+    parser.add_argument(
+        "--ground-truth-dataset",
+        type=str,
+        default=None,
+        help="Dataset key for the ground-truth volume. Defaults to --mask-dataset.",
+    )
+    parser.add_argument(
+        "--baseline-prediction-path",
+        type=str,
+        default=None,
+        help="Optional real baseline prediction path.",
+    )
+    parser.add_argument(
+        "--candidate-prediction-path",
+        type=str,
+        default=None,
+        help="Optional real candidate prediction path.",
+    )
+    parser.add_argument(
+        "--baseline-dataset",
+        type=str,
+        default=None,
+        help="Dataset key for the baseline prediction volume.",
+    )
+    parser.add_argument(
+        "--candidate-dataset",
+        type=str,
+        default=None,
+        help="Dataset key for the candidate prediction volume.",
+    )
+    parser.add_argument(
+        "--baseline-channel",
+        type=int,
+        default=None,
+        help=(
+            "Optional channel index for channel-first/channel-last baseline "
+            "prediction volumes such as PyTC result_xy.h5."
+        ),
+    )
+    parser.add_argument(
+        "--candidate-channel",
+        type=int,
+        default=None,
+        help=(
+            "Optional channel index for channel-first/channel-last candidate "
+            "prediction volumes such as PyTC result_xy.h5."
+        ),
+    )
+    parser.add_argument(
+        "--crop",
+        type=str,
+        default=None,
+        help="Optional crop like '0:8,0:256,0:256'. Use this for large volumes.",
+    )
+    parser.add_argument(
+        "--training-iterations",
+        type=int,
+        default=None,
+        help="Optional training iteration override for dry-run rehearsal metadata.",
+    )
+    parser.add_argument(
+        "--inference-iterations",
+        type=int,
+        default=None,
+        help="Optional inference iteration override for dry-run rehearsal metadata.",
+    )
+    args = parser.parse_args()
+
+    output_dir = args.output_dir or Path(
+        tempfile.mkdtemp(prefix="pytc-closed-loop-smoke-")
+    )
+    report = run_closed_loop_smoke(
+        output_dir=output_dir,
+        include_research_plan=not args.no_research_plan,
+        image_path=args.image_path,
+        mask_path=args.mask_path,
+        image_dataset=args.image_dataset,
+        mask_dataset=args.mask_dataset,
+        baseline_prediction_path=args.baseline_prediction_path,
+        candidate_prediction_path=args.candidate_prediction_path,
+        baseline_dataset=args.baseline_dataset,
+        candidate_dataset=args.candidate_dataset,
+        baseline_channel=args.baseline_channel,
+        candidate_channel=args.candidate_channel,
+        ground_truth_path=args.ground_truth_path,
+        ground_truth_dataset=args.ground_truth_dataset,
+        require_explicit_ground_truth=args.ground_truth_required,
+        training_iterations=args.training_iterations,
+        inference_iterations=args.inference_iterations,
+        crop=args.crop,
+    )
+
+    print(json.dumps(report, indent=2, sort_keys=True))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/scripts/run_yixiao_case_study_smoke.py b/scripts/run_yixiao_case_study_smoke.py
new file mode 100755
index 00000000..17e3cd12
--- /dev/null
+++ b/scripts/run_yixiao_case_study_smoke.py
@@ -0,0 +1,1970 @@
+#!/usr/bin/env python3
+"""Smoke-test the Yixiao/TapeReader XRI case-study contract.
+
+This is a live API harness for the demo-facing workflow. It verifies the
+case-study assumptions that matter for paper/demo work: project mounting,
+manifest-backed file roles, progress counts, viewer creation, project memory,
+and agent action proposals.
+"""
+
+from __future__ import annotations
+
+import argparse
+import copy
+import json
+import subprocess
+import sys
+import time
+import urllib.error
+import urllib.request
+from pathlib import Path
+from typing import Any, Dict, Iterable, List, Optional
+from urllib.parse import urlsplit
+
+DEFAULT_BASE_URL = "http://127.0.0.1:4342"
+DEFAULT_PROJECT_ROOT = Path("/home/weidf/demo_data/yixiao_tapereader_xri_case_study")
+DEFAULT_HOLDOUT_ROOT = Path(
+    "/home/weidf/demo_data/yixiao_tapereader_xri_case_study_holdout_masks"
+)
+DEFAULT_REPORT_PATH = Path("/tmp/yixiao-case-study-smoke-report.json")
+DEFAULT_PRE_DEMO_GATE_REPORT_PATH = Path(
+    "/tmp/yixiao-case-study-pre-demo-gate-report.json"
+)
+DEFAULT_CLOSED_LOOP_REHEARSAL_REPORT_PATH = Path(
+    "/tmp/yixiao-closed-loop-rehearsal-report.json"
+)
+DEFAULT_POST_DEPLOY_REPORT_ROOT = Path("docs/case-studies")
+REPO_ROOT = Path(__file__).resolve().parents[1]
+PROJECT_TITLE = "Yixiao TapeReader XRI Case Study"
+PROJECT_SLUG = "yixiao_tapereader_xri_case_study"
+SUGGESTION_ID = "yixiao-tapereader-xri-case-study"
+IMAGE_ONLY_TARGET_IDS = ("6_1", "6_2")
+POST_DEPLOY_WORKFLOW_ID = 199
+POST_DEPLOY_PROJECT_ROOT = "/home/weidf/demo_data/yixiao_tapereader_xri_case_study"
+
+if str(REPO_ROOT) not in sys.path:
+    sys.path.insert(0, str(REPO_ROOT))
+
+
+class SmokeFailure(RuntimeError):
+    pass
+
+
+class SmokeHarness:
+    def __init__(self, *, base_url: str, verbose: bool = False) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.verbose = verbose
+        self.checks: List[Dict[str, Any]] = []
+        self.headers = {
+            "Accept": "application/json",
+            "User-Agent": "Mozilla/5.0 (compatible; pytc-yixiao-smoke)",
+        }
+
+    def note(self, message: str) -> None:
+        if self.verbose:
+            print(message)
+
+    def check(self, name: str, passed: bool, detail: Any = None) -> None:
+        self.checks.append({"name": name, "passed": bool(passed), "detail": detail})
+        if not passed:
+            raise SmokeFailure(f"{name} failed: {detail}")
+        self.note(f"ok - {name}")
+
+    def request_json_with_status(
+        self,
+        method: str,
+        path: str,
+        *,
+        payload: Optional[Dict[str, Any]] = None,
+        timeout: int = 30,
+        expect_json: bool = True,
+    ) -> Any:
+        data = None
+        headers = dict(self.headers)
+        if payload is not None:
+            data = json.dumps(payload).encode("utf-8")
+            headers["Content-Type"] = "application/json"
+        url = f"{self.base_url}{path}"
+        request = urllib.request.Request(url, data=data, method=method, headers=headers)
+        try:
+            with urllib.request.urlopen(request, timeout=timeout) as response:
+                status = response.status
+                raw = response.read().decode("utf-8")
+        except urllib.error.HTTPError as exc:
+            status = exc.code
+            raw = exc.read().decode("utf-8", errors="replace")
+        except urllib.error.URLError as exc:
+            raise SmokeFailure(f"{method} {path} failed: {exc}") from exc
+        if not raw:
+            return status, {}
+        if not expect_json:
+            return status, raw
+        try:
+            return status, json.loads(raw)
+        except json.JSONDecodeError as exc:
+            if status >= 400:
+                raise SmokeFailure(
+                    f"{method} {path} returned {status}: {raw[:300]}"
+                ) from exc
+            raise SmokeFailure(
+                f"{method} {path} returned non-JSON: {raw[:300]}"
+            ) from exc
+
+    def request_json(
+        self,
+        method: str,
+        path: str,
+        *,
+        payload: Optional[Dict[str, Any]] = None,
+        timeout: int = 30,
+    ) -> Any:
+        status, parsed = self.request_json_with_status(
+            method,
+            path,
+            payload=payload,
+            timeout=timeout,
+            expect_json=True,
+        )
+        if status >= 400:
+            raise SmokeFailure(f"{method} {path} returned {status}: {parsed}")
+        return parsed
+
+
+def _load_manifest(project_root: Path) -> Dict[str, Any]:
+    manifest_path = project_root / "project_manifest.json"
+    if not manifest_path.exists():
+        raise SmokeFailure(f"Missing project manifest: {manifest_path}")
+    return json.loads(manifest_path.read_text(encoding="utf-8"))
+
+
+def _rel_to_abs(project_root: Path, rel_path: Optional[str]) -> Optional[str]:
+    if not rel_path:
+        return None
+    path = Path(rel_path)
+    if path.is_absolute():
+        return str(path)
+    return str(project_root / path)
+
+
+def _manifest_volumes(manifest: Dict[str, Any]) -> List[Dict[str, Any]]:
+    volumes = manifest.get("volumes")
+    return volumes if isinstance(volumes, list) else []
+
+
+def _status_counts(volumes: Iterable[Dict[str, Any]]) -> Dict[str, int]:
+    counts: Dict[str, int] = {}
+    for volume in volumes:
+        status = str(volume.get("status") or "unknown")
+        counts[status] = counts.get(status, 0) + 1
+    return counts
+
+
+def _progress_overrides(manifest: Dict[str, Any]) -> Dict[str, Dict[str, str]]:
+    overrides: Dict[str, Dict[str, str]] = {}
+    for volume in _manifest_volumes(manifest):
+        image = volume.get("image")
+        status = volume.get("status")
+        if image and status:
+            overrides[str(image)] = {
+                "status": str(status),
+                "note": str(status),
+            }
+    return overrides
+
+
+def _first_volume_with_label(manifest: Dict[str, Any]) -> Dict[str, Any]:
+    for volume in _manifest_volumes(manifest):
+        if volume.get("image") and volume.get("segmentation"):
+            return volume
+    raise SmokeFailure("Manifest does not contain any image/segmentation pair.")
+
+
+def _first_volume_with_status(manifest: Dict[str, Any], status: str) -> Dict[str, Any]:
+    for volume in _manifest_volumes(manifest):
+        if volume.get("image") and volume.get("status") == status:
+            return volume
+    raise SmokeFailure(f"Manifest does not contain a {status!r} volume.")
+
+
+def _workflow_patch_payload(
+    project_root: Path, manifest: Dict[str, Any]
+) -> Dict[str, Any]:
+    first = _first_volume_with_label(manifest)
+    active_paths = manifest.get("active_paths") or {}
+    voxel = (manifest.get("voxel_size") or {}).get("zyx_nm") or [40, 16.3, 16.3]
+    context = {
+        "task_goal": manifest.get("task")
+        or "CytoTape fibre instance segmentation and workflow coordination case study",
+        "imaging_modality": manifest.get("imaging_modality")
+        or "X-ray / XRI volumetric microscopy",
+        "target_structure": manifest.get("target_structure") or "CytoTape fibres",
+        "task_family": manifest.get("task_family") or "fibre instance segmentation",
+        "optimization_priority": "case-study workflow fidelity",
+        "mask_status": "6 confirmed ground-truth volumes, 2 draft masks for proofreading, 2 image-only inference targets",
+        "image_only_strategy": "run inference on 6_1 and 6_2 after training/checkpoint selection",
+        "training_policy": "train only on confirmed ground-truth masks",
+        "voxel_size_nm": voxel,
+        "voxel_size_source": "project_manifest.json",
+    }
+    metadata = {
+        "created_from": "yixiao_case_study_smoke",
+        "project_name": PROJECT_TITLE,
+        "project_context": context,
+        "project_progress_overrides": _progress_overrides(manifest),
+        "visualization_scales": voxel,
+        "visualization_scales_source": "project_manifest.json",
+    }
+    return {
+        "title": PROJECT_TITLE,
+        "stage": "visualization",
+        "dataset_path": str(project_root),
+        "image_path": _rel_to_abs(project_root, first.get("image")),
+        "label_path": _rel_to_abs(project_root, first.get("segmentation")),
+        "mask_path": _rel_to_abs(project_root, first.get("segmentation")),
+        "config_path": _rel_to_abs(project_root, active_paths.get("config")),
+        "training_output_path": _rel_to_abs(project_root, "outputs/training"),
+        "metadata": metadata,
+    }
+
+
+def _find_yixiao_suggestion(suggestions: Any) -> Optional[Dict[str, Any]]:
+    items = (
+        suggestions
+        if isinstance(suggestions, list)
+        else suggestions.get("suggestions", [])
+    )
+    for item in items:
+        if item.get("id") == SUGGESTION_ID:
+            return item
+        text = " ".join(
+            str(item.get(key) or "")
+            for key in ("name", "title", "label", "directory_path")
+        ).lower()
+        if "yixiao" in text or "tapereader" in text or "xri" in text:
+            return item
+    return None
+
+
+def _assert_progress_counts(
+    harness: SmokeHarness,
+    progress: Dict[str, Any],
+    expected: Dict[str, int],
+    *,
+    expected_completion_pct: float = 60.0,
+    expected_segmentation_coverage_pct: float = 80.0,
+) -> None:
+    summary = progress.get("summary") or {}
+    for key, value in expected.items():
+        harness.check(f"progress {key}", summary.get(key) == value, summary)
+    harness.check(
+        "progress completion pct",
+        float(summary.get("completion_pct") or 0) == expected_completion_pct,
+        summary,
+    )
+    harness.check(
+        "progress segmentation coverage pct",
+        float(summary.get("segmentation_coverage_pct") or 0)
+        == expected_segmentation_coverage_pct,
+        summary,
+    )
+
+
+def _assert_profile(harness: SmokeHarness, suggestion: Dict[str, Any]) -> None:
+    profile = suggestion.get("profile") or {}
+    schema = profile.get("schema") if isinstance(profile.get("schema"), dict) else {}
+    primary = schema.get("primary_paths") or profile.get("primary_paths") or {}
+    volume_sets = schema.get("volume_sets") or profile.get("volume_sets") or []
+    audit = schema.get("audit") or profile.get("audit") or {}
+    audit_summary = audit.get("summary") or {}
+    harness.check(
+        "profile image root", primary.get("image_root") == "data/raw", primary
+    )
+    harness.check(
+        "profile label root", primary.get("label_root") == "data/seg", primary
+    )
+    harness.check(
+        "profile config",
+        primary.get("config") == "configs/TapeReader-Fiber-BCS-AppCompat-Sanity.yaml",
+        primary,
+    )
+    manifest_set = next(
+        (item for item in volume_sets if item.get("id") == "manifest-active-set"),
+        None,
+    )
+    harness.check(
+        "profile manifest volume set exists", manifest_set is not None, volume_sets
+    )
+    if manifest_set:
+        harness.check(
+            "profile image count", manifest_set.get("image_count") == 10, manifest_set
+        )
+        harness.check(
+            "profile label count", manifest_set.get("label_count") == 8, manifest_set
+        )
+        harness.check(
+            "profile pair count", manifest_set.get("pair_count") == 8, manifest_set
+        )
+    harness.check(
+        "profile audit errors", audit_summary.get("errors") == 0, audit_summary
+    )
+    harness.check(
+        "profile audit warnings", audit_summary.get("warnings") == 0, audit_summary
+    )
+    harness.check(
+        "profile audit pair checks",
+        audit_summary.get("pair_checks") == 8,
+        audit_summary,
+    )
+    harness.check(
+        "profile audit shape matches",
+        audit_summary.get("shape_match_count") == 8,
+        audit_summary,
+    )
+
+
+def _assert_agent_project_response(
+    harness: SmokeHarness, response: Dict[str, Any]
+) -> None:
+    text = response.get("response") or ""
+    harness.check(
+        "agent project intent", response.get("intent") == "project_context", response
+    )
+    for needle in ("Yixiao", "XRI", "CytoTape", "10 volume", "6 fully good"):
+        harness.check(f"agent project mentions {needle}", needle in text, text)
+
+
+def _assert_agent_training_response(
+    harness: SmokeHarness,
+    response: Dict[str, Any],
+    *,
+    expected_train_count: int = 6,
+    expected_review_count: int = 2,
+    expected_target_count: int = 2,
+) -> None:
+    harness.check(
+        "agent training intent", response.get("intent") == "start_training", response
+    )
+    actions = response.get("actions") or []
+    action = next(
+        (item for item in actions if item.get("id") == "start-training"), None
+    )
+    harness.check("agent training action exists", action is not None, actions)
+    if not action:
+        return
+    harness.check(
+        "agent training requires approval",
+        action.get("requires_approval") is True,
+        action,
+    )
+    harness.check("agent training risk", action.get("risk_level") == "runs_job", action)
+    effects = action.get("client_effects") or {}
+    subset = effects.get("training_volume_subset") or {}
+    harness.check(
+        "training subset GT count",
+        subset.get("train_volume_count") == expected_train_count,
+        subset,
+    )
+    harness.check(
+        "training subset review count",
+        subset.get("review_volume_count") == expected_review_count,
+        subset,
+    )
+    harness.check(
+        "training subset target count",
+        subset.get("target_volume_count") == expected_target_count,
+        subset,
+    )
+    for key in (
+        "set_training_image_path",
+        "set_training_label_path",
+        "set_training_output_path",
+    ):
+        path = effects.get(key)
+        harness.check(
+            f"training effect {key}", bool(path) and Path(path).exists(), path
+        )
+    manifest_path = subset.get("manifest_path")
+    harness.check(
+        "training subset manifest exists",
+        bool(manifest_path) and Path(manifest_path).exists(),
+        manifest_path,
+    )
+    _assert_pytc_training_subset_resolves(
+        harness,
+        effects,
+        expected_train_count=expected_train_count,
+    )
+
+
+def _assert_pytc_training_subset_resolves(
+    harness: SmokeHarness,
+    effects: Dict[str, Any],
+    *,
+    expected_train_count: int = 6,
+) -> None:
+    """Verify the worker-side config staging accepts the proposed subset.
+
+    This deliberately stops before launching PyTC. It catches the common failure
+    mode where the UI receives directory paths that the worker later treats as
+    an unrecognizable single volume.
+    """
+
+    try:
+        from server_pytc.services import model as pytc_model
+    except Exception as exc:  # pragma: no cover - only depends on local env
+        harness.check("PyTC worker resolver import", False, str(exc))
+        return
+
+    image_path = effects.get("set_training_image_path")
+    label_path = effects.get("set_training_label_path")
+    output_path = effects.get("set_training_output_path")
+    config_path = effects.get("set_training_config_preset")
+    images, labels, reason = pytc_model._resolve_runtime_training_inputs(
+        image_path,
+        label_path,
+    )
+    harness.check(
+        "PyTC subset resolver reason",
+        reason == "runtime_request_training_subset_manifest",
+        reason,
+    )
+    harness.check(
+        "PyTC subset resolver image count",
+        len(images) == expected_train_count,
+        images,
+    )
+    harness.check(
+        "PyTC subset resolver label count",
+        len(labels) == expected_train_count,
+        labels,
+    )
+    config_text = Path(config_path).read_text(encoding="utf-8")
+    staged_config, _changes = pytc_model._apply_runtime_path_overrides(
+        config_text,
+        {
+            "inputImagePath": image_path,
+            "inputLabelPath": label_path,
+            "outputPath": output_path,
+        },
+        kind="training",
+    )
+    pytc_model._validate_runtime_launch_inputs(staged_config, kind="training")
+    harness.check("PyTC staged training config validates", True, config_path)
+
+
+def _normalize_smoke_args(args: argparse.Namespace) -> argparse.Namespace:
+    """Normalize legacy boolean presets for one smoke invocation."""
+
+    normalized = copy.copy(args)
+    if normalized.prepare_live:
+        normalized.reset_workspace = True
+        normalized.mount_project = True
+        normalized.reset_workflow = True
+    return normalized
+
+
+def _run_smoke_step(
+    args: argparse.Namespace,
+    *,
+    step_name: str,
+    report_path: Path,
+) -> Dict[str, Any]:
+    step_args = copy.copy(args)
+    step_args = _normalize_smoke_args(step_args)
+    step_args.report = str(report_path)
+    start = time.time()
+
+    entry: Dict[str, Any] = {
+        "name": step_name,
+        "report_path": str(report_path),
+        "passed": False,
+    }
+    try:
+        report = run(step_args)
+    except Exception as exc:  # pragma: no cover - exercised in caller tests.
+        entry.update(
+            {
+                "error": str(exc),
+                "duration_seconds": time.time() - start,
+            }
+        )
+        return entry
+
+    entry.update(
+        {
+            "passed": True,
+            "workflow_id": report.get("workflow_id"),
+            "duration_seconds": time.time() - start,
+            "report": report,
+        }
+    )
+    return entry
+
+
+def _run_readiness_check(
+    harness: SmokeHarness,
+    *,
+    workflow_id: int,
+    timeout: int = 20,
+) -> Dict[str, Any]:
+    start = time.time()
+    try:
+        payload = harness.request_json(
+            "GET",
+            f"/api/workflows/{workflow_id}/case-study-readiness",
+            timeout=timeout,
+        )
+    except Exception as exc:
+        return {
+            "name": "readiness_check",
+            "passed": False,
+            "duration_seconds": time.time() - start,
+            "error": str(exc),
+            "payload_missing_keys": [],
+        }
+
+    if not isinstance(payload, dict):
+        return {
+            "name": "readiness_check",
+            "passed": False,
+            "duration_seconds": time.time() - start,
+            "error": "readiness response is not a JSON object",
+            "payload_missing_keys": [],
+        }
+
+    required = {
+        "workflow_id",
+        "ready_for_case_study",
+        "completed_count",
+        "total_count",
+        "gates",
+        "next_required_items",
+    }
+    missing = sorted(required - set(payload.keys()))
+    return {
+        "name": "readiness_check",
+        "passed": not missing,
+        "duration_seconds": time.time() - start,
+        "ready_for_case_study": bool(payload.get("ready_for_case_study")),
+        "completed_count": int(payload.get("completed_count", 0)),
+        "total_count": int(payload.get("total_count", 0)),
+        "next_required_items": payload.get("next_required_items") or [],
+        "payload_missing_keys": missing,
+    }
+
+
+def _run_export_bundle_check(
+    harness: SmokeHarness,
+    *,
+    workflow_id: int,
+    timeout: int = 30,
+) -> Dict[str, Any]:
+    start = time.time()
+    try:
+        payload = harness.request_json(
+            "POST",
+            f"/api/workflows/{workflow_id}/export-bundle",
+            timeout=timeout,
+        )
+    except Exception as exc:
+        return {
+            "name": "export_sanity",
+            "passed": False,
+            "duration_seconds": time.time() - start,
+            "error": str(exc),
+            "payload_missing_keys": [],
+        }
+
+    if not isinstance(payload, dict):
+        return {
+            "name": "export_sanity",
+            "passed": False,
+            "duration_seconds": time.time() - start,
+            "error": "export response is not a JSON object",
+            "payload_missing_keys": [],
+        }
+
+    required = {
+        "schema_version",
+        "workflow_id",
+        "events",
+        "artifacts",
+        "model_runs",
+        "model_versions",
+        "correction_sets",
+        "agent_plans",
+        "bundle_directory",
+        "bundle_manifest_path",
+    }
+    missing = sorted(required - set(payload.keys()))
+
+    bundle_manifest = payload.get("bundle_manifest_path")
+    bundle_directory = payload.get("bundle_directory")
+    return {
+        "name": "export_sanity",
+        "passed": not missing,
+        "duration_seconds": time.time() - start,
+        "bundle_directory": bundle_directory,
+        "bundle_manifest_path": bundle_manifest,
+        "bundle_manifest_exists": bool(
+            bundle_manifest and Path(bundle_manifest).exists()
+        ),
+        "bundle_directory_exists": bool(
+            bundle_directory and Path(bundle_directory).exists()
+        ),
+        "artifact_counts": {
+            "events": len(payload.get("events") or []),
+            "artifacts": len(payload.get("artifacts") or []),
+            "model_runs": len(payload.get("model_runs") or []),
+            "model_versions": len(payload.get("model_versions") or []),
+            "correction_sets": len(payload.get("correction_sets") or []),
+            "evaluation_results": len(payload.get("evaluation_results") or []),
+            "agent_plans": len(payload.get("agent_plans") or []),
+            "persisted_hotspots": len(payload.get("persisted_hotspots") or []),
+        },
+        "payload_missing_keys": missing,
+    }
+
+
+def _default_post_deploy_report_paths() -> Dict[str, Path]:
+    stamp = time.strftime("%Y%m%d-%H%M%S")
+    markdown_path = (
+        DEFAULT_POST_DEPLOY_REPORT_ROOT / f"yixiao-postdeploy-smoke-report-{stamp}.md"
+    )
+    return {
+        "markdown_path": markdown_path,
+        "json_path": markdown_path.with_suffix(".json"),
+    }
+
+
+def _normalize_post_deploy_api_base(base_url: str) -> str:
+    base = base_url.rstrip("/")
+    if base.endswith("/api"):
+        return base
+    return f"{base}/api"
+
+
+def _probe_endpoint(
+    harness: SmokeHarness,
+    *,
+    name: str,
+    method: str,
+    path: str,
+    payload: Optional[Dict[str, Any]] = None,
+    timeout: int = 20,
+    expect_json: bool = True,
+) -> Dict[str, Any]:
+    start = time.time()
+    try:
+        status, payload_data = harness.request_json_with_status(
+            method,
+            path,
+            payload=payload,
+            timeout=timeout,
+            expect_json=expect_json,
+        )
+        return {
+            "name": name,
+            "method": method,
+            "path": path,
+            "passed": status == 200,
+            "status_code": status,
+            "duration_seconds": time.time() - start,
+            "payload": payload_data if expect_json else None,
+            "raw_body": payload_data if not expect_json else None,
+        }
+    except Exception as exc:  # pragma: no cover - exercised in integration path
+        return {
+            "name": name,
+            "method": method,
+            "path": path,
+            "passed": False,
+            "status_code": None,
+            "duration_seconds": time.time() - start,
+            "error": str(exc),
+            "payload": None,
+            "raw_body": None,
+        }
+
+
+def _query_agent_action(
+    harness: SmokeHarness,
+    *,
+    workflow_id: int,
+    query: str,
+    timeout: int = 45,
+) -> Dict[str, Any]:
+    step = _probe_endpoint(
+        harness,
+        name=f"agent_query:{query}",
+        method="POST",
+        path=f"/api/workflows/{workflow_id}/agent/query",
+        payload={"query": query},
+        timeout=timeout,
+    )
+    if not step["passed"]:
+        return step
+    payload = step.get("payload") or {}
+    actions = payload.get("actions") or []
+    return {
+        "name": step["name"],
+        "passed": bool(actions),
+        "method": "POST",
+        "path": f"/api/workflows/{workflow_id}/agent/query",
+        "status_code": step["status_code"],
+        "duration_seconds": step["duration_seconds"],
+        "query": query,
+        "intent": payload.get("intent"),
+        "response": payload.get("response"),
+        "actions": [
+            {
+                "id": action.get("id"),
+                "requires_approval": action.get("requires_approval"),
+                "label": action.get("label"),
+            }
+            for action in actions
+            if isinstance(action, dict)
+        ],
+        "action_count": len(actions),
+    }
+
+
+def _expected_progress_summary() -> Dict[str, Any]:
+    return {
+        "total": 10,
+        "tracked_total": 10,
+        "ground_truth": 6,
+        "needs_proofreading": 2,
+        "missing_segmentation": 2,
+        "ignored": 0,
+        "completion_pct": 60.0,
+        "segmentation_coverage_pct": 80.0,
+    }
+
+
+def _compare_progress(
+    observed: Optional[Dict[str, Any]],
+    *,
+    expected: Dict[str, Any],
+) -> List[str]:
+    issues: List[str] = []
+    if not isinstance(observed, dict):
+        return ["progress summary missing"]
+    for key, value in expected.items():
+        if observed.get(key) != value:
+            issues.append(
+                f"summary[{key}] expected {value!r}, got {observed.get(key)!r}"
+            )
+    return issues
+
+
+def _build_post_deploy_report(args: argparse.Namespace) -> Dict[str, Any]:
+    start = time.time()
+    api_base = _normalize_post_deploy_api_base(args.base_url)
+    public_root = args.base_url.rstrip("/")
+    harness = SmokeHarness(base_url=api_base, verbose=args.verbose)
+    checks: List[Dict[str, Any]] = []
+    caveats: List[str] = []
+    report: Dict[str, Any] = {
+        "generated_at_unix": time.time(),
+        "base_url": api_base,
+        "public_root_url": public_root,
+        "report_type": "post_deploy_readonly",
+        "checks": checks,
+        "caveats": caveats,
+        "agent_queries": [],
+        "public_endpoints": [],
+        "duration_seconds": 0.0,
+    }
+
+    endpoint_checks: List[Dict[str, Any]] = []
+    report["public_endpoints"] = endpoint_checks
+
+    current = _probe_endpoint(
+        harness, name="workflow_current", method="GET", path="/api/workflows/current"
+    )
+    endpoint_checks.append(current)
+    workflow_payload = current.get("payload") or {}
+    current_workflow = (
+        workflow_payload.get("workflow") if isinstance(workflow_payload, dict) else None
+    )
+    if not isinstance(current_workflow, dict):
+        checks.append(
+            {
+                "name": "workflow_current_payload_shape",
+                "passed": False,
+                "error": "GET /api/workflows/current did not return workflow object",
+            }
+        )
+        return {
+            **report,
+            "passed": False,
+            "checks": checks,
+            "duration_seconds": time.time() - start,
+        }
+
+    workflow_id = current_workflow.get("id")
+    if args.workflow_id is not None:
+        workflow_id = args.workflow_id
+    if workflow_id is None:
+        checks.append(
+            {
+                "name": "workflow_id_resolved",
+                "passed": False,
+                "error": "workflow_id unavailable",
+            }
+        )
+        report["passed"] = False
+        return {**report, "checks": checks, "duration_seconds": time.time() - start}
+    workflow_id = int(workflow_id)
+
+    if workflow_id != POST_DEPLOY_WORKFLOW_ID:
+        caveats.append(
+            f"Expected workflow id {POST_DEPLOY_WORKFLOW_ID} for the post-deploy fixture, "
+            f"but active workflow is {workflow_id}"
+        )
+
+    checks.append({"name": "workflow_id", "passed": True, "workflow_id": workflow_id})
+    report["workflow_id"] = workflow_id
+    report["workflow_title"] = current_workflow.get("title")
+    report["project_root_detected"] = current_workflow.get("dataset_path")
+    report["expected_project_root"] = POST_DEPLOY_PROJECT_ROOT
+
+    if report["project_root_detected"] != POST_DEPLOY_PROJECT_ROOT:
+        caveats.append(
+            "Detected workflow dataset_path differs from expected mounted Yixiao fixture path."
+        )
+
+    project_progress = _probe_endpoint(
+        harness,
+        name="project_progress",
+        method="GET",
+        path=f"/api/workflows/{workflow_id}/project-progress",
+    )
+    endpoint_checks.append(project_progress)
+    summary = None
+    if project_progress["passed"]:
+        summary = project_progress.get("payload", {}).get("summary")
+        issue_lines = _compare_progress(summary, expected=_expected_progress_summary())
+        if issue_lines:
+            checks.append(
+                {"name": "progress_counts", "passed": False, "issues": issue_lines}
+            )
+            caveats.append("Progress counts are not the expected 6/2/2 split.")
+        else:
+            checks.append(
+                {"name": "progress_counts", "passed": True, "summary": summary}
+            )
+    else:
+        checks.append(
+            {
+                "name": "progress_counts",
+                "passed": False,
+                "error": project_progress.get("error"),
+            }
+        )
+
+    memory = _probe_endpoint(
+        harness,
+        name="workflow_memory",
+        method="GET",
+        path=f"/api/workflows/{workflow_id}/memory",
+    )
+    endpoint_checks.append(memory)
+    if memory["passed"] and isinstance(memory.get("payload"), dict):
+        checks.append(
+            {
+                "name": "memory_schema_version",
+                "passed": memory["payload"].get("schema_version")
+                == "pytc-project-memory/v1",
+                "schema_version": memory["payload"].get("schema_version"),
+            }
+        )
+    else:
+        checks.append(
+            {
+                "name": "memory_schema_version",
+                "passed": False,
+                "error": memory.get("error"),
+            }
+        )
+
+    overview = _probe_endpoint(
+        harness,
+        name="workflow_overview",
+        method="GET",
+        path=f"/api/workflows/{workflow_id}/overview",
+    )
+    endpoint_checks.append(overview)
+
+    readiness = _run_readiness_check(harness, workflow_id=workflow_id)
+    checks.append(readiness)
+    report["readiness"] = readiness
+    if readiness.get("passed"):
+        checks.append(
+            {
+                "name": "case_study_readiness_gate",
+                "passed": bool(readiness.get("ready_for_case_study")),
+                "ready_for_case_study": readiness.get("ready_for_case_study"),
+                "next_required_items": readiness.get("next_required_items"),
+            }
+        )
+        if not readiness.get("ready_for_case_study"):
+            caveats.append("Case-study readiness gate is not yet met.")
+
+    export_sanity = _run_export_bundle_check(harness, workflow_id=workflow_id)
+    checks.append(export_sanity)
+    report["export_bundle"] = export_sanity
+
+    suggestions = _probe_endpoint(
+        harness,
+        name="project_suggestions",
+        method="GET",
+        path="/files/project-suggestions",
+    )
+    endpoint_checks.append(suggestions)
+    suggestion_error: Optional[str] = None
+    suggestion = None
+    if suggestions["passed"] and isinstance(suggestions.get("payload"), list):
+        suggestion = _find_yixiao_suggestion(suggestions["payload"])
+        if suggestion:
+            checks.append(
+                {
+                    "name": "yixiao_suggestion",
+                    "passed": bool(suggestion),
+                    "mounted": suggestion.get("already_mounted"),
+                    "directory_path": suggestion.get("directory_path"),
+                }
+            )
+            if suggestion.get("already_mounted") is not True:
+                caveats.append("Yixiao suggestion exists but is not currently mounted.")
+        else:
+            suggestion_error = (
+                "Yixiao suggestion not found in files/project-suggestions"
+            )
+    else:
+        suggestion_error = suggestion_error or "Could not load project-suggestions"
+    if suggestion_error:
+        checks.append(
+            {"name": "yixiao_suggestion", "passed": False, "error": suggestion_error}
+        )
+
+    visualization_payload = None
+    if summary and summary.get("total") == 10:
+        visualization_payload = {
+            "workflow_id": workflow_id,
+            "image": f"{POST_DEPLOY_PROJECT_ROOT}/data/raw/1/1-xri_raw.tif",
+            "label": f"{POST_DEPLOY_PROJECT_ROOT}/data/seg/1/1-mask.tif",
+            "scales": [40, 16.3, 16.3],
+        }
+    visualization_steps: List[Dict[str, Any]] = []
+    create_viewer = _probe_endpoint(
+        harness,
+        name="neuroglancer_create",
+        method="POST",
+        path="/neuroglancer",
+        payload=visualization_payload or {},
+        timeout=30,
+    )
+    visualization_steps.append(create_viewer)
+    public_viewer_url = ""
+    if create_viewer.get("passed") and isinstance(create_viewer.get("payload"), dict):
+        public_viewer_url = str(
+            create_viewer["payload"].get("url")
+            or create_viewer["payload"].get("neuroglancer_url")
+            or ""
+        ).strip()
+    if public_viewer_url:
+        public_path = urlsplit(public_viewer_url).path or "/neuroglancer/"
+        public_viewer = _probe_endpoint(
+            SmokeHarness(base_url=public_root, verbose=args.verbose),
+            name="neuroglancer_public_viewer",
+            method="GET",
+            path=public_path,
+            timeout=20,
+            expect_json=False,
+        )
+        public_viewer["url"] = public_viewer_url
+        visualization_steps.append(public_viewer)
+    report["visualization"] = visualization_steps
+    for candidate in visualization_steps:
+        if (
+            candidate.get("name") == "neuroglancer_public_viewer"
+            and candidate.get("status_code") == 200
+        ):
+            break
+    else:
+        caveats.append(
+            "Public visualization viewer did not return a successful response; "
+            "check demo.seg.bio/neuroglancer runtime health and viewer retention."
+        )
+
+    agent_queries = [
+        "what project are we looking at?",
+        "train on the fully good masks to segment the image-only volumes",
+        "what should I proofread next?",
+        "Can we run inference on image-only targets next?",
+    ]
+    agent_checks: List[Dict[str, Any]] = []
+    for query in agent_queries:
+        agent_checks.append(
+            _query_agent_action(
+                harness,
+                workflow_id=workflow_id,
+                query=query,
+                timeout=args.agent_timeout,
+            )
+        )
+    report["agent_queries"] = agent_checks
+    training_query = next(
+        (row for row in agent_checks if row.get("query") == agent_queries[1]), {}
+    )
+    if training_query.get("passed") and any(
+        action.get("id") == "start-training"
+        for action in training_query.get("actions", [])
+    ):
+        checks.append(
+            {
+                "name": "training_action_proposal",
+                "passed": True,
+                "action_ids": [a.get("id") for a in training_query.get("actions", [])],
+            }
+        )
+    else:
+        checks.append(
+            {
+                "name": "training_action_proposal",
+                "passed": False,
+                "error": "start-training action not returned for training prompt",
+            }
+        )
+        caveats.append(
+            "Training action proposal is not currently returning expected `start-training` behavior."
+        )
+    proofread_query = next(
+        (row for row in agent_checks if row.get("query") == agent_queries[2]), {}
+    )
+    if proofread_query.get("passed") and any(
+        action.get("id") == "start-proofreading"
+        for action in proofread_query.get("actions", [])
+    ):
+        checks.append(
+            {
+                "name": "proofread_action_proposal",
+                "passed": True,
+                "action_ids": [a.get("id") for a in proofread_query.get("actions", [])],
+            }
+        )
+    else:
+        checks.append(
+            {
+                "name": "proofread_action_proposal",
+                "passed": False,
+                "error": "start-proofreading action not returned",
+            }
+        )
+        caveats.append(
+            "Proofread action proposal is weak or not returning expected identifier."
+        )
+    inference_query = next(
+        (row for row in agent_checks if row.get("query") == agent_queries[3]), {}
+    )
+    if inference_query.get("passed") and (
+        any(
+            action.get("id") == "open-inference"
+            for action in inference_query.get("actions", [])
+        )
+        or any(
+            action.get("id") == "start-inference"
+            for action in inference_query.get("actions", [])
+        )
+    ):
+        checks.append(
+            {
+                "name": "inference_action_proposal",
+                "passed": True,
+                "action_ids": [a.get("id") for a in inference_query.get("actions", [])],
+            }
+        )
+    else:
+        checks.append(
+            {
+                "name": "inference_action_proposal",
+                "passed": False,
+                "error": "Inference proposal action not returned",
+            }
+        )
+        caveats.append(
+            "Inference proposal may need checkpoint/agent sequencing before action can be launched."
+        )
+
+    report["checks"] = checks
+    report["caveats"] = caveats
+    participant_start_ready = all(
+        bool(check.get("passed"))
+        for check in checks
+        if check.get("name")
+        not in {
+            "case_study_readiness_gate",
+        }
+    ) and any(
+        row.get("name") == "neuroglancer_public_viewer" and row.get("passed")
+        for row in visualization_steps
+    )
+    report["participant_start_ready"] = participant_start_ready
+    report["passed"] = participant_start_ready
+    report["duration_seconds"] = time.time() - start
+    return report
+
+
+def _write_post_deploy_report_markdown(report: Dict[str, Any], path: Path) -> None:
+    public_endpoints = report.get("public_endpoints") or []
+    checks = report.get("checks") or []
+    readiness = report.get("readiness") or {}
+    viz = report.get("visualization") or []
+    agent_queries = report.get("agent_queries") or []
+    progress = None
+    for check in checks:
+        if check.get("name") == "progress_counts":
+            progress = check.get("summary") or check.get("issues")
+            break
+
+    lines = [
+        "# Yixiao Post-Deploy Smoke Report",
+        "",
+        f"- Timestamp: {time.strftime('%Y-%m-%d %H:%M:%S UTC', time.gmtime(report.get('generated_at_unix', 0)))}",
+        f"- Report type: {report.get('report_type')}",
+        f"- Public root: `{report.get('public_root_url')}`",
+        f"- Workflow endpoint API base: `{report.get('base_url')}`",
+        f"- Workflow id (active): `{report.get('workflow_id')}`",
+        f"- Workflow title: `{report.get('workflow_title')}`",
+        f"- Workflow dataset path: `{report.get('project_root_detected')}`",
+        f"- Expected dataset path: `{report.get('expected_project_root')}`",
+        "",
+        f"- Participant starting fixture: {'READY' if report.get('participant_start_ready') else 'NOT READY'}",
+        f"- Full case-study completion gate: {'PASS' if readiness.get('ready_for_case_study') else 'NOT YET'}",
+    ]
+
+    if readiness:
+        lines.extend(
+            [
+                "",
+                "## Case-Study Readiness",
+                f"- Ready flag: `{readiness.get('ready_for_case_study')}`",
+                f"- Completed count: `{readiness.get('completed_count')}`",
+                f"- Total count: `{readiness.get('total_count')}`",
+                f"- Next required items: {', '.join(readiness.get('next_required_items') or ['(none)'])}",
+            ]
+        )
+
+    lines.extend(
+        [
+            "",
+            "## Progress Summary",
+            f"- {progress if progress is not None else 'Not available'}",
+        ]
+    )
+
+    lines.extend(["", "## Public Endpoint Status", ""])
+    for row in public_endpoints:
+        status = row.get("status_code")
+        lines.append(
+            f"- `{row.get('name')}` `{row.get('method')}` `{row.get('path')}` -> {status} ({'PASS' if row.get('passed') else 'FAIL'})"
+        )
+
+    lines.extend(["", "## Visualization Probe", ""])
+    for row in viz:
+        target = row.get("url") or row.get("path")
+        lines.append(
+            f"- `{row.get('name')}` `{target}` -> {row.get('status_code')} ({'PASS' if row.get('passed') else 'FAIL'})"
+        )
+    lines.append("")
+    lines.extend(["", "## Agent Proposal Probes", ""])
+    for row in agent_queries:
+        lines.append(
+            f"- Q: `{row.get('query')}` -> `{row.get('intent')}` / "
+            f"actions={row.get('action_count')} status={row.get('status_code')}"
+        )
+        if row.get("actions"):
+            lines.append(
+                "  - "
+                + ", ".join(
+                    [
+                        f"{action.get('id')} (approval={action.get('requires_approval')})"
+                        for action in row.get("actions")
+                        if isinstance(action, dict)
+                    ]
+                )
+            )
+        if row.get("error"):
+            lines.append(f"  - error: `{row.get('error')}`")
+
+    if report.get("caveats"):
+        lines.extend(["", "## Known Risks", ""])
+        for caveat in report["caveats"]:
+            lines.append(f"- {caveat}")
+
+    path.write_text("\n".join(lines), encoding="utf-8")
+
+
+def _volume_id(volume: Dict[str, Any]) -> str:
+    return str(volume.get("id") or "").strip()
+
+
+def _volume_by_id(manifest: Dict[str, Any], volume_id: str) -> Dict[str, Any]:
+    for volume in _manifest_volumes(manifest):
+        if _volume_id(volume) == volume_id:
+            return volume
+    raise SmokeFailure(f"Manifest does not contain volume id {volume_id!r}.")
+
+
+def _path_under(path_value: Path, root_value: Path) -> bool:
+    try:
+        path_value.resolve().relative_to(root_value.resolve())
+        return True
+    except ValueError:
+        return False
+
+
+def _withheld_ground_truth_path(
+    *,
+    project_root: Path,
+    holdout_root: Path,
+    volume: Dict[str, Any],
+) -> Path:
+    volume_id = _volume_id(volume)
+    configured = volume.get("withheld_ground_truth")
+    if configured:
+        ground_truth = Path(str(configured)).expanduser()
+    else:
+        ground_truth = holdout_root / f"{volume_id}-mask.tif"
+    if not ground_truth.is_absolute():
+        ground_truth = holdout_root / ground_truth
+    ground_truth = ground_truth.resolve()
+    if not ground_truth.exists():
+        raise SmokeFailure(
+            f"Missing withheld ground truth for {volume_id}: {ground_truth}"
+        )
+    if _path_under(ground_truth, project_root):
+        raise SmokeFailure(
+            f"Withheld ground truth for {volume_id} must live outside the mounted "
+            f"project root; got {ground_truth}"
+        )
+    mounted_segmentation = volume.get("segmentation")
+    if mounted_segmentation:
+        mounted_path = Path(str(mounted_segmentation))
+        if not mounted_path.is_absolute():
+            mounted_path = project_root / mounted_path
+        if mounted_path.resolve() == ground_truth:
+            raise SmokeFailure(
+                f"Withheld ground truth for {volume_id} resolves to the mounted "
+                "segmentation path."
+            )
+    return ground_truth
+
+
+def _run_closed_loop_rehearsal_target(
+    *,
+    output_dir: Path,
+    image_path: Path,
+    ground_truth_path: Path,
+    crop: Optional[str],
+    training_iterations: Optional[int] = None,
+    inference_iterations: Optional[int] = None,
+) -> Dict[str, Any]:
+    from scripts.run_closed_loop_smoke import run_closed_loop_smoke
+
+    return run_closed_loop_smoke(
+        output_dir=output_dir,
+        image_path=str(image_path),
+        mask_path=str(ground_truth_path),
+        ground_truth_path=str(ground_truth_path),
+        require_explicit_ground_truth=True,
+        training_iterations=training_iterations,
+        inference_iterations=inference_iterations,
+        crop=crop,
+    )
+
+
+def _build_closed_loop_rehearsal_report(args: argparse.Namespace) -> Dict[str, Any]:
+    start = time.time()
+    project_root = Path(args.project_root).expanduser().resolve()
+    holdout_root = Path(args.holdout_root).expanduser().resolve()
+    manifest = _load_manifest(project_root)
+    report_path = Path(args.report).resolve()
+    output_root = report_path.with_suffix("")
+    output_root.mkdir(parents=True, exist_ok=True)
+    target_reports: List[Dict[str, Any]] = []
+    caveats = [
+        "This is a local rehearsal: it validates closed-loop evidence/evaluation wiring "
+        "with explicit withheld masks, but does not launch GPU training or inference.",
+        "Derived baseline/candidate masks are generated from withheld truth unless real "
+        "prediction paths are supplied in a future rehearsal.",
+    ]
+
+    for target_id in IMAGE_ONLY_TARGET_IDS:
+        image_path = Path("")
+        ground_truth_path = Path("")
+        target_output_dir = output_root / target_id
+        try:
+            volume = _volume_by_id(manifest, target_id)
+            if volume.get("status") != "missing_segmentation":
+                raise SmokeFailure(
+                    f"Closed-loop target {target_id} must remain image-only; "
+                    f"manifest status is {volume.get('status')!r}."
+                )
+            if volume.get("segmentation"):
+                raise SmokeFailure(
+                    f"Closed-loop target {target_id} unexpectedly has a mounted segmentation."
+                )
+            image_path = Path(_rel_to_abs(project_root, volume.get("image")) or "")
+            if not image_path.exists():
+                raise SmokeFailure(f"Missing image for {target_id}: {image_path}")
+            ground_truth_path = _withheld_ground_truth_path(
+                project_root=project_root,
+                holdout_root=holdout_root,
+                volume=volume,
+            )
+            closed_loop = _run_closed_loop_rehearsal_target(
+                output_dir=target_output_dir,
+                image_path=image_path,
+                ground_truth_path=ground_truth_path,
+                crop=args.closed_loop_crop,
+                training_iterations=args.closed_loop_training_iterations,
+                inference_iterations=args.closed_loop_inference_iterations,
+            )
+        except Exception as exc:
+            target_reports.append(
+                {
+                    "target_id": target_id,
+                    "passed": False,
+                    "error": str(exc),
+                    "image_path": str(image_path),
+                    "ground_truth_path": str(ground_truth_path),
+                    "output_dir": str(target_output_dir),
+                }
+            )
+            continue
+        target_reports.append(
+            {
+                "target_id": target_id,
+                "passed": bool(closed_loop.get("passed", True)),
+                "image_path": str(image_path),
+                "ground_truth_path": str(ground_truth_path),
+                "output_dir": str(target_output_dir),
+                "artifact_mode": closed_loop.get("artifact_mode"),
+                "source_data": closed_loop.get("source_data"),
+                "runtime_overrides": closed_loop.get("runtime_overrides"),
+                "runtime_checkpoints": closed_loop.get("runtime_checkpoints"),
+                "closed_loop_report": closed_loop,
+            }
+        )
+
+    return {
+        "passed": all(item.get("passed") for item in target_reports),
+        "generated_at_unix": time.time(),
+        "project_root": str(project_root),
+        "holdout_root": str(holdout_root),
+        "runtime_overrides": {
+            "training_iterations": args.closed_loop_training_iterations,
+            "inference_iterations": args.closed_loop_inference_iterations,
+        },
+        "target_ids": list(IMAGE_ONLY_TARGET_IDS),
+        "crop": args.closed_loop_crop,
+        "targets": target_reports,
+        "caveats": caveats,
+        "duration_seconds": time.time() - start,
+    }
+
+
+def _build_pre_demo_gate_report(args: argparse.Namespace) -> Dict[str, Any]:
+    gate_start = time.time()
+    project_root = Path(args.project_root).expanduser().resolve()
+    report_dir = Path(args.report).resolve().parent
+    report_dir.mkdir(parents=True, exist_ok=True)
+    report_stem = Path(args.report).stem
+    baseline_report_path = report_dir / f"{report_stem}.baseline-smoke.json"
+    promotion_report_path = report_dir / f"{report_stem}.promotion-smoke.json"
+    restore_report_path = report_dir / f"{report_stem}.restore-smoke.json"
+    steps: List[Dict[str, Any]] = []
+
+    baseline = _run_smoke_step(
+        _normalize_smoke_args(
+            argparse.Namespace(
+                **{
+                    **vars(args),
+                    "prepare_live": True,
+                    "exercise_promotion": False,
+                    "workflow_id": None,
+                    "reset_fixture": args.reset_fixture,
+                }
+            )
+        ),
+        step_name="normal_smoke",
+        report_path=baseline_report_path,
+    )
+    steps.append(baseline)
+
+    workflow_id = baseline.get("workflow_id")
+    if workflow_id is None and baseline.get("report"):
+        workflow_id = baseline.get("report", {}).get("workflow_id")
+
+    if workflow_id is not None:
+        promotion = _run_smoke_step(
+            argparse.Namespace(
+                **{
+                    **vars(args),
+                    "prepare_live": False,
+                    "exercise_promotion": True,
+                    "workflow_id": workflow_id,
+                    "reset_workspace": False,
+                    "mount_project": False,
+                    "reset_workflow": False,
+                    "reset_fixture": False,
+                }
+            ),
+            step_name="promotion_roundtrip",
+            report_path=promotion_report_path,
+        )
+        steps.append(promotion)
+
+    restore = _run_smoke_step(
+        _normalize_smoke_args(
+            argparse.Namespace(
+                **{
+                    **vars(args),
+                    "prepare_live": True,
+                    "exercise_promotion": False,
+                    "workflow_id": None,
+                    "reset_fixture": False,
+                }
+            )
+        ),
+        step_name="restore_state",
+        report_path=restore_report_path,
+    )
+    steps.append(restore)
+
+    restore_workflow_id = restore.get("workflow_id")
+    if restore_workflow_id is None and restore.get("report"):
+        restore_workflow_id = restore.get("report", {}).get("workflow_id")
+
+    if not args.skip_readiness_check and restore_workflow_id:
+        harness = SmokeHarness(base_url=args.base_url, verbose=args.verbose)
+        checks = _run_readiness_check(harness, workflow_id=restore_workflow_id)
+        checks["name"] = "readiness_check"
+        steps.append(checks)
+
+    if not args.skip_export_check and restore_workflow_id:
+        harness = SmokeHarness(base_url=args.base_url, verbose=args.verbose)
+        checks = _run_export_bundle_check(harness, workflow_id=restore_workflow_id)
+        checks["name"] = "export_sanity"
+        steps.append(checks)
+
+    passed = all(step.get("passed", False) for step in steps[:3])
+    caveats: List[str] = []
+
+    if not args.skip_readiness_check:
+        if not restore_workflow_id:
+            caveats.append(
+                "readiness check could not run because restore step did not return a workflow id"
+            )
+            passed = False
+        else:
+            readiness_step = next(
+                (s for s in steps if s.get("name") == "readiness_check"), None
+            )
+            if readiness_step is None:
+                caveats.append("readiness check was requested but not executed")
+                passed = False
+            elif readiness_step.get("error"):
+                passed = False
+                caveats.append(f"readiness check failed: {readiness_step.get('error')}")
+            elif readiness_step.get("payload_missing_keys"):
+                passed = False
+                caveats.append("readiness response missing required fields")
+            elif not readiness_step.get("ready_for_case_study", False):
+                caveats.append(
+                    "case-study readiness is not fully met; next items: "
+                    + ", ".join(readiness_step.get("next_required_items") or ["(none)"])
+                )
+
+    if not args.skip_export_check:
+        if not restore_workflow_id:
+            caveats.append(
+                "export sanity check could not run because restore step did not return a workflow id"
+            )
+            passed = False
+        else:
+            export_step = next(
+                (s for s in steps if s.get("name") == "export_sanity"), None
+            )
+            if export_step is None:
+                caveats.append("export sanity check was requested but not executed")
+                passed = False
+            elif export_step.get("error"):
+                passed = False
+                caveats.append(
+                    f"export sanity check failed: {export_step.get('error')}"
+                )
+            elif export_step.get("payload_missing_keys"):
+                passed = False
+                caveats.append("export payload missing required fields")
+            elif not export_step.get("bundle_manifest_exists", False):
+                passed = False
+                caveats.append("export bundle manifest does not exist on disk")
+
+    return {
+        "passed": passed,
+        "generated_at_unix": time.time(),
+        "base_url": args.base_url,
+        "project_root": str(project_root),
+        "report_directory": str(report_dir),
+        "steps": steps,
+        "caveats": caveats,
+        "duration_seconds": time.time() - gate_start,
+    }
+
+
+def _exercise_proofreading_promotion(
+    harness: SmokeHarness,
+    *,
+    workflow_id: int,
+    manifest: Dict[str, Any],
+    agent_timeout: int,
+    skip_agent: bool,
+) -> Dict[str, Any]:
+    """Promote one draft mask and verify memory/proposal state follows it."""
+
+    draft_volume = _first_volume_with_status(manifest, "needs_proofreading")
+    volume_id = str(draft_volume.get("image") or "")
+    promotion = harness.request_json(
+        "POST",
+        f"/api/workflows/{workflow_id}/project-progress/volume-status",
+        payload={
+            "volume_id": volume_id,
+            "status": "ground_truth",
+            "note": "Smoke-test promotion: draft mask accepted as proofread ground truth.",
+        },
+        timeout=90,
+    )
+    promoted_expected = {
+        "total": 10,
+        "tracked_total": 10,
+        "ground_truth": 7,
+        "needs_proofreading": 1,
+        "missing_segmentation": 2,
+        "ignored": 0,
+    }
+    _assert_progress_counts(
+        harness,
+        promotion,
+        promoted_expected,
+        expected_completion_pct=70.0,
+        expected_segmentation_coverage_pct=80.0,
+    )
+
+    memory = harness.request_json(
+        "GET",
+        f"/api/workflows/{workflow_id}/memory",
+        timeout=30,
+    )
+    items = (memory.get("volume_states") or {}).get("items") or []
+    promoted = next(
+        (item for item in items if item.get("volume_id") == volume_id), None
+    )
+    harness.check("promoted volume appears in memory", promoted is not None, items)
+    if promoted:
+        harness.check(
+            "promoted volume legacy status",
+            promoted.get("status") == "ground_truth",
+            promoted,
+        )
+        harness.check(
+            "promoted volume canonical status",
+            promoted.get("canonical_status") == "proofread_ground_truth",
+            promoted,
+        )
+
+    training_answer = None
+    if not skip_agent:
+        training_answer = harness.request_json(
+            "POST",
+            f"/api/workflows/{workflow_id}/agent/query",
+            payload={
+                "query": "train on the fully good masks to segment the image-only volumes"
+            },
+            timeout=agent_timeout,
+        )
+        _assert_agent_training_response(
+            harness,
+            training_answer,
+            expected_train_count=7,
+            expected_review_count=1,
+            expected_target_count=2,
+        )
+
+    return {
+        "promoted_volume_id": volume_id,
+        "progress_summary": promotion.get("summary"),
+        "memory_promoted_volume": promoted,
+        "agent_training_response": (training_answer or {}).get("response"),
+    }
+
+
+def run(args: argparse.Namespace) -> Dict[str, Any]:
+    project_root = Path(args.project_root).expanduser().resolve()
+    manifest = _load_manifest(project_root)
+    volumes = _manifest_volumes(manifest)
+    counts = _status_counts(volumes)
+    harness = SmokeHarness(base_url=args.base_url, verbose=args.verbose)
+
+    expected_counts = {
+        "total": 10,
+        "tracked_total": 10,
+        "ground_truth": 6,
+        "needs_proofreading": 2,
+        "missing_segmentation": 2,
+        "ignored": 0,
+    }
+
+    harness.check("project root exists", project_root.is_dir(), str(project_root))
+    harness.check("manifest volume count", len(volumes) == 10, len(volumes))
+    harness.check("manifest GT count", counts.get("ground_truth") == 6, counts)
+    harness.check("manifest draft count", counts.get("needs_proofreading") == 2, counts)
+    harness.check(
+        "manifest image-only count", counts.get("missing_segmentation") == 2, counts
+    )
+
+    if args.reset_fixture:
+        reset_script = project_root / "reset_to_initial.sh"
+        harness.check("reset script exists", reset_script.exists(), str(reset_script))
+        subprocess.run([str(reset_script)], check=True)
+
+    health = harness.request_json("GET", "/health", timeout=8)
+    harness.check("backend health", health.get("status") == "ok", health)
+
+    if args.reset_workspace:
+        reset = harness.request_json("DELETE", "/files/workspace", timeout=30)
+        harness.check(
+            "workspace reset", reset.get("message") == "Workspace reset", reset
+        )
+
+    if args.mount_project:
+        mount = harness.request_json(
+            "POST",
+            "/files/mount",
+            payload={
+                "directory_path": str(project_root),
+                "mount_name": PROJECT_TITLE,
+            },
+            timeout=90,
+        )
+        harness.check("project mounted", bool(mount.get("mounted_root_id")), mount)
+
+    suggestions = harness.request_json("GET", "/files/project-suggestions", timeout=90)
+    suggestion = _find_yixiao_suggestion(suggestions)
+    harness.check("Yixiao suggestion exists", suggestion is not None, suggestions)
+    assert suggestion is not None
+    harness.check(
+        "Yixiao suggestion mounted",
+        suggestion.get("already_mounted") is True,
+        suggestion,
+    )
+    _assert_profile(harness, suggestion)
+
+    workflow_id = args.workflow_id
+    if args.reset_workflow or workflow_id is None:
+        created = harness.request_json(
+            "POST",
+            "/api/workflows/current/reset",
+            payload={
+                "title": PROJECT_TITLE,
+                "metadata": {"created_from": "yixiao_case_study_smoke"},
+            },
+            timeout=30,
+        )
+        workflow_id = int((created.get("workflow") or {}).get("id"))
+        harness.check("workflow reset created id", workflow_id > 0, created)
+
+    patch_payload = _workflow_patch_payload(project_root, manifest)
+    workflow = harness.request_json(
+        "PATCH",
+        f"/api/workflows/{workflow_id}",
+        payload=patch_payload,
+        timeout=30,
+    )
+    harness.check("workflow title", workflow.get("title") == PROJECT_TITLE, workflow)
+    harness.check(
+        "workflow dataset", workflow.get("dataset_path") == str(project_root), workflow
+    )
+    harness.check("workflow stage", workflow.get("stage") == "visualization", workflow)
+
+    progress = harness.request_json(
+        "GET", f"/api/workflows/{workflow_id}/project-progress", timeout=90
+    )
+    _assert_progress_counts(harness, progress, expected_counts)
+
+    memory = harness.request_json(
+        "GET", f"/api/workflows/{workflow_id}/memory", timeout=30
+    )
+    facts = memory.get("project_facts") or {}
+    context = facts.get("project_context") or {}
+    summary = (memory.get("volume_states") or {}).get("summary") or {}
+    harness.check(
+        "memory schema",
+        memory.get("schema_version") == "pytc-project-memory/v1",
+        memory,
+    )
+    harness.check(
+        "memory task preset",
+        (facts.get("task_family_preset") or {}).get("id") == "tapereader_xri_fiber",
+        facts,
+    )
+    harness.check(
+        "memory modality", "XRI" in str(context.get("imaging_modality")), context
+    )
+    harness.check("memory tracked volumes", summary.get("tracked_total") == 10, summary)
+
+    first = _first_volume_with_label(manifest)
+    viewer = harness.request_json(
+        "POST",
+        "/neuroglancer",
+        payload={
+            "image": _rel_to_abs(project_root, first.get("image")),
+            "label": _rel_to_abs(project_root, first.get("segmentation")),
+            "scales": (manifest.get("voxel_size") or {}).get("zyx_nm")
+            or [40, 16.3, 16.3],
+            "workflow_id": workflow_id,
+        },
+        timeout=120,
+    )
+    harness.check("viewer url", "/neuroglancer/v/" in str(viewer.get("url")), viewer)
+    pair_discovery = viewer.get("pair_discovery") or {}
+    harness.check(
+        "viewer pair count", pair_discovery.get("pair_count") == 1, pair_discovery
+    )
+    harness.check(
+        "viewer unpaired images",
+        pair_discovery.get("unpaired_images") == [],
+        pair_discovery,
+    )
+    harness.check(
+        "viewer unpaired labels",
+        pair_discovery.get("unpaired_labels") == [],
+        pair_discovery,
+    )
+
+    if not args.skip_agent:
+        project_answer = harness.request_json(
+            "POST",
+            f"/api/workflows/{workflow_id}/agent/query",
+            payload={"query": "what project are we looking at?"},
+            timeout=args.agent_timeout,
+        )
+        _assert_agent_project_response(harness, project_answer)
+
+        training_answer = harness.request_json(
+            "POST",
+            f"/api/workflows/{workflow_id}/agent/query",
+            payload={
+                "query": "train on the fully good masks to segment the image-only volumes"
+            },
+            timeout=args.agent_timeout,
+        )
+        _assert_agent_training_response(harness, training_answer)
+    else:
+        project_answer = None
+        training_answer = None
+
+    promotion_result = None
+    if args.exercise_promotion:
+        promotion_result = _exercise_proofreading_promotion(
+            harness,
+            workflow_id=workflow_id,
+            manifest=manifest,
+            agent_timeout=args.agent_timeout,
+            skip_agent=args.skip_agent,
+        )
+
+    report = {
+        "passed": True,
+        "generated_at_unix": time.time(),
+        "base_url": args.base_url,
+        "project_root": str(project_root),
+        "workflow_id": workflow_id,
+        "viewer_url": viewer.get("url"),
+        "progress_summary": progress.get("summary"),
+        "memory_summary": summary,
+        "promotion_result": promotion_result,
+        "agent_project_response": (project_answer or {}).get("response"),
+        "agent_training_response": (training_answer or {}).get("response"),
+        "checks": harness.checks,
+    }
+    return report
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--base-url", default=DEFAULT_BASE_URL)
+    parser.add_argument("--project-root", default=str(DEFAULT_PROJECT_ROOT))
+    parser.add_argument("--holdout-root", default=str(DEFAULT_HOLDOUT_ROOT))
+    parser.add_argument("--workflow-id", type=int, default=None)
+    parser.add_argument("--report", default=str(DEFAULT_REPORT_PATH))
+    parser.add_argument("--agent-timeout", type=int, default=45)
+    parser.add_argument(
+        "--closed-loop-rehearsal",
+        action="store_true",
+        help=(
+            "Run local closed-loop evidence/evaluation rehearsal on image-only "
+            "targets using explicit withheld masks. Does not mutate the live app."
+        ),
+    )
+    parser.add_argument(
+        "--closed-loop-crop",
+        default="0:8,0:128,0:128",
+        help=(
+            "Crop used for closed-loop rehearsal, e.g. '0:8,0:128,0:128'. "
+            "Use an empty string to load full volumes."
+        ),
+    )
+    parser.add_argument(
+        "--closed-loop-training-iterations",
+        type=int,
+        default=2,
+        help=(
+            "Training iterations to use for dry-run closed-loop rehearsal evidence "
+            "steps. Defaults to a small value suitable for operator checks."
+        ),
+    )
+    parser.add_argument(
+        "--closed-loop-inference-iterations",
+        type=int,
+        default=1,
+        help=(
+            "Inference iterations to use for dry-run closed-loop rehearsal evidence "
+            "steps. Defaults to a small value suitable for operator checks."
+        ),
+    )
+    parser.add_argument(
+        "--pre-demo-gate",
+        action="store_true",
+        help="Run normal smoke + promotion roundtrip + restore, with optional readiness/export checks.",
+    )
+    parser.add_argument(
+        "--post-deploy",
+        action="store_true",
+        help=(
+            "Run a read-only public post-deploy validation sweep for workflow "
+            "state, endpoint health, and dry-run proposal probes."
+        ),
+    )
+    parser.add_argument(
+        "--skip-readiness-check",
+        action="store_true",
+        help="Skip lightweight readiness endpoint check in pre-demo gate mode.",
+    )
+    parser.add_argument(
+        "--skip-export-check",
+        action="store_true",
+        help="Skip lightweight export bundle check in pre-demo gate mode.",
+    )
+    parser.add_argument("--reset-fixture", action="store_true")
+    parser.add_argument("--reset-workspace", action="store_true")
+    parser.add_argument("--mount-project", action="store_true")
+    parser.add_argument("--reset-workflow", action="store_true")
+    parser.add_argument(
+        "--exercise-promotion",
+        action="store_true",
+        help="Promote one draft mask to ground truth and verify progress/memory/training update.",
+    )
+    parser.add_argument(
+        "--prepare-live",
+        action="store_true",
+        help="Reset indexed workspace, mount the Yixiao project, and create a fresh workflow.",
+    )
+    parser.add_argument("--skip-agent", action="store_true")
+    parser.add_argument("--verbose", action="store_true")
+    args = parser.parse_args()
+
+    if args.pre_demo_gate and args.report == str(DEFAULT_REPORT_PATH):
+        args.report = str(DEFAULT_PRE_DEMO_GATE_REPORT_PATH)
+    if args.post_deploy and args.report == str(DEFAULT_REPORT_PATH):
+        default_paths = _default_post_deploy_report_paths()
+        args.report = str(default_paths["json_path"])
+    if args.closed_loop_rehearsal and args.report == str(DEFAULT_REPORT_PATH):
+        args.report = str(DEFAULT_CLOSED_LOOP_REHEARSAL_REPORT_PATH)
+    if args.closed_loop_crop == "":
+        args.closed_loop_crop = None
+
+    args = _normalize_smoke_args(args)
+    post_deploy_json_path: Path | None = None
+    post_deploy_markdown_path: Path | None = None
+    if args.post_deploy:
+        post_deploy_json_path = Path(args.report)
+        post_deploy_markdown_path = post_deploy_json_path.with_suffix(".md")
+
+    try:
+        if args.closed_loop_rehearsal:
+            report = _build_closed_loop_rehearsal_report(args)
+        elif args.post_deploy:
+            report = _build_post_deploy_report(args)
+        elif args.pre_demo_gate:
+            report = _build_pre_demo_gate_report(args)
+        else:
+            # pragma: no cover - main path used by CLI integration tests.
+            report = run(args)
+    except Exception as exc:
+        report = {
+            "passed": False,
+            "error": str(exc),
+            "base_url": args.base_url,
+            "project_root": args.project_root,
+        }
+        Path(args.report).write_text(
+            json.dumps(report, indent=2, sort_keys=True), encoding="utf-8"
+        )
+        print(f"Yixiao case-study smoke failed: {exc}", file=sys.stderr)
+        print(f"Report: {args.report}", file=sys.stderr)
+        return 1
+
+    Path(args.report).write_text(
+        json.dumps(report, indent=2, sort_keys=True), encoding="utf-8"
+    )
+    if args.post_deploy and post_deploy_markdown_path:
+        _write_post_deploy_report_markdown(report, post_deploy_markdown_path)
+    if args.closed_loop_rehearsal:
+        status = "passed" if report.get("passed") else "failed"
+        print(f"Yixiao closed-loop rehearsal {status}.")
+        print(f"Targets: {', '.join(report.get('target_ids') or [])}")
+        for target in report.get("targets") or []:
+            print(
+                f" - {target.get('target_id')}: "
+                f"{'pass' if target.get('passed') else 'fail'}"
+            )
+    elif args.post_deploy:
+        status = "passed" if report.get("passed") else "failed"
+        print(f"Yixiao post-deploy smoke {status}.")
+        print(f"Workflow: {report.get('workflow_id')}")
+        readiness = report.get("readiness") or {}
+        print(
+            f"Readiness: {readiness.get('ready_for_case_study')}, "
+            f"{len(readiness.get('next_required_items') or [])} pending item(s)"
+        )
+        print(f"Markdown report: {post_deploy_markdown_path}")
+    elif args.pre_demo_gate:
+        status = "passed" if report.get("passed") else "failed"
+        print(f"Yixiao pre-demo gate {status}.")
+        print(f"Steps: {len(report.get('steps') or [])}")
+        for step in report.get("steps") or []:
+            print(f" - {step.get('name')}: {'pass' if step.get('passed') else 'fail'}")
+    else:
+        print("Yixiao case-study smoke passed.")
+        print(f"Workflow: {report['workflow_id']}")
+        print(f"Viewer: {report['viewer_url']}")
+    print(f"Report: {args.report}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/scripts/setup_pytorch_connectomics.sh b/scripts/setup_pytorch_connectomics.sh
index 5c192183..a6be3e37 100644
--- a/scripts/setup_pytorch_connectomics.sh
+++ b/scripts/setup_pytorch_connectomics.sh
@@ -7,21 +7,44 @@ if ! command -v git >/dev/null 2>&1; then
 	exit 1
 fi
 
-PYTORCH_CONNECTOMICS_COMMIT="0a0dceb"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT_DIR="$(cd "${SCRIPT_DIR}/.." && pwd)"
+
+PYTORCH_CONNECTOMICS_COMMIT="04c2a35e78a1a7ca1138f83a98fc3ef27097abd4"
+PYTORCH_CONNECTOMICS_REF="refs/heads/pytc-client-legacy-runtime"
 REPO_URL="https://github.com/PytorchConnectomics/pytorch_connectomics.git"
-PYTORCH_CONNECTOMICS_DIR="pytorch_connectomics"
+PYTORCH_CONNECTOMICS_DIR="${ROOT_DIR}/pytorch_connectomics"
+
+fetch_pinned_commit() {
+	git fetch --depth 1 origin "${PYTORCH_CONNECTOMICS_REF}"
+	FETCHED_COMMIT="$(git rev-parse FETCH_HEAD)"
+	if [ "${FETCHED_COMMIT}" != "${PYTORCH_CONNECTOMICS_COMMIT}" ]; then
+		echo "${PYTORCH_CONNECTOMICS_REF} resolved to ${FETCHED_COMMIT}, expected ${PYTORCH_CONNECTOMICS_COMMIT}." >&2
+		exit 1
+	fi
+}
 
 if [ -d "${PYTORCH_CONNECTOMICS_DIR}/.git" ]; then
 	pushd "${PYTORCH_CONNECTOMICS_DIR}" >/dev/null
-	git fetch origin >/dev/null 2>&1 || true
-	CURRENT_COMMIT="$(git rev-parse HEAD 2>/dev/null || echo "")"
+	CURRENT_COMMIT="$(git rev-parse --verify HEAD 2>/dev/null || true)"
 	if [ "${CURRENT_COMMIT}" != "${PYTORCH_CONNECTOMICS_COMMIT}" ]; then
-		git checkout "${PYTORCH_CONNECTOMICS_COMMIT}"
+		fetch_pinned_commit
+		git checkout --detach "${PYTORCH_CONNECTOMICS_COMMIT}"
 	fi
 	popd >/dev/null
 else
-	git clone "${REPO_URL}" "${PYTORCH_CONNECTOMICS_DIR}"
+	if [ -d "${PYTORCH_CONNECTOMICS_DIR}" ]; then
+		rmdir "${PYTORCH_CONNECTOMICS_DIR}" 2>/dev/null || {
+			echo "${PYTORCH_CONNECTOMICS_DIR} exists but is not an empty Git checkout." >&2
+			exit 1
+		}
+	fi
+
+	mkdir -p "${PYTORCH_CONNECTOMICS_DIR}"
+	git -C "${PYTORCH_CONNECTOMICS_DIR}" init --quiet
+	git -C "${PYTORCH_CONNECTOMICS_DIR}" remote add origin "${REPO_URL}"
 	pushd "${PYTORCH_CONNECTOMICS_DIR}" >/dev/null
-	git checkout "${PYTORCH_CONNECTOMICS_COMMIT}"
+	fetch_pinned_commit
 	popd >/dev/null
+	git -C "${PYTORCH_CONNECTOMICS_DIR}" checkout --detach "${PYTORCH_CONNECTOMICS_COMMIT}"
 fi
diff --git a/scripts/start.sh b/scripts/start.sh
index 2311eae6..164dffbc 100755
--- a/scripts/start.sh
+++ b/scripts/start.sh
@@ -2,11 +2,30 @@
 
 set -euo pipefail
 
-# Prefer Homebrew's Node over nvm to avoid version conflicts
-export PATH="/opt/homebrew/bin:$PATH"
-export OLLAMA_BASE_URL="http://cscigpu08.bc.edu:4443"
-export OLLAMA_MODEL="gpt-oss:20b"
-export OLLAMA_EMBED_MODEL="qwen3-embedding:8b"
+# Prefer system/Homebrew Node over shell-specific managers to avoid version conflicts.
+append_path_if_dir() {
+	local dir="$1"
+	if [[ -d "${dir}" && ":${PATH}:" != *":${dir}:"* ]]; then
+		PATH="${dir}:${PATH}"
+	fi
+}
+
+append_path_if_dir "/opt/homebrew/bin"
+append_path_if_dir "/usr/local/bin"
+
+if command -v brew >/dev/null 2>&1; then
+	BREW_PREFIX="$(brew --prefix 2>/dev/null || true)"
+	if [[ -n "${BREW_PREFIX}" ]]; then
+		append_path_if_dir "${BREW_PREFIX}/bin"
+	fi
+fi
+
+export PATH
+export OLLAMA_BASE_URL="${OLLAMA_BASE_URL:-http://127.0.0.1:11434}"
+export OLLAMA_MODEL="${OLLAMA_MODEL:-qwen3.6:27b}"
+export PYTC_WORKFLOW_INTENT_MODEL="${PYTC_WORKFLOW_INTENT_MODEL:-${OLLAMA_MODEL}}"
+export OLLAMA_EMBED_MODEL="${OLLAMA_EMBED_MODEL:-qwen3-embedding:8b}"
+export PYTC_UNLOAD_OLLAMA_BEFORE_TRAINING="${PYTC_UNLOAD_OLLAMA_BEFORE_TRAINING:-0}"
 
 ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 CLIENT_DIR="${ROOT_DIR}/client"
@@ -16,9 +35,10 @@ if ! command -v uv >/dev/null 2>&1; then
 	echo "uv is required. Install it from https://docs.astral.sh/uv/." >&2
 	exit 1
 fi
+UV_BIN="$(command -v uv)"
 
-if ! command -v npm >/dev/null 2>&1; then
-	echo "npm is required to run the Electron client." >&2
+if ! NPM_BIN="$(command -v npm)"; then
+	echo "npm is required to run the Electron client. Current PATH: ${PATH}" >&2
 	exit 1
 fi
 
@@ -108,27 +128,61 @@ start_service \
 	8000 \
 	"http://localhost:8000/" \
 	"${LOG_DIR}/data-server.log" \
-	uv run --directory "${ROOT_DIR}" python server_api/scripts/serve_data.py
+	"${UV_BIN}" run --directory "${ROOT_DIR}" python server_api/scripts/serve_data.py
 
 start_service \
 	"API server" \
 	4242 \
 	"http://localhost:4242/health" \
 	"${LOG_DIR}/api-server.log" \
-	env PYTHONDONTWRITEBYTECODE=1 uv run --directory "${ROOT_DIR}" python -m server_api.main
+	env PYTHONDONTWRITEBYTECODE=1 "${UV_BIN}" run --directory "${ROOT_DIR}" python -m server_api.main
 
 start_service \
 	"PyTC server" \
 	4243 \
 	"http://localhost:4243/hello" \
 	"${LOG_DIR}/pytc-server.log" \
-	uv run --directory "${ROOT_DIR}" python -m server_pytc.main
+	"${UV_BIN}" run --directory "${ROOT_DIR}" python -m server_pytc.main
+
+ensure_client_dependencies() {
+	if [[ -x "${CLIENT_DIR}/node_modules/.bin/react-scripts" && -x "${CLIENT_DIR}/node_modules/.bin/cross-env" ]]; then
+		return 0
+	fi
+
+	local install_log="${LOG_DIR}/npm-install.log"
+	echo "Client dependencies missing; installing with npm (log: $(relative_log_path "${install_log}"))..."
+	: >"${install_log}"
+	if "${NPM_BIN}" install >"${install_log}" 2>&1; then
+		echo "Client dependencies installed"
+	else
+		echo "ERROR: npm install failed. Recent log output:" >&2
+		tail -n 60 "${install_log}" >&2 || true
+		exit 1
+	fi
+}
+
+patch_electron_dev_app_name() {
+	if [[ "$(uname -s)" != "Darwin" ]]; then
+		return 0
+	fi
+	local plist="${CLIENT_DIR}/node_modules/electron/dist/Electron.app/Contents/Info.plist"
+	if [[ ! -f "${plist}" || ! -x /usr/libexec/PlistBuddy ]]; then
+		return 0
+	fi
+	/usr/libexec/PlistBuddy -c "Set :CFBundleName PyTC Client" "${plist}" >/dev/null 2>&1 || true
+	/usr/libexec/PlistBuddy -c "Set :CFBundleDisplayName PyTC Client" "${plist}" >/dev/null 2>&1 ||
+		/usr/libexec/PlistBuddy -c "Add :CFBundleDisplayName string PyTC Client" "${plist}" >/dev/null 2>&1 || true
+	/usr/libexec/PlistBuddy -c "Set :CFBundleIdentifier bio.seg.pytc-client" "${plist}" >/dev/null 2>&1 || true
+	touch "${CLIENT_DIR}/node_modules/electron/dist/Electron.app" >/dev/null 2>&1 || true
+}
 
 pushd "${CLIENT_DIR}" >/dev/null
+ensure_client_dependencies
+patch_electron_dev_app_name
 if [[ "${SKIP_CLIENT_BUILD:-0}" != "1" ]]; then
 	BUILD_LOG="${LOG_DIR}/react-build.log"
 	echo "Building React client (log: $(relative_log_path "${BUILD_LOG}"))..."
-	if npm run build >"${BUILD_LOG}" 2>&1; then
+	if "${NPM_BIN}" run build >"${BUILD_LOG}" 2>&1; then
 		echo "React build complete"
 	else
 		echo "ERROR: React build failed. Recent log output:" >&2
@@ -148,7 +202,7 @@ if port_is_listening 3000; then
 else
 	: >"${REACT_LOG}"
 	echo "React server starting on :3000 (log: $(relative_log_path "${REACT_LOG}"))"
-	BROWSER=none npm start >"${REACT_LOG}" 2>&1 &
+	BROWSER=none "${NPM_BIN}" start >"${REACT_LOG}" 2>&1 &
 	STARTED_PIDS+=("$!")
 fi
 
@@ -171,7 +225,7 @@ wait_for_react() {
 if wait_for_react; then
 	echo "Startup logs are under $(relative_log_path "${LOG_DIR}")"
 	echo "Starting Electron client..."
-	ENVIRONMENT=development npm run electron
+	ENVIRONMENT=development "${NPM_BIN}" run electron
 else
 	echo "Failed to start React server" >&2
 	exit 1
diff --git a/scripts/summarize_app_log.py b/scripts/summarize_app_log.py
new file mode 100644
index 00000000..ad1ce9c0
--- /dev/null
+++ b/scripts/summarize_app_log.py
@@ -0,0 +1,100 @@
+#!/usr/bin/env python3
+
+from __future__ import annotations
+
+import argparse
+import json
+from collections import Counter, defaultdict
+from pathlib import Path
+
+DEFAULT_LOG = Path(__file__).resolve().parents[1] / ".logs" / "app" / "app-events.jsonl"
+
+
+def load_rows(path: Path):
+    rows = []
+    for line in path.read_text(encoding="utf-8").splitlines():
+        if not line.strip():
+            continue
+        try:
+            rows.append(json.loads(line))
+        except json.JSONDecodeError:
+            continue
+    return rows
+
+
+def summarize(rows, *, session_id: str | None = None, last: int = 12):
+    if session_id:
+        rows = [row for row in rows if row.get("session_id") == session_id]
+
+    if not rows:
+        print("No matching log rows.")
+        return
+
+    components = Counter(row.get("component", "?") for row in rows)
+    events = Counter(row.get("event", "?") for row in rows)
+    levels = Counter(row.get("level", "?") for row in rows)
+    sessions = Counter(row.get("session_id") for row in rows if row.get("session_id"))
+
+    print(f"rows: {len(rows)}")
+    print(f"first: {rows[0].get('timestamp')}")
+    print(f"last:  {rows[-1].get('timestamp')}")
+    if sessions and not session_id:
+        print(f"sessions: {dict(sessions)}")
+
+    print("\ncomponents:")
+    for name, count in components.most_common():
+        print(f"  {name}: {count}")
+
+    print("\nlevels:")
+    for name, count in levels.most_common():
+        print(f"  {name}: {count}")
+
+    print("\ntop events:")
+    for name, count in events.most_common(12):
+        print(f"  {name}: {count}")
+
+    print("\npossible issues:")
+    issue_rows = [
+        row
+        for row in rows
+        if row.get("level") == "ERROR"
+        or row.get("event")
+        in {"api_response_error", "window_error", "unhandled_rejection"}
+    ]
+    if not issue_rows:
+        print("  none")
+    else:
+        for row in issue_rows[:12]:
+            print(
+                f"  {row.get('timestamp')} {row.get('component')} "
+                f"{row.get('event')}: {row.get('message')}"
+            )
+
+    print("\nrecent:")
+    for row in rows[-last:]:
+        print(
+            f"  {row.get('timestamp')} {row.get('component')} "
+            f"{row.get('event')}: {row.get('message')}"
+        )
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Summarize PyTC app event logs")
+    parser.add_argument(
+        "--log", default=str(DEFAULT_LOG), help="Path to app-events.jsonl"
+    )
+    parser.add_argument(
+        "--session", default=None, help="Optional client session_id filter"
+    )
+    parser.add_argument("--last", type=int, default=12, help="Recent rows to print")
+    args = parser.parse_args()
+
+    log_path = Path(args.log).expanduser().resolve(strict=False)
+    if not log_path.is_file():
+        raise SystemExit(f"Log file not found: {log_path}")
+
+    summarize(load_rows(log_path), session_id=args.session, last=args.last)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/server_api/auth/models.py b/server_api/auth/models.py
index 4720793f..f45ee28c 100644
--- a/server_api/auth/models.py
+++ b/server_api/auth/models.py
@@ -1,3 +1,5 @@
+import json
+
 from sqlalchemy import (
     Column,
     Integer,
@@ -11,8 +13,8 @@
 from sqlalchemy.orm import relationship
 from sqlalchemy.sql import func
 from .database import Base
-from pydantic import BaseModel
-from typing import Optional, List
+from pydantic import BaseModel, Field
+from typing import Optional, List, Dict, Any
 from datetime import datetime
 
 
@@ -101,12 +103,44 @@ class ChatMessage(Base):
     conversation_id = Column(
         Integer, ForeignKey("conversations.id", ondelete="CASCADE"), nullable=False
     )
+    workflow_id = Column(Integer, nullable=True, index=True)
     role = Column(String, nullable=False)  # "user" or "assistant"
     content = Column(Text, nullable=False)
+    source = Column(String, nullable=True)
+    actions_json = Column(Text, nullable=True)
+    commands_json = Column(Text, nullable=True)
+    proposals_json = Column(Text, nullable=True)
+    trace_json = Column(Text, nullable=True)
     created_at = Column(DateTime(timezone=True), server_default=func.now())
 
     conversation = relationship("Conversation", back_populates="messages")
 
+    @staticmethod
+    def _decode_json_list(value):
+        if not value:
+            return []
+        try:
+            decoded = json.loads(value)
+        except (TypeError, json.JSONDecodeError):
+            return []
+        return decoded if isinstance(decoded, list) else []
+
+    @property
+    def actions(self):
+        return self._decode_json_list(self.actions_json)
+
+    @property
+    def commands(self):
+        return self._decode_json_list(self.commands_json)
+
+    @property
+    def proposals(self):
+        return self._decode_json_list(self.proposals_json)
+
+    @property
+    def trace(self):
+        return self._decode_json_list(self.trace_json)
+
 
 # Pydantic Schemas
 class UserBase(BaseModel):
@@ -154,6 +188,11 @@ class MountDirectoryRequest(BaseModel):
     mount_name: Optional[str] = None
 
 
+class ProjectContextProfileRequest(BaseModel):
+    directory_path: str
+    profile: Dict[str, Any] = Field(default_factory=dict)
+
+
 class FileResponse(FileBase):
     id: int
     user_id: int
@@ -204,11 +243,32 @@ class Config:
         from_attributes = True
 
 
+class MountedProjectResponse(BaseModel):
+    mounted_root_id: int
+    name: str
+    directory_path: str
+    mounted_folders: int = 0
+    mounted_files: int = 0
+    profile: Dict[str, Any] = Field(default_factory=dict)
+    created_at: datetime
+
+
+class UserProjectListResponse(BaseModel):
+    user: UserResponse
+    mounted_projects: List[MountedProjectResponse] = Field(default_factory=list)
+
+
 # Chat History Schemas
 class ChatMessageResponse(BaseModel):
     id: int
+    workflow_id: Optional[int] = None
     role: str
     content: str
+    source: Optional[str] = None
+    actions: List[dict] = Field(default_factory=list)
+    commands: List[dict] = Field(default_factory=list)
+    proposals: List[dict] = Field(default_factory=list)
+    trace: List[dict] = Field(default_factory=list)
     created_at: datetime
 
     class Config:
diff --git a/server_api/auth/router.py b/server_api/auth/router.py
index f50f7c7b..a3b271c0 100644
--- a/server_api/auth/router.py
+++ b/server_api/auth/router.py
@@ -4,25 +4,70 @@
 from sqlalchemy.orm import Session
 from . import models, utils, database
 from jose import JWTError, jwt
-from typing import List, Optional
+from typing import Any, List, Optional
+from datetime import datetime, timezone
+from urllib.parse import parse_qs, unquote, urlparse
+import json
 import shutil
 import os
 import uuid
 import mimetypes
+import re
+import math
+from server_api.utils.utils import resolve_existing_path
 
-try:  # Optional preview dependencies
+try:  # Optional preview dependency
     import cv2
-    import numpy as np
-    import tifffile
 except Exception:  # pragma: no cover - preview is best-effort
     cv2 = None
+
+try:  # Optional volume inspection dependency
+    import numpy as np
+except Exception:  # pragma: no cover - inspection is best-effort
     np = None
+
+try:  # Optional volume inspection dependency
+    import tifffile
+except Exception:  # pragma: no cover - inspection is best-effort
     tifffile = None
 
 router = APIRouter()
 
 oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token", auto_error=False)
-IGNORED_SYSTEM_FILENAMES = {".ds_store", "thumbs.db"}
+IGNORED_SYSTEM_FILENAMES = {
+    ".ds_store",
+    "thumbs.db",
+    ".pytc_proofreading.json",
+    ".pytc_instance_labels.tif",
+    ".pytc_project_context.json",
+}
+PROJECT_PROFILE_MAX_FILES = 2500
+PROJECT_PROFILE_TEXT_MAX_BYTES = 24000
+PROJECT_PROFILE_MAX_CONTENT_FILES = 24
+PROJECT_AUDIT_MAX_VOLUME_FILES = 16
+PROJECT_AUDIT_MAX_SAMPLE_VALUES = 250_000
+PROJECT_AUDIT_MAX_FINDINGS = 24
+PROJECT_CONTEXT_FILENAME = ".pytc_project_context.json"
+
+VOLUME_EXTENSIONS = {
+    ".h5",
+    ".hdf5",
+    ".tif",
+    ".tiff",
+    ".ome.tif",
+    ".ome.tiff",
+    ".npy",
+    ".npz",
+    ".zarr",
+    ".n5",
+    ".nii",
+    ".nii.gz",
+    ".mrc",
+    ".mrcs",
+}
+CONFIG_EXTENSIONS = {".yaml", ".yml", ".json", ".toml"}
+CHECKPOINT_EXTENSIONS = {".pt", ".pth", ".pth.tar", ".ckpt", ".onnx"}
+TEXT_SIGNAL_EXTENSIONS = CONFIG_EXTENSIONS | {".md", ".txt", ".csv", ".tsv"}
 
 
 def _format_size(size_bytes: int) -> str:
@@ -36,7 +81,1815 @@ def _format_size(size_bytes: int) -> str:
 
 
 def _is_ignored_system_file(name: Optional[str]) -> bool:
-    return str(name or "").strip().lower() in IGNORED_SYSTEM_FILENAMES
+    normalized = str(name or "").strip().lower()
+    return normalized in IGNORED_SYSTEM_FILENAMES or normalized.startswith(
+        ".__pytc_runtime_"
+    )
+
+
+def _project_suggestion_candidates() -> List[dict]:
+    repo_root = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", ".."))
+    workspace_root = os.path.abspath(os.path.join(repo_root, ".."))
+    return [
+        {
+            "id": "yixiao-tapereader-xri-case-study",
+            "name": "yixiao_tapereader_xri_case_study",
+            "directory_path": "/home/weidf/demo_data/yixiao_tapereader_xri_case_study",
+            "description": "Yixiao TapeReader XRI fibre segmentation case study with GT, draft, and image-only volumes.",
+            "recommended": True,
+            "context_hints": {
+                "imaging_modality": "X-ray / XRI volumetric microscopy",
+                "target_structure": "CytoTape fibres",
+                "task_family": "XRI fibre instance segmentation",
+                "mask_status": "mixed: 6 ground-truth masks, 2 draft masks, 2 image-only targets",
+                "image_only_strategy": "run inference on image-only volumes later",
+                "training_policy": "train only on confirmed ground-truth masks",
+                "task_goal": "instance segmentation, proofreading, and model retraining",
+                "optimization_priority": "paper-faithful workflow coordination",
+                "voxel_size_nm": [40, 16.3, 16.3],
+            },
+        },
+        {
+            "id": "mitoem2-progress-demo",
+            "name": "mitoem2_progress_demo",
+            "directory_path": "/home/weidf/demo_data/mitoem2_progress_demo",
+            "description": "MitoEM2.0 progress demo with curated, draft, and missing segmentations.",
+            "recommended": False,
+            "context_hints": {
+                "imaging_modality": "EM / ssSEM",
+                "target_structure": "mitochondria",
+                "task_goal": "segmentation",
+                "optimization_priority": "accuracy",
+                "voxel_size_nm": [30, 8, 8],
+            },
+        },
+        {
+            "id": "prepilot-lucchi-pp",
+            "name": "prepilot_lucchi_pp",
+            "directory_path": "/home/weidf/demo_data/prepilot_lucchi_pp",
+            "description": "Prepilot Lucchi++ mitochondria segmentation project.",
+            "recommended": False,
+            "context_hints": {
+                "imaging_modality": "EM",
+                "target_structure": "mitochondria",
+                "task_goal": "segmentation",
+                "optimization_priority": "accuracy",
+            },
+        },
+        {
+            "id": "mito25-paper-loop-smoke",
+            "name": "mito25-paper-loop-smoke",
+            "directory_path": os.path.join(
+                repo_root, "testing_projects", "mito25_paper_loop_smoke"
+            ),
+            "description": "Curated mito25 smoke project with image/seg, configs, checkpoint, and prediction artifacts.",
+            "recommended": False,
+        },
+        {
+            "id": "mito25-raw-data",
+            "name": "mito25",
+            "directory_path": os.path.join(workspace_root, "testing_data", "mito25"),
+            "description": "Raw mito25 image/seg source data.",
+            "recommended": False,
+        },
+        {
+            "id": "mito25-smoke-raw-data",
+            "name": "mito25-smoke",
+            "directory_path": os.path.join(
+                workspace_root, "testing_data", "mito25_smoke"
+            ),
+            "description": "Small paired mito25 HDF5 image/seg volumes for fast smoke testing.",
+            "recommended": False,
+        },
+        {
+            "id": "snemi-proofreading-data",
+            "name": "snemi-proofreading",
+            "directory_path": os.path.join(workspace_root, "testing_data", "snemi"),
+            "description": "SNEMI-style TIFF image/label volumes for proofreading-focused testing.",
+            "recommended": False,
+        },
+    ]
+
+
+def _lower_path_parts(path: str) -> List[str]:
+    normalized = os.path.normpath(path).lower()
+    return [part for part in normalized.split(os.sep) if part]
+
+
+def _project_extension(name: str) -> str:
+    lower = name.lower()
+    for compound in (".ome.tiff", ".ome.tif", ".nii.gz", ".pth.tar"):
+        if lower.endswith(compound):
+            return compound
+    return os.path.splitext(lower)[1]
+
+
+def _role_for_project_file(relative_path: str) -> Optional[str]:
+    parts = _lower_path_parts(relative_path)
+    name = parts[-1] if parts else os.path.basename(relative_path).lower()
+    stem = name
+    extension = _project_extension(name)
+    if extension:
+        stem = name[: -len(extension)]
+    haystack = " ".join(parts + [stem])
+
+    if extension in CHECKPOINT_EXTENSIONS or "checkpoint" in haystack:
+        return "checkpoint"
+    if extension in CONFIG_EXTENSIONS and (
+        "config" in haystack or "mito" in haystack or "pytc" in haystack
+    ):
+        return "config"
+    if extension not in VOLUME_EXTENSIONS:
+        if extension in {".md", ".txt"} or "notes" in haystack:
+            return "notes"
+        return None
+
+    if any(
+        token in haystack
+        for token in (
+            "prediction",
+            "predictions",
+            "result",
+            "inference",
+            "candidate",
+            "baseline",
+        )
+    ):
+        return "prediction"
+    if any(
+        token in haystack
+        for token in (
+            "_seg",
+            " seg",
+            "segmentation",
+            "label",
+            "labels",
+            "mask",
+            "masks",
+            "ground",
+            "truth",
+            "consensus",
+            "gt",
+        )
+    ):
+        return "label"
+    if any(token in haystack for token in ("image", "images", "_im", "raw")):
+        return "image"
+    return "volume"
+
+
+def _looks_like_image_label_pair(image_path: str, label_path: str) -> bool:
+    image_name = os.path.basename(image_path).lower()
+    label_name = os.path.basename(label_path).lower()
+    normalized_image = (
+        image_name.replace("_image", "")
+        .replace("_images", "")
+        .replace("_im", "")
+        .replace("-image", "")
+        .replace("image_", "")
+        .replace("img_", "")
+        .replace("raw_", "")
+    )
+    normalized_label = (
+        label_name.replace("_seg", "")
+        .replace("_label", "")
+        .replace("_labels", "")
+        .replace("_mask", "")
+        .replace("_mito", "")
+        .replace("_consensus", "")
+        .replace("-seg", "")
+        .replace("seg_", "")
+        .replace("label_", "")
+        .replace("labels_", "")
+        .replace("mask_", "")
+    )
+    return normalized_image.split(".")[0] == normalized_label.split(".")[0]
+
+
+def _safe_text_sample(path: str) -> str:
+    try:
+        with open(path, "rb") as handle:
+            raw = handle.read(PROJECT_PROFILE_TEXT_MAX_BYTES)
+    except OSError:
+        return ""
+    return raw.decode("utf-8", errors="ignore")
+
+
+def _inspect_hdf5_container(path: str, *, max_datasets: int = 16) -> Optional[dict]:
+    try:
+        import h5py  # type: ignore
+    except Exception:  # pragma: no cover - optional dependency
+        return None
+
+    datasets = []
+    root_attrs = []
+    try:
+        with h5py.File(path, "r") as handle:
+            for key in list(handle.attrs.keys())[:8]:
+                root_attrs.append(str(key))
+
+            def visit(name, obj):
+                if len(datasets) >= max_datasets:
+                    return
+                if isinstance(obj, h5py.Dataset):
+                    datasets.append(
+                        {
+                            "path": name,
+                            "shape": list(obj.shape),
+                            "dtype": str(obj.dtype),
+                        }
+                    )
+
+            handle.visititems(visit)
+    except Exception as exc:
+        return {"format": "hdf5", "readable": False, "error": type(exc).__name__}
+
+    return {
+        "format": "hdf5",
+        "readable": True,
+        "datasets": datasets,
+        "root_attrs": root_attrs,
+    }
+
+
+def _inspect_tiff_container(path: str) -> Optional[dict]:
+    if tifffile is None:
+        return None
+    try:
+        with tifffile.TiffFile(path) as handle:
+            series = handle.series[0] if handle.series else None
+            return {
+                "format": "tiff",
+                "readable": True,
+                "shape": list(series.shape) if series is not None else [],
+                "dtype": str(series.dtype) if series is not None else None,
+                "axes": getattr(series, "axes", None) if series is not None else None,
+                "pages": len(handle.pages),
+            }
+    except Exception as exc:
+        return {"format": "tiff", "readable": False, "error": type(exc).__name__}
+
+
+def _json_safe_metadata_value(value: Any, *, max_items: int = 16) -> Any:
+    if isinstance(value, (bytes, bytearray)):
+        return value.decode("utf-8", errors="ignore")
+    if np is not None:
+        if isinstance(value, np.generic):
+            value = value.item()
+        elif isinstance(value, np.ndarray):
+            flattened = value.reshape(-1)
+            return [
+                _json_safe_metadata_value(item, max_items=max_items)
+                for item in flattened[:max_items]
+            ]
+    if isinstance(value, (list, tuple)):
+        return [
+            _json_safe_metadata_value(item, max_items=max_items)
+            for item in list(value)[:max_items]
+        ]
+    if isinstance(value, dict):
+        return {
+            str(key): _json_safe_metadata_value(item, max_items=max_items)
+            for key, item in list(value.items())[:max_items]
+        }
+    if isinstance(value, float):
+        return value if math.isfinite(value) else None
+    if isinstance(value, (str, int, bool)) or value is None:
+        return value
+    return str(value)
+
+
+def _attrs_to_safe_dict(attrs: Any, *, max_attrs: int = 16) -> dict:
+    values = {}
+    try:
+        keys = list(attrs.keys())[:max_attrs]
+    except Exception:
+        return values
+    for key in keys:
+        try:
+            values[str(key)] = _json_safe_metadata_value(attrs[key])
+        except Exception:
+            values[str(key)] = "<unreadable>"
+    return values
+
+
+def _numeric_values_from_metadata(value: Any) -> List[float]:
+    if value is None:
+        return []
+    if isinstance(value, (bytes, bytearray)):
+        value = value.decode("utf-8", errors="ignore")
+    if np is not None:
+        if isinstance(value, np.generic):
+            value = value.item()
+        elif isinstance(value, np.ndarray):
+            return [
+                float(item)
+                for item in value.reshape(-1).tolist()
+                if isinstance(item, (int, float)) and math.isfinite(float(item))
+            ]
+    if isinstance(value, (list, tuple)):
+        parsed = []
+        for item in value:
+            if isinstance(item, (int, float)) and math.isfinite(float(item)):
+                parsed.append(float(item))
+            elif isinstance(item, str):
+                parsed.extend(_numeric_values_from_metadata(item))
+        return parsed
+    if isinstance(value, (int, float)) and math.isfinite(float(value)):
+        return [float(value)]
+    if isinstance(value, str):
+        return [
+            float(match)
+            for match in re.findall(r"\d+(?:\.\d+)?", value)
+            if math.isfinite(float(match))
+        ]
+    return []
+
+
+def _metadata_voxel_size_nm(attrs: dict) -> Optional[List[float]]:
+    preferred_keys = (
+        "voxel_size_nm_zyx",
+        "voxel_size_nm",
+        "resolution_nm",
+        "spacing_nm",
+        "pixel_size_nm",
+        "voxel_size",
+        "resolution",
+        "spacing",
+        "pixel_size",
+        "scale",
+    )
+    normalized = {str(key).lower(): value for key, value in (attrs or {}).items()}
+    ordered_keys = [
+        key for preferred in preferred_keys for key in normalized if preferred in key
+    ]
+    for key in ordered_keys:
+        values = _numeric_values_from_metadata(normalized[key])
+        if len(values) < 3:
+            continue
+        multiplier = 1000.0 if re.search(r"(^|[_\s-])(um|micron)", key) else 1.0
+        triplet = [round(value * multiplier, 6) for value in values[:3]]
+        if all(value > 0 for value in triplet):
+            return triplet
+    return None
+
+
+def _downsample_array_for_stats(
+    array: Any, *, max_values: int = PROJECT_AUDIT_MAX_SAMPLE_VALUES
+):
+    if np is None:
+        return None
+    try:
+        shape = tuple(int(axis) for axis in getattr(array, "shape", ()))
+    except Exception:
+        shape = ()
+    if not shape:
+        try:
+            return np.asarray(array[()])
+        except Exception:
+            return None
+
+    try:
+        total_size = int(math.prod(shape))
+    except Exception:
+        total_size = 0
+    if total_size <= 0:
+        return None
+
+    stride = 1
+    if total_size > max_values:
+        stride = max(1, int(math.ceil((total_size / max_values) ** (1 / len(shape)))))
+    slices = tuple(slice(None, None, stride) for _ in shape)
+    try:
+        sample = np.asarray(array[slices])
+    except Exception:
+        try:
+            sample = np.asarray(array)
+        except Exception:
+            return None
+
+    if sample.size > max_values:
+        stride = max(1, int(math.ceil((sample.size / max_values) ** (1 / sample.ndim))))
+        sample = sample[tuple(slice(None, None, stride) for _ in range(sample.ndim))]
+    return sample
+
+
+def _sample_array_stats(array: Any) -> Optional[dict]:
+    if np is None:
+        return None
+    sample = _downsample_array_for_stats(array)
+    if sample is None:
+        return None
+    try:
+        sample = np.asarray(sample)
+    except Exception:
+        return None
+    stats = {
+        "sampled_voxels": int(sample.size),
+    }
+    if sample.size == 0:
+        stats.update({"empty": True})
+        return stats
+
+    if np.issubdtype(sample.dtype, np.number):
+        numeric = sample.astype(np.float64, copy=False)
+        finite_mask = np.isfinite(numeric)
+        finite = numeric[finite_mask]
+        stats["finite_fraction"] = float(finite.size / sample.size)
+        if finite.size == 0:
+            stats["empty"] = True
+            return stats
+        minimum = float(np.min(finite))
+        maximum = float(np.max(finite))
+        stats.update(
+            {
+                "min": minimum,
+                "max": maximum,
+                "mean": float(np.mean(finite)),
+                "std": float(np.std(finite)),
+                "dynamic_range": maximum - minimum,
+                "nonzero_fraction": float(np.count_nonzero(finite) / finite.size),
+            }
+        )
+        if np.issubdtype(sample.dtype, np.integer) or np.issubdtype(
+            sample.dtype, np.bool_
+        ):
+            unique_values = np.unique(sample)
+            stats["unique_count_sample"] = int(unique_values.size)
+            stats["unique_values_preview"] = [
+                _json_safe_metadata_value(item) for item in unique_values[:12]
+            ]
+    return stats
+
+
+def _audit_findings_for_stats(
+    relative_path: str, role: str, stats: Optional[dict]
+) -> List[dict]:
+    if not stats:
+        return []
+    findings = []
+    nonzero_fraction = stats.get("nonzero_fraction")
+    dynamic_range = stats.get("dynamic_range")
+    unique_count = stats.get("unique_count_sample")
+    if role == "image":
+        if stats.get("sampled_voxels", 0) == 0:
+            findings.append(
+                {
+                    "level": "warning",
+                    "code": "empty_image_sample",
+                    "message": "Image sample is empty.",
+                    "path": relative_path,
+                    "source": "volume_sample",
+                }
+            )
+        elif nonzero_fraction == 0:
+            findings.append(
+                {
+                    "level": "warning",
+                    "code": "zero_image_sample",
+                    "message": "Image sample is all zero.",
+                    "path": relative_path,
+                    "source": "volume_sample",
+                }
+            )
+        elif dynamic_range is not None and dynamic_range <= 1:
+            findings.append(
+                {
+                    "level": "warning",
+                    "code": "low_dynamic_range_image",
+                    "message": "Image sample has very little intensity variation.",
+                    "path": relative_path,
+                    "source": "volume_sample",
+                }
+            )
+    elif role in {"label", "prediction"}:
+        if nonzero_fraction == 0 or unique_count == 1:
+            findings.append(
+                {
+                    "level": "warning",
+                    "code": "empty_mask_sample",
+                    "message": "Mask-like sample has no foreground labels.",
+                    "path": relative_path,
+                    "source": "volume_sample",
+                }
+            )
+    return findings
+
+
+def _audit_hdf5_volume(
+    path: str,
+    relative_path: str,
+    role: str,
+    *,
+    collect_stats: bool = True,
+) -> dict:
+    try:
+        import h5py  # type: ignore
+    except Exception:  # pragma: no cover - optional dependency
+        return {
+            "path": relative_path,
+            "role": role,
+            "format": "hdf5",
+            "readable": False,
+            "error": "h5py_missing",
+        }
+
+    dataset_records = []
+    findings = []
+    try:
+        with h5py.File(path, "r") as handle:
+            root_attrs = _attrs_to_safe_dict(handle.attrs)
+
+            def visit(name, obj):
+                if len(dataset_records) >= 12:
+                    return
+                if isinstance(obj, h5py.Dataset):
+                    dataset_attrs = _attrs_to_safe_dict(obj.attrs)
+                    dataset_records.append(
+                        {
+                            "path": name,
+                            "shape": list(obj.shape),
+                            "dtype": str(obj.dtype),
+                            "attrs": dataset_attrs,
+                        }
+                    )
+
+            handle.visititems(visit)
+            preferred_tokens = {
+                "image": ("raw", "image", "img", "volume"),
+                "label": ("label", "labels", "seg", "mask", "mito", "gt"),
+                "prediction": ("prediction", "result", "seg", "mask"),
+            }.get(role, ())
+            selected_record = None
+            for record in dataset_records:
+                record_path = str(record.get("path", "")).lower()
+                if preferred_tokens and any(
+                    token in record_path for token in preferred_tokens
+                ):
+                    selected_record = record
+                    break
+            selected_record = selected_record or (
+                dataset_records[0] if dataset_records else None
+            )
+            stats = None
+            voxel_size_nm = _metadata_voxel_size_nm(root_attrs)
+            if selected_record:
+                dataset = handle[selected_record["path"]]
+                stats = _sample_array_stats(dataset) if collect_stats else None
+                voxel_size_nm = voxel_size_nm or _metadata_voxel_size_nm(
+                    selected_record.get("attrs") or {}
+                )
+                if stats:
+                    findings.extend(
+                        _audit_findings_for_stats(relative_path, role, stats)
+                    )
+    except Exception as exc:
+        return {
+            "path": relative_path,
+            "role": role,
+            "format": "hdf5",
+            "readable": False,
+            "error": type(exc).__name__,
+            "findings": [
+                {
+                    "level": "error",
+                    "code": "unreadable_volume",
+                    "message": f"Could not read {relative_path} as HDF5.",
+                    "path": relative_path,
+                    "source": "volume_metadata",
+                }
+            ],
+        }
+
+    result = {
+        "path": relative_path,
+        "role": role,
+        "format": "hdf5",
+        "readable": True,
+        "datasets": dataset_records,
+        "dataset_path": selected_record.get("path") if selected_record else None,
+        "shape": selected_record.get("shape") if selected_record else None,
+        "dtype": selected_record.get("dtype") if selected_record else None,
+        "stats": stats,
+        "findings": findings,
+    }
+    if voxel_size_nm:
+        result["voxel_size_nm_zyx"] = voxel_size_nm
+    return result
+
+
+def _audit_tiff_volume(
+    path: str,
+    relative_path: str,
+    role: str,
+    *,
+    collect_stats: bool = True,
+) -> dict:
+    metadata = _inspect_tiff_container(path)
+    if not metadata:
+        return {
+            "path": relative_path,
+            "role": role,
+            "format": "tiff",
+            "readable": False,
+            "error": "tifffile_missing",
+        }
+    result = {"path": relative_path, "role": role, **metadata}
+    if (
+        collect_stats
+        and metadata.get("readable")
+        and tifffile is not None
+        and np is not None
+    ):
+        try:
+            sample = tifffile.memmap(path)
+            stats = _sample_array_stats(sample)
+            result["stats"] = stats
+            result["findings"] = _audit_findings_for_stats(relative_path, role, stats)
+        except Exception:
+            result["findings"] = []
+    return result
+
+
+def _audit_volume_file(
+    directory_path: str,
+    relative_path: str,
+    role: str,
+    *,
+    collect_stats: bool = True,
+) -> dict:
+    absolute_path = os.path.join(directory_path, relative_path)
+    extension = _project_extension(relative_path)
+    if extension in {".h5", ".hdf5"}:
+        return _audit_hdf5_volume(
+            absolute_path,
+            relative_path,
+            role,
+            collect_stats=collect_stats,
+        )
+    if extension in {".tif", ".tiff", ".ome.tif", ".ome.tiff"}:
+        return _audit_tiff_volume(
+            absolute_path,
+            relative_path,
+            role,
+            collect_stats=collect_stats,
+        )
+    if extension in {".zarr", ".n5"}:
+        return {
+            "path": relative_path,
+            "role": role,
+            "format": extension.lstrip("."),
+            "readable": os.path.isdir(absolute_path),
+            "findings": [],
+        }
+    return {
+        "path": relative_path,
+        "role": role,
+        "format": extension.lstrip(".") or "unknown",
+        "readable": os.path.exists(absolute_path),
+        "findings": [],
+    }
+
+
+def _audit_context_facts(volumes: List[dict]) -> List[dict]:
+    facts = []
+    seen = set()
+    for volume in volumes:
+        voxel_size_nm = volume.get("voxel_size_nm_zyx")
+        if not voxel_size_nm:
+            continue
+        key = ("voxel_size_nm", tuple(voxel_size_nm))
+        if key in seen:
+            continue
+        seen.add(key)
+        facts.append(
+            {
+                "key": "voxel_size_nm",
+                "label": "Voxel size",
+                "value": voxel_size_nm,
+                "unit": "nm",
+                "axis_order": "z,y,x",
+                "source": f"volume_metadata:{volume.get('path')}",
+                "confidence": "high",
+            }
+        )
+    return facts[:8]
+
+
+def _build_project_audit(
+    directory_path: str,
+    roles: dict,
+    paired_examples: List[dict],
+    *,
+    include_volume_details: bool = True,
+    collect_stats: bool = True,
+) -> dict:
+    volume_candidates = []
+    seen_paths = set()
+
+    def add_candidate(relative_path: Optional[str], role: str) -> None:
+        if len(volume_candidates) >= PROJECT_AUDIT_MAX_VOLUME_FILES:
+            return
+        path = str(relative_path or "").strip()
+        if not path or path in seen_paths:
+            return
+        seen_paths.add(path)
+        volume_candidates.append((path, role))
+
+    # Pair checks are only useful if both sides are inspected. Prefer declared
+    # image/label pairs before filling the remaining sample budget.
+    for pair in paired_examples:
+        add_candidate(pair.get("image"), "image")
+        add_candidate(pair.get("label"), "label")
+        if len(volume_candidates) >= PROJECT_AUDIT_MAX_VOLUME_FILES:
+            break
+
+    for role in ("image", "label", "prediction", "volume"):
+        for relative_path in roles.get(role) or []:
+            add_candidate(relative_path, role)
+            if len(volume_candidates) >= PROJECT_AUDIT_MAX_VOLUME_FILES:
+                break
+        if len(volume_candidates) >= PROJECT_AUDIT_MAX_VOLUME_FILES:
+            break
+
+    volumes = [
+        _audit_volume_file(
+            directory_path,
+            relative_path,
+            role,
+            collect_stats=collect_stats,
+        )
+        for relative_path, role in volume_candidates
+    ]
+    volume_by_path = {volume.get("path"): volume for volume in volumes}
+    pair_checks = []
+    findings = []
+    for volume in volumes:
+        findings.extend(volume.get("findings") or [])
+        if volume.get("readable") is False:
+            findings.append(
+                {
+                    "level": "error",
+                    "code": "unreadable_volume",
+                    "message": f"Could not read {volume.get('path')}.",
+                    "path": volume.get("path"),
+                    "source": "volume_metadata",
+                }
+            )
+
+    for pair in paired_examples[:PROJECT_AUDIT_MAX_VOLUME_FILES]:
+        image_path = pair.get("image")
+        label_path = pair.get("label")
+        image_volume = volume_by_path.get(image_path)
+        label_volume = volume_by_path.get(label_path)
+        image_shape = image_volume.get("shape") if image_volume else None
+        label_shape = label_volume.get("shape") if label_volume else None
+        shape_match = bool(image_shape and label_shape and image_shape == label_shape)
+        pair_check = {
+            "image": image_path,
+            "label": label_path,
+            "image_shape": image_shape,
+            "label_shape": label_shape,
+            "shape_match": shape_match,
+            "source": "volume_metadata",
+        }
+        pair_checks.append(pair_check)
+        if image_shape and label_shape:
+            findings.append(
+                {
+                    "level": "info" if shape_match else "warning",
+                    "code": (
+                        "pair_shape_match" if shape_match else "pair_shape_mismatch"
+                    ),
+                    "message": (
+                        "Image and mask shapes match."
+                        if shape_match
+                        else "Image and mask shapes do not match."
+                    ),
+                    "path": image_path,
+                    "related_path": label_path,
+                    "source": "volume_metadata",
+                }
+            )
+
+    level_counts = {"info": 0, "warning": 0, "error": 0}
+    for finding in findings:
+        level = finding.get("level")
+        if level in level_counts:
+            level_counts[level] += 1
+
+    audit = {
+        "schema_version": "pytc-project-audit/v1",
+        "generated_at": datetime.now(timezone.utc).isoformat(),
+        "summary": {
+            "audited_volumes": len(volumes),
+            "readable_volumes": sum(1 for volume in volumes if volume.get("readable")),
+            "pair_checks": len(pair_checks),
+            "shape_match_count": sum(
+                1 for pair in pair_checks if pair.get("shape_match")
+            ),
+            "shape_mismatch_count": sum(
+                1
+                for pair in pair_checks
+                if pair.get("image_shape")
+                and pair.get("label_shape")
+                and not pair.get("shape_match")
+            ),
+            "warnings": level_counts["warning"],
+            "errors": level_counts["error"],
+        },
+        "pair_checks": pair_checks,
+        "findings": findings[:PROJECT_AUDIT_MAX_FINDINGS],
+        "context_facts": _audit_context_facts(volumes),
+    }
+    if include_volume_details:
+        audit["volumes"] = volumes
+    return audit
+
+
+def _merge_audit_context_hints(context_hints: dict, audit: dict) -> dict:
+    hints = dict(context_hints or {})
+    for fact in audit.get("context_facts") or []:
+        if fact.get("key") == "voxel_size_nm" and fact.get("value"):
+            hints["voxel_size_nm"] = fact["value"]
+            hints["voxel_size_source"] = fact.get("source") or "volume_metadata"
+            break
+    return hints
+
+
+def _context_terms_for_text(text: str) -> List[str]:
+    checks = {
+        "EM": r"\bEM\b|electron microscopy|electron microscope|FIB-SEM|TEM|SEM",
+        "XRI": r"\bXRI\b|x[\s-]?ray|xray",
+        "CT": r"micro[\s-]?CT|micro.?ct|\bCT\b",
+        "fluorescence": r"fluorescen|confocal|light[\s-]?sheet",
+        "mitochondria": r"mitochond(?:ria|rion|rial)",
+        "fibres": r"\b(?:fiber|fibers|fibre|fibres|cytotape)\b",
+        "nuclei": r"\b(?:nuclei|nucleus|nuclear)\b",
+        "neurites": r"\b(?:neurite|axon|dendrite|neuron[_\s-]?ids?)\b",
+        "synapses": r"\b(?:synapse|synaptic|presynaptic|postsynaptic|cleft)\b",
+        "segmentation": r"\bsegment(?:ation|ed|ing)?\b",
+        "proofreading": r"\b(?:proofread|curat|correct)\b",
+    }
+    return [
+        label
+        for label, pattern in checks.items()
+        if re.search(pattern, text, flags=re.IGNORECASE)
+    ]
+
+
+def _collect_project_content_signals(
+    directory_path: str, roles: dict, extension_counts: dict
+):
+    text_candidates = []
+    seen_text_candidates = set()
+    volume_candidates = []
+    seen_volume_candidates = set()
+
+    def add_text_candidate(relative_path: str) -> None:
+        if relative_path in seen_text_candidates:
+            return
+        if len(text_candidates) >= PROJECT_PROFILE_MAX_CONTENT_FILES:
+            return
+        seen_text_candidates.add(relative_path)
+        text_candidates.append(relative_path)
+
+    for relative_path in (roles.get("config") or []) + (roles.get("notes") or []):
+        add_text_candidate(relative_path)
+
+    for current_dir, dirnames, filenames in os.walk(directory_path):
+        dirnames[:] = [
+            dirname
+            for dirname in sorted(dirnames)
+            if not _is_ignored_system_file(dirname)
+        ]
+        for filename in sorted(filenames):
+            if _is_ignored_system_file(filename):
+                continue
+            relative_path = os.path.relpath(
+                os.path.join(current_dir, filename), directory_path
+            )
+            relative_lower = relative_path.lower()
+            extension = _project_extension(filename)
+            if filename.lower() in {
+                "project_manifest.json",
+                "manifest.json",
+                "readme.md",
+                "README.md".lower(),
+            } or (
+                extension in TEXT_SIGNAL_EXTENSIONS
+                and any(
+                    token in relative_lower
+                    for token in ("manifest", "metadata", "readme", "config", "note")
+                )
+            ):
+                add_text_candidate(relative_path)
+            if len(text_candidates) >= PROJECT_PROFILE_MAX_CONTENT_FILES:
+                break
+        if len(text_candidates) >= PROJECT_PROFILE_MAX_CONTENT_FILES:
+            break
+
+    for role in ("image", "label", "prediction", "volume"):
+        for relative_path in roles.get(role) or []:
+            if relative_path in seen_volume_candidates:
+                continue
+            seen_volume_candidates.add(relative_path)
+            volume_candidates.append(relative_path)
+            if len(volume_candidates) >= PROJECT_PROFILE_MAX_CONTENT_FILES:
+                break
+        if len(volume_candidates) >= PROJECT_PROFILE_MAX_CONTENT_FILES:
+            break
+
+    text_sources = []
+    inference_text_parts = []
+    for relative_path in text_candidates:
+        absolute_path = os.path.join(directory_path, relative_path)
+        text = _safe_text_sample(absolute_path)
+        if not text:
+            continue
+        inference_text_parts.append(text)
+        text_sources.append(
+            {
+                "path": relative_path,
+                "extension": _project_extension(relative_path),
+                "bytes_checked": min(
+                    len(text.encode("utf-8", errors="ignore")),
+                    PROJECT_PROFILE_TEXT_MAX_BYTES,
+                ),
+                "matched_terms": _context_terms_for_text(text),
+            }
+        )
+
+    volume_metadata = []
+    for relative_path in volume_candidates:
+        absolute_path = os.path.join(directory_path, relative_path)
+        extension = _project_extension(relative_path)
+        metadata = None
+        if extension in {".h5", ".hdf5"}:
+            metadata = _inspect_hdf5_container(absolute_path)
+        elif extension in {".tif", ".tiff", ".ome.tif", ".ome.tiff"}:
+            metadata = _inspect_tiff_container(absolute_path)
+        elif extension in {".zarr", ".n5"}:
+            metadata = {
+                "format": extension.lstrip("."),
+                "readable": os.path.isdir(absolute_path),
+            }
+        if metadata:
+            dataset_text = " ".join(
+                dataset.get("path", "")
+                for dataset in metadata.get("datasets", [])
+                if isinstance(dataset, dict)
+            )
+            if dataset_text:
+                inference_text_parts.append(dataset_text)
+            volume_metadata.append(
+                {
+                    "path": relative_path,
+                    "extension": extension,
+                    **metadata,
+                }
+            )
+
+    return {
+        "extension_counts": extension_counts,
+        "text_sources": text_sources,
+        "volume_metadata": volume_metadata,
+    }, "\n".join(inference_text_parts)
+
+
+def _best_context_hint(text: str, patterns: List[tuple]) -> tuple:
+    matches = []
+    for value, pattern in patterns:
+        count = len(re.findall(pattern, text, flags=re.IGNORECASE))
+        if count:
+            matches.append({"value": value, "count": count})
+    matches.sort(key=lambda item: item["count"], reverse=True)
+    if not matches:
+        return None, []
+    if len(matches) > 1 and matches[0]["count"] == matches[1]["count"]:
+        return None, matches
+    return matches[0]["value"], matches
+
+
+def _parse_voxel_size_nm_hint(text: str) -> Optional[List[float]]:
+    source = text or ""
+    if not source.strip():
+        return None
+    three_axis_match = re.search(
+        r"(?:voxel(?:\s+(?:size|spacing))?|resolution|spacing|pixel\s+size|scale)"
+        r"[^\d]{0,60}"
+        r"(\d+(?:\.\d+)?)\s*(?:x|by|,|;|/|-|\s)\s*"
+        r"(\d+(?:\.\d+)?)\s*(?:x|by|,|;|/|-|\s)\s*"
+        r"(\d+(?:\.\d+)?)(?:\s*(nm|nanometers?|um|\u00b5m|microns?))?",
+        source,
+        flags=re.IGNORECASE,
+    )
+    if three_axis_match:
+        unit_text = (three_axis_match.group(4) or source).lower()
+        multiplier = 1000.0 if re.search(r"\u00b5m|um|microns?", unit_text) else 1.0
+        return [
+            float(three_axis_match.group(index)) * multiplier for index in (1, 2, 3)
+        ]
+
+    unit_qualified_match = re.search(
+        r"(?:at|@)?\s*(\d+(?:\.\d+)?)\s*(?:x|by|,|;|/|-)\s*"
+        r"(\d+(?:\.\d+)?)\s*(?:x|by|,|;|/|-)\s*"
+        r"(\d+(?:\.\d+)?)\s*(nm|nanometers?|um|\u00b5m|microns?)",
+        source,
+        flags=re.IGNORECASE,
+    )
+    if unit_qualified_match:
+        unit_text = unit_qualified_match.group(4).lower()
+        multiplier = 1000.0 if re.search(r"\u00b5m|um|microns?", unit_text) else 1.0
+        return [
+            float(unit_qualified_match.group(index)) * multiplier for index in (1, 2, 3)
+        ]
+
+    isotropic_match = re.search(
+        r"(?:isotropic|cubic|same\s+voxel|same\s+scale)[^\d]{0,60}"
+        r"(\d+(?:\.\d+)?)(?:\s*(nm|nanometers?|um|\u00b5m|microns?))?",
+        source,
+        flags=re.IGNORECASE,
+    )
+    if isotropic_match:
+        unit_text = (isotropic_match.group(2) or source).lower()
+        multiplier = 1000.0 if re.search(r"\u00b5m|um|microns?", unit_text) else 1.0
+        value = float(isotropic_match.group(1)) * multiplier
+        return [value, value, value]
+    return None
+
+
+def _infer_project_context_hints(content_text: str) -> dict:
+    text = content_text or ""
+    hints = {"source": "content_spot_check"}
+
+    modality, modality_candidates = _best_context_hint(
+        text,
+        [
+            ("EM", r"\bEM\b|electron microscopy|electron microscope|FIB-SEM|TEM|SEM"),
+            ("X-ray / XRI volumetric microscopy", r"\bXRI\b|x[\s-]?ray|xray"),
+            ("CT", r"micro[\s-]?CT|micro.?ct|\bCT\b"),
+            ("fluorescence microscopy", r"fluorescen|confocal|light[\s-]?sheet"),
+            ("MRI", r"\bMRI\b"),
+        ],
+    )
+    target, target_candidates = _best_context_hint(
+        text,
+        [
+            ("mitochondria", r"mitochond(?:ria|rion|rial)"),
+            ("fibres", r"\b(?:fiber|fibers|fibre|fibres|cytotape)\b"),
+            ("nuclei", r"\b(?:nuclei|nucleus|nuclear)\b"),
+            ("neurites", r"\b(?:neurite|axon|dendrite|neuron[_\s-]?ids?)\b"),
+            ("synapses", r"\b(?:synapse|synaptic|presynaptic|postsynaptic|cleft)\b"),
+            ("membranes", r"\bmembranes?\b"),
+            ("cells", r"\bcells?\b"),
+        ],
+    )
+    task_goal, task_candidates = _best_context_hint(
+        text,
+        [
+            ("segmentation", r"\bsegment(?:ation|ed|ing)?\b"),
+            ("proofreading", r"\b(?:proofread|curat|correct)\b"),
+            ("training", r"\b(?:train|retrain|fine[\s-]?tune)\b"),
+            ("comparison", r"\b(?:compare|metric|evaluate|evaluation)\b"),
+        ],
+    )
+    priority, priority_candidates = _best_context_hint(
+        text,
+        [
+            ("accuracy", r"\b(?:accuracy|accurate|quality|careful)\b"),
+            ("speed", r"\b(?:speed|fast|quick|smoke|rough)\b"),
+        ],
+    )
+
+    if modality:
+        hints["imaging_modality"] = modality
+    if target:
+        hints["target_structure"] = target
+    if task_goal:
+        hints["task_goal"] = task_goal
+    if priority:
+        hints["optimization_priority"] = priority
+    if modality and target:
+        lower_modality = modality.lower()
+        lower_target = target.lower()
+        if "xri" in lower_modality and "fibre" in lower_target:
+            hints["task_family"] = "XRI fibre instance segmentation"
+        elif "mitochond" in lower_target:
+            hints["task_family"] = "mitochondria instance segmentation"
+        elif "synap" in lower_target:
+            hints["task_family"] = "synapse segmentation"
+        elif "nuclei" in lower_target:
+            hints["task_family"] = "nuclei instance segmentation"
+    voxel_size_nm = _parse_voxel_size_nm_hint(text)
+    if voxel_size_nm:
+        hints["voxel_size_nm"] = voxel_size_nm
+        hints["voxel_size_source"] = "content_spot_check"
+    if modality_candidates:
+        hints["modality_candidates"] = modality_candidates[:4]
+    if target_candidates:
+        hints["target_candidates"] = target_candidates[:6]
+    if task_candidates:
+        hints["task_goal_candidates"] = task_candidates[:4]
+    if priority_candidates:
+        hints["priority_candidates"] = priority_candidates[:3]
+    return hints
+
+
+def _project_role_directories(
+    role_paths: List[str], *, max_directories: int = 6
+) -> List[dict]:
+    grouped = {}
+    for role_path in role_paths:
+        directory = os.path.dirname(role_path) or "."
+        if directory not in grouped:
+            grouped[directory] = {"path": directory, "count": 0, "examples": []}
+        grouped[directory]["count"] += 1
+        if len(grouped[directory]["examples"]) < 3:
+            grouped[directory]["examples"].append(role_path)
+    return sorted(
+        grouped.values(),
+        key=lambda item: (-item["count"], item["path"]),
+    )[:max_directories]
+
+
+def _project_primary_root(
+    role_directories: dict, role: str, counts: dict
+) -> Optional[str]:
+    directories = role_directories.get(role) or []
+    if not directories:
+        return None
+    # A single-file project is clearer as a file. Multi-volume projects should
+    # default to the folder that owns the batch.
+    if counts.get(role, 0) <= 1:
+        return None
+    return directories[0]["path"]
+
+
+def _prepend_preferred_role_directory(
+    role_directories: dict,
+    role: str,
+    preferred_root: Optional[str],
+    role_paths: List[str],
+    *,
+    max_directories: int = 6,
+) -> None:
+    root = str(preferred_root or "").strip().replace("\\", "/").rstrip("/")
+    if not root:
+        return
+    prefix = f"{root}/"
+    examples = [
+        path
+        for path in role_paths
+        if path == root or str(path).replace("\\", "/").startswith(prefix)
+    ]
+    if not examples:
+        return
+    preferred = {
+        "path": root,
+        "count": len(examples),
+        "examples": examples[:3],
+        "source": "project_manifest",
+    }
+    remaining = [
+        item for item in (role_directories.get(role) or []) if item.get("path") != root
+    ]
+    role_directories[role] = [preferred, *remaining][:max_directories]
+
+
+def _first_project_path(roles: dict, role: str) -> Optional[str]:
+    values = roles.get(role) or []
+    return values[0] if values else None
+
+
+def _load_project_manifest_profile(directory_path: str) -> Optional[dict]:
+    manifest_path = os.path.join(directory_path, "project_manifest.json")
+    if not os.path.isfile(manifest_path):
+        return None
+    try:
+        with open(manifest_path, "r", encoding="utf-8") as handle:
+            manifest = json.load(handle)
+    except (OSError, json.JSONDecodeError):
+        return None
+    return manifest if isinstance(manifest, dict) else None
+
+
+def _unique_project_paths(paths: List[Optional[str]]) -> List[str]:
+    seen = set()
+    unique = []
+    for path in paths:
+        value = str(path or "").strip().replace("\\", "/")
+        if not value or value in seen:
+            continue
+        seen.add(value)
+        unique.append(value)
+    return unique
+
+
+def _manifest_volume_profile(manifest: Optional[dict]) -> dict:
+    if not isinstance(manifest, dict):
+        return {}
+    volumes = [item for item in manifest.get("volumes") or [] if isinstance(item, dict)]
+    if not volumes:
+        return {}
+    active_paths = manifest.get("active_paths")
+    if not isinstance(active_paths, dict):
+        active_paths = {}
+
+    image_paths = _unique_project_paths([volume.get("image") for volume in volumes])
+    label_paths = _unique_project_paths(
+        [volume.get("segmentation") for volume in volumes if volume.get("segmentation")]
+    )
+    paired_examples = [
+        {"image": volume.get("image"), "label": volume.get("segmentation")}
+        for volume in volumes
+        if volume.get("image") and volume.get("segmentation")
+    ]
+    image_root = active_paths.get("image_root") or (
+        os.path.commonpath(image_paths) if len(image_paths) > 1 else None
+    )
+    label_root = active_paths.get("label_root") or (
+        os.path.commonpath(label_paths) if len(label_paths) > 1 else None
+    )
+    volume_sets = []
+    if image_paths:
+        volume_sets.append(
+            {
+                "id": "manifest-active-set",
+                "name": "manifest raw + masks",
+                "image_root": image_root,
+                "label_root": label_root,
+                "image_count": len(image_paths),
+                "label_count": len(label_paths),
+                "pair_count": len(paired_examples),
+                "examples": paired_examples[:3],
+                "source": "project_manifest",
+            }
+        )
+
+    voxel_size = manifest.get("voxel_size")
+    voxel_size_nm = None
+    if isinstance(voxel_size, dict):
+        voxel_size_nm = voxel_size.get("zyx_nm")
+    hints = {}
+    if manifest.get("imaging_modality"):
+        hints["imaging_modality"] = manifest.get("imaging_modality")
+    if manifest.get("target_structure"):
+        hints["target_structure"] = manifest.get("target_structure")
+    if manifest.get("task_family"):
+        hints["task_family"] = manifest.get("task_family")
+    if manifest.get("task"):
+        hints["task_goal"] = manifest.get("task")
+    if voxel_size_nm:
+        hints["voxel_size_nm"] = voxel_size_nm
+        hints["voxel_size_source"] = "project_manifest.json"
+    summary = manifest.get("initial_progress_summary")
+    if isinstance(summary, dict):
+        gt = int(summary.get("ground_truth") or 0)
+        draft = int(summary.get("needs_proofreading") or 0)
+        missing = int(summary.get("missing_segmentation") or 0)
+        hints["mask_status"] = (
+            f"mixed: {gt} ground-truth masks, {draft} draft masks, "
+            f"{missing} image-only targets"
+        )
+    workflow_split = manifest.get("workflow_split")
+    if isinstance(workflow_split, dict):
+        if workflow_split.get("image_only_inference_targets"):
+            hints["image_only_strategy"] = (
+                "run inference on image-only volumes after training"
+            )
+        if workflow_split.get("ground_truth_training_volumes"):
+            hints["training_policy"] = "train only on confirmed ground-truth masks"
+
+    return {
+        "active_paths": active_paths,
+        "image_paths": image_paths,
+        "label_paths": label_paths,
+        "paired_examples": paired_examples,
+        "volume_sets": volume_sets,
+        "context_hints": hints,
+    }
+
+
+def _project_stage_status(
+    *,
+    ready: bool,
+    missing: Optional[List[str]] = None,
+    ready_label: str,
+    needed_label: str,
+    blocked_label: str = "Add an image volume first.",
+) -> dict:
+    missing = missing or []
+    if ready:
+        return {"status": "ready", "label": ready_label, "missing": []}
+    if missing:
+        return {"status": "needs_input", "label": needed_label, "missing": missing}
+    return {"status": "blocked", "label": blocked_label, "missing": []}
+
+
+def _build_project_workable_schema(
+    roles: dict,
+    counts: dict,
+    paired_examples: List[dict],
+    role_directories: dict,
+    volume_sets: List[dict],
+    *,
+    truncated: bool,
+) -> dict:
+    primary_image = _first_project_path(roles, "image") or _first_project_path(
+        roles, "volume"
+    )
+    primary_label = (
+        paired_examples[0]["label"]
+        if paired_examples
+        else _first_project_path(roles, "label")
+    )
+    primary_prediction = _first_project_path(roles, "prediction")
+    primary_config = _first_project_path(roles, "config")
+    primary_checkpoint = _first_project_path(roles, "checkpoint")
+    has_image = bool(primary_image)
+    has_mask_like = bool(primary_label or primary_prediction)
+    has_image_label = bool(primary_image and primary_label)
+    # Configs are implementation details the agent can infer from presets. They
+    # are tracked for provenance, but should not block a biologist from starting
+    # an otherwise valid image/checkpoint or image/label workflow.
+    has_inference_inputs = bool(primary_image and primary_checkpoint)
+    has_training_inputs = bool(primary_image and primary_label)
+    has_evaluation_inputs = bool(primary_label and counts.get("prediction", 0) >= 2)
+
+    if not has_image:
+        mode = "not_workable"
+        summary = "No image volume detected yet."
+    elif has_evaluation_inputs and has_training_inputs and primary_checkpoint:
+        mode = "closed_loop_ready"
+        summary = (
+            "Ready for visualization, proofreading, training, and before/after checks."
+        )
+    elif has_image_label:
+        mode = "image_mask_pair"
+        summary = "Ready to start from an image and mask/label pair."
+    else:
+        mode = "image_only"
+        summary = "Ready to start from an image volume; masks, configs, or checkpoints can be added later."
+
+    inference_missing = []
+    if not primary_image:
+        inference_missing.append("image volume")
+    if not primary_checkpoint:
+        inference_missing.append("checkpoint")
+
+    proofreading_missing = []
+    if not primary_image:
+        proofreading_missing.append("image volume")
+    if not has_mask_like:
+        proofreading_missing.append("mask, label, or prediction")
+
+    training_missing = []
+    if not primary_image:
+        training_missing.append("image volume")
+    if not primary_label:
+        training_missing.append("label or corrected mask")
+
+    evaluation_missing = []
+    if counts.get("prediction", 0) < 2:
+        evaluation_missing.append("baseline and candidate predictions")
+    if not primary_label:
+        evaluation_missing.append("reference label or ground truth")
+
+    return {
+        "schema_version": "pytc-project-profile/v1",
+        "workable": has_image,
+        "mode": mode,
+        "summary": summary,
+        "truncated": truncated,
+        "primary_paths": {
+            "image": primary_image,
+            "image_root": _project_primary_root(role_directories, "image", counts)
+            or _project_primary_root(role_directories, "volume", counts),
+            "label": primary_label,
+            "label_root": _project_primary_root(role_directories, "label", counts),
+            "mask": primary_label or primary_prediction,
+            "mask_root": _project_primary_root(role_directories, "label", counts),
+            "prediction": primary_prediction,
+            "prediction_root": _project_primary_root(
+                role_directories, "prediction", counts
+            ),
+            "config": primary_config,
+            "checkpoint": primary_checkpoint,
+        },
+        "role_directories": role_directories,
+        "volume_sets": volume_sets,
+        "stages": {
+            "setup": _project_stage_status(
+                ready=has_image,
+                ready_label="Image volume detected.",
+                needed_label="Choose an image volume.",
+            ),
+            "visualization": _project_stage_status(
+                ready=has_image,
+                ready_label="Ready to visualize.",
+                needed_label="Choose an image volume.",
+            ),
+            "inference": _project_stage_status(
+                ready=has_inference_inputs,
+                ready_label="Ready to run inference.",
+                needed_label="Needs inference inputs.",
+                missing=inference_missing,
+            ),
+            "proofreading": _project_stage_status(
+                ready=bool(primary_image and has_mask_like),
+                ready_label="Ready to proofread masks.",
+                needed_label="Needs a mask, label, or prediction.",
+                missing=proofreading_missing,
+            ),
+            "training": _project_stage_status(
+                ready=has_training_inputs,
+                ready_label="Ready to train from labels/corrections.",
+                needed_label="Needs training inputs.",
+                missing=training_missing,
+            ),
+            "evaluation": _project_stage_status(
+                ready=has_evaluation_inputs,
+                ready_label="Ready to compare before/after predictions.",
+                needed_label="Needs comparison inputs.",
+                missing=evaluation_missing,
+            ),
+        },
+    }
+
+
+def _infer_project_volume_sets(roles: dict, role_directories: dict) -> List[dict]:
+    image_paths = roles.get("image") or roles.get("volume") or []
+    label_paths = roles.get("label") or []
+    volume_sets = []
+
+    if not image_paths:
+        return volume_sets
+
+    labels_by_directory = {}
+    for label_path in label_paths:
+        labels_by_directory.setdefault(os.path.dirname(label_path) or ".", []).append(
+            label_path
+        )
+
+    image_directories = (
+        role_directories.get("image") or role_directories.get("volume") or []
+    )
+    for image_directory in image_directories:
+        directory = image_directory["path"]
+        images_in_directory = [
+            image_path
+            for image_path in image_paths
+            if (os.path.dirname(image_path) or ".") == directory
+        ]
+        best_label_directory = None
+        best_pairs = []
+        for label_directory in role_directories.get("label", []):
+            labels_in_directory = labels_by_directory.get(label_directory["path"], [])
+            pairs = []
+            for image_path in images_in_directory:
+                for label_path in labels_in_directory:
+                    if _looks_like_image_label_pair(image_path, label_path):
+                        pairs.append({"image": image_path, "label": label_path})
+                        break
+            if len(pairs) > len(best_pairs):
+                best_pairs = pairs
+                best_label_directory = label_directory
+
+        name = os.path.basename(directory) or directory
+        label_root = best_label_directory["path"] if best_label_directory else None
+        if label_root and os.path.basename(label_root) == name:
+            set_name = name
+        elif label_root:
+            set_name = f"{name} + {os.path.basename(label_root) or label_root}"
+        else:
+            set_name = name
+
+        if best_pairs or image_directory["count"] > 1:
+            volume_sets.append(
+                {
+                    "id": f"set-{len(volume_sets) + 1}",
+                    "name": set_name,
+                    "image_root": directory,
+                    "label_root": label_root,
+                    "image_count": image_directory["count"],
+                    "label_count": (
+                        best_label_directory["count"] if best_label_directory else 0
+                    ),
+                    "pair_count": len(best_pairs),
+                    "examples": best_pairs[:3],
+                }
+            )
+        if len(volume_sets) >= 6:
+            break
+
+    if not volume_sets and image_paths:
+        primary_image_directory = (
+            image_directories[0].get("path")
+            if image_directories
+            else os.path.dirname(image_paths[0]) or "."
+        )
+        primary_label_directory = (
+            role_directories.get("label", [{}])[0].get("path")
+            if role_directories.get("label")
+            else None
+        )
+        volume_sets.append(
+            {
+                "id": "set-1",
+                "name": os.path.basename(primary_image_directory)
+                or primary_image_directory,
+                "image_root": primary_image_directory,
+                "label_root": primary_label_directory,
+                "image_count": len(image_paths),
+                "label_count": len(label_paths),
+                "pair_count": 0,
+                "examples": [],
+            }
+        )
+
+    return volume_sets
+
+
+def _record_project_role_path(
+    roles: dict,
+    counts: dict,
+    role: Optional[str],
+    relative_path: str,
+) -> None:
+    if role and role in roles:
+        counts[role] += 1
+        roles[role].append(relative_path)
+
+
+def _apply_manifest_profile_to_roles(roles: dict, manifest_profile: dict) -> None:
+    if not manifest_profile:
+        return
+    image_paths = manifest_profile.get("image_paths") or []
+    label_paths = manifest_profile.get("label_paths") or []
+    active_paths = manifest_profile.get("active_paths") or {}
+    if image_paths:
+        roles["image"] = _unique_project_paths(
+            [*image_paths, *(roles.get("image") or [])]
+        )
+    if label_paths:
+        roles["label"] = _unique_project_paths(
+            [*label_paths, *(roles.get("label") or [])]
+        )
+    active_config = active_paths.get("config")
+    if active_config:
+        roles["config"] = _unique_project_paths(
+            [active_config, *(roles.get("config") or [])]
+        )
+
+
+def _scan_project_profile(directory_path: str, *, audit_detail: str = "full") -> dict:
+    roles = {
+        "image": [],
+        "label": [],
+        "prediction": [],
+        "config": [],
+        "checkpoint": [],
+        "volume": [],
+        "notes": [],
+    }
+    counts = {role: 0 for role in roles}
+    extension_counts = {}
+    scanned_files = 0
+    truncated = False
+
+    for current_dir, dirnames, filenames in os.walk(directory_path):
+        next_dirnames = []
+        for dirname in sorted(dirnames):
+            if _is_ignored_system_file(dirname):
+                continue
+            absolute_dir = os.path.join(current_dir, dirname)
+            relative_dir = os.path.relpath(absolute_dir, directory_path)
+            if _project_extension(dirname) in {".zarr", ".n5"}:
+                extension = _project_extension(dirname)
+                extension_counts[extension] = extension_counts.get(extension, 0) + 1
+                _record_project_role_path(
+                    roles,
+                    counts,
+                    _role_for_project_file(relative_dir),
+                    relative_dir,
+                )
+                continue
+            next_dirnames.append(dirname)
+        dirnames[:] = next_dirnames
+        for filename in sorted(filenames):
+            if _is_ignored_system_file(filename):
+                continue
+            scanned_files += 1
+            if scanned_files > PROJECT_PROFILE_MAX_FILES:
+                truncated = True
+                break
+            absolute_path = os.path.join(current_dir, filename)
+            relative_path = os.path.relpath(absolute_path, directory_path)
+            extension = _project_extension(filename) or "<none>"
+            extension_counts[extension] = extension_counts.get(extension, 0) + 1
+            _record_project_role_path(
+                roles,
+                counts,
+                _role_for_project_file(relative_path),
+                relative_path,
+            )
+        if truncated:
+            break
+
+    manifest = _load_project_manifest_profile(directory_path)
+    manifest_profile = _manifest_volume_profile(manifest)
+    _apply_manifest_profile_to_roles(roles, manifest_profile)
+
+    paired_examples = manifest_profile.get("paired_examples") or []
+    for image_path in roles["image"]:
+        if len(paired_examples) >= 4:
+            break
+        for label_path in roles["label"]:
+            if _looks_like_image_label_pair(image_path, label_path):
+                pair = {"image": image_path, "label": label_path}
+                if pair not in paired_examples:
+                    paired_examples.append(pair)
+                break
+
+    role_directories = {
+        role: _project_role_directories(paths) for role, paths in roles.items()
+    }
+    manifest_active_paths = manifest_profile.get("active_paths") or {}
+    _prepend_preferred_role_directory(
+        role_directories,
+        "image",
+        manifest_active_paths.get("image_root"),
+        roles.get("image") or [],
+    )
+    _prepend_preferred_role_directory(
+        role_directories,
+        "label",
+        manifest_active_paths.get("label_root"),
+        roles.get("label") or [],
+    )
+    volume_sets = manifest_profile.get("volume_sets") or _infer_project_volume_sets(
+        roles, role_directories
+    )
+    examples = {role: paths[:8] for role, paths in roles.items()}
+    schema = _build_project_workable_schema(
+        examples,
+        counts,
+        paired_examples,
+        role_directories,
+        volume_sets,
+        truncated=truncated,
+    )
+    content_signals, content_text = _collect_project_content_signals(
+        directory_path,
+        roles,
+        extension_counts,
+    )
+    use_summary_audit = audit_detail == "summary"
+    audit = _build_project_audit(
+        directory_path,
+        roles,
+        paired_examples,
+        include_volume_details=not use_summary_audit,
+        collect_stats=not use_summary_audit,
+    )
+    context_hints = _merge_audit_context_hints(
+        _infer_project_context_hints(content_text),
+        audit,
+    )
+    context_hints = {
+        **context_hints,
+        **(manifest_profile.get("context_hints") or {}),
+    }
+    schema["context_hints"] = context_hints
+    schema["audit"] = audit
+    if manifest_profile:
+        schema["manifest"] = {
+            "title": manifest.get("title") if isinstance(manifest, dict) else None,
+            "active_paths": manifest_profile.get("active_paths") or {},
+            "initial_progress_summary": (
+                manifest.get("initial_progress_summary")
+                if isinstance(manifest, dict)
+                else None
+            ),
+        }
+
+    required_roles = {
+        "image": counts["image"] > 0,
+        "label": counts["label"] > 0,
+        "config": counts["config"] > 0,
+        "checkpoint": counts["checkpoint"] > 0,
+        "prediction": counts["prediction"] >= 2,
+    }
+    missing_roles = [role for role, present in required_roles.items() if not present]
+
+    return {
+        "scanned_files": min(scanned_files, PROJECT_PROFILE_MAX_FILES),
+        "truncated": truncated,
+        "counts": counts,
+        "examples": examples,
+        "role_directories": role_directories,
+        "volume_sets": volume_sets,
+        "paired_examples": paired_examples,
+        "content_signals": content_signals,
+        "context_hints": context_hints,
+        "audit": audit,
+        "ready_for_smoke": not missing_roles,
+        "missing_roles": missing_roles,
+        "schema": schema,
+    }
+
+
+def _project_context_file_path(directory_path: str) -> str:
+    source_dir = os.path.abspath(os.path.expanduser(directory_path))
+    if not os.path.isdir(source_dir):
+        raise HTTPException(status_code=400, detail="Directory does not exist")
+    return os.path.join(source_dir, PROJECT_CONTEXT_FILENAME)
+
+
+def _assert_project_context_access(
+    db: Session,
+    *,
+    user_id: int,
+    directory_path: str,
+) -> None:
+    source_dir = os.path.abspath(os.path.expanduser(directory_path))
+    if _is_managed_upload_path(user_id, source_dir):
+        return
+    mounted_roots = (
+        db.query(models.File)
+        .filter(
+            models.File.user_id == user_id,
+            models.File.path == "root",
+            models.File.is_folder.is_(True),
+            models.File.physical_path.isnot(None),
+        )
+        .all()
+    )
+    for root in mounted_roots:
+        root_path = os.path.abspath(os.path.expanduser(root.physical_path or ""))
+        if source_dir == root_path or source_dir.startswith(f"{root_path}{os.sep}"):
+            return
+    raise HTTPException(
+        status_code=403,
+        detail="Project context can only be read or written for mounted projects.",
+    )
+
+
+def _read_project_context_profile(directory_path: str) -> Optional[dict]:
+    context_path = _project_context_file_path(directory_path)
+    if not os.path.isfile(context_path):
+        return None
+    try:
+        with open(context_path, "r", encoding="utf-8") as handle:
+            data = json.load(handle)
+    except (OSError, json.JSONDecodeError) as exc:
+        raise HTTPException(
+            status_code=500, detail="Project context file could not be read"
+        ) from exc
+    return data if isinstance(data, dict) else None
+
+
+def _write_project_context_profile(directory_path: str, profile: dict) -> dict:
+    context_path = _project_context_file_path(directory_path)
+    now = datetime.now(timezone.utc).isoformat()
+    existing = _read_project_context_profile(directory_path) or {}
+    payload = {
+        **existing,
+        **(profile or {}),
+        "schema_version": "pytc-project-context/v1",
+        "updated_at": now,
+    }
+    payload.setdefault("created_at", existing.get("created_at") or now)
+    temp_path = f"{context_path}.tmp"
+    try:
+        with open(temp_path, "w", encoding="utf-8") as handle:
+            json.dump(payload, handle, indent=2, sort_keys=True)
+            handle.write("\n")
+        os.replace(temp_path, context_path)
+    except OSError as exc:
+        try:
+            if os.path.exists(temp_path):
+                os.remove(temp_path)
+        except OSError:
+            pass
+        raise HTTPException(
+            status_code=500, detail="Project context file could not be written"
+        ) from exc
+    return payload
+
+
+def _delete_project_context_profile(directory_path: str) -> bool:
+    context_path = _project_context_file_path(directory_path)
+    if not os.path.exists(context_path):
+        return False
+    try:
+        os.remove(context_path)
+    except OSError as exc:
+        raise HTTPException(
+            status_code=500, detail="Project context file could not be deleted"
+        ) from exc
+    return True
 
 
 def _ensure_unique_name(
@@ -58,6 +1911,82 @@ def _ensure_unique_name(
         index += 1
 
 
+def _normalize_mount_directory_input(raw_value: str) -> str:
+    value = str(raw_value or "").strip()
+    if not value:
+        raise HTTPException(status_code=400, detail="Project path is required")
+
+    parsed = urlparse(value)
+    if parsed.scheme == "file":
+        value = unquote(parsed.path)
+    elif parsed.scheme in {"http", "https"}:
+        query = parse_qs(parsed.query)
+        for key in ("directory_path", "project_path", "path", "project"):
+            if query.get(key) and query[key][0]:
+                value = query[key][0]
+                break
+        else:
+            candidate = unquote(parsed.path or "")
+            if candidate.startswith(("/home/", "/mnt/", "/data/", "/tmp/")):
+                value = candidate
+            elif os.getenv("PYTC_INITIAL_PROJECT_ROOT"):
+                value = os.getenv("PYTC_INITIAL_PROJECT_ROOT", "")
+            else:
+                raise HTTPException(
+                    status_code=400,
+                    detail=(
+                        "Remote browser mounts need a server path, or a URL with "
+                        "a path/directory_path query parameter."
+                    ),
+                )
+
+    return os.path.abspath(os.path.expanduser(value))
+
+
+def _mounted_project_response(
+    source_dir: str,
+    mounted_root: models.File,
+    *,
+    mounted_folders: int,
+    mounted_files: int,
+    message: str,
+) -> dict:
+    return {
+        "message": message,
+        "directory_path": source_dir,
+        "mounted_root_id": mounted_root.id,
+        "mount_name": mounted_root.name,
+        "mounted_folders": mounted_folders,
+        "mounted_files": mounted_files,
+        "profile": _scan_project_profile(source_dir),
+    }
+
+
+def _count_indexed_mount_descendants(
+    db: Session,
+    *,
+    user_id: int,
+    mounted_root_id: int,
+) -> tuple[int, int]:
+    pending_parent_ids = [str(mounted_root_id)]
+    mounted_folders = 0
+    mounted_files = 0
+    while pending_parent_ids:
+        parent_id = pending_parent_ids.pop(0)
+        children = (
+            db.query(models.File)
+            .filter(models.File.user_id == user_id, models.File.path == parent_id)
+            .all()
+        )
+        for child in children:
+            if child.is_folder:
+                mounted_folders += 1
+                pending_parent_ids.append(str(child.id))
+            else:
+                mounted_files += 1
+    return mounted_folders, mounted_files
+
+
 def _is_managed_upload_path(user_id: int, physical_path: Optional[str]) -> bool:
     if not physical_path:
         return False
@@ -69,6 +1998,74 @@ def _is_managed_upload_path(user_id: int, physical_path: Optional[str]) -> bool:
         return False
 
 
+def _repair_stale_mounted_entries(db: Session, user_id: int) -> None:
+    candidates = (
+        db.query(models.File)
+        .filter(
+            models.File.user_id == user_id,
+            models.File.physical_path.isnot(None),
+            models.File.path != "root",
+        )
+        .all()
+    )
+
+    changed = False
+    for entry in candidates:
+        if not entry.physical_path:
+            continue
+        if _is_managed_upload_path(user_id, entry.physical_path):
+            continue
+        if os.path.exists(entry.physical_path):
+            continue
+
+        repaired = resolve_existing_path(entry.physical_path)
+        if repaired is None or not repaired.exists():
+            continue
+        if entry.is_folder and not repaired.is_dir():
+            continue
+        if not entry.is_folder and not repaired.is_file():
+            continue
+
+        entry.physical_path = str(repaired)
+        entry.name = repaired.name
+        if not entry.is_folder:
+            entry.type = mimetypes.guess_type(str(repaired))[0] or entry.type
+            try:
+                entry.size = _format_size(repaired.stat().st_size)
+            except OSError:
+                pass
+        changed = True
+
+    if changed:
+        db.commit()
+
+
+def _prune_missing_managed_upload_entries(db: Session, user_id: int) -> None:
+    candidates = (
+        db.query(models.File)
+        .filter(
+            models.File.user_id == user_id,
+            models.File.is_folder.is_(False),
+            models.File.physical_path.isnot(None),
+        )
+        .all()
+    )
+
+    removed = False
+    for entry in candidates:
+        if not entry.physical_path:
+            continue
+        if not _is_managed_upload_path(user_id, entry.physical_path):
+            continue
+        if os.path.exists(entry.physical_path):
+            continue
+        db.delete(entry)
+        removed = True
+
+    if removed:
+        db.commit()
+
+
 def _delete_file_tree(
     db: Session,
     user_id: int,
@@ -180,6 +2177,49 @@ def read_users_me(current_user: models.User = Depends(get_current_user)):
     return current_user
 
 
+@router.get("/users/me/projects", response_model=models.UserProjectListResponse)
+def list_current_user_projects(
+    current_user: models.User = Depends(get_current_user),
+    db: Session = Depends(database.get_db),
+):
+    mounted_roots = (
+        db.query(models.File)
+        .filter(
+            models.File.user_id == current_user.id,
+            models.File.path == "root",
+            models.File.is_folder.is_(True),
+            models.File.physical_path.isnot(None),
+        )
+        .order_by(models.File.created_at.asc(), models.File.id.asc())
+        .all()
+    )
+    mounted_projects = []
+    for root in mounted_roots:
+        directory_path = os.path.abspath(os.path.expanduser(root.physical_path or ""))
+        if not os.path.isdir(directory_path):
+            continue
+        mounted_folders, mounted_files = _count_indexed_mount_descendants(
+            db,
+            user_id=current_user.id,
+            mounted_root_id=root.id,
+        )
+        mounted_projects.append(
+            models.MountedProjectResponse(
+                mounted_root_id=root.id,
+                name=root.name,
+                directory_path=directory_path,
+                mounted_folders=mounted_folders,
+                mounted_files=mounted_files,
+                profile=_scan_project_profile(directory_path, audit_detail="summary"),
+                created_at=root.created_at,
+            )
+        )
+    return models.UserProjectListResponse(
+        user=current_user,
+        mounted_projects=mounted_projects,
+    )
+
+
 # File Management Endpoints
 
 
@@ -189,13 +2229,36 @@ def get_files(
     current_user: models.User = Depends(get_current_user),
     db: Session = Depends(database.get_db),
 ):
+    _repair_stale_mounted_entries(db, current_user.id)
+    _prune_missing_managed_upload_entries(db, current_user.id)
     query = db.query(models.File).filter(models.File.user_id == current_user.id)
     if parent is not None:
+        if parent != "root":
+            try:
+                parent_id = int(parent)
+            except (TypeError, ValueError):
+                parent_id = -1
+            parent_folder = (
+                db.query(models.File)
+                .filter(
+                    models.File.id == parent_id,
+                    models.File.user_id == current_user.id,
+                    models.File.is_folder.is_(True),
+                )
+                .first()
+            )
+            if not parent_folder:
+                raise HTTPException(
+                    status_code=404,
+                    detail=f"Folder is no longer mounted or indexed: {parent}",
+                )
         query = query.filter(models.File.path == parent)
 
     return [
         file
-        for file in query.order_by(models.File.is_folder.desc(), models.File.name.asc()).all()
+        for file in query.order_by(
+            models.File.is_folder.desc(), models.File.name.asc()
+        ).all()
         if not _is_ignored_system_file(file.name)
     ]
 
@@ -287,9 +2350,7 @@ def upload_file(
     db: Session = Depends(database.get_db),
 ):
     if _is_ignored_system_file(file.filename):
-        raise HTTPException(
-            status_code=400, detail="System metadata files are ignored"
-        )
+        raise HTTPException(status_code=400, detail="System metadata files are ignored")
 
     # Create uploads directory if not exists
     upload_dir = f"uploads/{current_user.id}"
@@ -406,9 +2467,12 @@ def mount_directory(
     # This endpoint creates an app-managed file index for a project root.
     # The same contract can later be backed by cloud project files/URIs for
     # programmatic access without changing the UI workflow.
-    source_dir = os.path.abspath(os.path.expanduser(mount_request.directory_path))
+    source_dir = _normalize_mount_directory_input(mount_request.directory_path)
     if not os.path.isdir(source_dir):
-        raise HTTPException(status_code=400, detail="Directory does not exist")
+        raise HTTPException(
+            status_code=400,
+            detail=f"Directory does not exist on the server: {source_dir}",
+        )
 
     destination_path = mount_request.destination_path or "root"
     if destination_path != "root":
@@ -430,6 +2494,33 @@ def mount_directory(
         if not destination_folder:
             raise HTTPException(status_code=404, detail="Destination folder not found")
 
+    existing_mount = (
+        db.query(models.File)
+        .filter(
+            models.File.user_id == current_user.id,
+            models.File.path == destination_path,
+            models.File.is_folder.is_(True),
+            models.File.physical_path == source_dir,
+        )
+        .first()
+    )
+    if existing_mount:
+        child_count = (
+            db.query(models.File)
+            .filter(
+                models.File.user_id == current_user.id,
+                models.File.path == str(existing_mount.id),
+            )
+            .count()
+        )
+        return _mounted_project_response(
+            source_dir,
+            existing_mount,
+            mounted_folders=1,
+            mounted_files=child_count,
+            message=f"{existing_mount.name} is already mounted.",
+        )
+
     default_name = os.path.basename(source_dir.rstrip(os.sep)) or "mounted-project"
     requested_name = (
         mount_request.mount_name.strip()
@@ -505,11 +2596,144 @@ def mount_directory(
 
     db.commit()
 
+    return _mounted_project_response(
+        source_dir,
+        mounted_root,
+        mounted_folders=mounted_folders,
+        mounted_files=mounted_files,
+        message=f"Mounted {mounted_files} files from {source_dir}",
+    )
+
+
+@router.get("/files/project-suggestions")
+def list_project_suggestions(
+    current_user: models.User = Depends(get_current_user),
+    db: Session = Depends(database.get_db),
+):
+    suggestions = []
+    mounted_roots = (
+        db.query(models.File)
+        .filter(
+            models.File.user_id == current_user.id,
+            models.File.path == "root",
+            models.File.is_folder.is_(True),
+            models.File.physical_path.isnot(None),
+        )
+        .all()
+    )
+    mounted_by_path = {
+        os.path.abspath(os.path.expanduser(root.physical_path)): root
+        for root in mounted_roots
+        if root.physical_path
+    }
+    for candidate in _project_suggestion_candidates():
+        directory_path = os.path.abspath(
+            os.path.expanduser(candidate["directory_path"])
+        )
+        if not os.path.isdir(directory_path):
+            continue
+        mounted_root = mounted_by_path.get(directory_path)
+        profile = _scan_project_profile(directory_path, audit_detail="summary")
+        candidate_context_hints = candidate.get("context_hints")
+        if isinstance(candidate_context_hints, dict):
+            scanned_context_hints = profile.get("context_hints")
+            if not isinstance(scanned_context_hints, dict):
+                scanned_context_hints = {}
+            merged_context_hints = {
+                **scanned_context_hints,
+                **candidate_context_hints,
+            }
+            profile["context_hints"] = merged_context_hints
+            schema = profile.get("schema")
+            if isinstance(schema, dict):
+                schema["context_hints"] = merged_context_hints
+        suggestions.append(
+            {
+                **candidate,
+                "directory_path": directory_path,
+                "already_mounted": mounted_root is not None,
+                "mounted_root_id": mounted_root.id if mounted_root else None,
+                "profile": profile,
+            }
+        )
+    suggested_paths = {item["directory_path"] for item in suggestions}
+    for mounted_path, mounted_root in mounted_by_path.items():
+        if mounted_path in suggested_paths or not os.path.isdir(mounted_path):
+            continue
+        suggestions.append(
+            {
+                "id": f"mounted-{mounted_root.id}",
+                "name": mounted_root.name,
+                "directory_path": mounted_path,
+                "description": "Mounted project directory.",
+                "recommended": False,
+                "already_mounted": True,
+                "mounted_root_id": mounted_root.id,
+                "profile": _scan_project_profile(
+                    mounted_path,
+                    audit_detail="summary",
+                ),
+            }
+        )
+    return suggestions
+
+
+@router.get("/files/project-context")
+def read_project_context_profile(
+    directory_path: str,
+    current_user: models.User = Depends(get_current_user),
+    db: Session = Depends(database.get_db),
+):
+    _assert_project_context_access(
+        db,
+        user_id=current_user.id,
+        directory_path=directory_path,
+    )
+    profile = _read_project_context_profile(directory_path)
     return {
-        "message": f"Mounted {mounted_files} files from {source_dir}",
-        "mounted_root_id": mounted_root.id,
-        "mounted_folders": mounted_folders,
-        "mounted_files": mounted_files,
+        "exists": profile is not None,
+        "filename": PROJECT_CONTEXT_FILENAME,
+        "profile": profile,
+    }
+
+
+@router.put("/files/project-context")
+def write_project_context_profile(
+    body: models.ProjectContextProfileRequest,
+    current_user: models.User = Depends(get_current_user),
+    db: Session = Depends(database.get_db),
+):
+    _assert_project_context_access(
+        db,
+        user_id=current_user.id,
+        directory_path=body.directory_path,
+    )
+    profile = _write_project_context_profile(body.directory_path, body.profile)
+    return {
+        "message": "Project context saved",
+        "filename": PROJECT_CONTEXT_FILENAME,
+        "profile": profile,
+    }
+
+
+@router.delete("/files/project-context")
+def delete_project_context_profile(
+    directory_path: str,
+    current_user: models.User = Depends(get_current_user),
+    db: Session = Depends(database.get_db),
+):
+    _assert_project_context_access(
+        db,
+        user_id=current_user.id,
+        directory_path=directory_path,
+    )
+    deleted = _delete_project_context_profile(directory_path)
+    return {
+        "message": (
+            "Project context deleted" if deleted else "Project context not found"
+        ),
+        "filename": PROJECT_CONTEXT_FILENAME,
+        "deleted": deleted,
     }
 
 
diff --git a/server_api/chatbot/agent_cli.py b/server_api/chatbot/agent_cli.py
index fab95874..e0bc8f5f 100644
--- a/server_api/chatbot/agent_cli.py
+++ b/server_api/chatbot/agent_cli.py
@@ -18,19 +18,15 @@
 
 from server_api.chatbot.chatbot import build_chain
 
-
 # ── Failed questions from 40-question test ──────────────────────────────────
 
 BATCH_QUESTIONS = [
     # Test #10 - Fabricated CLI flags --batch-size, --checkpoint-interval
     "Give me the command to train on CREMI with batch size 2 and save checkpoints every 5000 iterations",
-    
     # Test #14 - Didn't override scheduler explicitly
     "Train on MitoEM with the WarmupCosineLR scheduler and a base learning rate of 0.002",
-    
     # Test #17 - Wrong override format --inference.AUG_NUM=8
     "Generate an inference command for CREMI. Use configs/CREMI/CREMI-Base.yaml and checkpoint outputs/CREMI/checkpoint_100000.pth.tar with 8 TTA augmented views",
-    
     # Test #32 - Fabricated scripts/evaluate.py
     "How do I evaluate synapse detection results for the CREMI challenge?",
 ]
@@ -87,16 +83,16 @@ def run_single(question: str):
 
 def interactive_mode():
     """Interactive mode for testing custom questions."""
-    print("\n" + "="*80)
+    print("\n" + "=" * 80)
     print("INTERACTIVE AGENT TEST MODE")
-    print("="*80)
+    print("=" * 80)
     print("Type your questions to test the agent.")
     print("Type 'quit' or 'exit' to stop.\n")
     agent, reset_search_counter = build_chain()
     while True:
         try:
             question = input("\nYour question: ").strip()
-            if question.lower() in ['quit', 'exit', 'q']:
+            if question.lower() in ["quit", "exit", "q"]:
                 break
             if not question:
                 continue
@@ -111,14 +107,20 @@ def interactive_mode():
         except Exception as e:
             print(f"\nError: {e}")
             import traceback
+
             traceback.print_exc()
 
 
 if __name__ == "__main__":
     import argparse
+
     parser = argparse.ArgumentParser(description="Test the chatbot agent")
-    parser.add_argument("-b", "--batch", action="store_true", help="Run 20-question graded batch test")
-    parser.add_argument("-i", "--interactive", action="store_true", help="Interactive mode")
+    parser.add_argument(
+        "-b", "--batch", action="store_true", help="Run 20-question graded batch test"
+    )
+    parser.add_argument(
+        "-i", "--interactive", action="store_true", help="Interactive mode"
+    )
     parser.add_argument("question", nargs="*", help="Single question to test")
     args = parser.parse_args()
 
diff --git a/server_api/chatbot/chatbot.py b/server_api/chatbot/chatbot.py
index 6469a748..a00263c8 100644
--- a/server_api/chatbot/chatbot.py
+++ b/server_api/chatbot/chatbot.py
@@ -6,6 +6,7 @@
 # - Inference Agent: Handles checkpoint listing and inference command generation
 # - RAG: Documentation search via FAISS vector store
 
+import json
 import os
 from pathlib import Path
 
@@ -14,20 +15,154 @@
 from langchain_core.tools import tool
 from langchain.agents import create_agent
 from server_api.utils.utils import process_path
-from server_api.chatbot.update_faiss import ensure_faiss_index
+from server_api.chatbot.update_faiss import (
+    DEFAULT_OLLAMA_BASE_URL,
+    DEFAULT_OLLAMA_EMBED_MODEL,
+    ensure_faiss_index,
+)
 from server_api.chatbot.tools import (
     list_training_configs,
     read_config,
     list_checkpoints,
 )
 
-TRAINING_AGENT_PROMPT = """You are a **Training Agent** for PyTorch Connectomics.
+DEFAULT_OLLAMA_MODEL = "qwen3.6:27b"
+DEFAULT_HELPER_OLLAMA_MODEL = "qwen3.6:27b"
+
+AGENT_RESPONSE_STYLE = """
+RESPONSE STYLE FOR BIOLOGISTS:
+- Sound like a normal, helpful labmate. Keep visible replies conversational.
+- Default to one short paragraph or 3 bullets or fewer. Maximum 90 words unless the user asks for detail.
+- Put the recommended next action first, but avoid rigid labels like `Do this`, `Why`, and `Watch out`.
+- Avoid long background explanations, exhaustive lists, and implementation details.
+- Do not mention internal tools, agents, RAG, prompts, APIs, or code unless explicitly asked.
+- If a command is requested, provide one command plus at most one sentence of context.
+- If uncertainty matters, state the missing input in one sentence and stop.
+"""
+
+
+def _format_admin_llm_error(error: Exception) -> str:
+    return (
+        "The AI assistant could not connect to its configured language model. "
+        "Please contact your system administrator with this error: "
+        f"{str(error).strip() or error.__class__.__name__}"
+    )
+
+
+def _compact_agent_response(response: str, *, max_words: int = 120) -> str:
+    text = str(response or "").strip()
+    if not text:
+        return text
+
+    lines = [line.rstrip() for line in text.splitlines()]
+    content_lines = [line for line in lines if line.strip()]
+    words = text.split()
+    if len(words) <= max_words and len(content_lines) <= 8:
+        return text
+    if "```" in text and len(words) <= (max_words * 2) and len(content_lines) <= 8:
+        return text
+
+    kept = []
+    word_count = 0
+    for line in content_lines:
+        line_words = line.split()
+        if word_count + len(line_words) > max_words:
+            break
+        kept.append(line)
+        word_count += len(line_words)
+        if len(kept) >= 6:
+            break
+    compacted = "\n".join(kept).strip()
+    if not compacted:
+        compacted = " ".join(words[:max_words]).strip()
+    return f"{compacted}\n\nAsk for details if you want the full version."
+
+
+_PROMPT_LEAK_MARKERS = [
+    "you are the **supervisor agent**",
+    "you are the supervisor agent",
+    "response style for biologists",
+    "routing — decide which tool",
+    "routing - decide which tool",
+    "critical rules:",
+    "sub-agents:",
+    "tools:",
+    "search_documentation:",
+    "delegate_to_training_agent",
+    "delegate_to_inference_agent",
+    "system_prompt",
+    "internal tools",
+]
+
+
+def _looks_like_prompt_leak(response: str) -> bool:
+    text = str(response or "").lower()
+    return any(marker in text for marker in _PROMPT_LEAK_MARKERS)
+
+
+def _looks_like_raw_tool_call(response: str) -> bool:
+    text = str(response or "").strip()
+    if not (text.startswith("{") and text.endswith("}")):
+        return False
+    try:
+        parsed = json.loads(text)
+    except Exception:
+        return False
+    return isinstance(parsed, dict) and isinstance(parsed.get("name"), str)
+
+
+def _sanitize_agent_response(response: str) -> str:
+    text = str(response or "").strip()
+    if not text:
+        return text
+    if _looks_like_raw_tool_call(text):
+        return (
+            "I should not have shown that internal command. "
+            "Tell me the workflow job in plain language, and I will offer a safe app action."
+        )
+    if not _looks_like_prompt_leak(text):
+        return text
+    return (
+        "I can help with the PyTC workflow. Tell me whether you want to run the model, "
+        "proofread masks, use saved edits for training, or compare results. "
+        "I will ask before running long jobs or changing artifacts."
+    )
+
+
+def _resolve_ollama_settings(*, helper: bool = False):
+    if helper:
+        base_url = (
+            os.getenv("PYTC_HELPER_OLLAMA_BASE_URL")
+            or os.getenv("OLLAMA_HELPER_BASE_URL")
+            or os.getenv("OLLAMA_BASE_URL", DEFAULT_OLLAMA_BASE_URL)
+        )
+        model = (
+            os.getenv("PYTC_HELPER_OLLAMA_MODEL")
+            or os.getenv("OLLAMA_HELPER_MODEL")
+            or DEFAULT_HELPER_OLLAMA_MODEL
+        )
+        embed_model = (
+            os.getenv("PYTC_HELPER_OLLAMA_EMBED_MODEL")
+            or os.getenv("OLLAMA_HELPER_EMBED_MODEL")
+            or os.getenv("OLLAMA_EMBED_MODEL", DEFAULT_OLLAMA_EMBED_MODEL)
+        )
+        return base_url, model, embed_model
+    return (
+        os.getenv("OLLAMA_BASE_URL", DEFAULT_OLLAMA_BASE_URL),
+        os.getenv("OLLAMA_MODEL", DEFAULT_OLLAMA_MODEL),
+        os.getenv("OLLAMA_EMBED_MODEL", DEFAULT_OLLAMA_EMBED_MODEL),
+    )
+
+
+TRAINING_AGENT_PROMPT = f"""You are a **Training Agent** for PyTorch Connectomics.
+
+{AGENT_RESPONSE_STYLE}
 
 RULES:
 1. Only report values that your tools return. Do NOT invent config names, paths, or settings.
 2. Never tell the user to write a YAML from scratch. Always start from an existing config.
 3. If the task is unsupported, say so. PyTC only does segmentation.
-4. Be concise. State the facts, generate the command, stop.
+4. Be concise. State the facts and stop. Generate a CLI command only if the user explicitly asks for one.
 
 WORKFLOW: The available configs are provided in your task message. Pick the best match, then:
 1. Call read_config on the chosen config path to see its YAML overrides.
@@ -47,15 +182,17 @@
 
 NEVER invent keys like TRAIN.MAX_ITER, TRAINING.BATCH_SIZE, or CLI flags like --batch-size, --checkpoint-interval — these do not exist.
 
-Command format: `python scripts/main.py --config-file <path> [SECTION.KEY=value ...]`
-Always generate commands for the user to run — never execute directly."""
+Command format, only when explicitly requested: `python scripts/main.py --config-file <path> [SECTION.KEY=value ...]`
+Default app workflow: recommend agent-selected preset/defaults plus approval-gated training inside PyTC Client, not manual YAML tuning."""
 
 
-INFERENCE_AGENT_PROMPT = """You are an **Inference Agent** for PyTorch Connectomics.
+INFERENCE_AGENT_PROMPT = f"""You are an **Inference Agent** for PyTorch Connectomics.
+
+{AGENT_RESPONSE_STYLE}
 
 RULES:
 1. Only report values that your tools return. Do NOT invent checkpoint paths, config names, or settings.
-2. Be concise. State the facts, generate the command, stop.
+2. Be concise. State the facts and stop. Generate a CLI command only if the user explicitly asks for one.
 
 WORKFLOW:
 1. If the user did NOT provide a checkpoint path, call list_checkpoints first to see available checkpoints.
@@ -72,16 +209,18 @@
 - Process volumes one at a time → INFERENCE.DO_SINGLY
 - Batch size → INFERENCE.SAMPLES_PER_BATCH
 
-Command format: `python scripts/main.py --config-file <path> --inference --checkpoint <ckpt> [SECTION.KEY=value ...]`
+Command format, only when explicitly requested: `python scripts/main.py --config-file <path> --inference --checkpoint <ckpt> [SECTION.KEY=value ...]`
 
 IMPORTANT: Overrides use SECTION.KEY=value format (NO -- prefix). Example:
   ✅ CORRECT: INFERENCE.AUG_NUM=8
   ❌ WRONG: --inference.AUG_NUM=8
 
-Always generate commands for the user to run — never execute directly."""
+Default app workflow: recommend approval-gated inference inside PyTC Client, not manual stride/blending/chunking setup."""
+
 
+SUPERVISOR_PROMPT = f"""You are the **Supervisor Agent** for PyTorch Connectomics (PyTC Client).
 
-SUPERVISOR_PROMPT = """You are the **Supervisor Agent** for PyTorch Connectomics (PyTC Client).
+{AGENT_RESPONSE_STYLE}
 
 You help end users navigate and use the PyTC Client application.
 
@@ -90,6 +229,7 @@
 - **General PyTC questions** (what architectures are supported, what augmentations exist, what loss functions are available, etc.) → search_documentation
 - **Generate a specific training/inference command** → delegate_to_training_agent or delegate_to_inference_agent
 - **General/greeting/off-topic** → answer directly, no tool needed
+- **Run/segment/proofread/train/compare/export workflow jobs** → answer briefly that the app can do this through approval-gated workflow actions. Do not provide low-level tuning advice by default.
 
 CRITICAL RULES:
 1. **ALWAYS search documentation first for UI questions.** If the user asks "how do I train", "what do I need to provide", "how do I start", "where do I configure", etc., use search_documentation to find the UI workflow in the docs. Do NOT delegate to sub-agents for these questions.
@@ -98,6 +238,7 @@
 4. **Do not fabricate specifics.** Never make up keyboard shortcuts, button labels, or step-by-step instructions unless they come from retrieved docs or a sub-agent response.
 4a. **NEVER use command-line instructions for UI questions.** The PyTC Client is a desktop GUI application. If the user asks how to do something, explain the UI workflow (buttons, tabs, forms) from the documentation. Do NOT provide Python scripts, bash commands, or CLI examples unless the sub-agent explicitly generates them.
 4b. **NEVER fabricate file paths or scripts.** Do NOT invent scripts like `scripts/evaluate.py`, `scripts/resume_training.py`, or any other files that don't exist. If evaluation requires Python code, show inline code using `connectomics.utils.evaluate`, not fake script paths.
+4c. **Do not lead with low-level YAML parameters for biologists.** For ordinary training or inference requests, say the assistant should infer safe defaults from the current project and ask for approval before running. Mention stride, blending, chunking, GPUs, CPUs, or iterations only when asked to override or debug.
 5. **Answer every part of the user's question.** If they ask about two things, address both.
 6. **Use retrieved content even if wording differs.** If the documentation describes relevant features or workflows, use that information to answer the question. Don't claim something isn't documented just because it uses different terminology than the user's question.
 7. **HARD LIMIT: You may call search_documentation at most 3 times yourself.** Sub-agents also have access to search_documentation. If the tool returns "Search limit reached", immediately stop and answer based on what you already have.
@@ -114,10 +255,17 @@
 
 def build_chain():
     """Build the multi-agent system with supervisor, training, and inference agents."""
-    ollama_base_url = os.getenv("OLLAMA_BASE_URL", "http://cscigpu08.bc.edu:4443")
-    ollama_model = os.getenv("OLLAMA_MODEL", "gpt-oss:20b")
-    ollama_embed_model = os.getenv("OLLAMA_EMBED_MODEL", "qwen3-embedding:8b")
-    llm = ChatOllama(model=ollama_model, base_url=ollama_base_url, temperature=0)
+    ollama_base_url, ollama_model, ollama_embed_model = _resolve_ollama_settings()
+    print(
+        "[CHATBOT] Building main chain with "
+        f"model={ollama_model} embed_model={ollama_embed_model} base_url={ollama_base_url}"
+    )
+    llm = ChatOllama(
+        model=ollama_model,
+        base_url=ollama_base_url,
+        temperature=0,
+        reasoning=False,
+    )
     embeddings = OllamaEmbeddings(model=ollama_embed_model, base_url=ollama_base_url)
     faiss_path = process_path("server_api/chatbot/faiss_index")
     if ensure_faiss_index(
@@ -224,7 +372,9 @@ def delegate_to_training_agent(task: str) -> str:
         # Auto-inject available configs so the agent doesn't need to call list_training_configs
         configs = list_training_configs.invoke({})
         config_summary = "\n".join(
-            f"- {c['name']} ({c['model']}) → {c['path']}" for c in configs if isinstance(c, dict) and 'name' in c
+            f"- {c['name']} ({c['model']}) → {c['path']}"
+            for c in configs
+            if isinstance(c, dict) and "name" in c
         )
         enriched_task = (
             f"{task}\n\n"
@@ -238,6 +388,7 @@ def delegate_to_training_agent(task: str) -> str:
         response = (
             messages[-1].content if messages else "Training agent did not respond."
         )
+        response = _compact_agent_response(response)
         print(f"[TOOL] training_agent responded ({len(response)} chars)")
         return response
 
@@ -261,6 +412,7 @@ def delegate_to_inference_agent(task: str) -> str:
         response = (
             messages[-1].content if messages else "Inference agent did not respond."
         )
+        response = _compact_agent_response(response)
         print(f"[TOOL] inference_agent responded ({len(response)} chars)")
         return response
 
@@ -284,32 +436,116 @@ def delegate_to_inference_agent(task: str) -> str:
 # Has access to search_documentation only — cannot start training/inference.
 # ---------------------------------------------------------------------------
 
-HELPER_PROMPT = """You are a concise UI helper for PyTorch Connectomics (PyTC Client).
+HELPER_PROMPT = f"""You are a concise UI helper for PyTorch Connectomics (PyTC Client).
 
 You answer questions about a SPECIFIC field or setting the user is looking at.
-You have access to the application documentation via the search_documentation tool.
 
 RULES:
-1. Lead with a concrete recommendation or explanation (2-4 sentences max).
+1. Lead with a concrete recommendation or explanation (3 short bullets or fewer).
 2. Use plain, non-technical language — the user has no programming knowledge.
 3. Describe things in terms of what users can see and click in the interface.
 4. If you have enough context, recommend a specific value or action.
 5. Do NOT mention API endpoints, code, environment variables, or internal implementation.
-6. You may call search_documentation up to 2 times per question — then answer with what you have.
-7. You CANNOT start training or inference jobs. If the user asks, tell them to use the main AI Chat panel instead."""
+6. Do NOT paste documentation headings, excerpts, or "Relevant local docs" blocks.
+7. You CANNOT start training or inference jobs. If the user asks, tell them to use the main AI Chat panel instead.
+8. Stay scoped to the current field. Do not answer as the main workflow agent.
+9. Use the provided field context and local documentation snippets. If they are not enough, say what is missing in one sentence."""
+
+
+class FieldHelperChain:
+    """Small direct helper for inline field-level chat.
+
+    This intentionally avoids the general LangChain agent/tool loop used by the
+    main chat. Retrieval happens here, then the helper model receives only the
+    current field context, a short conversation tail, and compact docs snippets.
+    """
+
+    def __init__(self, llm, retriever, docs_by_name: dict[str, str]):
+        self.llm = llm
+        self.retriever = retriever
+        self.docs_by_name = docs_by_name
+
+    def _keyword_docs(self, query: str, *, limit: int = 2) -> list[str]:
+        query_lower = query.lower()
+        query_words = [word for word in query_lower.split() if len(word) > 2]
+        scored = []
+        for filename, content in self.docs_by_name.items():
+            content_lower = content.lower()
+            name_lower = filename.replace(".md", "").lower()
+            word_hits = sum(1 for word in query_words if word in content_lower)
+            name_hits = sum(3 for word in query_words if word in name_lower)
+            score = word_hits + name_hits
+            if score > 0:
+                scored.append((score, filename, content))
+        scored.sort(key=lambda item: item[0], reverse=True)
+        return [content for _, _, content in scored[:limit]]
+
+    def _retrieve_docs(self, query: str) -> str:
+        snippets = []
+        try:
+            docs = self.retriever.invoke(query)
+        except Exception:
+            docs = []
+        for doc in docs[:2]:
+            content = str(getattr(doc, "page_content", "") or "").strip()
+            if content:
+                snippets.append(content)
+        if not snippets:
+            snippets.extend(self._keyword_docs(query, limit=2))
+        compact = "\n\n".join(snippets[:2]).strip()
+        if len(compact) > 2200:
+            compact = compact[:2200].rsplit(" ", 1)[0].strip()
+        return compact or "No local documentation snippet matched this field."
+
+    def invoke(self, payload):
+        messages = payload.get("messages") or []
+        current = messages[-1] if messages else {"content": ""}
+        current_content = str(
+            current.get("content", "") if isinstance(current, dict) else current
+        )
+        history_tail = messages[-5:-1]
+        history_text = "\n".join(
+            f"{item.get('role', 'user')}: {item.get('content', '')}"
+            for item in history_tail
+            if isinstance(item, dict)
+        )
+        docs_text = self._retrieve_docs(current_content)
+        user_prompt = (
+            f"Current field question:\n{current_content}\n\n"
+            f"Recent same-field chat:\n{history_text or 'None'}\n\n"
+            f"Local documentation snippets:\n{docs_text}\n\n"
+            "Answer only for this field. Use at most 3 short bullets."
+        )
+        response = self.llm.invoke(
+            [
+                ("system", HELPER_PROMPT),
+                ("human", user_prompt),
+            ]
+        )
+        return {"messages": [response]}
 
 
 def build_helper_chain():
     """
     Build a lightweight helper agent for inline field-level help.
-    This agent has access to the same search_documentation tool as the main
-    chatbot but has NO access to training/inference sub-agents.
+    This is intentionally not the main workflow/chat agent. It has no tools and
+    no training/inference delegates; it receives only field-local context plus
+    compact local documentation snippets.
     Returns ``(agent, reset_search_counter)`` — same interface as ``build_chain``.
     """
-    ollama_base_url = os.getenv("OLLAMA_BASE_URL", "http://cscigpu08.bc.edu:4443")
-    ollama_model = os.getenv("OLLAMA_MODEL", "gpt-oss:20b")
-    ollama_embed_model = os.getenv("OLLAMA_EMBED_MODEL", "qwen3-embedding:8b")
-    llm = ChatOllama(model=ollama_model, base_url=ollama_base_url, temperature=0)
+    ollama_base_url, ollama_model, ollama_embed_model = _resolve_ollama_settings(
+        helper=True
+    )
+    print(
+        "[CHATBOT] Building helper chain with "
+        f"model={ollama_model} embed_model={ollama_embed_model} base_url={ollama_base_url}"
+    )
+    llm = ChatOllama(
+        model=ollama_model,
+        base_url=ollama_base_url,
+        temperature=0,
+        reasoning=False,
+    )
     embeddings = OllamaEmbeddings(model=ollama_embed_model, base_url=ollama_base_url)
     faiss_path = process_path("server_api/chatbot/faiss_index")
     if ensure_faiss_index(
@@ -330,53 +566,9 @@ def build_helper_chain():
     for md_file in summaries_dir.rglob("*.md"):
         _all_docs[md_file.name] = md_file.read_text(encoding="utf-8")
 
-    _search_call_count = [0]
-
     def reset_search_counter():
-        _search_call_count[0] = 0
-
-    @tool
-    def search_documentation(query: str) -> str:
-        """Search PyTC documentation for UI guides, field explanations, and feature descriptions.
-
-        Args:
-            query: The user's question
-
-        Returns:
-            Relevant documentation content
-        """
-        _search_call_count[0] += 1
-        if _search_call_count[0] > 2:
-            return (
-                "Search limit reached. Answer with the documentation already retrieved."
-            )
+        return None
 
-        docs = retriever.invoke(query)
-        if docs:
-            return "\n\n".join([doc.page_content for doc in docs])
-
-        # Keyword fallback
-        query_lower = query.lower()
-        query_words = [w for w in query_lower.split() if len(w) > 2]
-        scored = []
-        for filename, content in _all_docs.items():
-            content_lower = content.lower()
-            name_lower = filename.replace(".md", "").lower()
-            word_hits = sum(1 for w in query_words if w in content_lower)
-            name_hits = sum(3 for w in query_words if w in name_lower)
-            score = word_hits + name_hits
-            if score > 0:
-                scored.append((score, filename, content))
-        scored.sort(key=lambda x: x[0], reverse=True)
-        if scored:
-            return "\n\n".join([s[2] for s in scored[:3]])
-
-        return "No relevant documentation found."
-
-    helper_agent = create_agent(
-        model=llm,
-        tools=[search_documentation],
-        system_prompt=HELPER_PROMPT,
-    )
+    helper_agent = FieldHelperChain(llm, retriever, _all_docs)
 
     return helper_agent, reset_search_counter
diff --git a/server_api/chatbot/file_summaries/AgentRole.md b/server_api/chatbot/file_summaries/AgentRole.md
new file mode 100644
index 00000000..9455a9bc
--- /dev/null
+++ b/server_api/chatbot/file_summaries/AgentRole.md
@@ -0,0 +1,30 @@
+# Agent Role
+
+The PyTC Client assistant is a compact workflow copilot for biomedical
+segmentation. It helps users understand current state, identify missing inputs,
+choose the next safe action, and inspect evidence. It should not silently run
+risky jobs or overwrite/export artifacts without user approval.
+
+Responses should be short enough for a biologist to skim quickly: usually three
+bullets or fewer and under 90 words. Put the recommended next action first.
+Use UI labels the user can see. Do not mention internal tools, prompts, APIs,
+or implementation details unless the user asks.
+
+For normal app questions, explain the UI workflow. Only provide command-line
+instructions when the user explicitly asks for a command. Do not invent file
+paths, scripts, shortcuts, results, or hidden features.
+
+The assistant may propose navigation, form-fill suggestions, workflow actions,
+hotspot review, correction staging, metric computation, and evidence export.
+Training, inference, overwrite, export, retraining, and other risky actions
+should remain approval-gated and auditable through workflow events.
+
+For biologist-facing training and inference questions, the assistant should not
+lead with YAML, stride, blending, chunking, CPU/GPU, or iteration details. The
+normal workflow is: user provides the data/goal, assistant chooses a safe preset
+and default parameters, user approves the run, app shows progress. Advanced
+settings are for explicit overrides or debugging.
+
+If the user asks whether the assistant actually ran something, answer directly.
+Do not pretend a job ran. If no runtime action was approved, say the answer came
+from existing workflow/docs context and that long jobs require approval.
diff --git a/server_api/chatbot/file_summaries/GettingStarted.md b/server_api/chatbot/file_summaries/GettingStarted.md
index 0d82fb8f..5e8860c2 100644
--- a/server_api/chatbot/file_summaries/GettingStarted.md
+++ b/server_api/chatbot/file_summaries/GettingStarted.md
@@ -1,6 +1,6 @@
 # Getting Started with PyTC Client
 
-PyTC Client (PyTorch Connectomics Client) is a desktop application for biomedical image segmentation. It provides tools for managing files, visualizing data in Neuroglancer, training and running inference with deep learning models, monitoring experiments, and reviewing image masks.
+PyTC Client (PyTorch Connectomics Client) is a desktop application for biomedical image segmentation. It provides tools for managing files, visualizing data in Neuroglancer, training and running inference with deep learning models, tracking project progress, and reviewing image masks.
 
 ## Launching the Application
 
@@ -8,9 +8,10 @@ When you first open PyTC Client, the main workflows are available immediately in
 
 - **File Management** — Browse, upload, and organize files on the server
 - **Visualization** — View image and label data in Neuroglancer
-- **Model Training** — Configure and launch training jobs
-- **Model Inference** — Run inference with trained models
-- **Tensorboard** — Monitor training metrics in real time
+- **Train Model** — Configure and launch training jobs
+- **Run Model** — Generate predictions with trained models
+- **Progress** — Track which volumes have ground truth, draft segmentations, or no segmentation yet
+- **Train Model Runtime** — Check training status/logs and open TensorBoard from the Train Model page
 - **Mask Proofreading** — Review and edit mask layers in image stacks
 
 ## Application Layout
@@ -19,7 +20,7 @@ The application has three main areas:
 
 1. **Top Navigation Bar** — Displays the PyTC logo, application title, and a row of tabs for each workflow. Click a tab to switch between pages. The bar also includes an **AI Chat** toggle button.
 
-2. **Main Content Area** — Shows the currently selected workflow page (e.g., File Manager, Visualization, Model Training).
+2. **Main Content Area** — Shows the currently selected workflow page (e.g., File Manager, Visualization, Train Model).
 
 3. **AI Chat Drawer** — A collapsible panel on the right side of the screen. Click the **AI Chat** button in the top bar to open or close it. You can drag the left edge of the chat drawer to resize it. Use the chat to ask questions about the application, get help with workflows, or request training/inference commands.
 
@@ -33,16 +34,9 @@ The chat panel appears as a sliding drawer on the right. To use it:
 
 The chat supports markdown formatting, including tables, code blocks, and lists.
 
-### Conversation History
+### Workflow Chat
 
-The chat drawer includes a **sidebar** on the left that lists your saved conversations:
-
-- **New chat (+)** — Click the **+** button at the top to start a fresh conversation.
-- **Switch conversations** — Click any conversation in the sidebar to load it.
-- **Delete a conversation** — Click the trash icon next to a conversation and confirm.
-- **Collapse/expand sidebar** — Use the fold/unfold button to hide or show the conversation list.
-
-Conversations are saved automatically as you chat. When you reopen the drawer, your past chats are still available.
+The main assistant drawer keeps one continuous workflow chat for the current browser session. Closing and reopening the drawer preserves the same thread so the assistant can keep referring to the current project state and recent decisions.
 
 ### Inline Help ("?" Buttons)
 
diff --git a/server_api/chatbot/file_summaries/ModelInference.md b/server_api/chatbot/file_summaries/ModelInference.md
index e5a7a6cb..b4a3b1c0 100644
--- a/server_api/chatbot/file_summaries/ModelInference.md
+++ b/server_api/chatbot/file_summaries/ModelInference.md
@@ -1,65 +1,22 @@
-# Model Inference Page
+# Run Model
 
-The Model Inference page lets you run inference (prediction) using a trained segmentation model. It uses the same 3-step configuration wizard as Model Training, with slight differences in the required inputs and available settings.
+The normal workflow is: choose the image volume, choose a checkpoint, choose an
+output folder, then let the assistant start a model run after approval. The
+assistant should infer the closest safe config from project state when possible
+and should not ask a biologist to tune inference internals by default.
 
-## 3-Step Configuration Wizard
+Visible user-facing fields:
 
-### Step 1: Set Inputs
+- **Input image** is the volume to segment.
+- **Checkpoint** is the trained model file.
+- **Output folder** is where the prediction is written.
+- **Run Model** launches the approved run.
 
-Specify the file paths for your inference data:
+Advanced options such as batch size, test-time augmentation, stride, blending,
+chunking, eval mode, and raw YAML are for explicit override or debugging. If the
+user simply wants a volume segmented, prefer a run-ready action over an
+explanation of these controls.
 
-- **Input Image** — Path to the image data you want to run inference on (file or directory on the server). Click the folder icon to browse, type a path, or drag and drop. You can also click the **?** button next to the field for AI-powered help.
-- **Output Path** — Directory where inference results will be saved.
-- **Checkpoint Path** — Path to the trained model checkpoint file (e.g., `/path/to/checkpoint_100000.pth.tar`). This is the model that will be used for prediction.
-
-All three fields are required before you can proceed.
-
-### Step 2: Base Configuration
-
-Choose a YAML configuration file, just like in training:
-
-- **Upload YAML File** — Upload a config from your local machine.
-- **Choose a preset config** — Select a preset from the server dropdown.
-
-Once loaded, you will see:
-
-- **Loaded** indicator and **Revert to preset** option (if modified).
-- **Effective dataset paths** summary.
-- **Model architecture** dropdown.
-- **Sliders** for quick parameter adjustment:
-  - **Batch size** (1–32)
-  - **Augmentations** (1–16) — Number of test-time augmentations to average over.
-
-### Step 3: Advanced Configuration
-
-Fine-tune inference-specific parameters:
-
-**Common inference knobs:**
-
-- Batch size
-- Augmentations (AUG_NUM)
-- Blending mode (gaussian or constant)
-- Eval mode (on/off — whether to compute evaluation metrics)
-
-**Inference (advanced):**
-
-- Run singly (process volumes one at a time)
-- Unpad output (remove padding from output)
-- Augment mode (mean or max — how to combine augmented predictions)
-- Test count (number of test volumes)
-
-Each setting is displayed as a dropdown, number input, or toggle switch.
-
-**Open raw YAML** — Opens a full-screen YAML text editor modal for direct editing. Includes **Format YAML** and **Copy** buttons.
-
-Click **Done** to save the configuration.
-
-## Starting and Stopping Inference
-
-After completing the wizard:
-
-1. Click **Start Inference** to launch the inference job on the server.
-2. The page shows the current inference status.
-3. Click **Stop Inference** at any time to terminate the job.
-
-The inference status is polled automatically so you can monitor progress without refreshing.
+Runtime logs should be summarized as plain status: idle, running, completed,
+failed, or needs attention. Show raw terminal output only when the user asks or
+when troubleshooting a failure.
diff --git a/server_api/chatbot/file_summaries/ModelTraining.md b/server_api/chatbot/file_summaries/ModelTraining.md
index e0a5ccb9..938fb377 100644
--- a/server_api/chatbot/file_summaries/ModelTraining.md
+++ b/server_api/chatbot/file_summaries/ModelTraining.md
@@ -1,100 +1,24 @@
-# Model Training Page
-
-The Model Training page lets you configure and launch deep learning training jobs for biomedical image segmentation using PyTorch Connectomics. Setup follows a guided 3-step process, after which you can start and monitor your training run.
-
-## 3-Step Configuration Wizard
-
-The configuration wizard (stepper) walks you through three steps. You must complete each step before advancing to the next. Click **Next** to advance and **Previous** to go back.
-
-### Step 1: Set Inputs
-
-Specify the file paths for your training data:
-
-- **Input Image** — Path to your training image data (file or directory on the server). Click the folder icon to browse, type a path, or drag and drop. Each field also has a **?** button that opens an AI-powered help panel with explanations and recommended values.
-- **Input Label** — Path to the corresponding ground-truth labels.
-- **Output Path** — Directory where training outputs (checkpoints, logs) will be saved.
-- **Log Path** — Directory for training logs (used by TensorBoard for monitoring).
-
-All four fields are required before you can proceed. The application will show a warning listing any missing fields if you try to advance without filling them in.
-
-**Inline AI help:** Every input field on the training configuration page has a small **?** button. Clicking it opens a floating chat panel that explains the setting, suggests a recommended value, and accepts follow-up questions.
-
-### Step 2: Base Configuration
-
-Choose a starting YAML configuration file for your training job:
-
-- **Upload YAML File** — Click the **Upload YAML File** button to upload a configuration file from your local machine.
-- **Choose a preset config** — Select from a dropdown of preset configurations available on the server (e.g., `Lucchi-Mitochondria.yaml`, `CREMI-Synapse.yaml`).
-
-Once a config is loaded, you will see:
-
-- **Loaded** indicator showing which file or preset is active. If you modify settings, a **Modified** label appears with a **Revert to preset** link to restore the original values.
-- **Effective dataset paths** — A summary box showing the common folder, image name, label name, and output path that will be written into the YAML config.
-- **Model architecture** dropdown — Select the neural network architecture (e.g., `unet_super`, `fpn`). The available options are fetched from the server.
-- **Sliders** for quick adjustment of common parameters:
-  - **Batch size** (1–32)
-  - **GPUs** (0–8)
-  - **CPUs** (1–16)
-
-### Step 3: Advanced Configuration
-
-Fine-tune detailed training parameters using structured controls organized into sections:
-
-**Common training knobs:**
-
-- Optimizer (SGD, Adam, AdamW)
-- LR scheduler (MultiStepLR, CosineAnnealingLR, StepLR)
-- Learning rate
-- Batch size
-- Total iterations
-- Save interval (how often to save checkpoints)
-- Validation interval
-
-**System:**
-
-- Distributed training (on/off)
-- Parallel mode (DP or DDP)
-- Debug mode (on/off)
-
-**Model:**
-
-- Block type (residual, plain)
-- Backbone (resnet, repvgg, botnet)
-- Normalization (bn, sync_bn, in, gn, none)
-- Activation (relu, elu, leaky)
-- Pooling layer (on/off)
-- Mixed precision (on/off)
-- Aux output (on/off)
-
-**Dataset:**
-
-- 2D dataset (on/off)
-- Load 2D slices (on/off)
-- Isotropic data (on/off)
-- Drop channels (on/off)
-- Reduce labels (on/off)
-- Ensure min size (on/off)
-- Pad mode (reflect, constant, symmetric)
-
-**Solver (advanced):**
-
-- Weight decay
-- Momentum
-- Clip gradients (on/off)
-- Clip value
-
-Each setting is displayed as a dropdown, number input, or toggle switch.
-
-**Open raw YAML** — Click this button at the bottom to open a full-screen YAML text editor modal where you can directly edit the raw YAML configuration. The modal includes a **Format YAML** button to auto-format the text and a **Copy** button to copy the YAML to your clipboard. If there is a syntax error, a red warning appears.
-
-When finished, click **Done** to save the configuration.
-
-## Starting and Stopping Training
-
-After completing the 3-step wizard:
-
-1. Click **Start Training** to launch the training job on the server.
-2. The page displays the current training status (e.g., "Training in progress…").
-3. Click **Stop Training** at any time to terminate the running job.
-
-The training status is polled automatically so you can see updates without refreshing. You can switch to the **Tensorboard** tab to monitor training metrics like loss curves in real time.
+# Train Model
+
+The normal biologist workflow is not manual YAML tuning. The user should choose
+the image/label pair or saved proofreading edits, then ask the assistant to run
+training. The assistant should infer a safe preset from the current project,
+fill image, label, output, and log paths, apply conservative defaults, and ask
+for approval before launching the job.
+
+Use the **Train Model** tab when the user wants to inspect or override what the agent
+will run. Keep the visible explanation short:
+
+- **Input image** is the source volume.
+- **Input label** is the current mask, corrected mask, or ground truth.
+- **Output/log folder** is where checkpoints and run logs are written.
+- **Start Training** launches the approved job.
+
+Raw YAML, batch size, CPU/GPU counts, save interval, total iterations, stride,
+chunking, and blending are advanced controls. Mention them only if the user
+asks to override defaults, debug a failure, or inspect a completed run. Do not
+tell a normal biologist to hand-edit these settings as the default path.
+
+Training runtime logs should be treated as diagnostics. The app should summarize
+plain states such as idle, running, completed, failed, or needs attention. Show
+raw terminal output only on demand or when troubleshooting a failure.
diff --git a/server_api/chatbot/file_summaries/Monitoring.md b/server_api/chatbot/file_summaries/Monitoring.md
index 8e96888e..992a7af5 100644
--- a/server_api/chatbot/file_summaries/Monitoring.md
+++ b/server_api/chatbot/file_summaries/Monitoring.md
@@ -1,20 +1,22 @@
-# TensorBoard Monitoring Page
+# Train Model Runtime and TensorBoard
 
-The Monitoring page displays a live TensorBoard dashboard embedded directly inside the application. TensorBoard is used to track and visualize training metrics such as loss curves, learning rate schedules, and validation scores.
+The standalone Monitor tab has been retired. Training status, runtime logs, and TensorBoard entry points now live on the Train Model page.
 
 ## How It Works
 
-1. Navigate to the **Tensorboard** tab in the top navigation bar.
-2. If a training job is running (or has been run), TensorBoard will load automatically and display inside the page.
-3. The dashboard shows the standard TensorBoard interface with all its features — scalar plots, image samples, histograms, etc.
+1. Navigate to **Train Model**.
+2. Use the Train Model Runtime panel to check whether training is idle, running, complete, or failed.
+3. Use **Show log** or **Details** to inspect failures.
+4. After a successful run, use **TensorBoard** to open curves for the training output directory.
+5. Use **Open Run Model** when the latest checkpoint is ready for inference.
 
 ## Requirements
 
 - TensorBoard monitoring requires an active or completed training run with logs saved to the output directory.
-- The server automatically starts a TensorBoard instance pointed at your training output directory when you launch training from the Model Training page.
+- Runtime status should be interpreted from the Train Model panel, not from a separate Monitor tab.
 
 ## Tips
 
-- If the TensorBoard panel appears blank, make sure a training job has been started at least once and that the output path was set correctly in the Model Training configuration.
+- If TensorBoard fails to open, make sure a training job has been started at least once and that the output path was set correctly in Train Model.
 - TensorBoard updates in real time as new training data is written, so you can watch loss curves evolve during training.
-- You can interact with TensorBoard normally — zoom into charts, toggle runs on/off, and switch between the Scalars, Images, and other TensorBoard tabs within the embedded view.
+- You can interact with TensorBoard normally in the opened TensorBoard page.
diff --git a/server_api/chatbot/file_summaries/PyTC-Inference.md b/server_api/chatbot/file_summaries/PyTC-Inference.md
index c89f3d1a..7ed7eb34 100644
--- a/server_api/chatbot/file_summaries/PyTC-Inference.md
+++ b/server_api/chatbot/file_summaries/PyTC-Inference.md
@@ -1,89 +1,27 @@
-# PyTC Inference Guide
+# PyTC Inference
 
-This document explains how to run inference (prediction) with a trained PyTorch Connectomics model.
+PyTorch Connectomics inference creates a prediction mask from an image volume
+and a trained checkpoint. In PyTC Client, the assistant should normally hide the
+script-level details: infer a safe config from project state, fill input image,
+checkpoint, and output path, then ask the user to approve the run.
 
-## Inference Command
+Command-line form, for debugging or expert use only:
 
+```bash
+python scripts/main.py --config-file <config.yaml> --inference --checkpoint <checkpoint.pth.tar>
 ```
-python scripts/main.py --config-file <config.yaml> --inference --checkpoint <checkpoint.pth.tar> [OVERRIDES]
-```
-
-Example:
-```
-python scripts/main.py --config-file configs/Lucchi-Mitochondria.yaml --inference --checkpoint outputs/Lucchi_UNet/checkpoint_100000.pth.tar
-```
-
-The `--inference` flag switches the trainer to test mode. A `--checkpoint` path is required to load the trained model weights.
-
-## How Inference Works
-
-1. The config file is loaded and inference-specific settings override the training defaults (input path, image name, output path, pad size, input/output size).
-2. The model is built from the config and checkpoint weights are loaded.
-3. The test volume is loaded and divided into overlapping patches based on `INFERENCE.INPUT_SIZE` and `INFERENCE.STRIDE`.
-4. Each patch is fed through the model. If test-time augmentation is enabled, multiple augmented copies are predicted and aggregated.
-5. Overlapping predictions are blended together (Gaussian blending by default).
-6. The final prediction is saved to the output directory.
-
-## INFERENCE Configuration Options
-
-| Key | Description | Default |
-|-----|-------------|---------|
-| `INFERENCE.INPUT_SIZE` | Patch size `[z, y, x]` for inference (overrides MODEL.INPUT_SIZE) | None (uses model size) |
-| `INFERENCE.OUTPUT_SIZE` | Output patch size `[z, y, x]` (overrides MODEL.OUTPUT_SIZE) | None (uses model size) |
-| `INFERENCE.IMAGE_NAME` | Test image filename(s) relative to input path | None |
-| `INFERENCE.INPUT_PATH` | Override DATASET.INPUT_PATH for inference | None |
-| `INFERENCE.OUTPUT_PATH` | Directory where predictions are saved | `""` |
-| `INFERENCE.OUTPUT_NAME` | Output filename (e.g., `result.h5`, `pred`) | `'result.h5'` |
-| `INFERENCE.PAD_SIZE` | Padding `[z, y, x]` for inference volumes | None (uses dataset pad) |
-| `INFERENCE.STRIDE` | Stride `[z, y, x]` between patches. Smaller stride = more overlap = smoother results but slower | `[4, 128, 128]` |
-| `INFERENCE.BLENDING` | Blending mode for overlapping patches: `'gaussian'` or `'bump'` | `'gaussian'` |
-| `INFERENCE.OUTPUT_ACT` | Activation function(s) for output: `'sigmoid'`, `'softmax'`, `'tanh'` | `['sigmoid']` |
-| `INFERENCE.AUG_MODE` | Test-time augmentation aggregation: `'mean'` or `'min'` | `'mean'` |
-| `INFERENCE.AUG_NUM` | Number of augmented copies for TTA. Set to None to disable TTA | None |
-| `INFERENCE.SAMPLES_PER_BATCH` | Batch size for inference (patches per GPU) | `4` |
-| `INFERENCE.DO_EVAL` | Run with `model.eval()` (affects batchnorm/dropout) | `True` |
-| `INFERENCE.DO_SINGLY` | Process volumes one at a time (for multi-volume datasets) | `False` |
-| `INFERENCE.DO_SINGLY_START_INDEX` | Starting index when DO_SINGLY is True | `0` |
-| `INFERENCE.DO_SINGLY_STEP` | Step between volumes in DO_SINGLY mode | `1` |
-| `INFERENCE.DATA_SCALE` | Override DATASET.DATA_SCALE for inference | None |
-| `INFERENCE.OUTPUT_SCALE` | Rescale predictions after model output `[z, y, x]` | `[1.0, 1.0, 1.0]` |
 
-## Inference Output
+Biologist-facing answer pattern:
 
-- By default, predictions are saved as HDF5 files (`.h5`) in the `INFERENCE.OUTPUT_PATH` directory.
-- For chunked or DO_SINGLY inference, the output filename is a stem (e.g., `result`) and files are saved per volume.
-- For multi-class segmentation (`TARGET_OPT: ["9-N"]`), the output activation is automatically set to softmax if not specified.
-
-## Test-Time Augmentation (TTA)
-
-TTA applies geometric augmentations (flips, rotations) to the input, runs the model on each augmented copy, and aggregates the predictions.
-
-- `INFERENCE.AUG_NUM`: Number of augmented copies. Common values: `4`, `8`, `16`. Set to `None` to disable.
-- `INFERENCE.AUG_MODE`:
-  - `'mean'`: Average all predictions (recommended for most tasks).
-  - `'min'`: Take the minimum prediction (useful for conservative boundary detection).
-
-## Inference Stride and Blending
-
-The inference stride controls how much overlap there is between adjacent patches:
-- **Smaller stride** = more overlap = smoother results, but slower.
-- **Larger stride** = less overlap = faster, but may show tile boundary artifacts.
-- `'gaussian'` blending weights the center of each patch more heavily, producing smooth transitions.
-
-## Large-Scale (Chunked) Inference
-
-For datasets too large to fit in memory, use tiled inference:
-```yaml
-INFERENCE:
-  DO_CHUNK_TITLE: 1
-  DATA_CHUNK_NUM: [4, 8, 8]
-```
-The volume is split into chunks that are processed sequentially.
+- **Do this:** approve the inference run for the current image/checkpoint.
+- **Needs:** image volume, checkpoint, output folder.
+- **Watch out:** if the job fails, inspect the runtime summary before raw logs.
 
-## Tips
+Advanced controls include patch size, stride, blending, batch size, test-time
+augmentation, chunking, and raw YAML overrides. Do not lead with these controls
+unless the user asks to override defaults, speed up a run, reduce memory use, or
+debug visible artifacts.
 
-- Use the same config file for inference that was used for training. Only override inference-specific settings.
-- Increase `INFERENCE.SAMPLES_PER_BATCH` to speed up inference if GPU memory allows.
-- Increase `INFERENCE.AUG_NUM` (e.g., 8 or 16) for better accuracy at the cost of speed.
-- For multi-volume datasets (like CREMI with volumes A, B, C), set `INFERENCE.DO_SINGLY: True`.
-- The output directory must exist or the script will create it automatically.
+Inference outputs are usually HDF5 or TIFF-like prediction volumes. After a run
+finishes, the workflow should register the prediction as a model run/artifact so
+proofreading and before/after evaluation can use it.
diff --git a/server_api/chatbot/rag_eval.py b/server_api/chatbot/rag_eval.py
index 765ddcbe..0ffc47bf 100644
--- a/server_api/chatbot/rag_eval.py
+++ b/server_api/chatbot/rag_eval.py
@@ -133,9 +133,9 @@
         "hard",
     ),
     # ── Monitoring.md ───────────────────────────────────────────────────
-    ("How do I monitor training progress?", "Monitoring.md", "easy"),
+    ("How do I check training progress?", "Monitoring.md", "easy"),
     ("What is TensorBoard used for?", "Monitoring.md", "easy"),
-    ("How does the monitoring page work?", "Monitoring.md", "easy"),
+    ("Where do runtime logs live?", "Monitoring.md", "easy"),
     (
         "Where can I see training loss curves and metrics in real-time?",
         "Monitoring.md",
@@ -333,7 +333,11 @@
     ),
     # Real-user inference questions
     ("How do I make my inference predictions smoother?", "PyTC-Inference.md", "medium"),
-    ("Can I increase the batch size for faster inference?", "PyTC-Inference.md", "medium"),
+    (
+        "Can I increase the batch size for faster inference?",
+        "PyTC-Inference.md",
+        "medium",
+    ),
     ("What output format does inference produce?", "PyTC-Inference.md", "medium"),
     (
         "I'm seeing tile boundary artifacts in my predictions, how do I fix that?",
@@ -415,7 +419,11 @@
     ),
     # ── PyTC-Configs.md ────────────────────────────────────────────────
     ("What bundled configs does PyTC have?", "PyTC-Configs.md", "easy"),
-    ("Which config should I use for mitochondria segmentation?", "PyTC-Configs.md", "easy"),
+    (
+        "Which config should I use for mitochondria segmentation?",
+        "PyTC-Configs.md",
+        "easy",
+    ),
     ("What config is used for CREMI synapse detection?", "PyTC-Configs.md", "medium"),
     ("Which config uses the Swin UNETR architecture?", "PyTC-Configs.md", "medium"),
     (
@@ -431,7 +439,11 @@
     # ── PyTC-Evaluation.md ─────────────────────────────────────────────
     ("How do I evaluate segmentation results in PyTC?", "PyTC-Evaluation.md", "easy"),
     ("What is adapted Rand error?", "PyTC-Evaluation.md", "easy"),
-    ("What evaluation metric should I use for instance segmentation?", "PyTC-Evaluation.md", "medium"),
+    (
+        "What evaluation metric should I use for instance segmentation?",
+        "PyTC-Evaluation.md",
+        "medium",
+    ),
     ("How do I compute IoU for binary segmentation?", "PyTC-Evaluation.md", "medium"),
     (
         "What is variation of information in segmentation evaluation?",
@@ -445,7 +457,11 @@
     ),
     # Real-user evaluation questions
     ("How do I know if my model is good?", "PyTC-Evaluation.md", "medium"),
-    ("What metric should I report for the SNEMI3D challenge?", "PyTC-Evaluation.md", "hard"),
+    (
+        "What metric should I report for the SNEMI3D challenge?",
+        "PyTC-Evaluation.md",
+        "hard",
+    ),
     (
         "How do I compare my prediction against ground truth?",
         "PyTC-Evaluation.md",
@@ -512,7 +528,7 @@
 
 def main():
     embed_model = os.getenv("OLLAMA_EMBED_MODEL", "qwen3-embedding:8b")
-    base_url = os.getenv("OLLAMA_BASE_URL", "http://cscigpu08.bc.edu:4443")
+    base_url = os.getenv("OLLAMA_BASE_URL", "http://127.0.0.1:11434")
 
     print(f"Embeddings: {embed_model}  |  Ollama: {base_url}")
     print(f"FAISS dir:  {FAISS_DIR}")
diff --git a/server_api/chatbot/update_faiss.py b/server_api/chatbot/update_faiss.py
index bd7b6b0f..1e8d6ff5 100644
--- a/server_api/chatbot/update_faiss.py
+++ b/server_api/chatbot/update_faiss.py
@@ -1,11 +1,13 @@
 import argparse
+import json
 import os
 from pathlib import Path
 from typing import Optional, Tuple
 
-DEFAULT_OLLAMA_BASE_URL = "http://cscigpu08.bc.edu:4443"
+DEFAULT_OLLAMA_BASE_URL = "http://127.0.0.1:11434"
 DEFAULT_OLLAMA_EMBED_MODEL = "qwen3-embedding:8b"
 INDEX_FILENAMES = ("index.faiss", "index.pkl")
+INDEX_SETTINGS_FILENAME = "ollama_settings.json"
 
 
 def get_chatbot_paths(base_dir: Optional[Path] = None) -> Tuple[Path, Path]:
@@ -27,6 +29,33 @@ def faiss_index_exists(faiss_directory: Path) -> bool:
     return all((faiss_directory / name).is_file() for name in INDEX_FILENAMES)
 
 
+def read_index_settings(faiss_directory: Path) -> Optional[dict]:
+    settings_path = faiss_directory / INDEX_SETTINGS_FILENAME
+    if not settings_path.is_file():
+        return None
+    try:
+        return json.loads(settings_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+
+
+def write_index_settings(faiss_directory: Path, *, model: str, base_url: str) -> None:
+    settings_path = faiss_directory / INDEX_SETTINGS_FILENAME
+    settings_path.write_text(
+        json.dumps({"model": model, "base_url": base_url}, indent=2) + "\n",
+        encoding="utf-8",
+    )
+
+
+def faiss_index_matches_settings(
+    faiss_directory: Path, *, model: str, base_url: str
+) -> bool:
+    settings = read_index_settings(faiss_directory)
+    if settings is None:
+        return False
+    return settings.get("model") == model and settings.get("base_url") == base_url
+
+
 def build_faiss_index(
     summaries_directory: Path,
     faiss_directory: Path,
@@ -71,6 +100,11 @@ def build_faiss_index(
     vectorstore = FAISS.from_documents(chunks, embeddings)
     faiss_directory.mkdir(parents=True, exist_ok=True)
     vectorstore.save_local(str(faiss_directory))
+    write_index_settings(
+        faiss_directory,
+        model=embed_model,
+        base_url=resolved_base_url,
+    )
     print(f"FAISS index saved with {vectorstore.index.ntotal} vectors")
 
 
@@ -84,15 +118,20 @@ def ensure_faiss_index(
     default_summaries_directory, default_faiss_directory = get_chatbot_paths()
     summaries_directory = summaries_directory or default_summaries_directory
     faiss_directory = faiss_directory or default_faiss_directory
+    embed_model, resolved_base_url = resolve_ollama_settings(model, base_url)
 
-    if faiss_index_exists(faiss_directory):
+    if faiss_index_exists(faiss_directory) and faiss_index_matches_settings(
+        faiss_directory,
+        model=embed_model,
+        base_url=resolved_base_url,
+    ):
         return False
 
     build_faiss_index(
         summaries_directory,
         faiss_directory,
-        model=model,
-        base_url=base_url,
+        model=embed_model,
+        base_url=resolved_base_url,
     )
     return True
 
diff --git a/server_api/ehtool/data_manager.py b/server_api/ehtool/data_manager.py
index d0fc177a..45b7b328 100644
--- a/server_api/ehtool/data_manager.py
+++ b/server_api/ehtool/data_manager.py
@@ -8,6 +8,7 @@
 import time
 import shutil
 import tempfile
+import logging
 from datetime import datetime, timezone
 import glob
 import numpy as np
@@ -17,6 +18,8 @@
 from pathlib import Path
 from scipy import ndimage
 from collections import OrderedDict
+from app_event_logger import append_app_event
+from server_api.workflows.volume_io import load_volume, split_dataset_ref
 
 from .utils import (
     to_uint8,
@@ -32,6 +35,8 @@
     base64_to_array,
 )
 
+logger = logging.getLogger(__name__)
+
 
 class DataManager:
     """
@@ -82,6 +87,17 @@ def __init__(self):
         self.mask_source_kind: str = "none"
         self.mask_source_files: List[str] = []
 
+    def _append_event(self, event: str, level: str = "INFO", **fields: Any) -> None:
+        try:
+            append_app_event(
+                component="ehtool.data_manager",
+                event=event,
+                level=level,
+                **fields,
+            )
+        except Exception:
+            logger.debug("Failed to append DataManager app event", exc_info=True)
+
     def load_dataset(
         self, dataset_path: str, mask_path: Optional[str] = None
     ) -> Dict[str, Any]:
@@ -144,6 +160,17 @@ def load_dataset(
             self.mask_path
         )
 
+        self._append_event(
+            "proofreading_dataset_loaded",
+            dataset_path=dataset_path,
+            mask_path=mask_path,
+            total_layers=self.total_layers,
+            image_shape=self.image_shape,
+            has_masks=mask_data is not None,
+            mask_source_kind=self.mask_source_kind,
+            mask_source_files=len(self.mask_source_files),
+        )
+
         return {
             "total_layers": self.total_layers,
             "is_3d": self.is_3d,
@@ -191,14 +218,31 @@ def save_mask(self, layer_index: int, mask_base64: str) -> None:
         if self.mask_path:
             self._save_volume(self.mask_path, self.mask_volume, layer_index)
 
+    def _clear_slice_caches(self) -> None:
+        self._slice_cache.clear()
+        self._active_cache.clear()
+        self._raw_cache.clear()
+        self._resized_cache.clear()
+        self._resized_frame_cache.clear()
+        self._filmstrip_cache.clear()
+
+    def _semantic_foreground_value(self) -> int:
+        if self.mask_volume is None:
+            return 1
+        nonzero = np.asarray(self.mask_volume)[np.asarray(self.mask_volume) > 0]
+        if nonzero.size == 0:
+            return 1
+        value = int(nonzero.max())
+        return value if value > 0 else 1
+
     def save_instance_mask_slice(
         self, instance_id: int, axis: str, index: int, mask_base64: str
-    ) -> None:
+    ) -> Dict[str, Any]:
         """Apply an edited binary mask to the active instance on a slice."""
         if self.instance_volume is None:
             raise ValueError("Instance volume is not available")
-        if self.instance_mode != "instance":
-            raise ValueError("Instance editing requires labeled masks")
+        if self.instance_mode not in {"instance", "semantic"}:
+            raise ValueError("Instance editing requires mask-derived instances")
 
         axis = axis.lower()
         if axis not in {"xy", "zx", "zy"}:
@@ -264,23 +308,26 @@ def save_instance_mask_slice(
                 mask_slice = self.mask_volume[:, :, index]
             if mask_slice.shape == binary.shape:
                 previous_mask = np.array(mask_slice, copy=True)
-                old_mask_active = previous_mask == instance_id
-                writable_mask = (previous_mask == 0) | old_mask_active
-                add_mask = binary & writable_mask & ~old_mask_active
-                remove_mask = old_mask_active & ~binary
-                mask_slice[remove_mask] = 0
-                mask_slice[old_mask_active | add_mask] = instance_id
+                if self.instance_mode == "semantic":
+                    foreground_value = self._semantic_foreground_value()
+                    old_mask_active = old_active
+                    add_mask = add_pixels
+                    remove_mask = remove_pixels
+                    mask_slice[remove_mask] = 0
+                    mask_slice[old_mask_active | add_mask] = foreground_value
+                else:
+                    old_mask_active = previous_mask == instance_id
+                    writable_mask = (previous_mask == 0) | old_mask_active
+                    add_mask = binary & writable_mask & ~old_mask_active
+                    remove_mask = old_mask_active & ~binary
+                    mask_slice[remove_mask] = 0
+                    mask_slice[old_mask_active | add_mask] = instance_id
 
         # Update active instance stats without resetting classifications.
         self._update_instance_stats(instance_id)
 
         # Clear caches so overlays refresh
-        self._slice_cache.clear()
-        self._active_cache.clear()
-        self._raw_cache.clear()
-        self._resized_cache.clear()
-        self._resized_frame_cache.clear()
-        self._filmstrip_cache.clear()
+        self._clear_slice_caches()
 
         changed_pixels = int(
             np.count_nonzero(add_pixels) + np.count_nonzero(remove_pixels)
@@ -288,17 +335,35 @@ def save_instance_mask_slice(
         self.persistence_dirty = True
         self._persist_instance_artifact(force=True)
         blocked_pixels = int(np.count_nonzero(overwrite_blocked))
+        event_payload = {
+            "instance_id": int(instance_id),
+            "axis": axis,
+            "z_index": int(index),
+            "pixels_added": int(np.count_nonzero(add_pixels)),
+            "pixels_removed": int(np.count_nonzero(remove_pixels)),
+            "pixels_changed": changed_pixels,
+            "pixels_blocked": blocked_pixels,
+            "instance_mode": self.instance_mode,
+            "artifact_path": self.instance_artifact_path,
+            "artifact_exists": bool(
+                self.instance_artifact_path
+                and os.path.exists(self.instance_artifact_path)
+            ),
+            "last_saved_at": self.last_saved_at,
+        }
         self.save_progress(
             edit_event={
-                "instance_id": int(instance_id),
-                "axis": axis,
-                "z_index": int(index),
-                "pixels_added": int(np.count_nonzero(add_pixels)),
-                "pixels_removed": int(np.count_nonzero(remove_pixels)),
-                "pixels_changed": changed_pixels,
-                "pixels_blocked": blocked_pixels,
+                "instance_id": event_payload["instance_id"],
+                "axis": event_payload["axis"],
+                "z_index": event_payload["z_index"],
+                "pixels_added": event_payload["pixels_added"],
+                "pixels_removed": event_payload["pixels_removed"],
+                "pixels_changed": event_payload["pixels_changed"],
+                "pixels_blocked": event_payload["pixels_blocked"],
             }
         )
+        self._append_event("proofreading_mask_slice_saved", **event_payload)
+        return event_payload
 
     def _save_volume(self, path: str, volume: np.ndarray, layer_index: int = -1):
         """Save volume to disk"""
@@ -470,16 +535,40 @@ def _load_instance_artifact_if_available(self) -> None:
                 return
             self.instance_volume = loaded.astype(np.int32, copy=False)
             if self.mask_volume is not None and self.mask_volume.shape == loaded.shape:
-                self.mask_volume = loaded.astype(self.mask_volume.dtype, copy=False)
+                if self.instance_mode == "semantic":
+                    foreground_value = self._semantic_foreground_value()
+                    self.mask_volume = np.where(loaded > 0, foreground_value, 0).astype(
+                        self.mask_volume.dtype, copy=False
+                    )
+                else:
+                    self.mask_volume = loaded.astype(self.mask_volume.dtype, copy=False)
             saved_at = datetime.fromtimestamp(
                 os.path.getmtime(self.instance_artifact_path), tz=timezone.utc
             )
             self.last_saved_at = saved_at.isoformat()
             self.last_persist_error = None
             self.persistence_dirty = False
+            self._append_event(
+                "proofreading_instance_artifact_loaded",
+                artifact_path=self.instance_artifact_path,
+                instance_mode=self.instance_mode,
+                shape=loaded.shape,
+            )
         except Exception as exc:
             self.last_persist_error = f"Failed to load artifact: {exc}"
 
+    def _export_volume(self) -> np.ndarray:
+        if self.instance_volume is None:
+            raise ValueError("No instance volume available for export")
+        if self.instance_mode == "semantic":
+            if self.mask_volume is not None:
+                return self.mask_volume
+            foreground_value = self._semantic_foreground_value()
+            return np.where(self.instance_volume > 0, foreground_value, 0).astype(
+                np.uint8
+            )
+        return self.instance_volume
+
     def _backup_file(self, source_path: str, timestamp: str) -> str:
         source = Path(source_path)
         backup = source.with_name(
@@ -977,6 +1066,7 @@ def export_masks(
     ) -> Dict[str, Any]:
         if self.instance_volume is None:
             raise ValueError("No instance volume available for export")
+        export_volume = self._export_volume()
 
         mode_value = (mode or "").strip().lower()
         if mode_value not in {"new_file", "overwrite_source"}:
@@ -996,7 +1086,7 @@ def export_masks(
                 target = target.with_suffix(".tif")
             if target.exists() and create_backup:
                 backup_path = self._backup_file(str(target), timestamp)
-            self._atomic_write_tiff(str(target), self.instance_volume.astype(np.int32))
+            self._atomic_write_tiff(str(target), export_volume)
             written_path = str(target)
         else:
             if not self.mask_path:
@@ -1013,24 +1103,22 @@ def export_masks(
                 if create_backup:
                     backup_path = self._backup_file(source_file, timestamp)
                 if source_file.lower().endswith((".tif", ".tiff")):
-                    self._atomic_write_tiff(
-                        source_file, self.instance_volume.astype(np.int32)
-                    )
+                    self._atomic_write_tiff(source_file, export_volume)
                 else:
-                    if self.instance_volume.ndim == 3:
-                        if self.instance_volume.shape[0] != 1:
+                    if export_volume.ndim == 3:
+                        if export_volume.shape[0] != 1:
                             raise ValueError(
                                 "Cannot overwrite multi-slice volume into a single 2D source image"
                             )
-                        slice_data = self.instance_volume[0]
+                        slice_data = export_volume[0]
                     else:
-                        slice_data = self.instance_volume
+                        slice_data = export_volume
                     self._atomic_write_image(source_file, slice_data)
                 written_path = source_file
             else:
                 if create_backup:
                     backup_path = self._backup_file_set(source_files, timestamp)
-                self._write_volume_to_files(source_files, self.instance_volume)
+                self._write_volume_to_files(source_files, export_volume)
                 written_path = self.mask_path
 
         self.last_export_at = self._iso_now()
@@ -1039,6 +1127,15 @@ def export_masks(
         self.last_backup_path = backup_path
         self.last_persist_error = None
         self.save_progress()
+        self._append_event(
+            "proofreading_masks_exported",
+            mode=mode_value,
+            written_path=written_path,
+            backup_path=backup_path,
+            instance_mode=self.instance_mode,
+            shape=export_volume.shape,
+            dtype=str(export_volume.dtype),
+        )
 
         return {
             "message": "Masks exported successfully",
@@ -1115,7 +1212,6 @@ def get_instance_slice_axis(
         image_slice = ensure_grayscale_2d(image_slice)
         image_slice = enhance_contrast(image_slice)
         label_slice = ensure_grayscale_2d(label_slice)
-        label_slice = to_uint8(label_slice)
         active_mask = (label_slice == instance_id).astype(np.uint8)
         return image_slice, label_slice, active_mask, index, total
 
@@ -1530,12 +1626,37 @@ def get_sparse_active_mask(
 
     def _load_volume(self, path: str) -> Dict[str, Any]:
         """Load volume data from a path"""
-        path_obj = Path(path)
+        file_path, _dataset_key = split_dataset_ref(path)
+        path_obj = Path(file_path)
 
         # Single file
         if path_obj.is_file():
-            if path.lower().endswith((".tif", ".tiff")):
-                volume = tifffile.imread(path)
+            lower_name = path_obj.name.lower()
+            if lower_name.endswith((".tif", ".tiff")):
+                volume = tifffile.imread(file_path)
+            else:
+                volume = load_volume(path)
+
+            if volume.ndim == 2:
+                return {
+                    "volume": volume,
+                    "shape": volume.shape,
+                    "num_slices": 1,
+                    "is_3d": False,
+                }
+            if volume.ndim == 3:
+                return {
+                    "volume": volume,
+                    "shape": volume.shape,
+                    "num_slices": volume.shape[0],
+                    "is_3d": True,
+                }
+            raise ValueError(f"Unsupported volume dimensions: {volume.ndim}")
+
+        # Directory or glob pattern
+        elif path_obj.is_dir() or "*" in file_path or "?" in file_path:
+            if path_obj.is_dir() and path_obj.name.lower().endswith((".zarr", ".n5")):
+                volume = load_volume(path)
                 if volume.ndim == 2:
                     return {
                         "volume": volume,
@@ -1543,33 +1664,22 @@ def _load_volume(self, path: str) -> Dict[str, Any]:
                         "num_slices": 1,
                         "is_3d": False,
                     }
-                elif volume.ndim == 3:
+                if volume.ndim == 3:
                     return {
                         "volume": volume,
                         "shape": volume.shape,
                         "num_slices": volume.shape[0],
                         "is_3d": True,
                     }
-                else:
-                    raise ValueError(f"Unsupported TIFF dimensions: {volume.ndim}")
-            else:
-                image = load_image_file(path)
-                return {
-                    "volume": image,
-                    "shape": image.shape,
-                    "num_slices": 1,
-                    "is_3d": False,
-                }
+                raise ValueError(f"Unsupported volume dimensions: {volume.ndim}")
 
-        # Directory or glob pattern
-        elif path_obj.is_dir() or "*" in path or "?" in path:
             files = []
             if path_obj.is_dir():
                 for ext in ["*.tif", "*.tiff", "*.png", "*.jpg", "*.jpeg"]:
-                    files.extend(glob.glob(os.path.join(path, ext)))
-                    files.extend(glob.glob(os.path.join(path, ext.upper())))
+                    files.extend(glob.glob(os.path.join(file_path, ext)))
+                    files.extend(glob.glob(os.path.join(file_path, ext.upper())))
             else:
-                files = glob.glob(path)
+                files = glob.glob(file_path)
 
             if not files:
                 raise ValueError(f"No image files found at: {path}")
diff --git a/server_api/ehtool/router.py b/server_api/ehtool/router.py
index 567ce397..3f4bbdfd 100644
--- a/server_api/ehtool/router.py
+++ b/server_api/ehtool/router.py
@@ -8,9 +8,39 @@
 from typing import List, Optional
 import math
 import logging
+import time
 
 logger = logging.getLogger(__name__)
 
+
+def _extract_marching_cubes_surface(
+    measure,
+    padded_volume,
+    *,
+    initial_step: int,
+    face_limit: int,
+    max_step: int = 12,
+):
+    """Extract a valid surface by increasing marching-cubes stride if needed."""
+    mesh_step = max(1, int(initial_step or 1))
+    max_step = max(mesh_step, int(max_step or mesh_step))
+    last_result = None
+
+    while mesh_step <= max_step:
+        vertices, faces, normals, values = measure.marching_cubes(
+            padded_volume,
+            level=0.5,
+            step_size=mesh_step,
+            allow_degenerate=False,
+        )
+        last_result = (vertices, faces, normals, values, mesh_step)
+        if faces.shape[0] <= face_limit:
+            return last_result
+        mesh_step += 1
+
+    return last_result
+
+
 from server_api.auth.database import get_db
 from server_api.auth.router import get_current_user
 from server_api.auth.models import User
@@ -42,18 +72,26 @@
     get_user_workflow_or_404,
     update_workflow_fields,
 )
+from app_event_logger import append_app_event
 
 router = APIRouter()
 
-# DIAGNOSTIC: This should print when the module is loaded
-print("=" * 80)
-print("EHTOOL ROUTER MODULE LOADED - VERSION: DEBUG v2")
-print("=" * 80)
-
 # In-memory cache for DataManagers (session_id -> DataManager)
 _data_managers = {}
 
 
+def _append_ehtool_event(event: str, level: str = "INFO", **fields):
+    try:
+        append_app_event(
+            component="ehtool.router",
+            event=event,
+            level=level,
+            **fields,
+        )
+    except Exception:
+        logger.debug("Failed to append EHTool app event", exc_info=True)
+
+
 def get_data_manager(session_id: int, db: Session) -> DataManager:
     """Get or create DataManager for a session"""
     if session_id not in _data_managers:
@@ -98,6 +136,14 @@ async def load_detection_dataset(
                 db, workflow_id=request.workflow_id, user_id=current_user.id
             )
 
+        _append_ehtool_event(
+            "proofreading_load_requested",
+            dataset_path=request.dataset_path,
+            mask_path=request.mask_path,
+            project_name=request.project_name,
+            workflow_id=request.workflow_id,
+        )
+
         # Create DataManager and load dataset
         data_manager = DataManager()
         dataset_info = data_manager.load_dataset(
@@ -176,6 +222,14 @@ async def load_detection_dataset(
                 },
             )
 
+        _append_ehtool_event(
+            "proofreading_load_completed",
+            session_id=db_session.id,
+            total_layers=dataset_info["total_layers"],
+            project_name=request.project_name,
+            workflow_id=request.workflow_id,
+        )
+
         return DetectionLoadResponse(
             session_id=db_session.id,
             total_layers=dataset_info["total_layers"],
@@ -183,10 +237,13 @@ async def load_detection_dataset(
         )
 
     except FileNotFoundError as e:
+        _append_ehtool_event("proofreading_load_failed", level="ERROR", error=str(e))
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(e))
     except ValueError as e:
+        _append_ehtool_event("proofreading_load_failed", level="ERROR", error=str(e))
         raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
     except Exception as e:
+        _append_ehtool_event("proofreading_load_failed", level="ERROR", error=str(e))
         raise HTTPException(
             status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
             detail=f"Failed to load dataset: {str(e)}",
@@ -260,8 +317,11 @@ async def get_detection_layers(
                 layer_info.image_base64 = image_base64
                 layer_info.mask_base64 = mask_base64
             except Exception as e:
-                print(
-                    f"[GET_LAYERS] Warning: Failed to load image for layer {db_layer.layer_index}: {e}"
+                _append_ehtool_event(
+                    "layer_preview_load_failed",
+                    level="WARNING",
+                    layer_index=db_layer.layer_index,
+                    error=str(e),
                 )
 
         layers.append(layer_info)
@@ -479,6 +539,7 @@ async def get_instance_image(
             detail="No instance data available for this session",
         )
 
+    started_at = time.perf_counter()
     try:
         (
             image_bytes,
@@ -498,6 +559,24 @@ async def get_instance_image(
         )
     except ValueError as exc:
         raise HTTPException(status_code=400, detail=str(exc)) from exc
+    elapsed_ms = (time.perf_counter() - started_at) * 1000.0
+    _append_ehtool_event(
+        "proofreading_instance_image_served",
+        session_id=session_id,
+        instance_id=instance_id,
+        kind=kind,
+        axis=resolved_axis,
+        z_index=resolved_index,
+        total_layers=total,
+        quality=quality,
+        format=format,
+        max_dim=max_dim,
+        bytes=len(image_bytes),
+        elapsed_ms=round(elapsed_ms, 2),
+        cache_hit=bool(perf_meta.get("cache_hit")),
+        decode_ms=round(float(perf_meta.get("decode_ms", 0.0)), 2),
+        resize_ms=round(float(perf_meta.get("resize_ms", 0.0)), 2),
+    )
 
     headers = {
         "X-Z-Index": str(resolved_index),
@@ -510,6 +589,212 @@ async def get_instance_image(
     return Response(content=image_bytes, media_type=media_type, headers=headers)
 
 
+@router.get("/detection/instance-volume-preview")
+async def get_instance_volume_preview(
+    session_id: int,
+    instance_id: int,
+    max_points: int = 30000,
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    db_session = (
+        db.query(EHToolSession)
+        .filter(
+            EHToolSession.id == session_id, EHToolSession.user_id == current_user.id
+        )
+        .first()
+    )
+    if not db_session:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="Session not found"
+        )
+
+    data_manager = get_data_manager(session_id, db)
+    data_manager.ensure_instances()
+
+    if data_manager.instance_volume is None:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="No instance data available for this session",
+        )
+
+    import numpy as np
+
+    volume = data_manager.instance_volume
+    if volume.ndim == 2:
+        mask = volume == int(instance_id)
+        coords_yx = np.argwhere(mask)
+        coords = np.column_stack(
+            [
+                np.zeros(coords_yx.shape[0], dtype=np.int64),
+                coords_yx[:, 0],
+                coords_yx[:, 1],
+            ]
+        )
+        shape_zyx = [1, int(volume.shape[0]), int(volume.shape[1])]
+    else:
+        mask = volume == int(instance_id)
+        coords = np.argwhere(mask)
+        shape_zyx = [int(volume.shape[0]), int(volume.shape[1]), int(volume.shape[2])]
+
+    voxel_count = int(coords.shape[0])
+    if voxel_count == 0:
+        raise HTTPException(status_code=404, detail="Instance not found")
+
+    max_points = max(1000, min(int(max_points or 30000), 80000))
+    sample_step = max(1, int(math.ceil(voxel_count / max_points)))
+    sampled = coords[::sample_step]
+    bbox_min = coords.min(axis=0).astype(int).tolist()
+    bbox_max = coords.max(axis=0).astype(int).tolist()
+
+    return {
+        "session_id": session_id,
+        "instance_id": instance_id,
+        "mode": data_manager.instance_mode or "none",
+        "shape_zyx": shape_zyx,
+        "voxel_count": voxel_count,
+        "sample_step": sample_step,
+        "points_zyx": sampled.astype(int).tolist(),
+        "bbox_zyx": {"min": bbox_min, "max": bbox_max},
+    }
+
+
+@router.get("/detection/instance-mesh-preview")
+async def get_instance_mesh_preview(
+    session_id: int,
+    instance_id: int,
+    max_faces: int = 60000,
+    step_size: Optional[int] = None,
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    db_session = (
+        db.query(EHToolSession)
+        .filter(
+            EHToolSession.id == session_id, EHToolSession.user_id == current_user.id
+        )
+        .first()
+    )
+    if not db_session:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="Session not found"
+        )
+
+    data_manager = get_data_manager(session_id, db)
+    data_manager.ensure_instances()
+
+    if data_manager.instance_volume is None:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="No instance data available for this session",
+        )
+
+    try:
+        import numpy as np
+        from skimage import measure
+    except Exception as exc:
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="3D mesh extraction requires scikit-image",
+        ) from exc
+
+    started_at = time.perf_counter()
+    volume = data_manager.instance_volume
+    label = int(instance_id)
+
+    if volume.ndim == 2:
+        mask = volume == label
+        coords_yx = np.argwhere(mask)
+        if coords_yx.size == 0:
+            raise HTTPException(status_code=404, detail="Instance not found")
+        bbox_min = np.array([0, coords_yx[:, 0].min(), coords_yx[:, 1].min()])
+        bbox_max = np.array([0, coords_yx[:, 0].max(), coords_yx[:, 1].max()])
+        crop_min = np.array(
+            [0, max(int(bbox_min[1]) - 1, 0), max(int(bbox_min[2]) - 1, 0)]
+        )
+        crop_max = np.array(
+            [
+                1,
+                min(int(bbox_max[1]) + 2, volume.shape[0]),
+                min(int(bbox_max[2]) + 2, volume.shape[1]),
+            ]
+        )
+        crop = mask[crop_min[1] : crop_max[1], crop_min[2] : crop_max[2]][
+            np.newaxis, :, :
+        ]
+        shape_zyx = [1, int(volume.shape[0]), int(volume.shape[1])]
+        voxel_count = int(coords_yx.shape[0])
+    else:
+        mask = volume == label
+        coords = np.argwhere(mask)
+        if coords.size == 0:
+            raise HTTPException(status_code=404, detail="Instance not found")
+        bbox_min = coords.min(axis=0).astype(int)
+        bbox_max = coords.max(axis=0).astype(int)
+        shape = np.array(volume.shape[:3], dtype=int)
+        crop_min = np.maximum(bbox_min - 1, 0)
+        crop_max = np.minimum(bbox_max + 2, shape)
+        crop = mask[
+            crop_min[0] : crop_max[0],
+            crop_min[1] : crop_max[1],
+            crop_min[2] : crop_max[2],
+        ]
+        shape_zyx = [int(volume.shape[0]), int(volume.shape[1]), int(volume.shape[2])]
+        voxel_count = int(coords.shape[0])
+
+    padded = np.pad(crop.astype(np.float32), 1, mode="constant", constant_values=0)
+    mesh_offset = crop_min.astype(float) - 1.0
+    crop_voxels = int(crop.size)
+    computed_step = max(1, int(math.ceil((crop_voxels / 4_000_000) ** (1 / 3))))
+    mesh_step = max(1, min(int(step_size or computed_step), 8))
+    face_limit = max(1000, min(int(max_faces or 60000), 200000))
+
+    try:
+        vertices, faces, _normals, _values, mesh_step = _extract_marching_cubes_surface(
+            measure,
+            padded,
+            initial_step=mesh_step,
+            face_limit=face_limit,
+        )
+    except ValueError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Could not extract a surface for instance {instance_id}",
+        ) from exc
+
+    vertices = vertices + mesh_offset
+
+    elapsed_ms = (time.perf_counter() - started_at) * 1000.0
+    _append_ehtool_event(
+        "proofreading_instance_mesh_served",
+        session_id=session_id,
+        instance_id=instance_id,
+        vertex_count=int(vertices.shape[0]),
+        face_count=int(faces.shape[0]),
+        voxel_count=voxel_count,
+        mesh_step=mesh_step,
+        face_limit=face_limit,
+        crop_shape=[int(v) for v in crop.shape],
+        elapsed_ms=round(elapsed_ms, 2),
+    )
+
+    return {
+        "session_id": session_id,
+        "instance_id": instance_id,
+        "mode": data_manager.instance_mode or "none",
+        "shape_zyx": shape_zyx,
+        "voxel_count": voxel_count,
+        "mesh_step": mesh_step,
+        "face_limit": face_limit,
+        "vertices_zyx": np.round(vertices, 3).astype(float).tolist(),
+        "faces": faces.astype(int).tolist(),
+        "bbox_zyx": {
+            "min": bbox_min.astype(int).tolist(),
+            "max": bbox_max.astype(int).tolist(),
+        },
+    }
+
+
 @router.get("/detection/instance-filmstrip")
 async def get_instance_filmstrip(
     session_id: int,
@@ -545,6 +830,7 @@ async def get_instance_filmstrip(
             detail="No instance data available for this session",
         )
 
+    started_at = time.perf_counter()
     try:
         (
             image_bytes,
@@ -567,6 +853,26 @@ async def get_instance_filmstrip(
         )
     except ValueError as exc:
         raise HTTPException(status_code=400, detail=str(exc)) from exc
+    elapsed_ms = (time.perf_counter() - started_at) * 1000.0
+    _append_ehtool_event(
+        "proofreading_instance_filmstrip_served",
+        session_id=session_id,
+        instance_id=instance_id,
+        kind=kind,
+        axis=resolved_axis,
+        z_start=resolved_start,
+        z_count=resolved_count,
+        total_layers=total,
+        quality=quality,
+        format=format,
+        max_dim=max_dim,
+        bytes=len(image_bytes),
+        frame_height=frame_height,
+        elapsed_ms=round(elapsed_ms, 2),
+        cache_hit=bool(perf_meta.get("cache_hit")),
+        decode_ms=round(float(perf_meta.get("decode_ms", 0.0)), 2),
+        resize_ms=round(float(perf_meta.get("resize_ms", 0.0)), 2),
+    )
 
     headers = {
         "X-Z-Start": str(resolved_start),
@@ -814,7 +1120,14 @@ async def save_instance_mask(
 
     try:
         data_manager = get_data_manager(request.session_id, db)
-        data_manager.save_instance_mask_slice(
+        _append_ehtool_event(
+            "proofreading_mask_save_requested",
+            session_id=request.session_id,
+            instance_id=request.instance_id,
+            axis=request.axis,
+            z_index=request.z_index,
+        )
+        save_result = data_manager.save_instance_mask_slice(
             instance_id=request.instance_id,
             axis=request.axis,
             index=request.z_index,
@@ -836,13 +1149,48 @@ async def save_instance_mask(
                 "z_index": request.z_index,
             },
         )
-        return {"message": "Instance mask saved successfully"}
+        persistence = data_manager.get_persistence_status()
+        _append_ehtool_event(
+            "proofreading_mask_save_completed",
+            session_id=request.session_id,
+            instance_id=request.instance_id,
+            axis=request.axis,
+            z_index=request.z_index,
+            pixels_changed=save_result.get("pixels_changed"),
+            pixels_blocked=save_result.get("pixels_blocked"),
+            artifact_path=persistence.get("artifact_path"),
+            artifact_exists=persistence.get("artifact_exists"),
+            last_saved_at=persistence.get("last_saved_at"),
+        )
+        return {
+            "message": "Instance mask saved successfully",
+            "edit": save_result,
+            "persistence": persistence,
+        }
     except ValueError as exc:
+        _append_ehtool_event(
+            "proofreading_mask_save_failed",
+            level="ERROR",
+            session_id=request.session_id,
+            instance_id=request.instance_id,
+            axis=request.axis,
+            z_index=request.z_index,
+            error=str(exc),
+        )
         raise HTTPException(status_code=400, detail=str(exc)) from exc
     except Exception as e:
         import traceback
 
         traceback.print_exc()
+        _append_ehtool_event(
+            "proofreading_mask_save_failed",
+            level="ERROR",
+            session_id=request.session_id,
+            instance_id=request.instance_id,
+            axis=request.axis,
+            z_index=request.z_index,
+            error=str(e),
+        )
         raise HTTPException(
             status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
             detail=f"Failed to save instance mask: {str(e)}",
diff --git a/server_api/ehtool/utils.py b/server_api/ehtool/utils.py
index d74d4563..3b4b5644 100644
--- a/server_api/ehtool/utils.py
+++ b/server_api/ehtool/utils.py
@@ -40,21 +40,21 @@ def _build_glasbey_palette(size: int = 256) -> None:
 def labels_to_rgba(label_slice: np.ndarray) -> np.ndarray:
     """Convert a label slice into an RGBA overlay using a Glasbey-style palette."""
     _build_glasbey_palette()
-    labels = np.unique(label_slice)
-    labels = labels[labels != 0]
-
-    h, w = label_slice.shape
+    label_array = np.asarray(label_slice)
+    h, w = label_array.shape
     rgba = np.zeros((h, w, 4), dtype=np.uint8)
-    if labels.size == 0:
+
+    foreground = label_array != 0
+    if not np.any(foreground):
         return rgba
 
-    for label in labels:
-        color = GLASBEY_COLORS[int(label) % len(GLASBEY_COLORS)]
-        mask = label_slice == label
-        rgba[mask, 0] = color[0]
-        rgba[mask, 1] = color[1]
-        rgba[mask, 2] = color[2]
-        rgba[mask, 3] = 255
+    palette = np.asarray(GLASBEY_COLORS, dtype=np.uint8)
+    label_indices = np.mod(
+        label_array[foreground].astype(np.int64, copy=False),
+        len(palette),
+    )
+    rgba[foreground, :3] = palette[label_indices]
+    rgba[foreground, 3] = 255
     return rgba
 
 
diff --git a/server_api/main.py b/server_api/main.py
index 2ea8647e..4d5fd0a3 100644
--- a/server_api/main.py
+++ b/server_api/main.py
@@ -1,20 +1,34 @@
+import inspect as py_inspect
 import json
+import logging
+import math
+import os
 import pathlib
 import re
 import shutil
 import tempfile
+import threading
 import traceback
 import time
+import uuid
+from collections import OrderedDict
 from concurrent.futures import ThreadPoolExecutor, TimeoutError
-from typing import List, Optional
+from datetime import datetime, timezone
+from typing import Any, List, Optional
 from urllib.parse import urlsplit, urlunsplit
 
 import requests
 import uvicorn
 from fastapi import Depends, FastAPI, HTTPException, Request, UploadFile
 from fastapi.middleware.cors import CORSMiddleware
+from pydantic import BaseModel
 from sqlalchemy import inspect, text
 from sqlalchemy.orm import Session
+from app_event_logger import (
+    append_app_event,
+    configure_process_logging,
+    get_app_event_log_path,
+)
 from runtime_settings import (
     get_allowed_origins,
     get_neuroglancer_public_base,
@@ -30,12 +44,31 @@
     request_id_from_request,
 )
 from server_api.workflows import router as workflow_router
+from server_api.workflows.db_models import WorkflowCommand, WorkflowEvent
 from server_api.workflows.service import (
     append_event_for_workflow_if_present,
+    command_to_dict,
+    decode_json,
+    fail_workflow_command,
     get_user_workflow_or_404,
+    mark_workflow_command_running,
+    submit_workflow_command,
     update_workflow_fields,
 )
 from server_api.project_manager import router as pm_router
+from server_api.workflows.volume_io import load_volume
+from server_api.workflows.volume_pairs import (
+    _is_chunked_volume_directory,
+    _is_neuroglancer_volume_file,
+    _path_has_suffix,
+    _resolve_neuroglancer_image_path,
+    _resolve_neuroglancer_label_path,
+    _volume_file_candidates,
+    _volume_pair_key,
+    discover_neuroglancer_volume_pairs,
+    NEUROGLANCER_VOLUME_DIR_SUFFIXES,
+    NEUROGLANCER_VOLUME_FILE_SUFFIXES,
+)
 
 from fastapi.staticfiles import StaticFiles
 import os
@@ -46,7 +79,9 @@
     from server_api.chatbot.chatbot import (
         build_chain,
         build_helper_chain,
+        _compact_agent_response,
         _format_admin_llm_error,
+        _sanitize_agent_response,
     )
 except Exception as exc:  # pragma: no cover - exercised indirectly via endpoints
     build_chain = None
@@ -59,6 +94,13 @@ def _format_admin_llm_error(error):
             "Please contact your system administrator with this error: "
             f"{str(error).strip() or error.__class__.__name__}"
         )
+
+    def _compact_agent_response(response, max_words=120):
+        return str(response or "")
+
+    def _sanitize_agent_response(response):
+        return str(response or "").strip()
+
 else:
     _chatbot_error = None
 
@@ -73,6 +115,7 @@ def _format_admin_llm_error(error):
 # Helper chat (inline "?" popovers) — keyed by taskKey for isolated sessions
 _helper_chains = {}  # taskKey -> (agent, reset_fn)
 _helper_histories = {}  # taskKey -> list of messages
+_SHARED_HELPER_CHAIN_KEY = "__shared_inline_helper__"
 
 
 def _ensure_chatbot():
@@ -111,6 +154,16 @@ def _llm_unavailable_detail(error):
     }
 
 
+def _llm_unavailable_chat_response() -> str:
+    return (
+        "I cannot reach the documentation assistant right now.\n"
+        "Do this: use the workflow actions I can still inspect: status, show data, "
+        "run model, proofread, train, compare results, or move screens.\n"
+        "Watch out: documentation search may be incomplete until the local Ollama "
+        "models are configured."
+    )
+
+
 def _invoke_with_progress(invoke_fn, *, label: str, request_id: str, poll_seconds=5.0):
     start_time = time.perf_counter()
     with ThreadPoolExecutor(max_workers=1) as executor:
@@ -119,9 +172,7 @@ def _invoke_with_progress(invoke_fn, *, label: str, request_id: str, poll_second
             try:
                 result = future.result(timeout=poll_seconds)
                 elapsed = time.perf_counter() - start_time
-                print(
-                    f"[CHATBOT][{request_id}] {label} completed in {elapsed:.2f}s"
-                )
+                print(f"[CHATBOT][{request_id}] {label} completed in {elapsed:.2f}s")
                 return result
             except TimeoutError:
                 elapsed = time.perf_counter() - start_time
@@ -129,8 +180,32 @@ def _invoke_with_progress(invoke_fn, *, label: str, request_id: str, poll_second
                     f"[CHATBOT][{request_id}] {label} still running "
                     f"after {elapsed:.2f}s..."
                 )
-REACT_APP_SERVER_PROTOCOL = "http"
-REACT_APP_SERVER_URL = "localhost:4243"
+
+
+def _env_int(name: str, default: int) -> int:
+    raw_value = os.getenv(name)
+    if raw_value is None or raw_value == "":
+        return default
+    try:
+        return int(raw_value)
+    except ValueError as exc:
+        raise RuntimeError(f"{name} must be an integer, got {raw_value!r}") from exc
+
+
+REACT_APP_SERVER_PROTOCOL = os.getenv("PYTC_WORKER_PROTOCOL", "http")
+REACT_APP_SERVER_URL = os.getenv("PYTC_WORKER_URL", "localhost:4243")
+PYTC_API_HOST = os.getenv("PYTC_API_HOST", "0.0.0.0")
+PYTC_API_PORT = _env_int("PYTC_API_PORT", 4242)
+PYTC_NEUROGLANCER_BIND_HOST = os.getenv("PYTC_NEUROGLANCER_BIND_HOST", "0.0.0.0")
+PYTC_NEUROGLANCER_PORT = _env_int("PYTC_NEUROGLANCER_PORT", 4244)
+PYTC_NEUROGLANCER_VIEWER_TTL_SECONDS = _env_int(
+    "PYTC_NEUROGLANCER_VIEWER_TTL_SECONDS",
+    2 * 60 * 60,
+)
+PYTC_NEUROGLANCER_MAX_VIEWERS = _env_int("PYTC_NEUROGLANCER_MAX_VIEWERS", 12)
+
+_retained_neuroglancer_viewers = OrderedDict()
+_retained_neuroglancer_viewers_lock = threading.RLock()
 
 models.Base.metadata.create_all(bind=database.engine)
 
@@ -149,6 +224,31 @@ def _ensure_sqlite_column(table_name: str, column_name: str, ddl: str) -> None:
 
 
 _ensure_sqlite_column("ehtool_sessions", "workflow_id", "workflow_id INTEGER")
+_ensure_sqlite_column("chat_messages", "source", "source VARCHAR")
+_ensure_sqlite_column("chat_messages", "workflow_id", "workflow_id INTEGER")
+_ensure_sqlite_column("chat_messages", "actions_json", "actions_json TEXT")
+_ensure_sqlite_column("chat_messages", "commands_json", "commands_json TEXT")
+_ensure_sqlite_column("chat_messages", "proposals_json", "proposals_json TEXT")
+_ensure_sqlite_column("chat_messages", "trace_json", "trace_json TEXT")
+_ensure_sqlite_column("workflow_sessions", "config_path", "config_path VARCHAR")
+_ensure_sqlite_column(
+    "workflow_events", "schema_version", "schema_version INTEGER DEFAULT 1 NOT NULL"
+)
+_ensure_sqlite_column("workflow_events", "idempotency_key", "idempotency_key VARCHAR")
+_ensure_sqlite_column("workflow_model_runs", "run_id", "run_id VARCHAR")
+_ensure_sqlite_column(
+    "workflow_volume_states", "annotation_state", "annotation_state VARCHAR"
+)
+_ensure_sqlite_column("workflow_volume_states", "role_state", "role_state VARCHAR")
+_ensure_sqlite_column(
+    "workflow_volume_states", "execution_state", "execution_state VARCHAR"
+)
+_ensure_sqlite_column(
+    "workflow_volume_states", "region_scope_json", "region_scope_json TEXT"
+)
+_ensure_sqlite_column(
+    "workflow_volume_states", "state_schema_version", "state_schema_version VARCHAR"
+)
 
 app = FastAPI()
 
@@ -169,12 +269,601 @@ def _ensure_sqlite_column(table_name: str, column_name: str, ddl: str) -> None:
     allow_headers=["*"],
 )
 
+logger = logging.getLogger(__name__)
+
+
+UM_NEUROGLANCER_RAW_IMAGE_SHADER = """#uicontrol invlerp normalized
+#uicontrol float brightness slider(min=-1, max=1)
+#uicontrol float contrast slider(min=-3, max=3, step=0.01)
+
+void main() {
+  emitGrayscale((normalized() + brightness) * exp(contrast));
+}
+"""
+
+UM_NEUROGLANCER_MASK_RED_SHADER = """void main() {
+  emitRGB(vec3(1.0, 0.0, 0.0));
+}
+"""
+
+
+def _has_single_neuroglancer_main(shader: str) -> bool:
+    return len(re.findall(r"\bvoid\s+main\s*\(", shader)) == 1
+
+
+def _resolve_raw_image_shader() -> str:
+    # Applied to raw image layers by default for the UM/Yixiao Neuroglancer view.
+    # This is intentionally shared for all raw image layers unless this helper is
+    # tightened later for a narrower demo scope.
+    return UM_NEUROGLANCER_RAW_IMAGE_SHADER
+
+
+def _resolve_mask_image_shader() -> str:
+    # Red mask/prediction image-layer shader. Segmentation layers use
+    # dedicated segmentation rendering instead and should not receive this shader.
+    return UM_NEUROGLANCER_MASK_RED_SHADER
+
+
+def _with_neuroglancer_image_shader(
+    neuroglancer_module,
+    layer_source,
+    shader: str,
+):
+    image_layer = getattr(neuroglancer_module, "ImageLayer", None)
+    if image_layer is None:
+        try:
+            layer_source.shader = shader
+        except Exception:
+            logger.debug(
+                "Unable to attach Neuroglancer image shader directly.", exc_info=True
+            )
+        return layer_source
+
+    try:
+        image_init_signature = py_inspect.signature(image_layer.__init__)
+        if "shader" in image_init_signature.parameters:
+            return image_layer(source=layer_source, shader=shader)
+    except Exception:
+        logger.debug(
+            "Unable to probe Neuroglancer ImageLayer __init__ signature.", exc_info=True
+        )
+
+    try:
+        return image_layer(source=layer_source, shader=shader)
+    except TypeError:
+        try:
+            layer_source.shader = shader
+        except Exception:
+            logger.debug(
+                "Unable to apply Neuroglancer image shader to layer source.",
+                exc_info=True,
+            )
+    return layer_source
+
+
+def _build_neuroglancer_local_volume_source(
+    neuroglancer_module,
+    data,
+    dimensions,
+    *,
+    volume_type: str = "image",
+    voxel_offset=(0, 0, 0),
+):
+    return neuroglancer_module.LocalVolume(
+        data,
+        dimensions=dimensions,
+        volume_type=volume_type,
+        voxel_offset=voxel_offset,
+    )
+
+
+def _build_neuroglancer_layer(
+    neuroglancer_module,
+    data,
+    dimensions,
+    *,
+    volume_type: str = "image",
+    voxel_offset=(0, 0, 0),
+    image_shader: Optional[str] = None,
+    segmentation_kwargs: Optional[dict[str, Any]] = None,
+):
+    source = _build_neuroglancer_local_volume_source(
+        neuroglancer_module,
+        data,
+        dimensions,
+        volume_type=volume_type,
+        voxel_offset=voxel_offset,
+    )
+    if volume_type == "segmentation":
+        if segmentation_kwargs is None:
+            return neuroglancer_module.SegmentationLayer(source=source)
+        return neuroglancer_module.SegmentationLayer(
+            source=source, **segmentation_kwargs
+        )
+    shader = image_shader or _resolve_raw_image_shader()
+    return _with_neuroglancer_image_shader(neuroglancer_module, source, shader)
+
+
+class ClientAppLogEvent(BaseModel):
+    event: str
+    level: str = "INFO"
+    message: Optional[str] = None
+    source: Optional[str] = None
+    sessionId: Optional[str] = None
+    url: Optional[str] = None
+    data: Optional[dict[str, Any]] = None
+
+
+class WorkflowInferenceRuntimeSyncRequest(BaseModel):
+    stage: Optional[str] = None
+
+
+class NeuroglancerProofreadRequest(BaseModel):
+    image: Optional[str] = None
+    label: Optional[str] = None
+    scales: Optional[List[float]] = None
+    workflow_id: Optional[int] = None
+    workflowId: Optional[int] = None
+    session_id: Optional[int] = None
+    sessionId: Optional[int] = None
+    active_instance_id: Optional[int] = None
+    activeInstanceId: Optional[int] = None
+    initial_voxel: Optional[List[float]] = None
+    initialVoxel: Optional[List[float]] = None
+
+
+_PREDICTION_OUTPUT_SUFFIXES = (
+    ".h5",
+    ".hdf5",
+    ".hdf",
+    ".tif",
+    ".tiff",
+    ".ome.tif",
+    ".ome.tiff",
+    ".zarr",
+    ".n5",
+    ".npy",
+    ".npz",
+    ".nii",
+    ".nii.gz",
+    ".mrc",
+    ".map",
+    ".rec",
+)
+
+
+def _path_has_prediction_suffix(path: pathlib.Path) -> bool:
+    lower_name = path.name.lower()
+    lower_path = str(path).lower()
+    return lower_name.endswith(_PREDICTION_OUTPUT_SUFFIXES) or lower_path.endswith(
+        (".ome.tif", ".ome.tiff", ".nii.gz")
+    )
+
+
+def _is_prediction_output_candidate(path: pathlib.Path) -> bool:
+    if path.name.startswith("."):
+        return False
+    if not _path_has_prediction_suffix(path):
+        return False
+    if path.is_dir():
+        return path.name.lower().endswith((".zarr", ".n5"))
+    return path.is_file()
+
+
+def _prediction_output_priority(path: pathlib.Path) -> tuple[float, int, str]:
+    name = path.name.lower()
+    preferred = 0
+    if name.startswith("result_xy"):
+        preferred = 3
+    elif name.startswith("result"):
+        preferred = 2
+    elif "prediction" in name or "pred" in name:
+        preferred = 1
+    try:
+        mtime = path.stat().st_mtime
+    except OSError:
+        mtime = 0.0
+    return (mtime, preferred, path.name)
+
+
+def _discover_prediction_output(path_value: Optional[str]) -> Optional[str]:
+    if not path_value or not str(path_value).strip():
+        return None
+
+    candidate = pathlib.Path(str(path_value).strip()).expanduser()
+    if not candidate.is_absolute():
+        candidate = (pathlib.Path.cwd() / candidate).resolve()
+    else:
+        candidate = candidate.resolve()
+    if _is_prediction_output_candidate(candidate):
+        return str(candidate)
+
+    if candidate.is_dir():
+        output_dir = candidate
+    elif candidate.parent.exists():
+        output_dir = candidate.parent
+    else:
+        return None
+
+    candidates = [
+        child
+        for child in output_dir.rglob("*")
+        if _is_prediction_output_candidate(child)
+    ]
+    if not candidates:
+        return None
+    return str(max(candidates, key=_prediction_output_priority).resolve())
+
+
+def _metadata_path(metadata: dict[str, Any], *keys: str) -> Optional[str]:
+    for key in keys:
+        value = metadata.get(key)
+        if isinstance(value, str) and value.strip():
+            return value
+    return None
+
+
+def _find_synced_inference_event(
+    db: Session,
+    *,
+    workflow_id: int,
+    event_type: str,
+    output_path: Optional[str] = None,
+    ended_at: Optional[str] = None,
+) -> Optional[WorkflowEvent]:
+    events = (
+        db.query(WorkflowEvent)
+        .filter(
+            WorkflowEvent.workflow_id == workflow_id,
+            WorkflowEvent.event_type == event_type,
+        )
+        .order_by(WorkflowEvent.id.desc())
+        .all()
+    )
+    for event in events:
+        payload = decode_json(event.payload_json)
+        if payload.get("source") != "runtime_sync":
+            continue
+        if output_path and payload.get("outputPath") == output_path:
+            return event
+        if ended_at and payload.get("runtimeEndedAt") == ended_at:
+            return event
+    return None
+
+
+def _resolve_existing_runtime_path(path_value: Any) -> Optional[str]:
+    if not isinstance(path_value, str) or not path_value.strip():
+        return None
+    candidate = pathlib.Path(path_value).expanduser()
+    if not candidate.is_absolute():
+        candidate = pathlib.Path(process_path(path_value))
+    if candidate.exists():
+        return str(candidate.resolve())
+    return None
+
+
+def _require_runtime_path(path_value: Any, role: str) -> str:
+    resolved = _resolve_existing_runtime_path(path_value)
+    if resolved:
+        return resolved
+    raise HTTPException(
+        status_code=400,
+        detail=f"{role} path does not exist: {path_value or '<empty>'}",
+    )
+
+
+def _first_existing_runtime_path(role: str, *path_values: Any) -> str:
+    first_requested = None
+    for path_value in path_values:
+        if not isinstance(path_value, str) or not path_value.strip():
+            continue
+        if first_requested is None:
+            first_requested = path_value
+        resolved = _resolve_existing_runtime_path(path_value)
+        if resolved:
+            return resolved
+    raise HTTPException(
+        status_code=400,
+        detail=f"{role} path does not exist: {first_requested or '<empty>'}",
+    )
+
+
+def _runtime_body_with_workflow_fallbacks(
+    body: dict[str, Any],
+    workflow,
+    *,
+    mode: str,
+) -> dict[str, Any]:
+    next_body = dict(body)
+    metadata = decode_json(getattr(workflow, "metadata_json", None))
+    if mode == "training":
+        next_body["inputImagePath"] = _first_existing_runtime_path(
+            "Training image",
+            next_body.get("inputImagePath"),
+            workflow.image_path,
+            metadata.get("image_path"),
+            metadata.get("image"),
+            metadata.get("imageDataPath"),
+            metadata.get("inputImagePath"),
+        )
+        next_body["inputLabelPath"] = _first_existing_runtime_path(
+            "Training label",
+            next_body.get("inputLabelPath"),
+            workflow.corrected_mask_path,
+            workflow.label_path,
+            workflow.mask_path,
+            metadata.get("corrected_mask_path"),
+            metadata.get("label_path"),
+            metadata.get("mask_path"),
+            metadata.get("inputLabelPath"),
+        )
+        return next_body
+
+    if mode == "inference":
+        next_body["inputImagePath"] = _first_existing_runtime_path(
+            "Inference image",
+            next_body.get("inputImagePath"),
+            workflow.image_path,
+            metadata.get("image_path"),
+            metadata.get("image"),
+            metadata.get("imageDataPath"),
+            metadata.get("inputImagePath"),
+        )
+        checkpoint = (next_body.get("arguments") or {}).get(
+            "checkpoint"
+        ) or next_body.get("checkpointPath")
+        checkpoint = _first_existing_runtime_path(
+            "Checkpoint",
+            checkpoint,
+            workflow.checkpoint_path,
+            metadata.get("checkpoint_path"),
+            metadata.get("checkpointPath"),
+        )
+        arguments = dict(next_body.get("arguments") or {})
+        arguments["checkpoint"] = checkpoint
+        next_body["arguments"] = arguments
+        next_body["checkpointPath"] = checkpoint
+        return next_body
+
+    return next_body
+
+
+def _first_string(*values: Any) -> Optional[str]:
+    for value in values:
+        if isinstance(value, str) and value.strip():
+            return value.strip()
+    return None
+
+
+def _build_training_body_from_command(
+    command: WorkflowCommand,
+    workflow,
+) -> dict[str, Any]:
+    command_input = decode_json(command.input_json)
+    client_effects = command_input.get("client_effects")
+    if not isinstance(client_effects, dict):
+        client_effects = {}
+    runtime_action = client_effects.get("runtime_action")
+    if not isinstance(runtime_action, dict):
+        runtime_action = {}
+
+    config_origin_path = _first_string(
+        command_input.get("configOriginPath"),
+        command_input.get("config_origin_path"),
+        command_input.get("config_preset"),
+        client_effects.get("set_training_config_preset"),
+        workflow.config_path,
+    )
+    training_config = _first_string(
+        command_input.get("trainingConfig"),
+        command_input.get("training_config"),
+    )
+    if not training_config:
+        if not config_origin_path:
+            raise HTTPException(
+                status_code=400,
+                detail="Training command is missing a config preset or config text.",
+            )
+        config_origin_path, training_config = _read_pytc_config_content(
+            config_origin_path
+        )
+
+    output_path = _first_string(
+        command_input.get("outputPath"),
+        command_input.get("output_path"),
+        client_effects.get("set_training_output_path"),
+        workflow.training_output_path,
+    )
+    if not output_path:
+        raise HTTPException(
+            status_code=400,
+            detail="Training command is missing an output path.",
+        )
+
+    label_path = _first_string(
+        command_input.get("inputLabelPath"),
+        command_input.get("label_path"),
+        client_effects.get("set_training_label_path"),
+        workflow.corrected_mask_path,
+        workflow.label_path,
+        workflow.mask_path,
+    )
+    image_path = _first_string(
+        command_input.get("inputImagePath"),
+        command_input.get("image_path"),
+        client_effects.get("set_training_image_path"),
+        workflow.image_path,
+    )
+    log_path = _first_string(
+        command_input.get("logPath"),
+        command_input.get("log_path"),
+        client_effects.get("set_training_log_path"),
+        output_path,
+    )
+    run_id = _first_string(
+        command_input.get("run_id"),
+        command_input.get("runId"),
+        f"workflow-command-{command.id}",
+    )
+
+    return {
+        "trainingConfig": training_config,
+        "configOriginPath": config_origin_path,
+        "outputPath": output_path,
+        "logPath": log_path,
+        "inputImagePath": image_path,
+        "inputLabelPath": label_path,
+        "workflowId": workflow.id,
+        "workflow_id": workflow.id,
+        "command_id": command.id,
+        "run_id": run_id,
+        "autoParameters": bool(
+            command_input.get("autoParameters")
+            or command_input.get("auto_parameters")
+            or command_input.get("autopick_parameters")
+            or runtime_action.get("autopick_parameters")
+        ),
+    }
+
+
+@app.on_event("startup")
+async def configure_app_event_logging():
+    log_path = configure_process_logging("server_api")
+    logger.info("App event logging enabled at %s", log_path)
+    append_app_event(
+        component="server_api",
+        event="api_runtime_configured",
+        level="INFO",
+        message="API runtime configuration loaded.",
+        api_host=PYTC_API_HOST,
+        api_port=PYTC_API_PORT,
+        worker_protocol=REACT_APP_SERVER_PROTOCOL,
+        worker_url=REACT_APP_SERVER_URL,
+        neuroglancer_port=PYTC_NEUROGLANCER_PORT,
+        neuroglancer_public_base=get_neuroglancer_public_base(),
+        log_path=str(log_path),
+    )
+
+
+def _normalize_api_compat_path(path: str) -> Optional[str]:
+    if path.startswith("/api/api/"):
+        return "/api/" + path[len("/api/api/") :]
+    if path == "/api/files":
+        return "/files"
+    if path.startswith("/api/files/"):
+        return "/files/" + path[len("/api/files/") :]
+    if path.startswith("/api/app/"):
+        return "/app/" + path[len("/api/app/") :]
+    if path == "/api/neuroglancer":
+        return "/neuroglancer"
+    if path.startswith("/api/neuroglancer/"):
+        return "/neuroglancer/" + path[len("/api/neuroglancer/") :]
+    if path.startswith("/api/start_model_"):
+        return path[len("/api") :]
+    if path.startswith("/api/stop_model_"):
+        return path[len("/api") :]
+    if path in {
+        "/api/training_status",
+        "/api/training_logs",
+        "/api/inference_status",
+        "/api/inference_logs",
+        "/api/start_tensorboard",
+        "/api/get_tensorboard_url",
+        "/api/get_tensorboard_status",
+    }:
+        return path[len("/api") :]
+    return None
+
+
+@app.middleware("http")
+async def log_http_requests(request: Request, call_next):
+    request_id = request_id_from_request(request)
+    start_time = time.perf_counter()
+    path = request.url.path
+    normalized_path = _normalize_api_compat_path(path)
+    if normalized_path:
+        request.scope["path"] = normalized_path
+        request.scope["raw_path"] = normalized_path.encode("utf-8")
+        path = normalized_path
+    method = request.method
+    client_host = request.client.host if request.client else None
+    is_client_log_endpoint = path == "/app/log-event"
+    if not is_client_log_endpoint:
+        append_app_event(
+            component="server_api",
+            event="http_request_started",
+            level="INFO",
+            message=f"{method} {path}",
+            request_id=request_id,
+            method=method,
+            path=path,
+            query=str(request.url.query or ""),
+            client_host=client_host,
+        )
+    try:
+        response = await call_next(request)
+    except Exception as exc:
+        append_app_event(
+            component="server_api",
+            event="http_request_failed",
+            level="ERROR",
+            message=f"{method} {path} failed",
+            request_id=request_id,
+            method=method,
+            path=path,
+            client_host=client_host,
+            latency_ms=round((time.perf_counter() - start_time) * 1000, 2),
+            error_type=exc.__class__.__name__,
+            error=str(exc),
+        )
+        raise
+
+    response.headers.setdefault("x-request-id", request_id)
+    latency_ms = round((time.perf_counter() - start_time) * 1000, 2)
+    if not is_client_log_endpoint or response.status_code >= 400 or latency_ms >= 1000:
+        append_app_event(
+            component="server_api",
+            event="http_request_completed",
+            level="INFO",
+            message=f"{method} {path} -> {response.status_code}",
+            request_id=request_id,
+            method=method,
+            path=path,
+            client_host=client_host,
+            status_code=response.status_code,
+            latency_ms=latency_ms,
+        )
+    return response
+
 
 @app.get("/health")
 def health():
     return {"status": "ok"}
 
 
+@app.get("/app/log-path")
+def app_log_path():
+    return {"path": str(get_app_event_log_path())}
+
+
+@app.post("/app/log-event")
+async def app_log_event(payload: ClientAppLogEvent, request: Request):
+    request_id = request_id_from_request(request)
+    append_app_event(
+        component="client",
+        event=payload.event,
+        level=payload.level,
+        message=payload.message,
+        source=payload.source,
+        session_id=payload.sessionId,
+        url=payload.url,
+        data=payload.data or {},
+        request_id=request_id,
+        client_host=request.client.host if request.client else None,
+    )
+    return {"status": "ok"}
+
+
 def _worker_url(path: str) -> str:
     return f"{REACT_APP_SERVER_PROTOCOL}://{REACT_APP_SERVER_URL}{path}"
 
@@ -194,7 +883,7 @@ def _derive_neuroglancer_public_base(request: Request) -> str:
         forwarded_host.split(",")[0].strip() if forwarded_host else request.url.netloc
     )
     hostname = request_host.split(":")[0] or "localhost"
-    return f"{scheme}://{hostname}:4244"
+    return f"{scheme}://{hostname}:{PYTC_NEUROGLANCER_PORT}"
 
 
 def _build_neuroglancer_public_url(viewer_url: str, request: Request) -> str:
@@ -215,6 +904,123 @@ def _build_neuroglancer_public_url(viewer_url: str, request: Request) -> str:
     )
 
 
+def _neuroglancer_token_from_url(viewer_url: str) -> Optional[str]:
+    path_parts = [part for part in urlsplit(viewer_url).path.split("/") if part]
+    if len(path_parts) >= 2 and path_parts[-2] == "v":
+        return path_parts[-1]
+    return None
+
+
+def _cleanup_retained_neuroglancer_viewers(now: Optional[float] = None):
+    if now is None:
+        now = time.time()
+    evicted = []
+    ttl_seconds = max(PYTC_NEUROGLANCER_VIEWER_TTL_SECONDS, 0)
+
+    if ttl_seconds:
+        for token, entry in list(_retained_neuroglancer_viewers.items()):
+            if now - entry["created_at"] > ttl_seconds:
+                evicted.append(
+                    {
+                        "token": token,
+                        "reason": "ttl",
+                        "age_seconds": round(now - entry["created_at"], 3),
+                        "mode": entry.get("mode"),
+                    }
+                )
+                _retained_neuroglancer_viewers.pop(token, None)
+
+    max_viewers = max(PYTC_NEUROGLANCER_MAX_VIEWERS, 0)
+    while max_viewers and len(_retained_neuroglancer_viewers) > max_viewers:
+        token, entry = _retained_neuroglancer_viewers.popitem(last=False)
+        evicted.append(
+            {
+                "token": token,
+                "reason": "capacity",
+                "age_seconds": round(now - entry["created_at"], 3),
+                "mode": entry.get("mode"),
+            }
+        )
+
+    return evicted
+
+
+def _retain_neuroglancer_viewer(
+    viewer,
+    *,
+    public_url: str,
+    internal_viewer_url: str,
+    mode: str,
+    workflow_id: Optional[int] = None,
+    image_path: Optional[str] = None,
+    label_path: Optional[str] = None,
+) -> Optional[str]:
+    token = getattr(viewer, "token", None) or _neuroglancer_token_from_url(
+        internal_viewer_url
+    )
+    if not token:
+        append_app_event(
+            component="server_api",
+            event="neuroglancer_viewer_retain_failed",
+            level="ERROR",
+            message="Could not retain Neuroglancer viewer because no token was found.",
+            public_url=public_url,
+            internal_viewer_url=internal_viewer_url,
+            workflow_id=workflow_id,
+            mode=mode,
+        )
+        return None
+
+    now = time.time()
+    with _retained_neuroglancer_viewers_lock:
+        if PYTC_NEUROGLANCER_MAX_VIEWERS <= 0:
+            _retained_neuroglancer_viewers.clear()
+            append_app_event(
+                component="server_api",
+                event="neuroglancer_viewer_retention_disabled",
+                level="ERROR",
+                message="Neuroglancer viewer retention is disabled; returned viewer URLs may expire immediately.",
+                viewer_token=token,
+                public_url=public_url,
+                workflow_id=workflow_id,
+                mode=mode,
+            )
+            return token
+
+        evicted = _cleanup_retained_neuroglancer_viewers(now)
+        _retained_neuroglancer_viewers[token] = {
+            "viewer": viewer,
+            "public_url": public_url,
+            "internal_viewer_url": internal_viewer_url,
+            "mode": mode,
+            "workflow_id": workflow_id,
+            "image_path": image_path,
+            "label_path": label_path,
+            "created_at": now,
+        }
+        _retained_neuroglancer_viewers.move_to_end(token)
+        evicted.extend(_cleanup_retained_neuroglancer_viewers(now))
+        retained_count = len(_retained_neuroglancer_viewers)
+
+    append_app_event(
+        component="server_api",
+        event="neuroglancer_viewer_retained",
+        message="Retained live Neuroglancer viewer for iframe access.",
+        viewer_token=token,
+        public_url=public_url,
+        internal_viewer_url=internal_viewer_url,
+        workflow_id=workflow_id,
+        mode=mode,
+        image_path=image_path,
+        label_path=label_path,
+        retained_count=retained_count,
+        max_viewers=PYTC_NEUROGLANCER_MAX_VIEWERS,
+        ttl_seconds=PYTC_NEUROGLANCER_VIEWER_TTL_SECONDS,
+        evicted=evicted,
+    )
+    return token
+
+
 def _extract_upstream_payload(response: requests.Response):
     try:
         return response.json()
@@ -232,6 +1038,20 @@ def _proxy_to_worker(
     timeout: int = 30,
 ):
     target_url = _worker_url(path)
+    start_time = time.perf_counter()
+    method_upper = method.upper()
+    append_app_event(
+        component="server_api",
+        event="worker_proxy_request_started",
+        level="INFO",
+        message=f"{method_upper} {path} -> PyTC worker",
+        method=method_upper,
+        path=path,
+        worker_url=target_url,
+        timeout_seconds=timeout,
+        has_json_body=bool(json_body),
+        json_keys=sorted(json_body.keys()) if isinstance(json_body, dict) else None,
+    )
     try:
         response = requests.request(
             method=method,
@@ -241,6 +1061,18 @@ def _proxy_to_worker(
             timeout=timeout,
         )
     except requests.exceptions.ConnectionError as exc:
+        append_app_event(
+            component="server_api",
+            event="worker_proxy_request_failed",
+            level="ERROR",
+            message="Failed to connect to PyTC worker.",
+            method=method_upper,
+            path=path,
+            worker_url=target_url,
+            latency_ms=round((time.perf_counter() - start_time) * 1000, 2),
+            error="ConnectionError",
+            reason=str(exc),
+        )
         raise HTTPException(
             status_code=503,
             detail={
@@ -251,6 +1083,17 @@ def _proxy_to_worker(
             },
         ) from exc
     except requests.exceptions.Timeout as exc:
+        append_app_event(
+            component="server_api",
+            event="worker_proxy_request_failed",
+            level="ERROR",
+            message="PyTC worker request timed out.",
+            method=method_upper,
+            path=path,
+            worker_url=target_url,
+            latency_ms=round((time.perf_counter() - start_time) * 1000, 2),
+            error="Timeout",
+        )
         raise HTTPException(
             status_code=504,
             detail={
@@ -260,6 +1103,18 @@ def _proxy_to_worker(
             },
         ) from exc
     except requests.RequestException as exc:
+        append_app_event(
+            component="server_api",
+            event="worker_proxy_request_failed",
+            level="ERROR",
+            message="Unexpected error while calling PyTC worker.",
+            method=method_upper,
+            path=path,
+            worker_url=target_url,
+            latency_ms=round((time.perf_counter() - start_time) * 1000, 2),
+            error=type(exc).__name__,
+            reason=str(exc),
+        )
         raise HTTPException(
             status_code=502,
             detail={
@@ -270,6 +1125,18 @@ def _proxy_to_worker(
             },
         ) from exc
     except Exception as exc:
+        append_app_event(
+            component="server_api",
+            event="worker_proxy_request_failed",
+            level="ERROR",
+            message="Unhandled error while calling PyTC worker.",
+            method=method_upper,
+            path=path,
+            worker_url=target_url,
+            latency_ms=round((time.perf_counter() - start_time) * 1000, 2),
+            error=type(exc).__name__,
+            reason=str(exc),
+        )
         raise HTTPException(
             status_code=502,
             detail={
@@ -282,6 +1149,18 @@ def _proxy_to_worker(
 
     payload = _extract_upstream_payload(response)
     if response.status_code >= 400:
+        append_app_event(
+            component="server_api",
+            event="worker_proxy_request_completed",
+            level="ERROR",
+            message="PyTC worker returned an error.",
+            method=method_upper,
+            path=path,
+            worker_url=target_url,
+            latency_ms=round((time.perf_counter() - start_time) * 1000, 2),
+            status_code=response.status_code,
+            upstream_body=payload,
+        )
         raise HTTPException(
             status_code=response.status_code,
             detail={
@@ -291,6 +1170,17 @@ def _proxy_to_worker(
                 "upstream_body": payload,
             },
         )
+    append_app_event(
+        component="server_api",
+        event="worker_proxy_request_completed",
+        level="INFO",
+        message=f"{method_upper} {path} -> PyTC worker {response.status_code}",
+        method=method_upper,
+        path=path,
+        worker_url=target_url,
+        latency_ms=round((time.perf_counter() - start_time) * 1000, 2),
+        status_code=response.status_code,
+    )
     return payload
 
 
@@ -338,13 +1228,48 @@ def _is_valid_config_path(path: pathlib.Path) -> bool:
     )
 
 
+def _iter_external_config_roots():
+    root_values = [
+        os.getenv("PYTC_INITIAL_PROJECT_ROOT"),
+        "/home/weidf/demo_data",
+    ]
+    configured = os.getenv("PYTC_ADDITIONAL_CONFIG_ROOTS", "")
+    if configured:
+        root_values.extend(
+            value.strip()
+            for chunk in configured.split(os.pathsep)
+            for value in chunk.split(",")
+            if value.strip()
+        )
+    seen = set()
+    for value in root_values:
+        if not value:
+            continue
+        root = pathlib.Path(value).expanduser().resolve()
+        if root in seen or not root.exists() or not root.is_dir():
+            continue
+        seen.add(root)
+        yield root
+
+
+def _is_valid_external_config_path(path: pathlib.Path) -> bool:
+    if not path.is_file():
+        return False
+    if path.suffix.lower() not in PYTC_CONFIG_SUFFIXES:
+        return False
+    return any(_is_relative_to(path, root) for root in _iter_external_config_roots())
+
+
 def _resolve_requested_config(path: str) -> Optional[pathlib.Path]:
     if not path:
         return None
 
     normalized = path.replace("\\", "/").strip()
-    if not normalized or normalized.startswith("/"):
+    if not normalized:
         return None
+    if normalized.startswith("/"):
+        candidate = pathlib.Path(normalized).expanduser().resolve()
+        return candidate if _is_valid_external_config_path(candidate) else None
     if ".." in pathlib.PurePosixPath(normalized).parts:
         return None
 
@@ -358,23 +1283,30 @@ def _resolve_requested_config(path: str) -> Optional[pathlib.Path]:
     return None
 
 
+def _config_response_path(path: pathlib.Path) -> str:
+    try:
+        return str(path.relative_to(PYTC_ROOT)).replace("\\", "/")
+    except ValueError:
+        return str(path)
+
+
 def _read_model_architectures() -> List[str]:
-    # Prefer runtime registry from the installed connectomics package.
+    # Prefer the runtime model map from the installed connectomics package.
     try:
-        from connectomics.models.arch import list_architectures
+        from connectomics.model.build import MODEL_MAP
 
-        architectures = list_architectures()
+        architectures = sorted(set(MODEL_MAP.keys()))
         if architectures:
-            return sorted(set(architectures))
+            return architectures
     except Exception:
         pass
 
-    # Fallback: parse decorator registrations from source files.
-    pattern = re.compile(r"""@register_architecture\(\s*['"]([^'"]+)['"]\s*\)""")
+    # Fallback: parse the static model map from source.
+    pattern = re.compile(r"""['"]([^'"]+)['"]\s*:\s*[A-Za-z_][A-Za-z0-9_]*""")
     architectures = []
-    arch_root = PYTC_ROOT / "connectomics" / "models" / "arch"
-    for py_file in arch_root.rglob("*.py"):
-        text = py_file.read_text(encoding="utf-8", errors="ignore")
+    build_file = PYTC_ROOT / "connectomics" / "model" / "build.py"
+    if build_file.is_file():
+        text = build_file.read_text(encoding="utf-8", errors="ignore")
         architectures.extend(pattern.findall(text))
     return sorted(set(architectures))
 
@@ -395,10 +1327,19 @@ def get_pytc_config(path: str):
     if requested is None:
         raise HTTPException(status_code=404, detail="Config not found.")
     content = requested.read_text(encoding="utf-8", errors="ignore")
-    canonical_path = str(requested.relative_to(PYTC_ROOT)).replace("\\", "/")
+    canonical_path = _config_response_path(requested)
     return {"path": canonical_path, "content": content}
 
 
+def _read_pytc_config_content(path: str) -> tuple[str, str]:
+    requested = _resolve_requested_config(path)
+    if requested is None:
+        raise HTTPException(status_code=404, detail=f"Config not found: {path}")
+    content = requested.read_text(encoding="utf-8", errors="ignore")
+    canonical_path = _config_response_path(requested)
+    return canonical_path, content
+
+
 @app.get("/pytc/architectures")
 def list_pytc_architectures():
     architectures = _read_model_architectures()
@@ -445,6 +1386,249 @@ def _is_probable_label_volume(image_array) -> bool:
     return False
 
 
+def _smallest_unsigned_dtype_for_max(max_value: int):
+    import numpy as np
+
+    if max_value <= np.iinfo(np.uint8).max:
+        return np.uint8
+    if max_value <= np.iinfo(np.uint16).max:
+        return np.uint16
+    if max_value <= np.iinfo(np.uint32).max:
+        return np.uint32
+    return np.uint64
+
+
+def _derive_two_channel_prediction_preview(array):
+    import numpy as np
+
+    semantic = np.asarray(array[0])
+    boundary = np.asarray(array[1])
+
+    if np.issubdtype(semantic.dtype, np.floating):
+        if not np.all(np.isfinite(semantic)):
+            raise ValueError(
+                "2-channel prediction foreground contains NaN or infinity."
+            )
+        foreground_threshold = (
+            0.5 if float(np.nanmax(semantic, initial=0.0)) <= 1.0 else 127.5
+        )
+        foreground = semantic > foreground_threshold
+    else:
+        foreground = semantic > 0
+
+    if np.issubdtype(boundary.dtype, np.floating):
+        if not np.all(np.isfinite(boundary)):
+            raise ValueError("2-channel prediction boundary contains NaN or infinity.")
+        boundary_threshold = (
+            0.5 if float(np.nanmax(boundary, initial=0.0)) <= 1.0 else 127.5
+        )
+        boundary_mask = boundary > boundary_threshold
+    else:
+        boundary_mask = boundary > 0
+
+    foreground = foreground & ~boundary_mask
+    if not np.any(foreground):
+        return foreground.astype(np.uint8, copy=False)
+
+    try:
+        from scipy import ndimage
+
+        labels, _count = ndimage.label(foreground)
+    except Exception:
+        labels = foreground.astype(np.uint8, copy=False)
+    return labels
+
+
+def _normalize_segmentation_volume_for_neuroglancer(volume):
+    import numpy as np
+
+    array = np.asarray(volume)
+    if array.ndim == 4:
+        if array.shape[0] <= 16:
+            channel_axis = 0
+        elif array.shape[-1] <= 16:
+            channel_axis = -1
+        else:
+            raise ValueError(
+                "4D label volumes must use a small channel axis to be visualized."
+            )
+
+        if channel_axis != 0:
+            array = np.moveaxis(array, channel_axis, 0)
+
+        channel_count = int(array.shape[0])
+        if channel_count == 1:
+            array = array[0]
+        elif channel_count == 2:
+            try:
+                from connectomics.utils.process import bc_watershed
+
+                array = bc_watershed(array, thres_small=1, seed_thres=1)
+            except Exception as exc:
+                append_app_event(
+                    component="server_api",
+                    event="neuroglancer_prediction_preview_fallback",
+                    level="WARNING",
+                    message=(
+                        "Falling back to connected-component prediction preview "
+                        "because connectomics bc_watershed failed."
+                    ),
+                    error=str(exc),
+                )
+                array = _derive_two_channel_prediction_preview(array)
+        else:
+            array = np.argmax(array, axis=0)
+
+    if array.size == 0:
+        return array.astype(np.uint8, copy=False)
+
+    if np.issubdtype(array.dtype, np.bool_):
+        return array.astype(np.uint8, copy=False)
+
+    if np.issubdtype(array.dtype, np.floating):
+        if not np.all(np.isfinite(array)):
+            raise ValueError(
+                "Segmentation volumes must not contain NaN or infinite values."
+            )
+        rounded = np.rint(array)
+        if not np.allclose(array, rounded):
+            raise ValueError("Segmentation volumes must use integer-valued labels.")
+        array = rounded.astype(np.int64, copy=False)
+
+    if not np.issubdtype(array.dtype, np.integer):
+        raise ValueError(f"Segmentation volume dtype {array.dtype} is not supported.")
+
+    min_value = int(array.min())
+    if min_value < 0:
+        raise ValueError("Segmentation volumes must contain non-negative label ids.")
+
+    max_value = int(array.max())
+    target_dtype = _smallest_unsigned_dtype_for_max(max_value)
+    if array.dtype == np.dtype(target_dtype):
+        return array
+    return array.astype(target_dtype, copy=False)
+
+
+def _raise_missing_volume_error(path: pathlib.Path, role: str) -> None:
+    target = str(path)
+    role_name = "image" if role == "image" else "label"
+    if "/uploads/" in target or target.startswith("uploads/"):
+        raise HTTPException(
+            status_code=400,
+            detail=(
+                f"The selected {role_name} file is no longer present in app uploads. "
+                f"Please re-select or re-upload it."
+            ),
+        )
+    raise HTTPException(
+        status_code=400,
+        detail=f"The selected {role_name} file does not exist on disk: {target}",
+    )
+
+
+def _coerce_neuroglancer_scales(scales: Optional[List[float]]) -> List[float]:
+    if scales is None:
+        raise HTTPException(
+            status_code=400,
+            detail="Neuroglancer scales are required as z, y, x nanometers.",
+        )
+    if len(scales) != 3:
+        raise HTTPException(
+            status_code=400,
+            detail="Neuroglancer scales must contain z, y, x values.",
+        )
+    try:
+        coerced = [float(value) for value in scales]
+    except (TypeError, ValueError) as exc:
+        raise HTTPException(
+            status_code=400,
+            detail="Neuroglancer scales must be numeric.",
+        ) from exc
+    if any(not math.isfinite(value) or value <= 0 for value in coerced):
+        raise HTTPException(
+            status_code=400,
+            detail="Neuroglancer scales must be finite positive numbers.",
+        )
+    return coerced
+
+
+def _coerce_initial_voxel(
+    voxel: Optional[List[float]], shape: Optional[tuple[int, ...]] = None
+) -> Optional[List[float]]:
+    if voxel is None:
+        if not shape or len(shape) < 3:
+            return None
+        return [
+            float(max(int(shape[-3] // 2), 0)),
+            float(max(int(shape[-2] // 2), 0)),
+            float(max(int(shape[-1] // 2), 0)),
+        ]
+    if len(voxel) != 3:
+        raise HTTPException(
+            status_code=400,
+            detail="Initial Neuroglancer voxel must contain z, y, x values.",
+        )
+    try:
+        return [float(value) for value in voxel]
+    except (TypeError, ValueError) as exc:
+        raise HTTPException(
+            status_code=400,
+            detail="Initial Neuroglancer voxel values must be numeric.",
+        ) from exc
+
+
+def _selected_segment_from_action_state(action_state, layer_names: List[str]):
+    selected_values = getattr(action_state, "selected_values", None) or {}
+    for layer_name in layer_names:
+        selected = selected_values.get(layer_name)
+        if selected is None:
+            continue
+        value = getattr(selected, "value", selected)
+        key = getattr(value, "key", None)
+        if key is not None:
+            value = key
+        try:
+            value = int(value)
+        except (TypeError, ValueError):
+            continue
+        if value != 0:
+            return value
+    return None
+
+
+def _record_neuroglancer_proofread_action(
+    *,
+    workflow_id: Optional[int],
+    action_type: str,
+    payload: dict[str, Any],
+) -> None:
+    append_app_event(
+        component="server_api",
+        event="neuroglancer_proofread_action",
+        message=f"Neuroglancer proofreading action: {action_type}",
+        action_type=action_type,
+        workflow_id=workflow_id,
+        **payload,
+    )
+    if not workflow_id:
+        return
+    db = database.SessionLocal()
+    try:
+        append_event_for_workflow_if_present(
+            db,
+            workflow_id=int(workflow_id),
+            actor="user",
+            event_type="proofreading.neuroglancer_action",
+            stage="proofreading",
+            summary=f"Recorded Neuroglancer proofreading action: {action_type}.",
+            payload={"action_type": action_type, **payload},
+        )
+    except Exception:
+        logger.debug("Failed to record Neuroglancer workflow event", exc_info=True)
+    finally:
+        db.close()
+
+
 @app.post("/neuroglancer")
 async def neuroglancer(
     req: Request,
@@ -483,58 +1667,266 @@ async def neuroglancer(
                 cleanup_paths.append(label)
         else:
             payload = await req.json()
-            image = process_path(payload["image"])
-            label = process_path(payload.get("label"))
-            scales = payload["scales"]
+            image_value = (
+                payload.get("image")
+                or payload.get("image_path")
+                or payload.get("imagePath")
+            )
+            if not image_value:
+                raise HTTPException(
+                    status_code=400, detail="Image path or file is required."
+                )
+            image = process_path(image_value)
+            label = process_path(
+                payload.get("label")
+                or payload.get("label_path")
+                or payload.get("labelPath")
+            )
+            scales = payload.get("scales")
+            if scales is None:
+                raise HTTPException(status_code=400, detail="Scales are required.")
             workflow_id = payload.get("workflow_id") or payload.get("workflowId")
 
-        print(image, label, scales)
-
+        scales = _coerce_neuroglancer_scales(scales)
         if image is None:
             raise HTTPException(
                 status_code=400, detail="Image path or file is required."
             )
+        original_image_path = pathlib.Path(image)
+        original_label_path = pathlib.Path(label) if label is not None else None
+        if not original_image_path.exists():
+            _raise_missing_volume_error(original_image_path, "image")
+        if original_label_path is not None and not original_label_path.exists():
+            _raise_missing_volume_error(original_label_path, "label")
+        append_app_event(
+            component="server_api",
+            event="neuroglancer_request_prepared",
+            message="Preparing Neuroglancer viewer request.",
+            image_path=str(original_image_path),
+            label_path=str(original_label_path) if original_label_path else None,
+            scales=scales,
+            workflow_id=workflow_id,
+            content_type=content_type,
+            request_host=req.headers.get("host"),
+            forwarded_proto=req.headers.get("x-forwarded-proto"),
+            forwarded_host=req.headers.get("x-forwarded-host"),
+            configured_public_base=get_neuroglancer_public_base(),
+        )
+
+        pair_discovery = discover_neuroglancer_volume_pairs(
+            original_image_path,
+            original_label_path,
+        )
+        if pair_discovery["pair_count"]:
+            append_app_event(
+                component="server_api",
+                event="neuroglancer_volume_pairs_detected",
+                message="Detected image/segmentation pairs from visualization input.",
+                image_path=str(original_image_path),
+                label_path=str(original_label_path) if original_label_path else None,
+                pair_count=pair_discovery["pair_count"],
+                image_candidate_count=pair_discovery["image_candidate_count"],
+                label_candidate_count=pair_discovery["label_candidate_count"],
+                selected_pair=pair_discovery["pairs"][0],
+            )
+
+        try:
+            resolved_image_path, image_resolution_note = (
+                _resolve_neuroglancer_image_path(
+                    original_image_path,
+                    original_label_path,
+                )
+            )
+            resolved_label_path, label_resolution_note = (
+                _resolve_neuroglancer_label_path(
+                    original_label_path,
+                    resolved_image_path,
+                )
+            )
+        except ValueError as exc:
+            append_app_event(
+                component="server_api",
+                event="neuroglancer_volume_resolution_failed",
+                level="ERROR",
+                message=str(exc),
+                image_path=str(original_image_path),
+                label_path=str(original_label_path) if original_label_path else None,
+            )
+            raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+        if image_resolution_note or label_resolution_note:
+            append_app_event(
+                component="server_api",
+                event="neuroglancer_volume_path_resolved",
+                message="Resolved folder-level visualization inputs to concrete volume files.",
+                image_path=str(original_image_path),
+                label_path=str(original_label_path) if original_label_path else None,
+                resolved_image_path=str(resolved_image_path),
+                resolved_label_path=(
+                    str(resolved_label_path) if resolved_label_path else None
+                ),
+                image_resolution_note=image_resolution_note,
+                label_resolution_note=label_resolution_note,
+            )
 
         # neuroglancer setting -- bind to this to make accessible outside of container
-        ip = "0.0.0.0"
-        port = 4244
-        neuroglancer.set_server_bind_address(ip, port)
+        neuroglancer.set_server_bind_address(
+            PYTC_NEUROGLANCER_BIND_HOST, PYTC_NEUROGLANCER_PORT
+        )
         viewer = neuroglancer.Viewer()
         # Neuroglancer expects the EM volume axes in z, y, x order.
         res = neuroglancer.CoordinateSpace(
             names=["z", "y", "x"], units=["nm", "nm", "nm"], scales=scales
         )
         try:
-            im = readVol(image, image_type="im")
-            gt = readVol(label, image_type="im") if label else None
+            im = load_volume(str(resolved_image_path), label="image")
         except Exception as e:
             raise HTTPException(
                 status_code=400, detail=f"Failed to read image volume: {str(e)}"
             )
-
-        def ngLayer(data, res, oo=[0, 0, 0], tt="segmentation"):
-            return neuroglancer.LocalVolume(
-                data, dimensions=res, volume_type=tt, voxel_offset=oo
+        try:
+            gt = (
+                load_volume(str(resolved_label_path), label="label")
+                if resolved_label_path
+                else None
+            )
+            if gt is not None:
+                gt = _normalize_segmentation_volume_for_neuroglancer(gt)
+        except Exception as e:
+            raise HTTPException(
+                status_code=400, detail=f"Failed to prepare label volume: {str(e)}"
             )
 
+        def ngLayer(
+            data,
+            res,
+            tt="image",
+            oo=(0, 0, 0),
+            *,
+            image_shader: Optional[str] = None,
+            segmentation_kwargs: Optional[dict[str, Any]] = None,
+        ):
+            try:
+                return _build_neuroglancer_layer(
+                    neuroglancer,
+                    data,
+                    res,
+                    volume_type=tt,
+                    voxel_offset=oo,
+                    image_shader=image_shader or _resolve_raw_image_shader(),
+                    segmentation_kwargs=segmentation_kwargs,
+                )
+            except Exception as exc:
+                raise HTTPException(
+                    status_code=400,
+                    detail=f"Failed to prepare Neuroglancer {tt} layer: {exc}",
+                ) from exc
+
         with viewer.txn() as s:
             s.layers.append(name="im", layer=ngLayer(im, res, tt="image"))
             if gt is not None:
-                s.layers.append(name="gt", layer=ngLayer(gt, res, tt="segmentation"))
+                s.layers.append(
+                    name="gt",
+                    layer=ngLayer(
+                        gt,
+                        res,
+                        tt="segmentation",
+                    ),
+                )
 
-        public_url = _build_neuroglancer_public_url(str(viewer), req)
+        internal_viewer_url = str(viewer)
+        public_url = _build_neuroglancer_public_url(internal_viewer_url, req)
+        viewer_token = _retain_neuroglancer_viewer(
+            viewer,
+            public_url=public_url,
+            internal_viewer_url=internal_viewer_url,
+            mode="visualization",
+            workflow_id=workflow_id,
+            image_path=str(resolved_image_path),
+            label_path=str(resolved_label_path) if resolved_label_path else None,
+        )
+        append_app_event(
+            component="server_api",
+            event="neuroglancer_viewer_created",
+            level="ERROR" if public_url.startswith("http://") else "INFO",
+            message="Created Neuroglancer viewer URL.",
+            internal_viewer_url=internal_viewer_url,
+            public_url=public_url,
+            public_url_scheme=urlsplit(public_url).scheme,
+            bind_host=PYTC_NEUROGLANCER_BIND_HOST,
+            bind_port=PYTC_NEUROGLANCER_PORT,
+            configured_public_base=get_neuroglancer_public_base(),
+            request_host=req.headers.get("host"),
+            forwarded_proto=req.headers.get("x-forwarded-proto"),
+            image_path=str(resolved_image_path),
+            label_path=str(resolved_label_path) if resolved_label_path else None,
+            image_shape=list(getattr(im, "shape", []) or []),
+            label_shape=(
+                list(getattr(gt, "shape", []) or []) if gt is not None else None
+            ),
+            scales=scales,
+            workflow_id=workflow_id,
+            viewer_token=viewer_token,
+        )
+        response_payload = {
+            "url": public_url,
+            "neuroglancer_url": public_url,
+            "viewer_token": viewer_token,
+            "image_path": str(resolved_image_path),
+            "label_path": str(resolved_label_path) if resolved_label_path else None,
+            "requested_image_path": str(original_image_path),
+            "requested_label_path": (
+                str(original_label_path) if original_label_path else None
+            ),
+            "image_resolution_note": image_resolution_note,
+            "label_resolution_note": label_resolution_note,
+            "scales": scales,
+            "pair_discovery": pair_discovery,
+            "pair_question": (
+                (
+                    "I found "
+                    f"{pair_discovery['pair_count']} clear image/segmentation pairs. "
+                    "I opened the first one. Are there other folders or pairs I should include?"
+                )
+                if pair_discovery["pair_count"] > 1
+                else None
+            ),
+        }
         if workflow_id:
             workflow = get_user_workflow_or_404(
                 db, workflow_id=int(workflow_id), user_id=current_user.id
             )
+            metadata = decode_json(workflow.metadata_json)
+            metadata["active_volume_pair"] = {
+                "image_path": str(resolved_image_path),
+                "label_path": str(resolved_label_path) if resolved_label_path else None,
+                "source": "neuroglancer",
+            }
+            metadata["visualization_scales"] = scales
+            metadata["visualization_scales_source"] = "visualization"
+            if pair_discovery["pair_count"]:
+                metadata["volume_pair_discovery"] = {
+                    "source": "neuroglancer",
+                    "pair_count": pair_discovery["pair_count"],
+                    "image_candidate_count": pair_discovery["image_candidate_count"],
+                    "label_candidate_count": pair_discovery["label_candidate_count"],
+                    "pairs": pair_discovery["pairs"][:12],
+                    "unpaired_images": pair_discovery["unpaired_images"],
+                    "unpaired_labels": pair_discovery["unpaired_labels"],
+                    "requested_image_path": pair_discovery["requested_image_path"],
+                    "requested_label_path": pair_discovery["requested_label_path"],
+                }
             update_workflow_fields(
                 db,
                 workflow,
                 {
                     "stage": "visualization",
-                    "image_path": str(image),
-                    "label_path": str(label) if label else None,
+                    "image_path": str(resolved_image_path),
+                    "label_path": (
+                        str(resolved_label_path) if resolved_label_path else None
+                    ),
                     "neuroglancer_url": public_url,
+                    "metadata": metadata,
                 },
                 commit=True,
             )
@@ -546,14 +1938,23 @@ def ngLayer(data, res, oo=[0, 0, 0], tt="segmentation"):
                 stage="visualization",
                 summary="Created Neuroglancer viewer.",
                 payload={
-                    "image_path": str(image),
-                    "label_path": str(label) if label else None,
+                    "image_path": str(resolved_image_path),
+                    "label_path": (
+                        str(resolved_label_path) if resolved_label_path else None
+                    ),
+                    "requested_image_path": str(original_image_path),
+                    "requested_label_path": (
+                        str(original_label_path) if original_label_path else None
+                    ),
+                    "image_resolution_note": image_resolution_note,
+                    "label_resolution_note": label_resolution_note,
+                    "pair_discovery": pair_discovery,
+                    "pair_question": response_payload["pair_question"],
                     "scales": scales,
                     "neuroglancer_url": public_url,
                 },
             )
-        print(public_url)
-        return public_url
+        return response_payload
     finally:
         for path in cleanup_paths:
             try:
@@ -564,6 +1965,398 @@ def ngLayer(data, res, oo=[0, 0, 0], tt="segmentation"):
                 pass
 
 
+@app.post("/neuroglancer/proofread")
+async def neuroglancer_proofread(
+    payload: NeuroglancerProofreadRequest,
+    req: Request,
+    current_user: models.User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    import neuroglancer
+
+    workflow_id = payload.workflow_id or payload.workflowId
+    session_id = payload.session_id or payload.sessionId
+    active_instance_id = payload.active_instance_id or payload.activeInstanceId
+    image = process_path(payload.image) if payload.image else None
+    label = process_path(payload.label) if payload.label else None
+    scales = _coerce_neuroglancer_scales(payload.scales)
+    session_context = None
+    persistence_context = None
+
+    if session_id:
+        from server_api.ehtool.db_models import EHToolSession
+        from server_api.ehtool.router import get_data_manager
+
+        session_context = (
+            db.query(EHToolSession)
+            .filter(
+                EHToolSession.id == int(session_id),
+                EHToolSession.user_id == current_user.id,
+            )
+            .first()
+        )
+        if not session_context:
+            raise HTTPException(
+                status_code=404, detail="Proofreading session not found."
+            )
+        image = image or session_context.dataset_path
+        label = label or session_context.mask_path
+        workflow_id = workflow_id or session_context.workflow_id
+        try:
+            data_manager = get_data_manager(int(session_id), db)
+            persistence_context = data_manager.get_persistence_status()
+            if persistence_context.get("artifact_exists") and persistence_context.get(
+                "artifact_path"
+            ):
+                label = persistence_context["artifact_path"]
+        except Exception:
+            logger.debug(
+                "Unable to inspect proofreading persistence for Neuroglancer launch",
+                exc_info=True,
+            )
+
+    if not image:
+        raise HTTPException(
+            status_code=400,
+            detail="Image path is required to open Neuroglancer proofreading.",
+        )
+
+    original_image_path = pathlib.Path(image)
+    original_label_path = pathlib.Path(label) if label else None
+    if not original_image_path.exists():
+        _raise_missing_volume_error(original_image_path, "image")
+    if original_label_path is not None and not original_label_path.exists():
+        _raise_missing_volume_error(original_label_path, "label")
+
+    try:
+        resolved_image_path, image_resolution_note = _resolve_neuroglancer_image_path(
+            original_image_path,
+            original_label_path,
+        )
+        resolved_label_path, label_resolution_note = _resolve_neuroglancer_label_path(
+            original_label_path,
+            resolved_image_path,
+        )
+    except ValueError as exc:
+        append_app_event(
+            component="server_api",
+            event="neuroglancer_proofread_resolution_failed",
+            level="ERROR",
+            message=str(exc),
+            image_path=str(original_image_path),
+            label_path=str(original_label_path) if original_label_path else None,
+            session_id=session_id,
+            workflow_id=workflow_id,
+        )
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+    try:
+        im = load_volume(str(resolved_image_path), label="image")
+    except Exception as exc:
+        raise HTTPException(
+            status_code=400, detail=f"Failed to read image volume: {str(exc)}"
+        ) from exc
+
+    gt = None
+    if resolved_label_path:
+        try:
+            gt = load_volume(str(resolved_label_path), label="label")
+            gt = _normalize_segmentation_volume_for_neuroglancer(gt)
+        except Exception as exc:
+            raise HTTPException(
+                status_code=400,
+                detail=f"Failed to prepare label volume for proofreading: {str(exc)}",
+            ) from exc
+
+    neuroglancer.set_server_bind_address(
+        PYTC_NEUROGLANCER_BIND_HOST, PYTC_NEUROGLANCER_PORT
+    )
+    viewer = neuroglancer.Viewer()
+    dimensions = neuroglancer.CoordinateSpace(
+        names=["z", "y", "x"], units=["nm", "nm", "nm"], scales=scales
+    )
+
+    def make_local_volume(data, volume_type: str, voxel_offset=(0, 0, 0)):
+        try:
+            return _build_neuroglancer_local_volume_source(
+                neuroglancer,
+                data,
+                dimensions,
+                volume_type=volume_type,
+                voxel_offset=voxel_offset,
+            )
+        except Exception as exc:
+            raise HTTPException(
+                status_code=400,
+                detail=f"Failed to prepare Neuroglancer {volume_type} layer: {exc}",
+            ) from exc
+
+    image_layer = _build_neuroglancer_layer(
+        neuroglancer,
+        im,
+        dimensions,
+        volume_type="image",
+        voxel_offset=[0, 0, 0],
+    )
+    segmentation_source = (
+        make_local_volume(gt, "segmentation") if gt is not None else None
+    )
+    initial_voxel = _coerce_initial_voxel(
+        payload.initial_voxel or payload.initialVoxel,
+        tuple(getattr(im, "shape", ()) or ()),
+    )
+
+    def append_point(layer_name: str, coordinates, description: str):
+        if coordinates is None:
+            return
+        point = [float(value) for value in coordinates]
+        with viewer.txn() as state:
+            if state.layers.index(layer_name) == -1:
+                return
+            layer = state.layers[layer_name]
+            annotations = list(layer.annotations)
+            annotations.append(
+                dict(
+                    type="point",
+                    id=str(uuid.uuid4()),
+                    point=point,
+                    description=description,
+                )
+            )
+            layer.annotations = annotations
+
+    def handle_marker_action(action_type: str, layer_name: str, description: str):
+        def _handler(action_state):
+            coordinates = getattr(action_state, "mouse_voxel_coordinates", None)
+            if coordinates is None:
+                return
+            selected_segment = _selected_segment_from_action_state(
+                action_state,
+                ["selected-instance", "segmentation"],
+            )
+            point = [float(value) for value in coordinates]
+            marker_description = description
+            if selected_segment is not None:
+                marker_description = f"{description}; segment {selected_segment}"
+            append_point(layer_name, point, marker_description)
+            _record_neuroglancer_proofread_action(
+                workflow_id=workflow_id,
+                action_type=action_type,
+                payload={
+                    "coordinates_zyx": point,
+                    "selected_segment": selected_segment,
+                    "session_id": session_id,
+                    "active_instance_id": active_instance_id,
+                    "image_path": str(resolved_image_path),
+                    "label_path": (
+                        str(resolved_label_path) if resolved_label_path else None
+                    ),
+                },
+            )
+            with viewer.config_state.txn() as config:
+                config.status_messages["pytc-last-action"] = marker_description
+
+        return _handler
+
+    def handle_save_review(_action_state):
+        _record_neuroglancer_proofread_action(
+            workflow_id=workflow_id,
+            action_type="save_review_checkpoint",
+            payload={
+                "session_id": session_id,
+                "active_instance_id": active_instance_id,
+                "image_path": str(resolved_image_path),
+                "label_path": str(resolved_label_path) if resolved_label_path else None,
+            },
+        )
+        with viewer.config_state.txn() as config:
+            config.status_messages["pytc-last-action"] = (
+                "Saved Neuroglancer proofreading checkpoint to the workflow log."
+            )
+
+    key_bindings = [
+        ("control+mousedown0", "pytc-merge-source", "merge source"),
+        ("control+shift+mousedown0", "pytc-merge-target", "merge target"),
+        ("shift+mousedown0", "pytc-split-seed", "split seed"),
+        ("alt+mousedown0", "pytc-needs-fix", "needs-fix marker"),
+        ("control+keys", "pytc-save-review", "save review checkpoint"),
+    ]
+    viewer.actions.add(
+        "pytc-merge-source",
+        handle_marker_action("merge_source", "merge-points", "merge source"),
+    )
+    viewer.actions.add(
+        "pytc-merge-target",
+        handle_marker_action("merge_target", "merge-points", "merge target"),
+    )
+    viewer.actions.add(
+        "pytc-split-seed",
+        handle_marker_action("split_seed", "split-seeds", "split seed"),
+    )
+    viewer.actions.add(
+        "pytc-needs-fix",
+        handle_marker_action("needs_fix", "needs-fix", "needs-fix marker"),
+    )
+    viewer.actions.add("pytc-save-review", handle_save_review)
+
+    layer_names = ["image"]
+    with viewer.txn() as state:
+        state.layers.append(name="image", layer=image_layer)
+        if segmentation_source is not None:
+            state.layers.append(
+                name="segmentation",
+                layer=neuroglancer.SegmentationLayer(
+                    source=segmentation_source,
+                    object_alpha=0.34,
+                    selected_alpha=0.7,
+                    not_selected_alpha=0.18,
+                ),
+            )
+            layer_names.append("segmentation")
+            if active_instance_id:
+                state.layers.append(
+                    name="selected-instance",
+                    layer=neuroglancer.SegmentationLayer(
+                        source=segmentation_source,
+                        segments={int(active_instance_id)},
+                        object_alpha=0.86,
+                        segment_colors={int(active_instance_id): "#f72585"},
+                    ),
+                )
+                layer_names.append("selected-instance")
+        state.layers.append(
+            name="merge-points",
+            layer=neuroglancer.LocalAnnotationLayer(
+                dimensions=dimensions,
+                annotation_color="#22d3ee",
+                annotations=[],
+            ),
+        )
+        state.layers.append(
+            name="split-seeds",
+            layer=neuroglancer.LocalAnnotationLayer(
+                dimensions=dimensions,
+                annotation_color="#f59e0b",
+                annotations=[],
+            ),
+        )
+        state.layers.append(
+            name="needs-fix",
+            layer=neuroglancer.LocalAnnotationLayer(
+                dimensions=dimensions,
+                annotation_color="#ef4444",
+                annotations=[],
+            ),
+        )
+        layer_names.extend(["merge-points", "split-seeds", "needs-fix"])
+        if initial_voxel:
+            state.voxel_coordinates = initial_voxel
+        state.show_slices = True
+        state.layout = neuroglancer.row_layout(
+            [
+                neuroglancer.LayerGroupViewer(layout="xy", layers=layer_names),
+                neuroglancer.LayerGroupViewer(layout="3d", layers=layer_names),
+            ]
+        )
+
+    with viewer.config_state.txn() as config:
+        config.status_messages["pytc-proofread"] = (
+            "PyTC Neuroglancer proofread: ctrl-click merge source, "
+            "ctrl-shift-click merge target, shift-click split seed, "
+            "alt-click needs-fix, ctrl-s logs checkpoint."
+        )
+        for binding, command, _label in key_bindings:
+            config.input_event_bindings.viewer[binding] = command
+            config.input_event_bindings.data_view[binding] = command
+            config.input_event_bindings.slice_view[binding] = command
+            config.input_event_bindings.perspective_view[binding] = command
+
+    internal_viewer_url = str(viewer)
+    public_url = _build_neuroglancer_public_url(internal_viewer_url, req)
+    viewer_token = _retain_neuroglancer_viewer(
+        viewer,
+        public_url=public_url,
+        internal_viewer_url=internal_viewer_url,
+        mode="proofreading",
+        workflow_id=workflow_id,
+        image_path=str(resolved_image_path),
+        label_path=str(resolved_label_path) if resolved_label_path else None,
+    )
+    response_payload = {
+        "url": public_url,
+        "neuroglancer_url": public_url,
+        "viewer_token": viewer_token,
+        "mode": "proofreading",
+        "image_path": str(resolved_image_path),
+        "label_path": str(resolved_label_path) if resolved_label_path else None,
+        "requested_image_path": str(original_image_path),
+        "requested_label_path": (
+            str(original_label_path) if original_label_path else None
+        ),
+        "image_resolution_note": image_resolution_note,
+        "label_resolution_note": label_resolution_note,
+        "scales": scales,
+        "workflow_id": workflow_id,
+        "session_id": session_id,
+        "active_instance_id": active_instance_id,
+        "persistence": persistence_context,
+        "controls": [
+            {"gesture": binding, "action": label}
+            for binding, _command, label in key_bindings
+        ],
+    }
+
+    if workflow_id:
+        workflow = get_user_workflow_or_404(
+            db, workflow_id=int(workflow_id), user_id=current_user.id
+        )
+        metadata = decode_json(workflow.metadata_json)
+        metadata["neuroglancer_proofreading"] = {
+            "url": public_url,
+            "image_path": str(resolved_image_path),
+            "label_path": str(resolved_label_path) if resolved_label_path else None,
+            "session_id": session_id,
+            "active_instance_id": active_instance_id,
+            "controls": response_payload["controls"],
+            "launched_at": datetime.now(timezone.utc).isoformat(),
+        }
+        update_workflow_fields(
+            db,
+            workflow,
+            {
+                "stage": "proofreading",
+                "image_path": str(resolved_image_path),
+                "mask_path": str(resolved_label_path) if resolved_label_path else None,
+                "neuroglancer_url": public_url,
+                "metadata": metadata,
+            },
+            commit=True,
+        )
+        append_event_for_workflow_if_present(
+            db,
+            workflow_id=workflow.id,
+            actor="user",
+            event_type="proofreading.neuroglancer_viewer_created",
+            stage="proofreading",
+            summary="Created Neuroglancer proofreading viewer.",
+            payload=response_payload,
+        )
+
+    append_app_event(
+        component="server_api",
+        event="neuroglancer_proofread_created",
+        message="Created Neuroglancer proofreading viewer.",
+        workflow_id=workflow_id,
+        session_id=session_id,
+        active_instance_id=active_instance_id,
+        image_path=str(resolved_image_path),
+        label_path=str(resolved_label_path) if resolved_label_path else None,
+        neuroglancer_url=public_url,
+        viewer_token=viewer_token,
+    )
+    return response_payload
+
+
 @app.post("/start_model_training")
 async def start_model_training(
     req: Request,
@@ -571,11 +2364,30 @@ async def start_model_training(
     db: Session = Depends(get_db),
 ):
     body = await req.json()
+    append_app_event(
+        component="server_api",
+        event="training_request_received",
+        level="INFO",
+        message="Training request received by API",
+        source="api_endpoint",
+        payload_keys=sorted(body.keys()),
+        config_origin_path=body.get("configOriginPath"),
+        output_path=body.get("outputPath"),
+        log_path=body.get("logPath"),
+        training_config_length=len(body.get("trainingConfig") or ""),
+        workflow_id=body.get("workflow_id") or body.get("workflowId"),
+        user_id=current_user.id,
+    )
     workflow_id = body.get("workflow_id") or body.get("workflowId")
     if workflow_id:
         workflow = get_user_workflow_or_404(
             db, workflow_id=int(workflow_id), user_id=current_user.id
         )
+        body = _runtime_body_with_workflow_fallbacks(
+            body,
+            workflow,
+            mode="training",
+        )
         update_workflow_fields(
             db,
             workflow,
@@ -596,6 +2408,8 @@ async def start_model_training(
                 "outputPath": body.get("outputPath"),
                 "logPath": body.get("logPath"),
                 "configOriginPath": body.get("configOriginPath"),
+                "inputImagePath": body.get("inputImagePath"),
+                "inputLabelPath": body.get("inputLabelPath"),
             },
         )
     worker_data = _proxy_to_worker(
@@ -610,6 +2424,151 @@ async def start_model_training(
     }
 
 
+@app.post("/api/workflows/{workflow_id}/commands/{command_id}/run")
+async def run_workflow_command(
+    workflow_id: int,
+    command_id: int,
+    current_user: models.User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    workflow = get_user_workflow_or_404(
+        db, workflow_id=int(workflow_id), user_id=current_user.id
+    )
+    command = (
+        db.query(WorkflowCommand)
+        .filter(
+            WorkflowCommand.id == command_id,
+            WorkflowCommand.workflow_id == workflow.id,
+        )
+        .first()
+    )
+    if not command:
+        raise HTTPException(status_code=404, detail="Workflow command not found.")
+    if command.command_type != "start_training":
+        raise HTTPException(
+            status_code=400,
+            detail=f"Unsupported workflow command type: {command.command_type}",
+        )
+
+    try:
+        body = _build_training_body_from_command(command, workflow)
+        body = _runtime_body_with_workflow_fallbacks(body, workflow, mode="training")
+        command = mark_workflow_command_running(
+            db,
+            command,
+            lease_owner="server_api.training_runner",
+            commit=True,
+        )
+        update_workflow_fields(
+            db,
+            workflow,
+            {
+                "stage": "retraining_staged",
+                "training_output_path": body.get("outputPath"),
+                "config_path": body.get("configOriginPath"),
+            },
+            commit=True,
+        )
+        started_event = append_event_for_workflow_if_present(
+            db,
+            workflow_id=workflow.id,
+            actor="system",
+            event_type="training.started",
+            stage=workflow.stage,
+            summary="Started model training from a durable workflow command.",
+            payload={
+                "run_id": body.get("run_id"),
+                "command_id": command.id,
+                "outputPath": body.get("outputPath"),
+                "logPath": body.get("logPath"),
+                "configOriginPath": body.get("configOriginPath"),
+                "inputImagePath": body.get("inputImagePath"),
+                "inputLabelPath": body.get("inputLabelPath"),
+                "source": "workflow_command_runner",
+            },
+            idempotency_key=f"workflow-command:{command.id}:training.started",
+        )
+        worker_data = _proxy_to_worker(
+            "post",
+            "/start_model_training",
+            json_body=body,
+            timeout=30,
+        )
+        command = submit_workflow_command(
+            db,
+            command,
+            result_payload={
+                "worker": worker_data,
+                "run_id": body.get("run_id"),
+                "started_event_id": started_event.id if started_event else None,
+                "submitted": True,
+            },
+            commit=True,
+        )
+        return {
+            "workflow_id": workflow.id,
+            "command": command_to_dict(command),
+            "worker": worker_data,
+            "run_id": body.get("run_id"),
+            "started_event_id": started_event.id if started_event else None,
+        }
+    except HTTPException as exc:
+        error_payload = {
+            "error": "HTTPException",
+            "status_code": exc.status_code,
+            "detail": exc.detail,
+        }
+        fail_workflow_command(
+            db,
+            command,
+            error_payload=error_payload,
+            retryable=exc.status_code in {503, 504},
+            commit=True,
+        )
+        append_event_for_workflow_if_present(
+            db,
+            workflow_id=workflow.id,
+            actor="system",
+            event_type="training.failed",
+            stage=workflow.stage,
+            summary="Failed to start model training from a durable workflow command.",
+            payload={
+                "command_id": command.id,
+                "source": "workflow_command_runner",
+                **error_payload,
+            },
+            idempotency_key=f"workflow-command:{command.id}:training.failed",
+        )
+        raise
+    except Exception as exc:
+        error_payload = {
+            "error": type(exc).__name__,
+            "detail": str(exc),
+        }
+        fail_workflow_command(
+            db,
+            command,
+            error_payload=error_payload,
+            retryable=False,
+            commit=True,
+        )
+        append_event_for_workflow_if_present(
+            db,
+            workflow_id=workflow.id,
+            actor="system",
+            event_type="training.failed",
+            stage=workflow.stage,
+            summary="Failed to start model training from a durable workflow command.",
+            payload={
+                "command_id": command.id,
+                "source": "workflow_command_runner",
+                **error_payload,
+            },
+            idempotency_key=f"workflow-command:{command.id}:training.failed",
+        )
+        raise HTTPException(status_code=500, detail=error_payload) from exc
+
+
 @app.post("/stop_model_training")
 async def stop_model_training():
     worker_data = _proxy_to_worker("post", "/stop_model_training", timeout=30)
@@ -637,11 +2596,31 @@ async def start_model_inference(
     db: Session = Depends(get_db),
 ):
     body = await req.json()
+    append_app_event(
+        component="server_api",
+        event="inference_request_received",
+        level="INFO",
+        message="Inference request received by API",
+        source="api_endpoint",
+        payload_keys=sorted(body.keys()),
+        config_origin_path=body.get("configOriginPath"),
+        output_path=body.get("outputPath"),
+        checkpoint_path=(body.get("arguments") or {}).get("checkpoint")
+        or body.get("checkpointPath"),
+        inference_config_length=len(body.get("inferenceConfig") or ""),
+        workflow_id=body.get("workflow_id") or body.get("workflowId"),
+        user_id=current_user.id,
+    )
     workflow_id = body.get("workflow_id") or body.get("workflowId")
     if workflow_id:
         workflow = get_user_workflow_or_404(
             db, workflow_id=int(workflow_id), user_id=current_user.id
         )
+        body = _runtime_body_with_workflow_fallbacks(
+            body,
+            workflow,
+            mode="inference",
+        )
         update_workflow_fields(
             db,
             workflow,
@@ -698,6 +2677,156 @@ async def get_inference_logs():
     return _proxy_to_worker("get", "/inference_logs", timeout=5)
 
 
+@app.post("/api/workflows/{workflow_id}/sync-inference-runtime")
+async def sync_workflow_inference_runtime(
+    workflow_id: int,
+    body: Optional[WorkflowInferenceRuntimeSyncRequest] = None,
+    current_user: models.User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    workflow = get_user_workflow_or_404(
+        db, workflow_id=int(workflow_id), user_id=current_user.id
+    )
+    runtime = _proxy_to_worker("get", "/inference_logs", timeout=5) or {}
+    metadata = runtime.get("metadata") if isinstance(runtime, dict) else {}
+    metadata = metadata if isinstance(metadata, dict) else {}
+    phase = runtime.get("phase") if isinstance(runtime, dict) else None
+    checkpoint_path = _metadata_path(
+        metadata,
+        "checkpointPath",
+        "latestCheckpointPath",
+        "checkpoint",
+    )
+    output_directory = _metadata_path(metadata, "outputPath", "output_path")
+    prediction_path = _metadata_path(
+        metadata,
+        "predictionPath",
+        "latestPredictionPath",
+        "outputPredictionPath",
+    ) or _discover_prediction_output(output_directory)
+
+    if phase not in {"finished", "failed"}:
+        return {
+            "synced": False,
+            "phase": phase or "unknown",
+            "reason": "runtime_not_terminal",
+            "metadata": metadata,
+        }
+
+    runtime_payload = {
+        "source": "runtime_sync",
+        "runtimePhase": phase,
+        "runtimePid": runtime.get("pid") if isinstance(runtime, dict) else None,
+        "runtimeExitCode": (
+            runtime.get("exitCode") if isinstance(runtime, dict) else None
+        ),
+        "runtimeStartedAt": (
+            runtime.get("startedAt") if isinstance(runtime, dict) else None
+        ),
+        "runtimeEndedAt": runtime.get("endedAt") if isinstance(runtime, dict) else None,
+        "runtimeLineCount": (
+            runtime.get("lineCount") if isinstance(runtime, dict) else None
+        ),
+        "outputDirectory": output_directory,
+        "checkpointPath": checkpoint_path,
+        "configPath": runtime.get("configPath") if isinstance(runtime, dict) else None,
+        "configOriginPath": (
+            runtime.get("configOriginPath") if isinstance(runtime, dict) else None
+        )
+        or metadata.get("configOriginPath"),
+        "workflowId": metadata.get("workflowId") or workflow_id,
+        "predictionName": (
+            pathlib.Path(prediction_path).name if prediction_path else None
+        ),
+    }
+
+    if phase == "failed":
+        ended_at = runtime_payload.get("runtimeEndedAt")
+        existing = _find_synced_inference_event(
+            db,
+            workflow_id=workflow.id,
+            event_type="inference.failed",
+            ended_at=ended_at,
+        )
+        if existing is None:
+            append_event_for_workflow_if_present(
+                db,
+                workflow_id=workflow.id,
+                actor="system",
+                event_type="inference.failed",
+                stage="inference",
+                summary="Synchronized failed PyTC inference runtime.",
+                payload={
+                    **runtime_payload,
+                    "lastError": (
+                        runtime.get("lastError") if isinstance(runtime, dict) else None
+                    ),
+                },
+            )
+        return {
+            "synced": True,
+            "phase": phase,
+            "event_type": "inference.failed",
+            "deduplicated": existing is not None,
+        }
+
+    if not prediction_path:
+        return {
+            "synced": False,
+            "phase": phase,
+            "reason": "prediction_artifact_not_found",
+            "metadata": metadata,
+        }
+
+    requested_stage = body.stage if body else None
+    target_stage = requested_stage or (
+        "evaluation"
+        if workflow.stage in {"retraining_staged", "evaluation"}
+        else "inference"
+    )
+    update_payload = {
+        "stage": target_stage,
+        "inference_output_path": prediction_path,
+    }
+    if checkpoint_path:
+        update_payload["checkpoint_path"] = checkpoint_path
+    update_workflow_fields(db, workflow, update_payload, commit=True)
+
+    existing = _find_synced_inference_event(
+        db,
+        workflow_id=workflow.id,
+        event_type="inference.completed",
+        output_path=prediction_path,
+        ended_at=runtime_payload.get("runtimeEndedAt"),
+    )
+    event = existing
+    if event is None:
+        event = append_event_for_workflow_if_present(
+            db,
+            workflow_id=workflow.id,
+            actor="system",
+            event_type="inference.completed",
+            stage=target_stage,
+            summary="Synchronized completed PyTC inference output.",
+            payload={
+                **runtime_payload,
+                "outputPath": prediction_path,
+                "latestPredictionPath": prediction_path,
+            },
+        )
+
+    return {
+        "synced": True,
+        "phase": phase,
+        "event_type": "inference.completed",
+        "event_id": event.id if event else None,
+        "deduplicated": existing is not None,
+        "outputPath": prediction_path,
+        "checkpointPath": checkpoint_path,
+        "stage": target_stage,
+    }
+
+
 @app.get("/start_tensorboard")
 async def start_tensorboard(logPath: Optional[str] = None):
     return _proxy_to_worker(
@@ -713,6 +2842,11 @@ async def get_tensorboard_url():
     return _proxy_to_worker("get", "/get_tensorboard_url", timeout=5)
 
 
+@app.get("/get_tensorboard_status")
+async def get_tensorboard_status():
+    return _proxy_to_worker("get", "/get_tensorboard_status", timeout=5)
+
+
 # TODO: Improve on this: basic idea: labels are binary -- black or white?
 # Check the unique values: Assume that the label should have 0 or 255
 # This is temporarily ditched in favor of allowing users to specify whether or not a file is a label or image.
@@ -865,7 +2999,11 @@ def update_conversation(
     if not convo:
         raise HTTPException(status_code=404, detail="Conversation not found")
     if "title" in req_body:
-        convo.title = req_body["title"][:120]  # cap at 120 chars
+        title = str(req_body["title"] or "").strip()
+        if not title:
+            raise HTTPException(status_code=400, detail="Title must be non-empty")
+        convo.title = title[:120]  # cap at 120 chars
+        convo.updated_at = datetime.now(timezone.utc)
     db.commit()
     db.refresh(convo)
     return convo
@@ -887,6 +3025,108 @@ def _load_history_for_convo(convo_id: int, db: Session):
 
 
 # Chatbot endpoints
+def _direct_general_chat_response(query: str) -> Optional[str]:
+    lower = query.strip().lower()
+    compact = re.sub(r"[^a-z0-9]+", "", lower)
+    if not compact:
+        return None
+
+    vowel_count = len(re.findall(r"[aeiou]", compact))
+    looks_like_gibberish_token = (
+        len(compact) >= 8
+        and " " not in lower
+        and vowel_count <= 2
+        and not lower.startswith("/")
+    )
+    if looks_like_gibberish_token:
+        return (
+            "I did not understand that.\n"
+            "Try a workflow job like: run inference, proofread, train on saved edits, compare results, or status."
+        )
+
+    quick_run_phrases = [
+        "how do you run so quickly",
+        "how did you run so quickly",
+        "why did you run so quickly",
+        "did you actually run",
+        "are you actually running",
+    ]
+    if any(phrase in lower for phrase in quick_run_phrases):
+        return (
+            "I did not run training or inference there.\n"
+            "I answered from existing workflow/docs context, which is fast.\n"
+            "Long jobs still require your approval and should show progress."
+        )
+
+    parameter_phrases = [
+        "do i need to set parameters",
+        "do i need to tune",
+        "choose parameters",
+        "pick parameters",
+        "infer parameters",
+        "stride",
+        "blending",
+        "chunk",
+    ]
+    if any(phrase in lower for phrase in parameter_phrases) and any(
+        term in lower for term in ["agent", "you", "biologist", "training", "inference"]
+    ):
+        return (
+            "You should not have to tune low-level parameters by default.\n"
+            "Do this: give me the image/mask goal and approve the run; I should choose a safe preset and defaults.\n"
+            "Use advanced settings only when you explicitly want to override me."
+        )
+
+    return None
+
+
+def _persist_chat_exchange(
+    db: Session,
+    *,
+    conversation: models.Conversation,
+    query: str,
+    response: str,
+    source: Optional[str] = None,
+) -> None:
+    db.add(
+        models.ChatMessage(conversation_id=conversation.id, role="user", content=query)
+    )
+    db.add(
+        models.ChatMessage(
+            conversation_id=conversation.id,
+            role="assistant",
+            content=response,
+            source=source,
+        )
+    )
+    if conversation.title == "New Chat":
+        conversation.title = query[:120].strip() or "New Chat"
+    conversation.updated_at = datetime.now(timezone.utc)
+
+
+def _get_or_create_chat_conversation(
+    db: Session, *, user_id: int, conversation_id: Optional[int]
+) -> models.Conversation:
+    if not conversation_id:
+        convo = models.Conversation(user_id=user_id, title="New Chat")
+        db.add(convo)
+        db.commit()
+        db.refresh(convo)
+        return convo
+
+    convo = (
+        db.query(models.Conversation)
+        .filter(
+            models.Conversation.id == conversation_id,
+            models.Conversation.user_id == user_id,
+        )
+        .first()
+    )
+    if not convo:
+        raise HTTPException(status_code=404, detail="Conversation not found")
+    return convo
+
+
 @app.post("/chat/query")
 async def chat_query(
     req: Request,
@@ -897,18 +3137,6 @@ async def chat_query(
     request_id = request_id_from_request(req).replace("-", "")[:8]
     request_start = time.perf_counter()
     print(f"[CHATBOT][{request_id}] Incoming /chat/query request from user={user.id}")
-    if not _ensure_chatbot():
-        print(f"[CHATBOT][{request_id}] Main chain unavailable before request")
-        log_request_summary(
-            request_id=request_id,
-            endpoint="/chat/query",
-            start_time=request_start,
-            status="error",
-            error_type="llm_unavailable",
-        )
-        raise HTTPException(
-            status_code=503, detail=_llm_unavailable_detail(_chatbot_error)
-        )
     body = await req.json()
     query = body.get("query")
     convo_id = body.get("conversationId")
@@ -919,24 +3147,56 @@ async def chat_query(
         f"query_len={len(query.strip())}"
     )
 
-    # Auto-create a conversation if none supplied
-    if not convo_id:
-        convo = models.Conversation(user_id=user.id, title="New Chat")
-        db.add(convo)
+    convo = _get_or_create_chat_conversation(
+        db, user_id=user.id, conversation_id=convo_id
+    )
+    convo_id = convo.id
+
+    direct_response = _direct_general_chat_response(query)
+    if direct_response:
+        _persist_chat_exchange(
+            db,
+            conversation=convo,
+            query=query,
+            response=direct_response,
+            source="direct_guard",
+        )
         db.commit()
-        db.refresh(convo)
-        convo_id = convo.id
-    else:
-        convo = (
-            db.query(models.Conversation)
-            .filter(
-                models.Conversation.id == convo_id,
-                models.Conversation.user_id == user.id,
-            )
-            .first()
+        log_request_summary(
+            request_id=request_id,
+            endpoint="/chat/query",
+            start_time=request_start,
+            status="ok",
+        )
+        return {
+            "response": direct_response,
+            "conversationId": convo_id,
+            "source": "direct_guard",
+        }
+
+    if not _ensure_chatbot():
+        print(f"[CHATBOT][{request_id}] Main chain unavailable before request")
+        response = _llm_unavailable_chat_response()
+        _persist_chat_exchange(
+            db,
+            conversation=convo,
+            query=query,
+            response=response,
+            source="llm_unavailable",
+        )
+        db.commit()
+        log_request_summary(
+            request_id=request_id,
+            endpoint="/chat/query",
+            start_time=request_start,
+            status="degraded",
+            error_type="llm_unavailable",
         )
-        if not convo:
-            raise HTTPException(status_code=404, detail="Conversation not found")
+        return {
+            "response": response,
+            "conversationId": convo_id,
+            "source": "llm_unavailable",
+        }
 
     # Rebuild in-memory history from DB when switching conversations
     _load_history_for_convo(convo_id, db)
@@ -961,38 +3221,45 @@ async def chat_query(
         )
     except Exception as exc:
         _chatbot_error = exc
-        print(
-            "[CHATBOT] LLM request failed: "
-            f"{exc.__class__.__name__}: {exc!r}"
-        )
+        print("[CHATBOT] LLM request failed: " f"{exc.__class__.__name__}: {exc!r}")
         traceback.print_exc()
+        response = _llm_unavailable_chat_response()
+        _persist_chat_exchange(
+            db,
+            conversation=convo,
+            query=query,
+            response=response,
+            source="llm_unavailable",
+        )
+        db.commit()
         log_request_summary(
             request_id=request_id,
             endpoint="/chat/query",
             start_time=request_start,
-            status="error",
+            status="degraded",
             error_type=exc.__class__.__name__,
         )
-        raise HTTPException(
-            status_code=503, detail=_llm_unavailable_detail(exc)
-        ) from exc
+        return {
+            "response": response,
+            "conversationId": convo_id,
+            "source": "llm_unavailable",
+        }
     messages = result.get("messages", [])
     response = messages[-1].content if messages else "No response generated"
+    response = _compact_agent_response(response)
+    response = _sanitize_agent_response(response)
     print(
         f"[CHATBOT][{request_id}] Chain returned messages={len(messages)}, "
         f"response_len={len(response) if isinstance(response, str) else 0}"
     )
 
-    # Persist to DB
-    db.add(models.ChatMessage(conversation_id=convo_id, role="user", content=query))
-    db.add(
-        models.ChatMessage(conversation_id=convo_id, role="assistant", content=response)
+    _persist_chat_exchange(
+        db,
+        conversation=convo,
+        query=query,
+        response=response,
+        source="llm",
     )
-
-    # Auto-title: first user message becomes the title (truncated)
-    if convo.title == "New Chat":
-        convo.title = query[:120].strip() or "New Chat"
-
     db.commit()
 
     # Update in-memory history
@@ -1010,7 +3277,7 @@ async def chat_query(
         status="ok",
     )
 
-    return {"response": response, "conversationId": convo_id}
+    return {"response": response, "conversationId": convo_id, "source": "llm"}
 
 
 @app.post("/chat/clear")
@@ -1019,11 +3286,6 @@ async def clear_chat(
 ):
     """Reset the in-memory LangChain context (does NOT delete DB messages)."""
     global _active_convo_id, _chat_history
-    if not _ensure_chatbot():
-        detail = "Chatbot is not configured"
-        if "_chatbot_error" in globals():
-            detail = f"{detail}: {_chatbot_error}"
-        raise HTTPException(status_code=503, detail=detail)
     if _reset_search is not None:
         _reset_search()
     _chat_history.clear()
@@ -1044,11 +3306,241 @@ async def chat_status():
 # Helper chat endpoints (inline "?" popovers — RAG only, no training/inference)
 # ---------------------------------------------------------------------------
 
+_INLINE_HELP_DOCS_CACHE: Optional[dict[str, str]] = None
+
+
+def _inline_helper_mode() -> str:
+    return os.getenv("PYTC_INLINE_HELP_MODE", "docs").strip().lower()
+
+
+def _load_inline_help_docs() -> dict[str, str]:
+    global _INLINE_HELP_DOCS_CACHE
+    if _INLINE_HELP_DOCS_CACHE is not None:
+        return _INLINE_HELP_DOCS_CACHE
+
+    docs_dir = BASE_DIR / "server_api" / "chatbot" / "file_summaries"
+    docs: dict[str, str] = {}
+    if docs_dir.is_dir():
+        for path in docs_dir.rglob("*.md"):
+            docs[path.name] = path.read_text(encoding="utf-8", errors="ignore")
+    _INLINE_HELP_DOCS_CACHE = docs
+    return docs
+
+
+def _helper_tokens(*values: Optional[str]) -> set[str]:
+    text = " ".join(value or "" for value in values).lower()
+    return {
+        token
+        for token in re.findall(r"[a-z0-9_]+", text)
+        if len(token) >= 3 and token not in {"the", "and", "for", "this", "that"}
+    }
+
+
+def _extract_helper_snippet(
+    content: str, tokens: set[str], *, max_lines: int = 3
+) -> str:
+    lines = [line.strip() for line in content.splitlines() if line.strip()]
+    matching = [
+        line
+        for line in lines
+        if any(token in line.lower() for token in tokens)
+        and not line.lower().startswith("image:")
+    ]
+    selected = matching[:max_lines] or lines[:max_lines]
+    return "\n".join(selected)
+
+
+def _history_text(history: Optional[list]) -> str:
+    if not isinstance(history, list):
+        return ""
+    parts = []
+    for item in history[-8:]:
+        if not isinstance(item, dict):
+            continue
+        content = str(item.get("content") or "").strip()
+        if content:
+            parts.append(content)
+    return " ".join(parts)
+
+
+def _looks_like_initial_helper_prompt(query: str) -> bool:
+    lower = query.lower()
+    return "give concise help for this setting" in lower or "label:" in lower
+
+
+def _is_casual_helper_message(query: str) -> bool:
+    compact = re.sub(r"[^a-z0-9]+", "", query.lower())
+    return compact in {"hi", "hello", "hey", "yo", "sup", "thanks", "thankyou"}
+
+
+def _direct_inline_help(
+    query: str, field_context: str, history: Optional[list] = None
+) -> Optional[str]:
+    normalized_query = query.lower()
+    normalized = f"{field_context} {query}".lower()
+    history_lower = _history_text(history).lower()
+    if _is_casual_helper_message(query):
+        return (
+            "Hi. Ask me about this specific field and I will keep the answer scoped "
+            "to what goes here, what format is expected, or what value is safest."
+        )
+    asks_meaning = any(
+        phrase in normalized_query
+        for phrase in [
+            "what does that mean",
+            "what does this mean",
+            "what is that",
+            "explain that",
+            "explain this",
+        ]
+    )
+    if asks_meaning and any(
+        term in f"{history_lower} {normalized}"
+        for term in ["h5", "tiff", "nifti", "zarr", "volume file", "directory/stack"]
+    ):
+        return (
+            "Those are common ways microscopy image volumes are stored. "
+            "`H5`, `TIFF`, `NIfTI`, and `Zarr` are file/container formats; a "
+            "directory or stack means the volume is split across many files in a "
+            "folder. For this field, pick whichever file or folder contains the raw "
+            "image volume you want PyTC to read."
+        )
+    if "h5" in normalized_query or "hdf5" in normalized_query:
+        return (
+            "For H5/HDF5 data, choose the `.h5` or `.hdf5` file that contains the "
+            "raw image volume. If the app later asks for an internal dataset name, "
+            "use the dataset path inside that file, such as `/main` or `/raw`."
+        )
+    if "input image" in normalized or "dataset.input_path" in normalized:
+        if not (
+            _looks_like_initial_helper_prompt(query)
+            or any(
+                phrase in normalized_query
+                for phrase in [
+                    "what do i put",
+                    "what should i put",
+                    "where",
+                    "choose",
+                    "select",
+                    "browse",
+                    "help",
+                ]
+            )
+        ):
+            return None
+        return (
+            "Use the folder icon or Browse button to pick the image volume. "
+            "Select a volume file for H5/TIFF/NIfTI/Zarr-style data, or select a "
+            "folder when the dataset is stored as a directory/stack."
+        )
+    if "input label" in normalized or "dataset.label_name" in normalized:
+        return (
+            "Pick the matching label or mask volume for the image input. Use the "
+            "same file/folder pattern as the image data so training pairs line up."
+        )
+    if "checkpoint" in normalized or "model.pre_model" in normalized:
+        return (
+            "Pick the trained model checkpoint file, usually a `.pth` or `.pth.tar` "
+            "file. If you are starting from scratch, leave this unset until a model "
+            "has been trained."
+        )
+    if "output path" in normalized:
+        return (
+            "Pick a folder where this run can write results. Use an empty or "
+            "experiment-specific folder so predictions, logs, and intermediate files "
+            "do not overwrite older work."
+        )
+    if "log path" in normalized or "solver.log_dir" in normalized:
+        return (
+            "Pick a folder for training logs and checkpoints. This should be writable "
+            "and separate from raw image data."
+        )
+    if "aug_num" in normalized or "augment" in normalized:
+        return (
+            "`INFERENCE.AUG_NUM` controls how many test-time transformed predictions are "
+            "averaged for inference. Use `4` for quick smoke runs; use `8` or `16` "
+            "when you can spend more time for a more stable output. Higher values "
+            "increase runtime substantially."
+        )
+    if "samples_per_batch" in normalized or "batch size" in normalized:
+        return (
+            "Batch size controls how many patches are processed at once. Keep it at "
+            "`1` for large 3D volumes or memory-constrained runs; raise it only after "
+            "a successful small run proves there is headroom."
+        )
+    if "blending" in normalized:
+        return (
+            "Blending controls how overlapping inference patches are combined. "
+            "`gaussian` is usually the safer default because it softens patch-edge "
+            "artifacts; use simpler blending only for quick debugging."
+        )
+    if "do_eval" in normalized or "eval mode" in normalized:
+        return (
+            "Eval mode asks the inference config to run evaluation-style behavior "
+            "when matching labels/metrics are available. Leave it off for a plain "
+            "prediction export unless you intentionally configured evaluation inputs."
+        )
+    return None
+
+
+def _docs_only_helper_response(
+    *,
+    task_key: str,
+    query: str,
+    field_context: str,
+    history: Optional[list] = None,
+) -> str:
+    direct = _direct_inline_help(query, field_context, history)
+    if direct:
+        return direct
+
+    docs = _load_inline_help_docs()
+    tokens = _helper_tokens(task_key, query, field_context, _history_text(history))
+    scored: list[tuple[int, str, str]] = []
+    for filename, content in docs.items():
+        haystack = f"{filename}\n{content}".lower()
+        score = sum(
+            3 if token in filename.lower() else 1
+            for token in tokens
+            if token in haystack
+        )
+        if score > 0:
+            scored.append((score, filename, content))
+    scored.sort(key=lambda item: item[0], reverse=True)
+
+    snippets = []
+    for _, filename, content in scored[:2]:
+        snippet = _extract_helper_snippet(content, tokens)
+        if snippet:
+            snippets.append(f"From `{filename}`:\n{snippet}")
+
+    if snippets:
+        joined = " ".join(
+            line
+            for snippet in snippets[:1]
+            for line in snippet.splitlines()
+            if line and not line.startswith("From `")
+        )
+        compact = re.sub(r"\s+", " ", joined).strip()
+        if len(compact) > 360:
+            compact = compact[:357].rstrip() + "..."
+        return f"Relevant guidance: {compact}"
+    return (
+        "I could not find a precise local-doc match for this field. Use the visible "
+        "YAML key and current value as the source of truth, and prefer a small smoke "
+        "run before increasing runtime-heavy settings."
+    )
+
+
+def _should_use_docs_for_hybrid_helper(query: str, history: Optional[list]) -> bool:
+    return _looks_like_initial_helper_prompt(query) or _is_casual_helper_message(query)
+
 
 def _ensure_helper_chat(task_key: str):
-    """Lazily build a helper agent for *task_key*, reusing it on subsequent calls."""
+    """Lazily build one helper agent, while keeping per-field histories."""
     global _chatbot_error
-    if task_key in _helper_chains:
+    if _SHARED_HELPER_CHAIN_KEY in _helper_chains:
+        _helper_histories.setdefault(task_key, [])
         print(f"[CHATBOT] Reusing helper chain for task_key={task_key}")
         return True
     if build_helper_chain is None:
@@ -1058,12 +3550,10 @@ def _ensure_helper_chat(task_key: str):
     print(f"[CHATBOT] Initializing helper chain for task_key={task_key}...")
     try:
         agent, reset_fn = build_helper_chain()
-        _helper_chains[task_key] = (agent, reset_fn)
+        _helper_chains[_SHARED_HELPER_CHAIN_KEY] = (agent, reset_fn)
         _helper_histories[task_key] = []
         elapsed = time.perf_counter() - start_time
-        print(
-            f"[CHATBOT] Helper chain ready for task_key={task_key} in {elapsed:.2f}s"
-        )
+        print(f"[CHATBOT] Shared helper chain ready in {elapsed:.2f}s")
         return True
     except Exception as exc:
         _chatbot_error = exc
@@ -1083,6 +3573,7 @@ async def chat_helper_query(req: Request):
     task_key = body.get("taskKey")
     query = body.get("query")
     field_context = body.get("fieldContext", "")
+    history = body.get("history") if isinstance(body.get("history"), list) else []
 
     if not task_key:
         raise HTTPException(status_code=400, detail="taskKey is required")
@@ -1093,8 +3584,32 @@ async def chat_helper_query(req: Request):
         f"task_key={task_key} query_len={len(query.strip())}"
     )
 
+    helper_mode = _inline_helper_mode()
+    if helper_mode not in {"agent", "hybrid"} or (
+        helper_mode == "hybrid" and _should_use_docs_for_hybrid_helper(query, history)
+    ):
+        print(
+            f"[CHATBOT][{request_id}] Inline helper mode={helper_mode}:docs "
+            f"task_key={task_key} field_context_len={len(str(field_context or ''))}"
+        )
+        response = _docs_only_helper_response(
+            task_key=task_key,
+            query=query,
+            field_context=field_context,
+            history=history,
+        )
+        log_request_summary(
+            request_id=request_id,
+            endpoint="/chat/helper/query",
+            start_time=request_start,
+            status="ok",
+        )
+        return {"response": response, "mode": "docs"}
+
     if not _ensure_helper_chat(task_key):
-        print(f"[CHATBOT][{request_id}] Helper chain unavailable for task_key={task_key}")
+        print(
+            f"[CHATBOT][{request_id}] Helper chain unavailable for task_key={task_key}"
+        )
         log_request_summary(
             request_id=request_id,
             endpoint="/chat/helper/query",
@@ -1106,7 +3621,7 @@ async def chat_helper_query(req: Request):
             status_code=503, detail=_llm_unavailable_detail(_chatbot_error)
         )
 
-    agent, reset_fn = _helper_chains[task_key]
+    agent, reset_fn = _helper_chains[_SHARED_HELPER_CHAIN_KEY]
     history = _helper_histories[task_key]
 
     # Prepend field context to the first message so the LLM knows what field
@@ -1117,7 +3632,8 @@ async def chat_helper_query(req: Request):
 
     reset_fn()
     print(
-        f"[CHATBOT][{request_id}] Helper history_len={len(history)}; invoking helper "
+        f"[CHATBOT][{request_id}] Inline helper mode={helper_mode} "
+        f"history_len={len(history)}; invoking helper "
         f"with context_len={len(user_content)}"
     )
     all_messages = history + [{"role": "user", "content": user_content}]
@@ -1129,8 +3645,7 @@ async def chat_helper_query(req: Request):
         )
     except Exception as exc:
         print(
-            "[CHATBOT] Helper LLM request failed: "
-            f"{exc.__class__.__name__}: {exc!r}"
+            "[CHATBOT] Helper LLM request failed: " f"{exc.__class__.__name__}: {exc!r}"
         )
         traceback.print_exc()
         log_request_summary(
@@ -1145,6 +3660,8 @@ async def chat_helper_query(req: Request):
         ) from exc
     messages = result.get("messages", [])
     response = messages[-1].content if messages else "No response generated"
+    response = _compact_agent_response(response, max_words=80)
+    response = _sanitize_agent_response(response)
     history.append({"role": "user", "content": user_content})
     history.append({"role": "assistant", "content": response})
     total_elapsed = time.perf_counter() - request_start
@@ -1171,10 +3688,12 @@ async def chat_helper_clear(req: Request):
 
 
 def run():
+    log_path = configure_process_logging("server_api")
+    print(f"[APP LOG] Writing app events to {log_path}")
     uvicorn.run(
         app,
-        host="0.0.0.0",
-        port=4242,
+        host=PYTC_API_HOST,
+        port=PYTC_API_PORT,
         reload=False,  # Temporarily disabled to force fresh load
         log_level="info",
     )
diff --git a/server_api/project_manager/discovery.py b/server_api/project_manager/discovery.py
index 87472d8a..85ba6a6f 100644
--- a/server_api/project_manager/discovery.py
+++ b/server_api/project_manager/discovery.py
@@ -86,7 +86,11 @@ def _discover_from_dir(
         for entry in files
         if _match_supported_suffix(entry, SUPPORTED_STACK_IMAGE_SUFFIXES)
     ]
-    if current != root and len(stack_slice_files) >= 2 and len(stack_slice_files) == len(files):
+    if (
+        current != root
+        and len(stack_slice_files) >= 2
+        and len(stack_slice_files) == len(files)
+    ):
         rel_path = str(current.relative_to(root))
         return [
             {
diff --git a/server_api/utils/utils.py b/server_api/utils/utils.py
index 48426e0e..ebfe2342 100644
--- a/server_api/utils/utils.py
+++ b/server_api/utils/utils.py
@@ -1,10 +1,65 @@
 import pathlib
 
+MOUNT_VARIANT_SUFFIXES = (
+    "_im",
+    "_image",
+    "_img",
+    "_seg",
+    "_mask",
+    "_label",
+    "_gt",
+)
+
+
+def _normalized_variant_name(name):
+    candidate = pathlib.Path(name)
+    stem = candidate.stem.lower()
+    suffix = candidate.suffix.lower()
+    for token in MOUNT_VARIANT_SUFFIXES:
+        if stem.endswith(token):
+            stem = stem[: -len(token)]
+            break
+    return stem, suffix
+
+
+def resolve_existing_path(path):
+    if not path:
+        return None
+
+    candidate = pathlib.Path(path).expanduser()
+    if candidate.exists():
+        return candidate
+
+    parent = candidate.parent
+    if not parent.exists() or not parent.is_dir():
+        return candidate
+
+    target_is_file = candidate.suffix != ""
+    normalized_stem, normalized_suffix = _normalized_variant_name(candidate.name)
+    matches = []
+
+    for child in parent.iterdir():
+        if target_is_file and not child.is_file():
+            continue
+        if not target_is_file and not child.is_dir():
+            continue
+
+        child_stem, child_suffix = _normalized_variant_name(child.name)
+        if target_is_file and child_suffix != normalized_suffix:
+            continue
+        if child_stem == normalized_stem:
+            matches.append(child)
+
+    if len(matches) == 1:
+        return matches[0]
+
+    return candidate
+
 
 def process_path(path):
     if not path:
         return None
     candidate = pathlib.Path(path).expanduser()
     if candidate.is_absolute():
-        return candidate
-    return candidate.resolve(strict=False)
+        return resolve_existing_path(candidate)
+    return resolve_existing_path(candidate.resolve(strict=False))
diff --git a/server_api/workflows/__init__.py b/server_api/workflows/__init__.py
index d03ab027..82fa579b 100644
--- a/server_api/workflows/__init__.py
+++ b/server_api/workflows/__init__.py
@@ -1,2 +1 @@
 """Workflow spine package for iterative segmentation sessions."""
-
diff --git a/server_api/workflows/agent_plan.py b/server_api/workflows/agent_plan.py
new file mode 100644
index 00000000..3fdfe678
--- /dev/null
+++ b/server_api/workflows/agent_plan.py
@@ -0,0 +1,316 @@
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, TypedDict
+
+from .db_models import WorkflowEvent, WorkflowSession
+from .service import decode_json
+
+try:  # LangGraph is optional at runtime for now, but the plan is graph-shaped.
+    from langgraph.graph import END, START, StateGraph
+
+    LANGGRAPH_AVAILABLE = True
+except Exception as exc:  # pragma: no cover - exercised only without LangGraph.
+    END = "__end__"
+    START = "__start__"
+    StateGraph = None
+    LANGGRAPH_AVAILABLE = False
+    LANGGRAPH_IMPORT_ERROR = str(exc)
+else:
+    LANGGRAPH_IMPORT_ERROR = None
+
+
+class PlanGraphState(TypedDict, total=False):
+    step_index: int
+    interrupted: bool
+    approval_required: bool
+
+
+def _latest_exported_mask_path(events: List[WorkflowEvent]) -> Optional[str]:
+    for event in reversed(events):
+        if event.event_type != "proofreading.masks_exported":
+            continue
+        payload = decode_json(event.payload_json)
+        value = (
+            payload.get("corrected_mask_path")
+            or payload.get("written_path")
+            or payload.get("output_path")
+        )
+        if value:
+            return str(value)
+    return None
+
+
+def _langgraph_runtime_summary() -> Dict[str, Any]:
+    if not LANGGRAPH_AVAILABLE:
+        return {
+            "status": "unavailable",
+            "import_error": LANGGRAPH_IMPORT_ERROR,
+        }
+
+    try:
+        graph = StateGraph(PlanGraphState)
+
+        def enter(state: PlanGraphState) -> PlanGraphState:
+            return {"step_index": state.get("step_index", 0)}
+
+        def approval_gate(state: PlanGraphState) -> PlanGraphState:
+            return {"approval_required": bool(state.get("approval_required"))}
+
+        graph.add_node("enter_plan", enter)
+        graph.add_node("approval_gate", approval_gate)
+        graph.add_edge(START, "enter_plan")
+        graph.add_edge("enter_plan", "approval_gate")
+        graph.add_edge("approval_gate", END)
+        graph.compile()
+    except Exception as exc:  # pragma: no cover - defensive compatibility guard.
+        return {
+            "status": "available_compile_failed",
+            "import_error": None,
+            "compile_error": str(exc),
+        }
+
+    return {
+        "status": "available_not_executing",
+        "state_graph": "StateGraph",
+        "interrupt_strategy": "persisted human approval gates",
+        "checkpointer": "sqlalchemy workflow_agent_plans/workflow_agent_steps",
+    }
+
+
+def _gate_lookup(gates: List[Dict[str, Any]]) -> Dict[str, Dict[str, Any]]:
+    return {str(gate.get("id")): gate for gate in gates}
+
+
+def _gate_complete(gates_by_id: Dict[str, Dict[str, Any]], gate_id: str) -> bool:
+    return bool(gates_by_id.get(gate_id, {}).get("complete"))
+
+
+def _node_status(
+    *,
+    action: str,
+    gate_id: Optional[str],
+    dependencies: List[str],
+    gates_by_id: Dict[str, Dict[str, Any]],
+    has_hotspots: bool,
+) -> str:
+    if action == "review_failure_hotspots" and has_hotspots:
+        return "completed"
+    if gate_id and _gate_complete(gates_by_id, gate_id):
+        return "completed"
+    if all(_gate_complete(gates_by_id, dependency) for dependency in dependencies):
+        return "ready"
+    return "blocked"
+
+
+def build_case_study_plan_graph(
+    *,
+    workflow: WorkflowSession,
+    events: List[WorkflowEvent],
+    gates: List[Dict[str, Any]],
+    title: Optional[str] = None,
+    goal: Optional[str] = None,
+) -> Dict[str, Any]:
+    gates_by_id = _gate_lookup(gates)
+    corrected_mask_path = workflow.corrected_mask_path or _latest_exported_mask_path(
+        events
+    )
+    has_hotspots = bool(getattr(workflow, "region_hotspots", []) or [])
+    latest_checkpoint = workflow.checkpoint_path
+
+    step_specs: List[Dict[str, Any]] = [
+        {
+            "action": "verify_data_context",
+            "title": "Verify data context",
+            "summary": "Confirm image, label/mask, config, and workflow metadata are linked.",
+            "stage": "setup",
+            "gate_id": "data_loaded",
+            "dependencies": ["workflow_context"],
+            "requires_approval": False,
+            "client_effects": {"navigate_to": "files"},
+            "required_for": ["CS1", "CS7"],
+        },
+        {
+            "action": "run_baseline_inference",
+            "title": "Run baseline inference",
+            "summary": "Produce or register the initial prediction artifact before proofreading.",
+            "stage": "inference",
+            "gate_id": "baseline_inference",
+            "dependencies": ["data_loaded"],
+            "requires_approval": True,
+            "client_effects": {
+                "navigate_to": "inference",
+                "runtime_action": {"kind": "start_inference"},
+            },
+            "required_for": ["CS1", "CS4"],
+        },
+        {
+            "action": "review_failure_hotspots",
+            "title": "Review failure hotspots",
+            "summary": "Rank likely failure regions and route the top region into proofreading.",
+            "stage": "proofreading",
+            "gate_id": None,
+            "dependencies": ["baseline_inference"],
+            "requires_approval": False,
+            "client_effects": {
+                "navigate_to": "mask-proofreading",
+                "refresh_insights": True,
+            },
+            "required_for": ["CS2"],
+        },
+        {
+            "action": "export_corrections",
+            "title": "Export corrections",
+            "summary": "Persist proofread masks as a correction set for retraining.",
+            "stage": "proofreading",
+            "gate_id": "proofreading_corrections",
+            "dependencies": ["baseline_inference"],
+            "requires_approval": False,
+            "client_effects": {"navigate_to": "mask-proofreading"},
+            "required_for": ["CS2", "CS3"],
+        },
+        {
+            "action": "stage_retraining_from_corrections",
+            "title": "Stage retraining",
+            "summary": "Attach the correction set to the next training configuration.",
+            "stage": "retraining_staged",
+            "gate_id": "retraining_handoff",
+            "dependencies": ["proofreading_corrections"],
+            "requires_approval": True,
+            "client_effects": {
+                "navigate_to": "training",
+                "set_training_label_path": corrected_mask_path or "",
+            },
+            "required_for": ["CS3", "CS5"],
+        },
+        {
+            "action": "launch_retraining",
+            "title": "Launch retraining",
+            "summary": "Run the candidate training job from staged corrections.",
+            "stage": "retraining_staged",
+            "gate_id": "training_completion",
+            "dependencies": ["retraining_handoff"],
+            "requires_approval": True,
+            "client_effects": {
+                "navigate_to": "training",
+                "set_training_label_path": corrected_mask_path or "",
+                "runtime_action": {"kind": "start_training"},
+            },
+            "required_for": ["CS3", "CS6"],
+        },
+        {
+            "action": "register_model_version",
+            "title": "Register model version",
+            "summary": "Link the produced checkpoint to a versioned candidate model.",
+            "stage": "evaluation",
+            "gate_id": "model_version",
+            "dependencies": ["training_completion"],
+            "requires_approval": False,
+            "client_effects": {"refresh_insights": True},
+            "required_for": ["CS3", "CS4"],
+        },
+        {
+            "action": "run_post_retraining_inference",
+            "title": "Run post-retraining inference",
+            "summary": "Run inference with the candidate checkpoint for before/after comparison.",
+            "stage": "evaluation",
+            "gate_id": "post_retraining_inference",
+            "dependencies": ["model_version"],
+            "requires_approval": True,
+            "client_effects": {
+                "navigate_to": "inference",
+                "set_inference_checkpoint_path": latest_checkpoint or "",
+                "runtime_action": {"kind": "start_inference"},
+            },
+            "required_for": ["CS4"],
+        },
+        {
+            "action": "compute_before_after_evaluation",
+            "title": "Compute before/after evaluation",
+            "summary": "Compare baseline and candidate predictions against held-out labels.",
+            "stage": "evaluation",
+            "gate_id": "evaluation_result",
+            "dependencies": ["post_retraining_inference"],
+            "requires_approval": False,
+            "client_effects": {"refresh_insights": True},
+            "required_for": ["CS4", "CS7"],
+        },
+        {
+            "action": "audit_agent_control",
+            "title": "Audit agent control",
+            "summary": "Record human decisions for plan approval, interruption, resume, or rejection.",
+            "stage": workflow.stage,
+            "gate_id": "agent_audit",
+            "dependencies": ["proofreading_corrections"],
+            "requires_approval": True,
+            "client_effects": {},
+            "required_for": ["CS5", "CS6"],
+        },
+        {
+            "action": "export_case_study_bundle",
+            "title": "Export case-study bundle",
+            "summary": "Export typed artifacts, events, metrics, plans, and evaluation evidence.",
+            "stage": "evaluation",
+            "gate_id": None,
+            "dependencies": [
+                "evaluation_result",
+                "agent_audit",
+                "agent_plan_preview",
+            ],
+            "requires_approval": False,
+            "client_effects": {"refresh_insights": True},
+            "required_for": ["CS7"],
+        },
+    ]
+
+    nodes: List[Dict[str, Any]] = []
+    for index, spec in enumerate(step_specs):
+        dependencies = list(spec["dependencies"])
+        status = _node_status(
+            action=spec["action"],
+            gate_id=spec["gate_id"],
+            dependencies=dependencies,
+            gates_by_id=gates_by_id,
+            has_hotspots=has_hotspots,
+        )
+        nodes.append(
+            {
+                "id": f"step_{index + 1:02d}",
+                "index": index,
+                **spec,
+                "status": status,
+            }
+        )
+
+    edges: List[Dict[str, str]] = []
+    action_to_node = {node["action"]: node["id"] for node in nodes}
+    gate_to_node = {
+        str(node["gate_id"]): node["id"] for node in nodes if node.get("gate_id")
+    }
+    for node in nodes:
+        for dependency in node["dependencies"]:
+            source = gate_to_node.get(dependency) or action_to_node.get(dependency)
+            if source:
+                edges.append({"source": source, "target": node["id"]})
+
+    completed_count = len([gate for gate in gates if gate.get("complete")])
+    total_count = len(gates)
+    return {
+        "graph_spec_version": "case-study-agent-plan/v1",
+        "workflow_id": workflow.id,
+        "title": title or "Closed-loop case-study plan",
+        "goal": goal
+        or "Drive the biomedical segmentation workflow through triage, proofreading, retraining, evaluation, and evidence export.",
+        "execution_model": {
+            "mode": "bounded_human_approved_plan_preview",
+            "mutating_steps_require_approval": True,
+            "durability": "workflow_agent_plans and workflow_agent_steps tables",
+            "langgraph": _langgraph_runtime_summary(),
+        },
+        "readiness_snapshot": {
+            "completed_count": completed_count,
+            "total_count": total_count,
+            "ready_for_case_study": completed_count == total_count,
+        },
+        "nodes": nodes,
+        "edges": edges,
+    }
diff --git a/server_api/workflows/bundle_export.py b/server_api/workflows/bundle_export.py
index 1abe8be1..aa3e937b 100644
--- a/server_api/workflows/bundle_export.py
+++ b/server_api/workflows/bundle_export.py
@@ -1,11 +1,384 @@
 from __future__ import annotations
 
+import hashlib
+import json
 import os
+import re
+import shutil
 from datetime import datetime, timezone
-from typing import Any, Dict, Iterable, List, Tuple
+from pathlib import Path
+from typing import Any, Dict, Iterable, List, Optional, Tuple
+
+from sqlalchemy.orm.exc import DetachedInstanceError
 
 from .db_models import WorkflowEvent, WorkflowSession
-from .service import event_to_dict, workflow_to_dict
+from .service import (
+    decode_json,
+    agent_plan_to_dict,
+    artifact_to_dict,
+    correction_set_to_dict,
+    evaluation_result_to_dict,
+    event_to_dict,
+    model_run_to_dict,
+    model_version_to_dict,
+    region_hotspot_to_dict,
+    volume_state_to_dict,
+    workflow_to_dict,
+)
+
+BUNDLE_SCHEMA_VERSION = "workflow-export-bundle/v1"
+DEFAULT_COPY_MAX_BYTES = 104_857_600
+DEFAULT_RAW_COPY_MAX_BYTES = 0
+IMAGE_FILE_EXTENSIONS = {
+    ".tif",
+    ".tiff",
+    ".h5",
+    ".hdf5",
+    ".nii",
+    ".nii.gz",
+    ".n5",
+    ".zarr",
+}
+PROJECT_MEMORY_SUMMARY_VERSION = "pytc-project-memory-summary/v1"
+COPY_POLICY_DEFAULT = {"allow_copy": True, "reason": None, "policy_code": "default"}
+COPY_POLICY_EXPLICIT_REASONS = {
+    "withheld_reference",
+    "ground_truth_reference_outside_dataset",
+    "external_reference_path",
+    "metadata_restriction",
+    "size_limit",
+    "missing",
+    "not_a_file",
+    "manifest_only",
+    "reference_only_policy",
+}
+
+
+def _safe_len_relationship(workflow: WorkflowSession, attr_name: str) -> int:
+    try:
+        records = getattr(workflow, attr_name)
+    except DetachedInstanceError:
+        return 0
+    return len(records or [])
+
+
+REFERENCE_ONLY_PATH_KEYS = {
+    "withheld_ground_truth",
+    "withheld_ground_truth_path",
+    "source_ground_truth",
+    "source_ground_truth_path",
+}
+
+
+def _parse_metadata_json(value: Any) -> Dict[str, Any]:
+    if isinstance(value, dict):
+        return value
+    if value is None:
+        return {}
+    try:
+        parsed = decode_json(value)
+    except Exception:
+        return {}
+    return parsed if isinstance(parsed, dict) else {}
+
+
+def _policy_code_for_reason(reason: Optional[str]) -> str:
+    if reason == "withheld_reference":
+        return "withheld_reference"
+    if reason == "ground_truth_reference_outside_dataset":
+        return "ground_truth_reference_outside_dataset"
+    if reason == "external_reference_path":
+        return "external_reference_path"
+    if reason == "missing":
+        return "missing_path"
+    if reason == "not_a_file":
+        return "not_a_file"
+    if reason == "manifest_only":
+        return "manifest_only"
+    if reason == "reference_only_policy":
+        return "reference_only_policy"
+    if reason in {"larger_than_copy_limit", "raw_larger_than_copy_limit"}:
+        return "size_limit"
+    return "metadata_restriction" if reason else "default"
+
+
+def _merge_copy_reasons(first: Optional[str], second: Optional[str]) -> Optional[str]:
+    if not first:
+        return second
+    if not second:
+        return first
+    if first == second:
+        return first
+    preference = [
+        "withheld_reference",
+        "ground_truth_reference_outside_dataset",
+        "external_reference_path",
+        "reference_only_policy",
+        "missing",
+        "not_a_file",
+        "larger_than_copy_limit",
+        "raw_larger_than_copy_limit",
+        "metadata_restriction",
+        "manifest_only",
+    ]
+    for reason in preference:
+        if reason in {first, second}:
+            return reason
+    return second
+
+
+def _normalize_copy_policy_reason(
+    policy: Dict[str, Any],
+    key: str,
+    path_text: str,
+    dataset_root: str | None,
+) -> Optional[str]:
+    base = policy.get("reason")
+    if base is None:
+        return None
+
+    if policy.get("allow_copy") is False:
+        should_reference_only, reference_reason = _should_mark_reference_only(
+            key, path_text, dataset_root
+        )
+        if should_reference_only:
+            return _merge_copy_reasons(str(base), reference_reason)
+    return str(base)
+
+
+def _is_path_key(key: str) -> bool:
+    lowered = key.lower()
+    if not lowered:
+        return False
+    if lowered in REFERENCE_ONLY_PATH_KEYS:
+        return True
+    if lowered.endswith("_path") or lowered == "path" or lowered.endswith("path"):
+        return True
+    if lowered.endswith("_ground_truth") or lowered == "ground_truth":
+        return True
+    if "ground_truth" in lowered and "path" in lowered:
+        return True
+    return False
+
+
+def _should_mark_reference_only(
+    key: str, path_text: str, dataset_root: str | None
+) -> tuple[bool, Optional[str]]:
+    lowered = key.lower()
+    if lowered in REFERENCE_ONLY_PATH_KEYS or "withheld" in lowered:
+        return True, "withheld_reference"
+    if "ground_truth" in lowered:
+        return (
+            not _path_within_root(path_text, dataset_root),
+            "ground_truth_reference_outside_dataset",
+        )
+    return False, None
+
+
+def _copy_policy_from_metadata(
+    metadata: Optional[Dict[str, Any]],
+) -> Optional[Dict[str, Any]]:
+    if not isinstance(metadata, dict):
+        return None
+    allow_copy = metadata.get("allow_copy_in_bundle")
+    if allow_copy is None:
+        return None
+    if allow_copy is False:
+        return {
+            "allow_copy": False,
+            "reason": metadata.get("copy_reason") or "metadata_restriction",
+        }
+    if allow_copy is True:
+        return {
+            "allow_copy": True,
+            "reason": metadata.get("copy_reason"),
+        }
+    return None
+
+
+def _build_copy_policy(
+    key: str,
+    path_text: str,
+    dataset_root: str | None,
+    metadata: Optional[Dict[str, Any]],
+) -> Dict[str, Any]:
+    policy = _copy_policy_from_metadata(metadata)
+    if policy is not None:
+        reason = _normalize_copy_policy_reason(
+            policy,
+            key=key,
+            path_text=path_text,
+            dataset_root=dataset_root,
+        )
+        return {
+            **COPY_POLICY_DEFAULT,
+            **policy,
+            "policy_code": _policy_code_for_reason(
+                reason if isinstance(reason, str) else None
+            ),
+        }
+    should_reference_only, reason = _should_mark_reference_only(
+        key, path_text, dataset_root
+    )
+    return {
+        "allow_copy": not should_reference_only,
+        "reason": reason,
+        "policy_code": _policy_code_for_reason(reason),
+    }
+
+
+def _reference_scope(key: str, reason: Optional[str]) -> Dict[str, Any]:
+    lowered = (key or "").lower()
+    is_reference_only = (
+        lowered in REFERENCE_ONLY_PATH_KEYS
+        or "withheld" in lowered
+        or reason == "withheld_reference"
+        or reason == "ground_truth_reference_outside_dataset"
+    )
+    return {
+        "is_reference_only": is_reference_only,
+        "reference_reason": reason if is_reference_only else None,
+        "reference_key": "withheld_reference" if is_reference_only else None,
+    }
+
+
+def _merge_copy_policies(
+    current: Dict[str, Any],
+    incoming: Dict[str, Any],
+) -> Dict[str, Any]:
+    merged = dict(COPY_POLICY_DEFAULT)
+    current = current or {}
+    incoming = incoming or {}
+    current_reason = (
+        current.get("reason") if isinstance(current.get("reason"), str) else None
+    )
+    incoming_reason = (
+        incoming.get("reason") if isinstance(incoming.get("reason"), str) else None
+    )
+    merged.update(current)
+    merged_allow_copy = bool(current.get("allow_copy", True)) and bool(
+        incoming.get("allow_copy", True)
+    )
+    merged_reason = _merge_copy_reasons(current_reason, incoming_reason)
+    if not merged_allow_copy and not merged_reason:
+        merged_reason = current_reason or incoming_reason or "metadata_restriction"
+    merged.update(incoming)
+    merged["allow_copy"] = merged_allow_copy
+    merged["reason"] = merged_reason
+    merged["policy_code"] = _policy_code_for_reason(
+        merged_reason if isinstance(merged_reason, str) else None
+    )
+    return merged
+
+
+def _coalesce_reference_scope(
+    current: Optional[Dict[str, Any]],
+    incoming: Optional[Dict[str, Any]],
+) -> Optional[Dict[str, Any]]:
+    current_scope = current or {}
+    incoming_scope = incoming or {}
+    if not current_scope:
+        return incoming_scope.copy() if incoming_scope else None
+    if not incoming_scope:
+        return current_scope.copy()
+    return {
+        "is_reference_only": bool(
+            current_scope.get("is_reference_only")
+            or incoming_scope.get("is_reference_only")
+        ),
+        "reference_reason": (
+            incoming_scope.get("reference_reason")
+            if incoming_scope.get("reference_reason")
+            else current_scope.get("reference_reason")
+        ),
+        "reference_key": (
+            incoming_scope.get("reference_key")
+            if incoming_scope.get("reference_key")
+            else current_scope.get("reference_key")
+        ),
+    }
+
+
+def _build_skipped_artifact_record(
+    *,
+    path: str,
+    reason: str,
+    exists: bool,
+    copy_policy: Optional[Dict[str, Any]] = None,
+    copy_mode: Optional[str] = None,
+    reference_scope: Optional[Dict[str, Any]] = None,
+    size_bytes: Optional[int] = None,
+    copy_limit_bytes: Optional[int] = None,
+    raw_copy_max_bytes: Optional[int] = None,
+) -> Dict[str, Any]:
+    policy = _merge_copy_policies({}, copy_policy or {})
+    if reason:
+        policy = _merge_copy_policies(
+            policy,
+            {
+                "allow_copy": False,
+                "reason": reason,
+            },
+        )
+    record = {
+        "path": path,
+        "reason": reason,
+        "exists": bool(exists),
+        "copy_policy": policy,
+        "copy_mode": copy_mode or reason,
+    }
+    if reference_scope is not None:
+        record["reference_scope"] = reference_scope
+    if size_bytes is not None:
+        record["size_bytes"] = int(size_bytes)
+    if copy_limit_bytes is not None:
+        record["copy_limit_bytes"] = int(copy_limit_bytes)
+    if raw_copy_max_bytes is not None:
+        record["raw_copy_max_bytes"] = int(raw_copy_max_bytes)
+    return record
+
+
+def _path_within_root(path_text: str, root: str | None) -> bool:
+    if not root:
+        return True
+    if not path_text:
+        return True
+    try:
+        candidate = os.path.abspath(str(path_text))
+        root_path = os.path.abspath(root)
+        return os.path.commonpath([candidate, root_path]) == root_path
+    except OSError:
+        return True
+
+
+def _parse_positive_int(value: Any, default: int, field_name: str) -> int:
+    if value is None:
+        return default
+    if isinstance(value, bool):
+        raise ValueError(f"{field_name} cannot be a boolean")
+    try:
+        parsed = int(value)
+    except (TypeError, ValueError) as exc:
+        raise ValueError(f"{field_name} must be an integer") from exc
+    if parsed < 0:
+        raise ValueError(f"{field_name} must be >= 0")
+    return parsed
+
+
+def _looks_like_raw_image_path(path_text: str) -> bool:
+    normalized = str(path_text).replace("\\", "/").lower()
+    if "/raw/" in normalized or normalized.endswith("/raw"):
+        return True
+    if re.search(r"(^|[._-])raw([._-]|$)", normalized):
+        return True
+    return any(
+        segment == "raw" for segment in normalized.strip("/").split("/") if segment
+    )
+
+
+def _is_image_like_path(path_text: str) -> bool:
+    path = Path(path_text)
+    return path.suffix.lower() in IMAGE_FILE_EXTENSIONS
 
 
 def _parse_timestamp(value: Any) -> datetime:
@@ -33,17 +406,175 @@ def _normalize_value(value: Any) -> Any:
     return value
 
 
-def _collect_paths(value: Any) -> Iterable[str]:
+def _safe_filename(value: str, fallback: str = "artifact") -> str:
+    name = os.path.basename(str(value).rstrip("/")) or fallback
+    cleaned = re.sub(r"[^A-Za-z0-9._-]+", "_", name).strip("._")
+    return cleaned or fallback
+
+
+def _collect_paths(
+    value: Any,
+    *,
+    source_type: str,
+    source_id: Optional[Any] = None,
+    path_key: Optional[str] = None,
+    parent_key: Optional[str] = None,
+    dataset_root: Optional[str] = None,
+    metadata: Optional[Dict[str, Any]] = None,
+) -> Iterable[Dict[str, Any]]:
     if isinstance(value, dict):
         for key, inner in value.items():
-            if isinstance(inner, str) and key.endswith("_path"):
-                yield inner
-            if key == "path" and isinstance(inner, str):
-                yield inner
-            yield from _collect_paths(inner)
+            item_metadata = value.get("metadata") if isinstance(value, dict) else None
+            if not isinstance(key, str):
+                yield from _collect_paths(
+                    inner,
+                    source_type=source_type,
+                    source_id=source_id,
+                    path_key=key,
+                    parent_key=key,
+                    dataset_root=dataset_root,
+                    metadata=item_metadata,
+                )
+                continue
+
+            if isinstance(inner, str) and _is_path_key(key):
+                _, reference_reason = _should_mark_reference_only(
+                    key, inner, dataset_root
+                )
+                yield {
+                    "path": inner,
+                    "source_type": source_type,
+                    "source_id": source_id,
+                    "source_key": key,
+                    "source_parent_key": parent_key,
+                    "copy_policy": _build_copy_policy(
+                        key, inner, dataset_root, metadata
+                    ),
+                    "reference_scope": _reference_scope(key, reference_reason),
+                }
+
+            yield from _collect_paths(
+                inner,
+                source_type=source_type,
+                source_id=source_id,
+                path_key=key,
+                parent_key=key,
+                dataset_root=dataset_root,
+                metadata=item_metadata,
+            )
     elif isinstance(value, list):
         for item in value:
-            yield from _collect_paths(item)
+            yield from _collect_paths(
+                item,
+                source_type=source_type,
+                source_id=source_id,
+                path_key=path_key,
+                parent_key=parent_key,
+                dataset_root=dataset_root,
+                metadata=metadata,
+            )
+    elif isinstance(value, str) and path_key and _is_path_key(path_key):
+        _, reference_reason = _should_mark_reference_only(path_key, value, dataset_root)
+        yield {
+            "path": value,
+            "source_type": source_type,
+            "source_id": source_id,
+            "source_key": path_key,
+            "source_parent_key": parent_key,
+            "copy_policy": _build_copy_policy(path_key, value, dataset_root, metadata),
+            "reference_scope": _reference_scope(path_key, reference_reason),
+        }
+
+
+def _coalesce_path_reference(
+    existing: Dict[str, Any], item: Dict[str, Any]
+) -> Dict[str, Any]:
+    merged = dict(existing)
+    merged.setdefault("sources", [])
+    source = {
+        "source_type": item.get("source_type"),
+        "source_id": item.get("source_id"),
+        "source_key": item.get("source_key"),
+        "source_parent_key": item.get("source_parent_key"),
+    }
+    if all(
+        source != existing_source
+        for existing_source in merged["sources"]
+        if isinstance(existing_source, dict)
+    ):
+        merged["sources"].append(source)
+    policy = item.get("copy_policy") or {}
+    merged["copy_policy"] = _merge_copy_policies(
+        merged.get("copy_policy") or {},
+        policy,
+    )
+    merged["reference_scope"] = _coalesce_reference_scope(
+        merged.get("reference_scope"),
+        item.get("reference_scope"),
+    )
+    return merged
+
+
+def _dedupe_path_refs(refs: Iterable[Dict[str, Any]]) -> List[Dict[str, Any]]:
+    by_path: Dict[str, Dict[str, Any]] = {}
+    for item in refs:
+        path = item.get("path")
+        if not path:
+            continue
+        path = str(path)
+        if path in by_path:
+            by_path[path] = _coalesce_path_reference(by_path[path], item)
+            continue
+        by_path[path] = {
+            "path": path,
+            "exists": os.path.exists(path),
+            "sources": [
+                {
+                    "source_type": item.get("source_type"),
+                    "source_id": item.get("source_id"),
+                    "source_key": item.get("source_key"),
+                    "source_parent_key": item.get("source_parent_key"),
+                }
+            ],
+            "copy_policy": _merge_copy_policies({}, item.get("copy_policy") or {}),
+            "reference_scope": item.get("reference_scope"),
+        }
+    return [
+        {
+            **entry,
+            "copy_policy": entry.get("copy_policy") or {"allow_copy": True},
+            "reference_scope": entry.get("reference_scope"),
+            "sources": entry.get("sources") or [],
+        }
+        for entry in by_path.values()
+    ]
+
+
+def _build_project_memory_summary(workflow: WorkflowSession) -> Dict[str, Any]:
+    metadata = _parse_metadata_json(workflow.metadata_json)
+    return {
+        "schema_version": PROJECT_MEMORY_SUMMARY_VERSION,
+        "workflow_id": workflow.id,
+        "workflow_stage": workflow.stage,
+        "workflow_title": workflow.title,
+        "dataset_path": workflow.dataset_path,
+        "project_context": metadata.get("project_context") or {},
+        "context_facts": metadata.get("context_facts") or [],
+        "counts": {
+            "artifact_count": _safe_len_relationship(workflow, "artifacts"),
+            "model_run_count": _safe_len_relationship(workflow, "model_runs"),
+            "model_version_count": _safe_len_relationship(workflow, "model_versions"),
+            "correction_set_count": _safe_len_relationship(workflow, "correction_sets"),
+            "evaluation_result_count": _safe_len_relationship(
+                workflow,
+                "evaluation_results",
+            ),
+            "region_hotspot_count": _safe_len_relationship(workflow, "region_hotspots"),
+            "volume_state_count": _safe_len_relationship(workflow, "volume_states"),
+            "agent_plan_count": _safe_len_relationship(workflow, "agent_plans"),
+            "command_count": _safe_len_relationship(workflow, "commands"),
+        },
+    }
 
 
 def build_export_bundle(
@@ -55,18 +586,331 @@ def build_export_bundle(
         (_normalize_value(event_to_dict(event)) for event in events),
         key=_event_sort_key,
     )
+    dataset_root = workflow.dataset_path
 
-    discovered = set(_collect_paths(session_snapshot))
+    discovered: List[Dict[str, Any]] = list(
+        _collect_paths(
+            session_snapshot,
+            source_type="session_snapshot",
+            dataset_root=dataset_root,
+        )
+    )
     for event in ordered_events:
-        discovered.update(_collect_paths(event))
-    artifact_paths = sorted(path for path in discovered if path)
-    artifacts = [{"path": path, "exists": os.path.exists(path)} for path in artifact_paths]
+        discovered.extend(
+            _collect_paths(
+                event,
+                source_type="event",
+                source_id=event.get("id"),
+                parent_key=event.get("event_type"),
+                dataset_root=dataset_root,
+            )
+        )
+    typed_artifacts = [
+        _normalize_value(artifact_to_dict(artifact))
+        for artifact in getattr(workflow, "artifacts", [])
+    ]
+    model_runs = [
+        _normalize_value(model_run_to_dict(run))
+        for run in getattr(workflow, "model_runs", [])
+    ]
+    model_versions = [
+        _normalize_value(model_version_to_dict(version))
+        for version in getattr(workflow, "model_versions", [])
+    ]
+    correction_sets = [
+        _normalize_value(correction_set_to_dict(correction_set))
+        for correction_set in getattr(workflow, "correction_sets", [])
+    ]
+    evaluation_results = [
+        _normalize_value(evaluation_result_to_dict(result))
+        for result in getattr(workflow, "evaluation_results", [])
+    ]
+    persisted_hotspots = [
+        _normalize_value(region_hotspot_to_dict(hotspot))
+        for hotspot in getattr(workflow, "region_hotspots", [])
+    ]
+    volume_states = [
+        _normalize_value(volume_state_to_dict(volume_state))
+        for volume_state in getattr(workflow, "volume_states", [])
+    ]
+    agent_plans = [
+        _normalize_value(agent_plan_to_dict(plan))
+        for plan in getattr(workflow, "agent_plans", [])
+    ]
+
+    for artifact in typed_artifacts:
+        discovered.extend(
+            _collect_paths(
+                artifact,
+                source_type="artifact",
+                source_id=artifact.get("id"),
+                dataset_root=dataset_root,
+            )
+        )
+    for run in model_runs:
+        discovered.extend(
+            _collect_paths(
+                run,
+                source_type="model_run",
+                source_id=run.get("id"),
+                dataset_root=dataset_root,
+            )
+        )
+    for version in model_versions:
+        discovered.extend(
+            _collect_paths(
+                version,
+                source_type="model_version",
+                source_id=version.get("id"),
+                dataset_root=dataset_root,
+            )
+        )
+    for correction_set in correction_sets:
+        discovered.extend(
+            _collect_paths(
+                correction_set,
+                source_type="correction_set",
+                source_id=correction_set.get("id"),
+                dataset_root=dataset_root,
+            )
+        )
+    for result in evaluation_results:
+        discovered.extend(
+            _collect_paths(
+                result,
+                source_type="evaluation_result",
+                source_id=result.get("id"),
+                dataset_root=dataset_root,
+            )
+        )
+    for volume_state in volume_states:
+        discovered.extend(
+            _collect_paths(
+                volume_state,
+                source_type="volume_state",
+                source_id=volume_state.get("id"),
+                dataset_root=dataset_root,
+            )
+        )
+    for plan in agent_plans:
+        discovered.extend(
+            _collect_paths(
+                plan,
+                source_type="agent_plan",
+                source_id=plan.get("id"),
+                dataset_root=dataset_root,
+            )
+        )
+
+    artifact_paths = sorted(
+        _dedupe_path_refs(discovered), key=lambda item: item["path"]
+    )
 
     return {
-        "schema_version": "workflow-export-bundle/v1",
+        "schema_version": BUNDLE_SCHEMA_VERSION,
         "exported_at": datetime.now(timezone.utc).isoformat(),
         "workflow_id": workflow.id,
         "session_snapshot": session_snapshot,
         "events": ordered_events,
-        "artifact_paths": artifacts,
+        "artifacts": typed_artifacts,
+        "model_runs": model_runs,
+        "model_versions": model_versions,
+        "correction_sets": correction_sets,
+        "evaluation_results": evaluation_results,
+        "persisted_hotspots": persisted_hotspots,
+        "volume_states": volume_states,
+        "agent_plans": agent_plans,
+        "artifact_paths": artifact_paths,
+        "project_memory_summary": _build_project_memory_summary(workflow),
     }
+
+
+def write_export_bundle_directory(
+    bundle: Dict[str, Any],
+    *,
+    base_dir: str | None = None,
+    copy_max_bytes: int | None = None,
+    raw_copy_max_bytes: int | None = None,
+    copy_manifest_only: bool = False,
+) -> Dict[str, Any]:
+    """Persist a paper/debuggable workflow bundle without blindly copying huge data."""
+
+    root = Path(
+        base_dir
+        or os.environ.get("PYTC_WORKFLOW_BUNDLE_DIR")
+        or ".logs/workflow-bundles"
+    )
+    root.mkdir(parents=True, exist_ok=True)
+
+    timestamp = datetime.now(timezone.utc).strftime("%Y%m%d-%H%M%S-%f")
+    workflow_id = bundle.get("workflow_id") or "unknown"
+    export_dir = root / f"workflow-{workflow_id}-{timestamp}"
+    export_dir.mkdir(parents=True, exist_ok=False)
+    files_dir = export_dir / "files"
+    files_dir.mkdir(parents=True, exist_ok=True)
+
+    max_bytes = _parse_positive_int(
+        copy_max_bytes,
+        default=int(
+            os.environ.get(
+                "PYTC_WORKFLOW_BUNDLE_COPY_MAX_BYTES", str(DEFAULT_COPY_MAX_BYTES)
+            )
+        ),
+        field_name="copy_max_bytes",
+    )
+    raw_image_max_bytes = _parse_positive_int(
+        raw_copy_max_bytes,
+        default=int(
+            os.environ.get(
+                "PYTC_WORKFLOW_BUNDLE_RAW_COPY_MAX_BYTES",
+                str(DEFAULT_RAW_COPY_MAX_BYTES),
+            )
+        ),
+        field_name="raw_copy_max_bytes",
+    )
+    copied_artifacts: List[Dict[str, Any]] = []
+    skipped_artifacts: List[Dict[str, Any]] = []
+
+    for artifact in bundle.get("artifact_paths") or []:
+        path_text = artifact.get("path")
+        if not path_text:
+            continue
+        copy_policy = artifact.get("copy_policy") or {}
+        reference_scope = artifact.get("reference_scope")
+        source = Path(path_text).expanduser()
+        if not source.exists():
+            skipped_artifacts.append(
+                _build_skipped_artifact_record(
+                    path=path_text,
+                    reason="missing",
+                    exists=False,
+                    copy_policy=copy_policy,
+                    copy_mode="missing",
+                    reference_scope=reference_scope,
+                )
+            )
+            continue
+        if not source.is_file():
+            skipped_artifacts.append(
+                _build_skipped_artifact_record(
+                    path=path_text,
+                    reason="not_a_file",
+                    exists=True,
+                    copy_policy=copy_policy,
+                    copy_mode="not_a_file",
+                    reference_scope=reference_scope,
+                )
+            )
+            continue
+        if copy_manifest_only:
+            skipped_artifacts.append(
+                _build_skipped_artifact_record(
+                    path=path_text,
+                    reason="manifest_only",
+                    exists=True,
+                    copy_policy=copy_policy,
+                    copy_mode="manifest_only",
+                    reference_scope=reference_scope,
+                )
+            )
+            continue
+        if copy_policy.get("allow_copy") is False:
+            skipped_artifacts.append(
+                _build_skipped_artifact_record(
+                    path=path_text,
+                    reason="reference_only_policy",
+                    exists=True,
+                    copy_policy=copy_policy,
+                    copy_mode="policy",
+                    reference_scope=reference_scope,
+                )
+            )
+            continue
+        size_bytes = source.stat().st_size
+        is_likely_raw_image = _is_image_like_path(
+            str(source)
+        ) and _looks_like_raw_image_path(str(source))
+        effective_max_bytes = raw_image_max_bytes if is_likely_raw_image else max_bytes
+        if size_bytes > effective_max_bytes:
+            skip_reason = (
+                "raw_larger_than_copy_limit"
+                if is_likely_raw_image
+                else "larger_than_copy_limit"
+            )
+            skipped_artifacts.append(
+                _build_skipped_artifact_record(
+                    path=path_text,
+                    reason=skip_reason,
+                    exists=True,
+                    copy_policy=copy_policy,
+                    copy_mode="size_limit",
+                    reference_scope=reference_scope,
+                    size_bytes=size_bytes,
+                    copy_limit_bytes=effective_max_bytes,
+                    raw_copy_max_bytes=(
+                        raw_image_max_bytes if is_likely_raw_image else None
+                    ),
+                )
+            )
+            continue
+        digest = hashlib.sha1(str(source.resolve()).encode("utf-8")).hexdigest()[:10]
+        destination = files_dir / f"{digest}-{_safe_filename(source.name)}"
+        shutil.copy2(source, destination)
+        copied_artifacts.append(
+            {
+                "path": path_text,
+                "bundle_path": str(destination),
+                "relative_bundle_path": str(destination.relative_to(export_dir)),
+                "size_bytes": size_bytes,
+            }
+        )
+
+    bundle.update(
+        {
+            "bundle_directory": str(export_dir),
+            "bundle_manifest_path": str(export_dir / "workflow-bundle.json"),
+            "copy_settings": {
+                "copy_max_bytes": max_bytes,
+                "raw_copy_max_bytes": raw_image_max_bytes,
+                "copy_manifest_only": copy_manifest_only,
+            },
+            "copied_artifacts": copied_artifacts,
+            "skipped_artifacts": skipped_artifacts,
+        }
+    )
+
+    with (export_dir / "workflow-bundle.json").open("w", encoding="utf-8") as handle:
+        json.dump(bundle, handle, ensure_ascii=False, indent=2, sort_keys=True)
+        handle.write("\n")
+    with (export_dir / "artifact-paths.json").open("w", encoding="utf-8") as handle:
+        json.dump(
+            bundle.get("artifact_paths") or [],
+            handle,
+            ensure_ascii=False,
+            indent=2,
+            sort_keys=True,
+        )
+        handle.write("\n")
+    with (export_dir / "README.md").open("w", encoding="utf-8") as handle:
+        handle.write(
+            "# PyTC Workflow Evidence Bundle\n\n"
+            f"- Workflow ID: {workflow_id}\n"
+            f"- Exported at: {bundle.get('exported_at')}\n"
+            f"- Events: {len(bundle.get('events') or [])}\n"
+            f"- Typed artifacts: {len(bundle.get('artifacts') or [])}\n"
+            f"- Model runs: {len(bundle.get('model_runs') or [])}\n"
+            f"- Model versions: {len(bundle.get('model_versions') or [])}\n"
+            f"- Correction sets: {len(bundle.get('correction_sets') or [])}\n"
+            f"- Evaluation results: {len(bundle.get('evaluation_results') or [])}\n"
+            f"- Copied files: {len(copied_artifacts)}\n"
+            f"- Skipped paths: {len(skipped_artifacts)}\n\n"
+            "Large files are referenced in `artifact-paths.json` and copied only "
+            "when they fit their configured limits.\n"
+            "- Non-raw image paths use `copy_max_bytes`.\n"
+            "- Raw-like image paths use `raw_copy_max_bytes`.\n"
+            "- Entries marked `copy_policy.allow_copy=false` are referenced only.\n"
+            "- Holdout/withheld ground-truth paths are imported as reference-only by default.\n"
+            "- Set `copy_manifest_only=true` to skip all file copying.\n"
+        )
+
+    return bundle
diff --git a/server_api/workflows/db_models.py b/server_api/workflows/db_models.py
index f7d2b56b..67f773a8 100644
--- a/server_api/workflows/db_models.py
+++ b/server_api/workflows/db_models.py
@@ -1,4 +1,14 @@
-from sqlalchemy import Column, DateTime, ForeignKey, Integer, String, Text
+from sqlalchemy import (
+    Boolean,
+    Column,
+    DateTime,
+    Float,
+    ForeignKey,
+    Integer,
+    String,
+    Text,
+    UniqueConstraint,
+)
 from sqlalchemy.orm import relationship
 from sqlalchemy.sql import func
 
@@ -19,6 +29,7 @@ class WorkflowSession(Base):
     neuroglancer_url = Column(Text, nullable=True)
     inference_output_path = Column(String, nullable=True)
     checkpoint_path = Column(String, nullable=True)
+    config_path = Column(String, nullable=True)
     proofreading_session_id = Column(Integer, nullable=True, index=True)
     corrected_mask_path = Column(String, nullable=True)
     training_output_path = Column(String, nullable=True)
@@ -34,10 +45,71 @@ class WorkflowSession(Base):
         cascade="all, delete-orphan",
         order_by="WorkflowEvent.created_at",
     )
+    artifacts = relationship(
+        "WorkflowArtifact",
+        back_populates="workflow",
+        cascade="all, delete-orphan",
+        order_by="WorkflowArtifact.created_at",
+    )
+    model_runs = relationship(
+        "WorkflowModelRun",
+        back_populates="workflow",
+        cascade="all, delete-orphan",
+        order_by="WorkflowModelRun.created_at",
+    )
+    model_versions = relationship(
+        "WorkflowModelVersion",
+        back_populates="workflow",
+        cascade="all, delete-orphan",
+        order_by="WorkflowModelVersion.created_at",
+    )
+    correction_sets = relationship(
+        "WorkflowCorrectionSet",
+        back_populates="workflow",
+        cascade="all, delete-orphan",
+        order_by="WorkflowCorrectionSet.created_at",
+    )
+    evaluation_results = relationship(
+        "WorkflowEvaluationResult",
+        back_populates="workflow",
+        cascade="all, delete-orphan",
+        order_by="WorkflowEvaluationResult.created_at",
+    )
+    region_hotspots = relationship(
+        "WorkflowRegionHotspot",
+        back_populates="workflow",
+        cascade="all, delete-orphan",
+        order_by="WorkflowRegionHotspot.updated_at",
+    )
+    agent_plans = relationship(
+        "WorkflowAgentPlan",
+        back_populates="workflow",
+        cascade="all, delete-orphan",
+        order_by="WorkflowAgentPlan.updated_at",
+    )
+    commands = relationship(
+        "WorkflowCommand",
+        back_populates="workflow",
+        cascade="all, delete-orphan",
+        order_by="WorkflowCommand.created_at",
+    )
+    volume_states = relationship(
+        "WorkflowVolumeState",
+        back_populates="workflow",
+        cascade="all, delete-orphan",
+        order_by="WorkflowVolumeState.volume_id",
+    )
 
 
 class WorkflowEvent(Base):
     __tablename__ = "workflow_events"
+    __table_args__ = (
+        UniqueConstraint(
+            "workflow_id",
+            "idempotency_key",
+            name="uq_workflow_events_workflow_id_idempotency_key",
+        ),
+    )
 
     id = Column(Integer, primary_key=True, index=True)
     workflow_id = Column(
@@ -48,8 +120,323 @@ class WorkflowEvent(Base):
     stage = Column(String, nullable=True, index=True)
     summary = Column(Text, nullable=False)
     payload_json = Column(Text, nullable=True)
+    schema_version = Column(Integer, default=1, nullable=False)
+    idempotency_key = Column(String, nullable=True, index=True)
     approval_status = Column(String, default="not_required", index=True)
     created_at = Column(DateTime(timezone=True), server_default=func.now())
 
     workflow = relationship("WorkflowSession", back_populates="events")
 
+
+class WorkflowCommand(Base):
+    __tablename__ = "workflow_commands"
+    __table_args__ = (
+        UniqueConstraint(
+            "workflow_id",
+            "idempotency_key",
+            name="uq_workflow_commands_workflow_id_idempotency_key",
+        ),
+    )
+
+    id = Column(Integer, primary_key=True, index=True)
+    workflow_id = Column(
+        Integer, ForeignKey("workflow_sessions.id"), nullable=False, index=True
+    )
+    command_type = Column(String, nullable=False, index=True)
+    status = Column(String, default="queued", nullable=False, index=True)
+    idempotency_key = Column(String, nullable=False, index=True)
+    actor = Column(String, default="agent", nullable=False, index=True)
+    source_event_id = Column(Integer, ForeignKey("workflow_events.id"), nullable=True)
+    approval_event_id = Column(Integer, ForeignKey("workflow_events.id"), nullable=True)
+    input_json = Column(Text, nullable=True)
+    result_json = Column(Text, nullable=True)
+    error_json = Column(Text, nullable=True)
+    attempt_count = Column(Integer, default=0, nullable=False)
+    lease_owner = Column(String, nullable=True, index=True)
+    lease_expires_at = Column(DateTime(timezone=True), nullable=True)
+    started_at = Column(DateTime(timezone=True), nullable=True)
+    completed_at = Column(DateTime(timezone=True), nullable=True)
+    created_at = Column(DateTime(timezone=True), server_default=func.now())
+    updated_at = Column(
+        DateTime(timezone=True), server_default=func.now(), onupdate=func.now()
+    )
+
+    workflow = relationship("WorkflowSession", back_populates="commands")
+    source_event = relationship("WorkflowEvent", foreign_keys=[source_event_id])
+    approval_event = relationship("WorkflowEvent", foreign_keys=[approval_event_id])
+
+
+class WorkflowArtifact(Base):
+    __tablename__ = "workflow_artifacts"
+    __table_args__ = (
+        UniqueConstraint(
+            "workflow_id",
+            "artifact_type",
+            "role",
+            "path",
+            name="uq_workflow_artifacts_identity",
+        ),
+    )
+
+    id = Column(Integer, primary_key=True, index=True)
+    workflow_id = Column(
+        Integer, ForeignKey("workflow_sessions.id"), nullable=False, index=True
+    )
+    artifact_type = Column(String, nullable=False, index=True)
+    role = Column(String, nullable=True, index=True)
+    name = Column(String, nullable=True)
+    path = Column(Text, nullable=True)
+    uri = Column(Text, nullable=True)
+    checksum = Column(String, nullable=True)
+    size_bytes = Column(Integer, nullable=True)
+    source_event_id = Column(Integer, ForeignKey("workflow_events.id"), nullable=True)
+    metadata_json = Column(Text, nullable=True)
+    created_at = Column(DateTime(timezone=True), server_default=func.now())
+
+    workflow = relationship("WorkflowSession", back_populates="artifacts")
+    source_event = relationship("WorkflowEvent")
+
+
+class WorkflowVolumeState(Base):
+    __tablename__ = "workflow_volume_states"
+    __table_args__ = (
+        UniqueConstraint(
+            "workflow_id",
+            "volume_id",
+            name="uq_workflow_volume_states_workflow_id_volume_id",
+        ),
+    )
+
+    id = Column(Integer, primary_key=True, index=True)
+    workflow_id = Column(
+        Integer, ForeignKey("workflow_sessions.id"), nullable=False, index=True
+    )
+    volume_id = Column(String, nullable=False, index=True)
+    name = Column(String, nullable=True)
+    status = Column(String, nullable=False, default="missing_segmentation", index=True)
+    annotation_state = Column(String, nullable=True, index=True)
+    role_state = Column(String, nullable=True, index=True)
+    execution_state = Column(String, nullable=True, index=True)
+    region_scope_json = Column(Text, nullable=True)
+    state_schema_version = Column(String, nullable=True)
+    status_source = Column(String, default="derived", nullable=False, index=True)
+    status_confidence = Column(Float, nullable=True)
+    project_root = Column(Text, nullable=True)
+    volume_set_id = Column(String, nullable=True, index=True)
+    volume_set_name = Column(String, nullable=True)
+    image_path = Column(Text, nullable=True)
+    label_path = Column(Text, nullable=True)
+    prediction_path = Column(Text, nullable=True)
+    corrected_mask_path = Column(Text, nullable=True)
+    eligible_for_training = Column(Boolean, default=False, nullable=False, index=True)
+    eligible_for_inference = Column(Boolean, default=False, nullable=False, index=True)
+    note = Column(Text, nullable=True)
+    metadata_json = Column(Text, nullable=True)
+    source_event_id = Column(Integer, ForeignKey("workflow_events.id"), nullable=True)
+    created_at = Column(DateTime(timezone=True), server_default=func.now())
+    updated_at = Column(
+        DateTime(timezone=True), server_default=func.now(), onupdate=func.now()
+    )
+
+    workflow = relationship("WorkflowSession", back_populates="volume_states")
+    source_event = relationship("WorkflowEvent")
+
+
+class WorkflowModelRun(Base):
+    __tablename__ = "workflow_model_runs"
+    __table_args__ = (
+        UniqueConstraint(
+            "workflow_id",
+            "run_id",
+            name="uq_workflow_model_runs_workflow_id_run_id",
+        ),
+    )
+
+    id = Column(Integer, primary_key=True, index=True)
+    workflow_id = Column(
+        Integer, ForeignKey("workflow_sessions.id"), nullable=False, index=True
+    )
+    run_id = Column(String, nullable=True, index=True)
+    run_type = Column(String, nullable=False, index=True)
+    status = Column(String, default="pending", index=True)
+    name = Column(String, nullable=True)
+    config_path = Column(Text, nullable=True)
+    log_path = Column(Text, nullable=True)
+    output_path = Column(Text, nullable=True)
+    checkpoint_path = Column(Text, nullable=True)
+    input_artifact_id = Column(
+        Integer, ForeignKey("workflow_artifacts.id"), nullable=True
+    )
+    output_artifact_id = Column(
+        Integer, ForeignKey("workflow_artifacts.id"), nullable=True
+    )
+    source_event_id = Column(Integer, ForeignKey("workflow_events.id"), nullable=True)
+    metrics_json = Column(Text, nullable=True)
+    metadata_json = Column(Text, nullable=True)
+    started_at = Column(DateTime(timezone=True), nullable=True)
+    completed_at = Column(DateTime(timezone=True), nullable=True)
+    created_at = Column(DateTime(timezone=True), server_default=func.now())
+    updated_at = Column(
+        DateTime(timezone=True), server_default=func.now(), onupdate=func.now()
+    )
+
+    workflow = relationship("WorkflowSession", back_populates="model_runs")
+    input_artifact = relationship("WorkflowArtifact", foreign_keys=[input_artifact_id])
+    output_artifact = relationship(
+        "WorkflowArtifact", foreign_keys=[output_artifact_id]
+    )
+    source_event = relationship("WorkflowEvent")
+
+
+class WorkflowModelVersion(Base):
+    __tablename__ = "workflow_model_versions"
+
+    id = Column(Integer, primary_key=True, index=True)
+    workflow_id = Column(
+        Integer, ForeignKey("workflow_sessions.id"), nullable=False, index=True
+    )
+    version_label = Column(String, nullable=False, index=True)
+    status = Column(String, default="candidate", index=True)
+    checkpoint_path = Column(Text, nullable=True)
+    training_run_id = Column(
+        Integer, ForeignKey("workflow_model_runs.id"), nullable=True
+    )
+    checkpoint_artifact_id = Column(
+        Integer, ForeignKey("workflow_artifacts.id"), nullable=True
+    )
+    correction_set_id = Column(
+        Integer, ForeignKey("workflow_correction_sets.id"), nullable=True
+    )
+    metrics_json = Column(Text, nullable=True)
+    metadata_json = Column(Text, nullable=True)
+    created_at = Column(DateTime(timezone=True), server_default=func.now())
+
+    workflow = relationship("WorkflowSession", back_populates="model_versions")
+    training_run = relationship("WorkflowModelRun")
+    checkpoint_artifact = relationship("WorkflowArtifact")
+
+
+class WorkflowCorrectionSet(Base):
+    __tablename__ = "workflow_correction_sets"
+
+    id = Column(Integer, primary_key=True, index=True)
+    workflow_id = Column(
+        Integer, ForeignKey("workflow_sessions.id"), nullable=False, index=True
+    )
+    artifact_id = Column(Integer, ForeignKey("workflow_artifacts.id"), nullable=True)
+    corrected_mask_path = Column(Text, nullable=False)
+    source_mask_path = Column(Text, nullable=True)
+    proofreading_session_id = Column(Integer, nullable=True, index=True)
+    edit_count = Column(Integer, default=0)
+    region_count = Column(Integer, default=0)
+    source_event_id = Column(Integer, ForeignKey("workflow_events.id"), nullable=True)
+    metadata_json = Column(Text, nullable=True)
+    created_at = Column(DateTime(timezone=True), server_default=func.now())
+
+    workflow = relationship("WorkflowSession", back_populates="correction_sets")
+    artifact = relationship("WorkflowArtifact")
+    source_event = relationship("WorkflowEvent")
+
+
+class WorkflowEvaluationResult(Base):
+    __tablename__ = "workflow_evaluation_results"
+
+    id = Column(Integer, primary_key=True, index=True)
+    workflow_id = Column(
+        Integer, ForeignKey("workflow_sessions.id"), nullable=False, index=True
+    )
+    name = Column(String, nullable=True)
+    baseline_run_id = Column(
+        Integer, ForeignKey("workflow_model_runs.id"), nullable=True
+    )
+    candidate_run_id = Column(
+        Integer, ForeignKey("workflow_model_runs.id"), nullable=True
+    )
+    model_version_id = Column(
+        Integer, ForeignKey("workflow_model_versions.id"), nullable=True
+    )
+    report_artifact_id = Column(
+        Integer, ForeignKey("workflow_artifacts.id"), nullable=True
+    )
+    report_path = Column(Text, nullable=True)
+    summary = Column(Text, nullable=True)
+    metrics_json = Column(Text, nullable=True)
+    metadata_json = Column(Text, nullable=True)
+    created_at = Column(DateTime(timezone=True), server_default=func.now())
+
+    workflow = relationship("WorkflowSession", back_populates="evaluation_results")
+    baseline_run = relationship("WorkflowModelRun", foreign_keys=[baseline_run_id])
+    candidate_run = relationship("WorkflowModelRun", foreign_keys=[candidate_run_id])
+    model_version = relationship("WorkflowModelVersion")
+    report_artifact = relationship("WorkflowArtifact")
+
+
+class WorkflowRegionHotspot(Base):
+    __tablename__ = "workflow_region_hotspots"
+
+    id = Column(Integer, primary_key=True, index=True)
+    workflow_id = Column(
+        Integer, ForeignKey("workflow_sessions.id"), nullable=False, index=True
+    )
+    region_key = Column(String, nullable=False, index=True)
+    score = Column(Float, default=0.0, index=True)
+    severity = Column(String, default="low", index=True)
+    status = Column(String, default="open", index=True)
+    source = Column(String, default="event_heuristic", index=True)
+    evidence_json = Column(Text, nullable=True)
+    created_at = Column(DateTime(timezone=True), server_default=func.now())
+    updated_at = Column(
+        DateTime(timezone=True), server_default=func.now(), onupdate=func.now()
+    )
+
+    workflow = relationship("WorkflowSession", back_populates="region_hotspots")
+
+
+class WorkflowAgentPlan(Base):
+    __tablename__ = "workflow_agent_plans"
+
+    id = Column(Integer, primary_key=True, index=True)
+    workflow_id = Column(
+        Integer, ForeignKey("workflow_sessions.id"), nullable=False, index=True
+    )
+    title = Column(String, nullable=False)
+    status = Column(String, default="draft", index=True)
+    risk_level = Column(String, default="medium", index=True)
+    approval_status = Column(String, default="pending", index=True)
+    goal = Column(Text, nullable=True)
+    graph_json = Column(Text, nullable=True)
+    metadata_json = Column(Text, nullable=True)
+    source_event_id = Column(Integer, ForeignKey("workflow_events.id"), nullable=True)
+    created_at = Column(DateTime(timezone=True), server_default=func.now())
+    updated_at = Column(
+        DateTime(timezone=True), server_default=func.now(), onupdate=func.now()
+    )
+
+    source_event = relationship("WorkflowEvent")
+    workflow = relationship("WorkflowSession", back_populates="agent_plans")
+    steps = relationship(
+        "WorkflowAgentStep",
+        back_populates="plan",
+        cascade="all, delete-orphan",
+        order_by="WorkflowAgentStep.step_index",
+    )
+
+
+class WorkflowAgentStep(Base):
+    __tablename__ = "workflow_agent_steps"
+
+    id = Column(Integer, primary_key=True, index=True)
+    plan_id = Column(Integer, ForeignKey("workflow_agent_plans.id"), nullable=False)
+    step_index = Column(Integer, nullable=False)
+    action = Column(String, nullable=False, index=True)
+    status = Column(String, default="pending", index=True)
+    requires_approval = Column(Boolean, default=True, index=True)
+    summary = Column(Text, nullable=True)
+    params_json = Column(Text, nullable=True)
+    result_json = Column(Text, nullable=True)
+    created_at = Column(DateTime(timezone=True), server_default=func.now())
+    updated_at = Column(
+        DateTime(timezone=True), server_default=func.now(), onupdate=func.now()
+    )
+
+    plan = relationship("WorkflowAgentPlan", back_populates="steps")
diff --git a/server_api/workflows/evaluation.py b/server_api/workflows/evaluation.py
new file mode 100644
index 00000000..65feac20
--- /dev/null
+++ b/server_api/workflows/evaluation.py
@@ -0,0 +1,172 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+import numpy as np
+
+from .volume_io import load_volume
+
+
+def _read_volume(
+    path: str,
+    *,
+    dataset_key: Optional[str] = None,
+    crop: Optional[str] = None,
+    channel: Optional[int] = None,
+    reference_ndim: Optional[int] = None,
+    label: str = "volume",
+) -> np.ndarray:
+    return np.asarray(
+        load_volume(
+            path,
+            dataset_key=dataset_key,
+            crop=crop,
+            channel=channel,
+            reference_ndim=reference_ndim,
+            label=label,
+        )
+    )
+
+
+def _read_eval_volume(
+    path: str,
+    *,
+    dataset_key: Optional[str] = None,
+    crop: Optional[str] = None,
+    channel: Optional[int] = None,
+    reference_ndim: Optional[int] = None,
+    label: str,
+) -> np.ndarray:
+    return _read_volume(
+        path,
+        dataset_key=dataset_key,
+        crop=crop,
+        channel=channel,
+        reference_ndim=reference_ndim,
+        label=label,
+    )
+
+
+def _validate_same_shape(*arrays: np.ndarray) -> None:
+    shapes = {array.shape for array in arrays}
+    if len(shapes) != 1:
+        raise ValueError(f"Evaluation arrays must have identical shape; got {shapes}")
+
+
+def _safe_ratio(
+    numerator: float, denominator: float, empty_value: float = 1.0
+) -> float:
+    if denominator == 0:
+        return empty_value
+    return float(numerator / denominator)
+
+
+def _segmentation_metrics(
+    prediction: np.ndarray, ground_truth: np.ndarray
+) -> Dict[str, Any]:
+    prediction_binary = prediction > 0
+    truth_binary = ground_truth > 0
+    intersection = np.logical_and(prediction_binary, truth_binary).sum()
+    prediction_sum = prediction_binary.sum()
+    truth_sum = truth_binary.sum()
+    union = np.logical_or(prediction_binary, truth_binary).sum()
+
+    metrics: Dict[str, Any] = {
+        "dice": round(_safe_ratio(2 * intersection, prediction_sum + truth_sum), 6),
+        "iou": round(_safe_ratio(intersection, union), 6),
+        "voxel_accuracy": round(float(np.mean(prediction == ground_truth)), 6),
+        "foreground_voxels": int(prediction_sum),
+        "truth_foreground_voxels": int(truth_sum),
+    }
+
+    try:
+        from skimage.metrics import adapted_rand_error, variation_of_information
+
+        are, precision, recall = adapted_rand_error(ground_truth, prediction)
+        split_vi, merge_vi = variation_of_information(ground_truth, prediction)
+        metrics.update(
+            {
+                "adapted_rand_error": round(float(are), 6),
+                "adapted_rand_precision": round(float(precision), 6),
+                "adapted_rand_recall": round(float(recall), 6),
+                "vi_split": round(float(split_vi), 6),
+                "vi_merge": round(float(merge_vi), 6),
+                "vi_total": round(float(split_vi + merge_vi), 6),
+            }
+        )
+    except Exception:
+        metrics["advanced_metrics_unavailable"] = True
+
+    return metrics
+
+
+def compute_before_after_evaluation(
+    *,
+    baseline_prediction_path: str,
+    candidate_prediction_path: str,
+    ground_truth_path: str,
+    baseline_dataset: Optional[str] = None,
+    candidate_dataset: Optional[str] = None,
+    ground_truth_dataset: Optional[str] = None,
+    crop: Optional[str] = None,
+    baseline_channel: Optional[int] = None,
+    candidate_channel: Optional[int] = None,
+    ground_truth_channel: Optional[int] = None,
+) -> Dict[str, Any]:
+    ground_truth = _read_eval_volume(
+        ground_truth_path,
+        dataset_key=ground_truth_dataset,
+        crop=crop,
+        channel=ground_truth_channel,
+        label="ground truth",
+    )
+    baseline = _read_eval_volume(
+        baseline_prediction_path,
+        dataset_key=baseline_dataset,
+        crop=crop,
+        channel=baseline_channel,
+        reference_ndim=ground_truth.ndim,
+        label="baseline prediction",
+    )
+    candidate = _read_eval_volume(
+        candidate_prediction_path,
+        dataset_key=candidate_dataset,
+        crop=crop,
+        channel=candidate_channel,
+        reference_ndim=ground_truth.ndim,
+        label="candidate prediction",
+    )
+    _validate_same_shape(baseline, candidate, ground_truth)
+
+    baseline_metrics = _segmentation_metrics(baseline, ground_truth)
+    candidate_metrics = _segmentation_metrics(candidate, ground_truth)
+    deltas: Dict[str, float] = {}
+    for key, candidate_value in candidate_metrics.items():
+        baseline_value = baseline_metrics.get(key)
+        if isinstance(candidate_value, (int, float)) and isinstance(
+            baseline_value, (int, float)
+        ):
+            deltas[key] = round(float(candidate_value - baseline_value), 6)
+
+    return {
+        "baseline": baseline_metrics,
+        "candidate": candidate_metrics,
+        "delta": deltas,
+        "summary": {
+            "dice_delta": deltas.get("dice"),
+            "iou_delta": deltas.get("iou"),
+            "voxel_accuracy_delta": deltas.get("voxel_accuracy"),
+            "candidate_improved_dice": bool(
+                candidate_metrics.get("dice", 0) >= baseline_metrics.get("dice", 0)
+            ),
+        },
+    }
+
+
+def write_evaluation_report(path: str, payload: Dict[str, Any]) -> str:
+    target = Path(path).expanduser()
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(json.dumps(payload, indent=2, sort_keys=True), encoding="utf-8")
+    return str(target)
diff --git a/server_api/workflows/evidence_export.py b/server_api/workflows/evidence_export.py
index ca51394f..19efb03d 100644
--- a/server_api/workflows/evidence_export.py
+++ b/server_api/workflows/evidence_export.py
@@ -1,13 +1,33 @@
 from __future__ import annotations
 
-from collections import Counter
-from typing import Any, Dict, List
+from collections import Counter, defaultdict
+from datetime import datetime
+from typing import Any, Dict, List, Optional
 
-from .db_models import WorkflowEvent, WorkflowSession
+from sqlalchemy.orm.exc import DetachedInstanceError
+
+from .bundle_export import _build_project_memory_summary
+from .db_models import WorkflowCommand, WorkflowEvent, WorkflowModelRun, WorkflowSession
 from .service import decode_json
 
 EVIDENCE_EXPORT_VERSION = "1.0"
 
+PROGRESS_EVENT_TYPES = {
+    "training.started",
+    "training.completed",
+    "training.failed",
+    "inference.started",
+    "inference.completed",
+    "inference.failed",
+    "evaluation.completed",
+    "evaluation.failed",
+}
+ACTION_EVENT_TYPES = {
+    "training.run_approved",
+    "agent.client_effects_approved",
+    "retraining.staged",
+}
+
 
 def _iso(value: Any) -> str | None:
     if value is None:
@@ -17,6 +37,61 @@ def _iso(value: Any) -> str | None:
     return str(value)
 
 
+def _event_payload(event: WorkflowEvent) -> Dict[str, Any]:
+    return decode_json(event.payload_json)
+
+
+def _parse_event_time(value: Any) -> datetime:
+    if value is None:
+        return datetime.min
+    if isinstance(value, datetime):
+        return value
+    if hasattr(value, "isoformat"):
+        parsed = value
+        if isinstance(parsed, str):
+            text = parsed
+            if text.endswith("Z"):
+                text = text.replace("Z", "+00:00")
+            try:
+                return datetime.fromisoformat(text)
+            except ValueError:
+                return datetime.min
+    return datetime.min
+
+
+def _event_run_id(payload: Dict[str, Any]) -> Optional[str]:
+    for key in (
+        "run_id",
+        "runId",
+        "job_id",
+        "jobId",
+        "execution_id",
+        "executionId",
+    ):
+        value = payload.get(key)
+        if value is not None:
+            return str(value)
+    return None
+
+
+def _event_run_type(event_type: Optional[str]) -> Optional[str]:
+    if not event_type or "." not in event_type:
+        return None
+    return event_type.split(".", 1)[0]
+
+
+def _command_run_type(command_type: Optional[str]) -> Optional[str]:
+    if not command_type:
+        return None
+    if command_type == "start_training":
+        return "training"
+    if command_type == "start_inference":
+        return "inference"
+    if command_type == "start_evaluation":
+        return "evaluation"
+    return None
+
+
 def _stage_progression(events: List[WorkflowEvent]) -> Dict[str, Any]:
     observed: List[str] = []
     entered_at: Dict[str, str] = {}
@@ -67,10 +142,102 @@ def _proposal_approval_summary(events: List[WorkflowEvent]) -> Dict[str, Any]:
     }
 
 
-def _timeline_snippet(events: List[WorkflowEvent], max_events: int = 20) -> List[Dict[str, Any]]:
+def _proposal_approval_links(events: List[WorkflowEvent]) -> List[Dict[str, Any]]:
+    created: Dict[int, Dict[str, Any]] = {}
+    links: List[Dict[str, Any]] = []
+
+    for event in events:
+        event_payload = _event_payload(event)
+        if event.event_type == "agent.proposal_created":
+            created[int(event.id)] = {
+                "proposal_id": int(event.id),
+                "proposal_summary": event.summary,
+                "proposal_stage": event.stage,
+                "proposal_actor": event.actor,
+                "proposal_action": event_payload.get("action"),
+                "proposal_params": event_payload.get("params"),
+                "created_at": _iso(event.created_at),
+            }
+            continue
+
+        if event.event_type in {"agent.proposal_approved", "agent.proposal_rejected"}:
+            proposal_event_id = event_payload.get("proposal_event_id")
+            if isinstance(proposal_event_id, int) and proposal_event_id in created:
+                links.append(
+                    {
+                        "proposal_event_id": proposal_event_id,
+                        "proposal_summary": created[proposal_event_id].get(
+                            "proposal_summary"
+                        ),
+                        "action": created[proposal_event_id].get("proposal_action"),
+                        "params": created[proposal_event_id].get("proposal_params"),
+                        "approval_event_id": event.id,
+                        "approval_status": event.event_type.split("_")[-1],
+                        "approval_stage": event.stage,
+                        "approval_actor": event.actor,
+                        "approval_at": _iso(event.created_at),
+                        "proposal_stage": created[proposal_event_id].get(
+                            "proposal_stage"
+                        ),
+                        "proposal_actor": created[proposal_event_id].get(
+                            "proposal_actor"
+                        ),
+                    }
+                )
+            else:
+                links.append(
+                    {
+                        "proposal_event_id": proposal_event_id,
+                        "approval_event_id": event.id,
+                        "approval_status": event.event_type.split("_")[-1],
+                        "approval_stage": event.stage,
+                        "approval_actor": event.actor,
+                        "approval_at": _iso(event.created_at),
+                    }
+                )
+
+    return links
+
+
+def _user_status_changes(events: List[WorkflowEvent]) -> List[Dict[str, Any]]:
+    status_changes: List[Dict[str, Any]] = []
+    last_stage: str | None = None
+    for event in events:
+        stage = event.stage
+        if not stage or event.actor != "user":
+            continue
+        if stage == last_stage:
+            continue
+        status_changes.append(
+            {
+                "at": _iso(event.created_at),
+                "event_id": event.id,
+                "event_type": event.event_type,
+                "stage": stage,
+                "source_event_id": event.id,
+                "summary": event.summary,
+            }
+        )
+        last_stage = stage
+    return status_changes
+
+
+def _safe_related_records(
+    workflow: WorkflowSession, relationship_name: str
+) -> List[Any]:
+    try:
+        records = getattr(workflow, relationship_name)
+    except DetachedInstanceError:
+        return []
+    return list(records or [])
+
+
+def _timeline_snippet(
+    events: List[WorkflowEvent], max_events: int = 20
+) -> List[Dict[str, Any]]:
     snippet: List[Dict[str, Any]] = []
     for event in events[:max_events]:
-        payload = decode_json(event.payload_json)
+        payload = _event_payload(event)
         snippet.append(
             {
                 "timestamp": _iso(event.created_at),
@@ -84,6 +251,285 @@ def _timeline_snippet(events: List[WorkflowEvent], max_events: int = 20) -> List
     return snippet
 
 
+def _safe_len_relationship(workflow: WorkflowSession, attr_name: str) -> int:
+    try:
+        related = getattr(workflow, attr_name)
+    except DetachedInstanceError:
+        return 0
+    return len(related or [])
+
+
+def _run_for_event(
+    event: WorkflowEvent,
+    runs: List[WorkflowModelRun],
+) -> Optional[WorkflowModelRun]:
+    payload = _event_payload(event)
+    run_id = _event_run_id(payload)
+    if run_id is not None:
+        for row in runs:
+            if str(row.run_id) == str(run_id):
+                return row
+
+    event_run_type = _event_run_type(event.event_type)
+    if event.id is not None:
+        for row in runs:
+            if row.source_event_id == event.id:
+                return row
+
+    if event_run_type is not None:
+        if event.created_at:
+            candidates = [
+                row
+                for row in runs
+                if row.run_type == event_run_type
+                and row.created_at
+                and row.created_at <= _parse_event_time(event.created_at)
+            ]
+            if candidates:
+                return max(
+                    candidates, key=lambda row: (row.created_at or datetime.min, row.id)
+                )
+
+        candidates = [
+            row for row in runs if row.run_type == event_run_type and row.id is not None
+        ]
+        if candidates:
+            return max(candidates, key=lambda row: row.id)
+
+    return None
+
+
+def _run_for_command(
+    command: WorkflowCommand,
+    runs: List[WorkflowModelRun],
+) -> Optional[WorkflowModelRun]:
+    run_type = _command_run_type(command.command_type)
+    if not run_type:
+        return None
+
+    created_at = _parse_event_time(command.created_at)
+    candidates = [
+        row
+        for row in runs
+        if row.run_type == run_type
+        and row.created_at
+        and _parse_event_time(row.created_at) >= created_at
+    ]
+    if candidates:
+        return min(candidates, key=lambda row: (row.created_at or datetime.min, row.id))
+
+    candidates = [
+        row for row in runs if row.run_type == run_type and row.id is not None
+    ]
+    return min(candidates, key=lambda row: row.id) if candidates else None
+
+
+def _progress_event_belongs_to_run(
+    event: WorkflowEvent,
+    run: WorkflowModelRun,
+) -> bool:
+    payload = _event_payload(event)
+    event_run_type = _event_run_type(event.event_type)
+    if event_run_type != run.run_type:
+        return False
+    if run.run_id is not None:
+        run_id = _event_run_id(payload)
+        if run_id is not None and str(run_id) == str(run.run_id):
+            return True
+    if event.id is not None and run.source_event_id == event.id:
+        return True
+
+    event_time = _parse_event_time(event.created_at)
+    run_started = _parse_event_time(run.started_at)
+    run_completed = _parse_event_time(run.completed_at)
+    if run.started_at and run.completed_at:
+        if run_started <= event_time <= run_completed:
+            return True
+    elif run.started_at and event_time >= run_started:
+        return True
+    return False
+
+
+def _build_progress_event_summary(
+    event: WorkflowEvent, run_id: str | None = None
+) -> Dict[str, Any]:
+    payload = _event_payload(event)
+    event_run_id = _event_run_id(payload)
+    return {
+        "event_id": event.id,
+        "event_type": event.event_type,
+        "status": event.event_type.split(".")[-1],
+        "run_type": _event_run_type(event.event_type),
+        "run_id": event_run_id if event_run_id is not None else run_id,
+        "stage": event.stage,
+        "actor": event.actor,
+        "created_at": _iso(event.created_at),
+        "summary": event.summary,
+        "payload_keys": sorted(payload.keys()),
+    }
+
+
+def _build_run_summary(
+    run: WorkflowModelRun,
+    progress_events: List[WorkflowEvent],
+) -> Dict[str, Any]:
+    run_progress = [
+        _build_progress_event_summary(event, run_id=str(run.run_id))
+        for event in progress_events
+        if _progress_event_belongs_to_run(event, run)
+    ]
+    return {
+        "run_record_id": run.id,
+        "run_id": run.run_id,
+        "run_type": run.run_type,
+        "status": run.status,
+        "name": run.name,
+        "config_path": run.config_path,
+        "checkpoint_path": run.checkpoint_path,
+        "log_path": run.log_path,
+        "output_path": run.output_path,
+        "source_event_id": run.source_event_id,
+        "created_at": _iso(run.created_at),
+        "started_at": _iso(run.started_at),
+        "completed_at": _iso(run.completed_at),
+        "progress_events": run_progress,
+    }
+
+
+def _build_command_summary(command: WorkflowCommand) -> Dict[str, Any]:
+    return {
+        "command_id": command.id,
+        "command_type": command.command_type,
+        "status": command.status,
+        "idempotency_key": command.idempotency_key,
+        "actor": command.actor,
+        "source_event_id": command.source_event_id,
+        "approval_event_id": command.approval_event_id,
+        "attempt_count": command.attempt_count,
+        "created_at": _iso(command.created_at),
+        "updated_at": _iso(command.updated_at),
+        "started_at": _iso(command.started_at),
+        "completed_at": _iso(command.completed_at),
+    }
+
+
+def _build_proposal_approval_graph(
+    workflow: WorkflowSession,
+    events: List[WorkflowEvent],
+) -> List[Dict[str, Any]]:
+    runs = _safe_related_records(workflow, "model_runs")
+    commands = _safe_related_records(workflow, "commands")
+    proposal_events = [
+        event for event in events if event.event_type == "agent.proposal_created"
+    ]
+    if not proposal_events:
+        return []
+
+    approvals = [
+        event
+        for event in events
+        if event.event_type in {"agent.proposal_approved", "agent.proposal_rejected"}
+    ]
+    approval_index: Dict[int, List[WorkflowEvent]] = defaultdict(list)
+    for approval in approvals:
+        approval_payload = _event_payload(approval)
+        proposal_id = approval_payload.get("proposal_event_id")
+        if isinstance(proposal_id, int):
+            approval_index[proposal_id].append(approval)
+
+    actions = [event for event in events if event.event_type in ACTION_EVENT_TYPES]
+
+    progress_events = [
+        event for event in events if event.event_type in PROGRESS_EVENT_TYPES
+    ]
+
+    graph: List[Dict[str, Any]] = []
+    for proposal in proposal_events:
+        proposal_payload = _event_payload(proposal)
+        proposal_id = proposal.id
+        approvals_for_proposal = (
+            approval_index.get(int(proposal_id), []) if proposal_id else []
+        )
+        approval = approvals_for_proposal[0] if approvals_for_proposal else None
+
+        action_events = [
+            event
+            for event in actions
+            if _event_payload(event).get("proposal_event_id") == proposal_id
+        ]
+
+        proposal_commands = [
+            command
+            for command in commands
+            if command.source_event_id == proposal_id
+            or (approval and command.approval_event_id == approval.id)
+        ]
+
+        linked_runs: Dict[int, WorkflowModelRun] = {}
+        for action_event in action_events:
+            run = _run_for_event(action_event, runs)
+            if run is not None and run.id is not None:
+                linked_runs[run.id] = run
+
+        for command in proposal_commands:
+            run = _run_for_command(command, runs)
+            if run is not None and run.id is not None:
+                linked_runs[run.id] = run
+
+        run_refs = [
+            _build_run_summary(run, progress_events)
+            for run in sorted(linked_runs.values(), key=lambda row: row.id)
+        ]
+
+        graph.append(
+            {
+                "proposal": {
+                    "event_id": proposal.id,
+                    "summary": proposal.summary,
+                    "stage": proposal.stage,
+                    "actor": proposal.actor,
+                    "action": proposal_payload.get("action"),
+                    "params": (
+                        proposal_payload.get("params")
+                        if isinstance(proposal_payload.get("params"), dict)
+                        else {}
+                    ),
+                    "created_at": _iso(proposal.created_at),
+                },
+                "approval": (
+                    None
+                    if approval is None
+                    else {
+                        "event_id": approval.id,
+                        "status": approval.event_type.split("_")[-1],
+                        "stage": approval.stage,
+                        "actor": approval.actor,
+                        "approved_at": _iso(approval.created_at),
+                        "approval_payload": _event_payload(approval),
+                    }
+                ),
+                "action_events": [
+                    {
+                        "event_id": event.id,
+                        "event_type": event.event_type,
+                        "stage": event.stage,
+                        "actor": event.actor,
+                        "created_at": _iso(event.created_at),
+                        "summary": event.summary,
+                        "payload": _event_payload(event),
+                    }
+                    for event in action_events
+                ],
+                "commands": [
+                    _build_command_summary(command) for command in proposal_commands
+                ],
+                "runs": run_refs,
+            }
+        )
+
+    return graph
+
+
 def build_workflow_evidence_export(
     workflow: WorkflowSession,
     events: List[WorkflowEvent],
@@ -91,6 +537,9 @@ def build_workflow_evidence_export(
     stage_progression = _stage_progression(events)
     proposal_summary = _proposal_approval_summary(events)
     timeline = _timeline_snippet(events)
+    proposal_links = _proposal_approval_links(events)
+    status_changes = _user_status_changes(events)
+    proposal_graph = _build_proposal_approval_graph(workflow, events)
 
     return {
         "version": EVIDENCE_EXPORT_VERSION,
@@ -98,5 +547,16 @@ def build_workflow_evidence_export(
         "workflow_stage": workflow.stage,
         "stage_progression_summary": stage_progression,
         "agent_proposal_approval_summary": proposal_summary,
+        "agent_proposal_approval_links": proposal_links,
+        "agent_proposal_approval_graph": proposal_graph,
+        "user_status_changes": status_changes,
+        "model_context": {
+            "model_run_count": _safe_len_relationship(workflow, "model_runs"),
+            "model_version_count": _safe_len_relationship(workflow, "model_versions"),
+            "evaluation_result_count": _safe_len_relationship(
+                workflow, "evaluation_results"
+            ),
+        },
+        "project_memory_summary": _build_project_memory_summary(workflow),
         "key_event_timeline_snippet": timeline,
     }
diff --git a/server_api/workflows/router.py b/server_api/workflows/router.py
index 5bcfe801..15aeb8f1 100644
--- a/server_api/workflows/router.py
+++ b/server_api/workflows/router.py
@@ -1,29 +1,72 @@
 from __future__ import annotations
 
+import json
+import os
+import pathlib
+import re
+import shutil
 from datetime import datetime, timezone
 from typing import Any, Dict, List, Optional
 
+import requests
 from fastapi import APIRouter, Depends, HTTPException
 from pydantic import BaseModel, Field
 from sqlalchemy.orm import Session
 
+from app_event_logger import append_app_event
 from server_api.auth import models as auth_models
 from server_api.auth.database import get_db
-from server_api.auth.router import get_current_user
+from server_api.auth.router import (
+    get_current_user,
+    _looks_like_image_label_pair,
+    _project_extension,
+    _role_for_project_file,
+    _scan_project_profile,
+)
 
-from .db_models import WorkflowEvent, WorkflowSession
+from .db_models import (
+    WorkflowAgentPlan,
+    WorkflowAgentStep,
+    WorkflowArtifact,
+    WorkflowCommand,
+    WorkflowCorrectionSet,
+    WorkflowEvaluationResult,
+    WorkflowEvent,
+    WorkflowModelRun,
+    WorkflowModelVersion,
+    WorkflowRegionHotspot,
+    WorkflowSession,
+    WorkflowVolumeState,
+)
 from .service import (
+    agent_plan_to_dict,
+    agent_step_to_dict,
     append_workflow_event,
+    artifact_to_dict,
+    command_to_dict,
+    correction_set_to_dict,
+    create_workflow_command,
+    create_workflow_session,
+    create_workflow_artifact,
     decode_json,
+    encode_json,
+    evaluation_result_to_dict,
     event_to_dict,
     get_current_or_create_workflow,
     get_user_workflow_or_404,
+    model_run_to_dict,
+    model_version_to_dict,
+    region_hotspot_to_dict,
     update_workflow_fields,
     validate_stage,
+    volume_state_to_dict,
     workflow_to_dict,
 )
-from .bundle_export import build_export_bundle
+from .bundle_export import build_export_bundle, write_export_bundle_directory
+from .agent_plan import build_case_study_plan_graph
+from .evaluation import compute_before_after_evaluation, write_evaluation_report
 from .metrics import compute_workflow_metrics
+from .volume_pairs import discover_neuroglancer_volume_pairs
 
 router = APIRouter()
 
@@ -40,6 +83,7 @@ class WorkflowResponse(BaseModel):
     neuroglancer_url: Optional[str] = None
     inference_output_path: Optional[str] = None
     checkpoint_path: Optional[str] = None
+    config_path: Optional[str] = None
     proofreading_session_id: Optional[int] = None
     corrected_mask_path: Optional[str] = None
     training_output_path: Optional[str] = None
@@ -58,6 +102,8 @@ class WorkflowEventResponse(BaseModel):
     summary: str
     payload_json: Optional[str] = None
     payload: Dict[str, Any] = Field(default_factory=dict)
+    schema_version: int = 1
+    idempotency_key: Optional[str] = None
     approval_status: str
     created_at: Any
 
@@ -77,18 +123,26 @@ class WorkflowUpdateRequest(BaseModel):
     neuroglancer_url: Optional[str] = None
     inference_output_path: Optional[str] = None
     checkpoint_path: Optional[str] = None
+    config_path: Optional[str] = None
     proofreading_session_id: Optional[int] = None
     corrected_mask_path: Optional[str] = None
     training_output_path: Optional[str] = None
     metadata: Optional[Dict[str, Any]] = None
 
 
+class WorkflowResetRequest(BaseModel):
+    title: Optional[str] = None
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+
+
 class WorkflowEventCreateRequest(BaseModel):
     actor: str = "system"
     event_type: str
     stage: Optional[str] = None
     summary: str
     payload: Optional[Dict[str, Any]] = None
+    schema_version: int = 1
+    idempotency_key: Optional[str] = None
     approval_status: str = "not_required"
 
 
@@ -98,13 +152,144 @@ class AgentActionCreateRequest(BaseModel):
     payload: Dict[str, Any] = Field(default_factory=dict)
 
 
+class AgentActionApprovalRequest(BaseModel):
+    overrides: Dict[str, Any] = Field(default_factory=dict)
+
+
 class AgentQueryRequest(BaseModel):
     query: str
+    conversation_id: Optional[int] = None
+    conversationId: Optional[int] = None
+
+
+class AgentChatAction(BaseModel):
+    id: str
+    label: str
+    description: str
+    orchestrator_agent: Dict[str, Any] = Field(default_factory=dict)
+    specialist_agent: Dict[str, Any] = Field(default_factory=dict)
+    agent_type: str = "project_manager"
+    agent_label: str = "Project Manager"
+    agent_color: str = "#111827"
+    agent_icon_key: str = "project"
+    agent_border_style: str = "solid"
+    action_type: str = "workflow_action"
+    card_type: str = "workflow.action_card/v2"
+    target: Optional[str] = None
+    variant: str = "default"
+    run_label: str = "Run in app"
+    risk_level: str = "read_only"
+    risk_tier: str = "R0_view"
+    requires_approval: bool = False
+    approval_reason: Optional[str] = None
+    summary_fields: List[Dict[str, Any]] = Field(default_factory=list)
+    input_artifacts: List[Dict[str, Any]] = Field(default_factory=list)
+    output_artifacts: List[Dict[str, Any]] = Field(default_factory=list)
+    expected_effects: List[str] = Field(default_factory=list)
+    blockers: List[str] = Field(default_factory=list)
+    action_card: Dict[str, Any] = Field(default_factory=dict)
+    disabled_reason: Optional[str] = None
+    client_effects: Dict[str, Any] = Field(default_factory=dict)
+    policy_decision: Optional[Dict[str, Any]] = None
+    blocking_reasons: List[Dict[str, Any]] = Field(default_factory=list)
+    freshness: Dict[str, Any] = Field(default_factory=dict)
+
+
+class AgentCommandBlock(BaseModel):
+    id: str
+    title: str
+    description: str
+    command: str
+    run_label: str = "Execute"
+    risk_level: str = "read_only"
+    requires_approval: bool = False
+    client_effects: Dict[str, Any] = Field(default_factory=dict)
+
+
+class AgentTaskItem(BaseModel):
+    id: str
+    label: str
+    status: str
+    detail: str
+    priority: str = "normal"
+
+
+class AgentTraceItem(BaseModel):
+    label: str
+    detail: str
+    status: str = "checked"
+    category: str = "checked"
+    agent_type: str = "project_manager"
+    agent_label: str = "Project Manager"
+    agent_color: str = "#111827"
+    agent_icon_key: str = "project"
+    agent_border_style: str = "solid"
+    data: Dict[str, Any] = Field(default_factory=dict)
+    evidence_refs: List[Dict[str, Any]] = Field(default_factory=list)
 
 
 class AgentQueryResponse(BaseModel):
     response: str
+    source: str = "workflow_orchestrator"
+    intent: str = "recommendation"
+    permission_mode: str = "approval_required_for_runtime"
+    orchestrator_agent: Dict[str, Any] = Field(default_factory=dict)
+    subagents: List[Dict[str, Any]] = Field(default_factory=list)
+    conversation_id: Optional[int] = None
+    conversationId: Optional[int] = None
     proposals: List[WorkflowEventResponse] = Field(default_factory=list)
+    actions: List[AgentChatAction] = Field(default_factory=list)
+    commands: List[AgentCommandBlock] = Field(default_factory=list)
+    tasks: List[AgentTaskItem] = Field(default_factory=list)
+    policy_decision: Optional[Dict[str, Any]] = None
+    blocking_reasons: List[Dict[str, Any]] = Field(default_factory=list)
+    freshness: Optional[Dict[str, Any]] = None
+    trace_schema_version: str = "agent_trace/v1"
+    trace: List[AgentTraceItem] = Field(default_factory=list)
+
+
+class AgentConversationMessage(BaseModel):
+    id: int
+    workflow_id: Optional[int] = None
+    role: str
+    content: str
+    source: Optional[str] = None
+    actions: List[Dict[str, Any]] = Field(default_factory=list)
+    commands: List[Dict[str, Any]] = Field(default_factory=list)
+    proposals: List[Dict[str, Any]] = Field(default_factory=list)
+    trace: List[Dict[str, Any]] = Field(default_factory=list)
+    created_at: Any
+
+
+class AgentConversationResponse(BaseModel):
+    conversation_id: Optional[int] = None
+    conversationId: Optional[int] = None
+    title: Optional[str] = None
+    messages: List[AgentConversationMessage] = Field(default_factory=list)
+
+
+class WorkflowCommandResponse(BaseModel):
+    id: int
+    workflow_id: int
+    command_type: str
+    status: str
+    idempotency_key: str
+    actor: str
+    source_event_id: Optional[int] = None
+    approval_event_id: Optional[int] = None
+    input_json: Optional[str] = None
+    input: Dict[str, Any] = Field(default_factory=dict)
+    result_json: Optional[str] = None
+    result: Dict[str, Any] = Field(default_factory=dict)
+    error_json: Optional[str] = None
+    error: Dict[str, Any] = Field(default_factory=dict)
+    attempt_count: int = 0
+    lease_owner: Optional[str] = None
+    lease_expires_at: Any = None
+    started_at: Any = None
+    completed_at: Any = None
+    created_at: Any
+    updated_at: Any
 
 
 class AgentActionResult(BaseModel):
@@ -112,6 +297,7 @@ class AgentActionResult(BaseModel):
     proposal: WorkflowEventResponse
     events: List[WorkflowEventResponse]
     client_effects: Dict[str, Any] = Field(default_factory=dict)
+    commands: List[WorkflowCommandResponse] = Field(default_factory=list)
 
 
 class WorkflowHotspotItem(BaseModel):
@@ -143,18 +329,470 @@ class WorkflowImpactPreviewResponse(BaseModel):
     next_actions: List[str] = Field(default_factory=list)
 
 
+class WorkflowReadinessItem(BaseModel):
+    id: str
+    label: str
+    complete: bool
+    detail: str
+    severity: str = "default"
+
+
+class WorkflowAgentRecommendationResponse(BaseModel):
+    workflow_id: int
+    generated_at: str
+    stage: str
+    decision: str
+    rationale: str
+    confidence: str
+    next_stage: str
+    can_act: bool = True
+    blockers: List[str] = Field(default_factory=list)
+    readiness: List[WorkflowReadinessItem] = Field(default_factory=list)
+    top_hotspot: Optional[WorkflowHotspotItem] = None
+    impact_preview: Optional[WorkflowImpactPreviewResponse] = None
+    actions: List[AgentChatAction] = Field(default_factory=list)
+    commands: List[AgentCommandBlock] = Field(default_factory=list)
+
+
+class WorkflowPreflightItem(BaseModel):
+    id: str
+    label: str
+    status: str
+    can_run: bool = False
+    missing: List[str] = Field(default_factory=list)
+    action: str
+    risk_level: str = "normal"
+    policy_decision: Optional[Dict[str, Any]] = None
+    blocking_reasons: List[Dict[str, Any]] = Field(default_factory=list)
+    freshness: Dict[str, Any] = Field(default_factory=dict)
+
+
+class WorkflowPreflightResponse(BaseModel):
+    workflow_id: int
+    generated_at: str
+    overall_status: str
+    summary: str
+    items: List[WorkflowPreflightItem] = Field(default_factory=list)
+
+
 class WorkflowMetricsResponse(BaseModel):
     workflow_id: int
     metrics: Dict[str, Any] = Field(default_factory=dict)
 
 
+class WorkflowProjectProgressVolume(BaseModel):
+    id: str
+    name: str
+    status: str
+    status_label: str
+    legacy_status: Optional[str] = None
+    canonical_status: Optional[str] = None
+    canonical_status_label: Optional[str] = None
+    annotation_state: Optional[str] = None
+    annotation_state_label: Optional[str] = None
+    role_state: Optional[str] = None
+    role_state_label: Optional[str] = None
+    execution_state: Optional[str] = None
+    execution_state_label: Optional[str] = None
+    region_scope: Dict[str, Any] = Field(default_factory=dict)
+    state_schema_version: Optional[str] = None
+    status_source: str
+    volume_state_id: Optional[int] = None
+    project_root: Optional[str] = None
+    volume_set_id: Optional[str] = None
+    volume_set_name: Optional[str] = None
+    image_path: Optional[str] = None
+    segmentation_path: Optional[str] = None
+    segmentation_kind: Optional[str] = None
+    eligible_for_training: bool = False
+    eligible_for_inference: bool = False
+    evidence: List[str] = Field(default_factory=list)
+    note: Optional[str] = None
+
+
+class WorkflowProjectProgressResponse(BaseModel):
+    workflow_id: int
+    generated_at: str
+    project_name: Optional[str] = None
+    project_roots: List[Dict[str, Any]] = Field(default_factory=list)
+    summary: Dict[str, Any] = Field(default_factory=dict)
+    status_definitions: Dict[str, str] = Field(default_factory=dict)
+    composite_state_definitions: Dict[str, Dict[str, str]] = Field(default_factory=dict)
+    volumes: List[WorkflowProjectProgressVolume] = Field(default_factory=list)
+
+
+class WorkflowProjectProgressVolumeUpdate(BaseModel):
+    volume_id: str
+    status: Optional[str] = None
+    note: Optional[str] = None
+
+
+class WorkflowOverviewStage(BaseModel):
+    id: str
+    label: str
+    target_view: str
+    complete: bool = False
+    current: bool = False
+    blocked: bool = False
+    detail: Optional[str] = None
+
+
+class WorkflowOverviewBlocker(BaseModel):
+    id: str
+    label: str
+    detail: str
+    severity: str = "warning"
+    target_view: Optional[str] = None
+
+
+class WorkflowOverviewAction(BaseModel):
+    id: str
+    label: str
+    detail: str
+    target_view: str
+    priority: str = "normal"
+    client_effects: Dict[str, Any] = Field(default_factory=dict)
+
+
+class WorkflowOverviewRun(BaseModel):
+    id: int
+    run_id: Optional[str] = None
+    run_type: str
+    status: str
+    output_path: Optional[str] = None
+    checkpoint_path: Optional[str] = None
+    summary: Optional[str] = None
+    started_at: Any = None
+    completed_at: Any = None
+    updated_at: Any = None
+
+
+class WorkflowOverviewResponse(BaseModel):
+    workflow_id: int
+    generated_at: str
+    project_name: Optional[str] = None
+    workflow_stage: str
+    phase: str
+    phase_label: str
+    phase_reason: str
+    phase_index: int
+    volume_summary: Dict[str, Any] = Field(default_factory=dict)
+    project_progress: Optional[WorkflowProjectProgressResponse] = None
+    stages: List[WorkflowOverviewStage] = Field(default_factory=list)
+    blockers: List[WorkflowOverviewBlocker] = Field(default_factory=list)
+    recommended_next_actions: List[WorkflowOverviewAction] = Field(default_factory=list)
+    active_runs: List[WorkflowOverviewRun] = Field(default_factory=list)
+    recent_events: List[WorkflowEventResponse] = Field(default_factory=list)
+
+
+class WorkflowVolumeStateResponse(BaseModel):
+    id: int
+    workflow_id: int
+    volume_id: str
+    name: Optional[str] = None
+    status: str
+    status_label: str
+    legacy_status: Optional[str] = None
+    canonical_status: Optional[str] = None
+    canonical_status_label: Optional[str] = None
+    annotation_state: Optional[str] = None
+    annotation_state_label: Optional[str] = None
+    role_state: Optional[str] = None
+    role_state_label: Optional[str] = None
+    execution_state: Optional[str] = None
+    execution_state_label: Optional[str] = None
+    region_scope: Dict[str, Any] = Field(default_factory=dict)
+    state_schema_version: Optional[str] = None
+    status_source: str
+    status_confidence: Optional[float] = None
+    project_root: Optional[str] = None
+    volume_set_id: Optional[str] = None
+    volume_set_name: Optional[str] = None
+    image_path: Optional[str] = None
+    label_path: Optional[str] = None
+    prediction_path: Optional[str] = None
+    corrected_mask_path: Optional[str] = None
+    eligible_for_training: bool = False
+    eligible_for_inference: bool = False
+    note: Optional[str] = None
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+    created_at: Any
+    updated_at: Any
+
+
+class WorkflowVolumeStateListResponse(BaseModel):
+    workflow_id: int
+    generated_at: str
+    summary: Dict[str, Any] = Field(default_factory=dict)
+    volumes: List[WorkflowVolumeStateResponse] = Field(default_factory=list)
+
+
+class WorkflowVolumeStateUpdateRequest(BaseModel):
+    volume_id: str
+    status: Optional[str] = None
+    annotation_state: Optional[str] = None
+    role_state: Optional[str] = None
+    execution_state: Optional[str] = None
+    region_scope: Optional[Dict[str, Any]] = None
+    note: Optional[str] = None
+    image_path: Optional[str] = None
+    label_path: Optional[str] = None
+    prediction_path: Optional[str] = None
+    corrected_mask_path: Optional[str] = None
+    eligible_for_training: Optional[bool] = None
+    eligible_for_inference: Optional[bool] = None
+    metadata: Optional[Dict[str, Any]] = None
+
+
 class WorkflowExportBundleResponse(BaseModel):
     schema_version: str
     exported_at: str
     workflow_id: int
     session_snapshot: Dict[str, Any] = Field(default_factory=dict)
     events: List[Dict[str, Any]] = Field(default_factory=list)
+    artifacts: List[Dict[str, Any]] = Field(default_factory=list)
+    model_runs: List[Dict[str, Any]] = Field(default_factory=list)
+    model_versions: List[Dict[str, Any]] = Field(default_factory=list)
+    correction_sets: List[Dict[str, Any]] = Field(default_factory=list)
+    evaluation_results: List[Dict[str, Any]] = Field(default_factory=list)
+    persisted_hotspots: List[Dict[str, Any]] = Field(default_factory=list)
+    volume_states: List[Dict[str, Any]] = Field(default_factory=list)
+    project_memory: Dict[str, Any] = Field(default_factory=dict)
+    project_memory_summary: Dict[str, Any] = Field(default_factory=dict)
+    agent_plans: List[Dict[str, Any]] = Field(default_factory=list)
+    agent_messages: List[Dict[str, Any]] = Field(default_factory=list)
+    action_card_index: List[Dict[str, Any]] = Field(default_factory=list)
+    trace_index: List[Dict[str, Any]] = Field(default_factory=list)
     artifact_paths: List[Dict[str, Any]] = Field(default_factory=list)
+    copy_settings: Dict[str, Any] = Field(default_factory=dict)
+    bundle_directory: Optional[str] = None
+    bundle_manifest_path: Optional[str] = None
+    copied_artifacts: List[Dict[str, Any]] = Field(default_factory=list)
+    skipped_artifacts: List[Dict[str, Any]] = Field(default_factory=list)
+
+
+class WorkflowArtifactCreateRequest(BaseModel):
+    artifact_type: str
+    role: Optional[str] = None
+    path: Optional[str] = None
+    uri: Optional[str] = None
+    name: Optional[str] = None
+    checksum: Optional[str] = None
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+
+
+class WorkflowArtifactResponse(BaseModel):
+    id: int
+    workflow_id: int
+    artifact_type: str
+    role: Optional[str] = None
+    name: Optional[str] = None
+    path: Optional[str] = None
+    uri: Optional[str] = None
+    checksum: Optional[str] = None
+    size_bytes: Optional[int] = None
+    source_event_id: Optional[int] = None
+    metadata_json: Optional[str] = None
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+    created_at: Any
+    exists: bool = False
+
+
+class WorkflowModelRunCreateRequest(BaseModel):
+    run_id: Optional[str] = None
+    run_type: str
+    status: str = "pending"
+    name: Optional[str] = None
+    config_path: Optional[str] = None
+    log_path: Optional[str] = None
+    output_path: Optional[str] = None
+    checkpoint_path: Optional[str] = None
+    input_artifact_id: Optional[int] = None
+    output_artifact_id: Optional[int] = None
+    metrics: Dict[str, Any] = Field(default_factory=dict)
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+
+
+class WorkflowModelRunResponse(BaseModel):
+    id: int
+    workflow_id: int
+    run_id: Optional[str] = None
+    run_type: str
+    status: str
+    name: Optional[str] = None
+    config_path: Optional[str] = None
+    log_path: Optional[str] = None
+    output_path: Optional[str] = None
+    checkpoint_path: Optional[str] = None
+    input_artifact_id: Optional[int] = None
+    output_artifact_id: Optional[int] = None
+    source_event_id: Optional[int] = None
+    metrics_json: Optional[str] = None
+    metrics: Dict[str, Any] = Field(default_factory=dict)
+    metadata_json: Optional[str] = None
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+    started_at: Any = None
+    completed_at: Any = None
+    created_at: Any
+    updated_at: Any
+
+
+class WorkflowModelVersionCreateRequest(BaseModel):
+    version_label: str
+    status: str = "candidate"
+    checkpoint_path: Optional[str] = None
+    training_run_id: Optional[int] = None
+    checkpoint_artifact_id: Optional[int] = None
+    correction_set_id: Optional[int] = None
+    metrics: Dict[str, Any] = Field(default_factory=dict)
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+
+
+class WorkflowModelVersionResponse(BaseModel):
+    id: int
+    workflow_id: int
+    version_label: str
+    status: str
+    checkpoint_path: Optional[str] = None
+    training_run_id: Optional[int] = None
+    checkpoint_artifact_id: Optional[int] = None
+    correction_set_id: Optional[int] = None
+    metrics_json: Optional[str] = None
+    metrics: Dict[str, Any] = Field(default_factory=dict)
+    metadata_json: Optional[str] = None
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+    created_at: Any
+
+
+class WorkflowCorrectionSetResponse(BaseModel):
+    id: int
+    workflow_id: int
+    artifact_id: Optional[int] = None
+    corrected_mask_path: str
+    source_mask_path: Optional[str] = None
+    proofreading_session_id: Optional[int] = None
+    edit_count: int = 0
+    region_count: int = 0
+    source_event_id: Optional[int] = None
+    metadata_json: Optional[str] = None
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+    created_at: Any
+
+
+class WorkflowEvaluationCreateRequest(BaseModel):
+    name: Optional[str] = None
+    baseline_run_id: Optional[int] = None
+    candidate_run_id: Optional[int] = None
+    model_version_id: Optional[int] = None
+    report_path: Optional[str] = None
+    summary: Optional[str] = None
+    metrics: Dict[str, Any] = Field(default_factory=dict)
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+
+
+class WorkflowEvaluationComputeRequest(BaseModel):
+    baseline_prediction_path: str
+    candidate_prediction_path: str
+    ground_truth_path: str
+    baseline_dataset: Optional[str] = None
+    candidate_dataset: Optional[str] = None
+    ground_truth_dataset: Optional[str] = None
+    crop: Optional[str] = None
+    baseline_channel: Optional[int] = None
+    candidate_channel: Optional[int] = None
+    ground_truth_channel: Optional[int] = None
+    name: Optional[str] = None
+    baseline_run_id: Optional[int] = None
+    candidate_run_id: Optional[int] = None
+    model_version_id: Optional[int] = None
+    report_path: Optional[str] = None
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+
+
+class WorkflowEvaluationResponse(BaseModel):
+    id: int
+    workflow_id: int
+    name: Optional[str] = None
+    baseline_run_id: Optional[int] = None
+    candidate_run_id: Optional[int] = None
+    model_version_id: Optional[int] = None
+    report_artifact_id: Optional[int] = None
+    report_path: Optional[str] = None
+    summary: Optional[str] = None
+    metrics_json: Optional[str] = None
+    metrics: Dict[str, Any] = Field(default_factory=dict)
+    metadata_json: Optional[str] = None
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+    created_at: Any
+
+
+class WorkflowRegionHotspotResponse(BaseModel):
+    id: int
+    workflow_id: int
+    region_key: str
+    score: float
+    severity: str
+    status: str
+    source: str
+    evidence_json: Optional[str] = None
+    evidence: Dict[str, Any] = Field(default_factory=dict)
+    created_at: Any
+    updated_at: Any
+
+
+class WorkflowAgentStepResponse(BaseModel):
+    id: int
+    plan_id: int
+    step_index: int
+    action: str
+    status: str
+    requires_approval: bool
+    summary: Optional[str] = None
+    params_json: Optional[str] = None
+    params: Dict[str, Any] = Field(default_factory=dict)
+    result_json: Optional[str] = None
+    result: Dict[str, Any] = Field(default_factory=dict)
+    created_at: Any
+    updated_at: Any
+
+
+class WorkflowAgentPlanResponse(BaseModel):
+    id: int
+    workflow_id: int
+    title: str
+    status: str
+    risk_level: str
+    approval_status: str
+    goal: Optional[str] = None
+    graph_json: Optional[str] = None
+    graph: Dict[str, Any] = Field(default_factory=dict)
+    metadata_json: Optional[str] = None
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+    source_event_id: Optional[int] = None
+    created_at: Any
+    updated_at: Any
+    steps: List[WorkflowAgentStepResponse] = Field(default_factory=list)
+
+
+class WorkflowAgentPlanCreateRequest(BaseModel):
+    title: Optional[str] = None
+    goal: Optional[str] = None
+    plan_type: str = "case_study_closed_loop"
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+
+
+class WorkflowAgentStepCompleteRequest(BaseModel):
+    status: str = "completed"
+    result: Dict[str, Any] = Field(default_factory=dict)
+
+
+class WorkflowReadinessResponse(BaseModel):
+    workflow_id: int
+    ready_for_case_study: bool
+    completed_count: int
+    total_count: int
+    gates: List[Dict[str, Any]] = Field(default_factory=list)
+    next_required_items: List[str] = Field(default_factory=list)
 
 
 def _workflow_response(workflow: WorkflowSession) -> WorkflowResponse:
@@ -165,6 +803,50 @@ def _event_response(event: WorkflowEvent) -> WorkflowEventResponse:
     return WorkflowEventResponse(**event_to_dict(event))
 
 
+def _artifact_response(artifact: WorkflowArtifact) -> WorkflowArtifactResponse:
+    return WorkflowArtifactResponse(**artifact_to_dict(artifact))
+
+
+def _model_run_response(run: WorkflowModelRun) -> WorkflowModelRunResponse:
+    return WorkflowModelRunResponse(**model_run_to_dict(run))
+
+
+def _model_version_response(
+    version: WorkflowModelVersion,
+) -> WorkflowModelVersionResponse:
+    return WorkflowModelVersionResponse(**model_version_to_dict(version))
+
+
+def _correction_set_response(
+    correction_set: WorkflowCorrectionSet,
+) -> WorkflowCorrectionSetResponse:
+    return WorkflowCorrectionSetResponse(**correction_set_to_dict(correction_set))
+
+
+def _evaluation_response(
+    result: WorkflowEvaluationResult,
+) -> WorkflowEvaluationResponse:
+    return WorkflowEvaluationResponse(**evaluation_result_to_dict(result))
+
+
+def _region_hotspot_response(
+    hotspot: WorkflowRegionHotspot,
+) -> WorkflowRegionHotspotResponse:
+    return WorkflowRegionHotspotResponse(**region_hotspot_to_dict(hotspot))
+
+
+def _agent_step_response(step: WorkflowAgentStep) -> WorkflowAgentStepResponse:
+    return WorkflowAgentStepResponse(**agent_step_to_dict(step))
+
+
+def _agent_plan_response(plan: WorkflowAgentPlan) -> WorkflowAgentPlanResponse:
+    return WorkflowAgentPlanResponse(**agent_plan_to_dict(plan))
+
+
+def _command_response(command: WorkflowCommand) -> WorkflowCommandResponse:
+    return WorkflowCommandResponse(**command_to_dict(command))
+
+
 def _event_list(db: Session, workflow_id: int) -> List[WorkflowEventResponse]:
     events = (
         db.query(WorkflowEvent)
@@ -203,6 +885,38 @@ def _get_pending_proposal_or_404(
     return event
 
 
+def _get_agent_plan_or_404(
+    db: Session, *, workflow_id: int, plan_id: int
+) -> WorkflowAgentPlan:
+    plan = (
+        db.query(WorkflowAgentPlan)
+        .filter(
+            WorkflowAgentPlan.id == plan_id,
+            WorkflowAgentPlan.workflow_id == workflow_id,
+        )
+        .first()
+    )
+    if not plan:
+        raise HTTPException(status_code=404, detail="Agent plan not found")
+    return plan
+
+
+def _get_agent_step_or_404(
+    db: Session, *, plan_id: int, step_id: int
+) -> WorkflowAgentStep:
+    step = (
+        db.query(WorkflowAgentStep)
+        .filter(
+            WorkflowAgentStep.id == step_id,
+            WorkflowAgentStep.plan_id == plan_id,
+        )
+        .first()
+    )
+    if not step:
+        raise HTTPException(status_code=404, detail="Agent plan step not found")
+    return step
+
+
 def _latest_exported_mask_path(db: Session, workflow_id: int) -> Optional[str]:
     event = (
         db.query(WorkflowEvent)
@@ -272,12 +986,12 @@ def _hotspot_severity(score: float) -> str:
 
 def _default_region_action(workflow: WorkflowSession, severity: str) -> str:
     if workflow.stage == "proofreading":
-        return "Open this region in proofreading and apply mask corrections."
+        return "Proofread this likely mistake."
     if severity == "high":
-        return "Prioritize this region for proofreading before the next training iteration."
+        return "Proofread this region before training again."
     if workflow.stage in {"visualization", "inference"}:
-        return "Inspect this region in visualization and route it into proofreading."
-    return "Inspect this region and log whether model output is acceptable."
+        return "Inspect this region, then proofread it if the mask looks wrong."
+    return "Check this region and mark whether the mask is usable."
 
 
 def _compute_hotspots(
@@ -365,9 +1079,7 @@ def ensure_region(region_key: str) -> Dict[str, Any]:
         )
         recommended_action = _default_region_action(workflow, severity)
         if stat["exports"] > 0 and workflow.stage != "retraining_staged":
-            recommended_action = (
-                "Corrections already exist; stage this region's masks for retraining."
-            )
+            recommended_action = "Use these saved edits for training."
 
         ranked.append(
             WorkflowHotspotItem(
@@ -393,6 +1105,46 @@ def ensure_region(region_key: str) -> Dict[str, Any]:
     ]
 
 
+def _persist_computed_hotspots(
+    db: Session,
+    *,
+    workflow_id: int,
+    hotspots: List[WorkflowHotspotItem],
+) -> None:
+    for item in hotspots:
+        existing = (
+            db.query(WorkflowRegionHotspot)
+            .filter(
+                WorkflowRegionHotspot.workflow_id == workflow_id,
+                WorkflowRegionHotspot.region_key == item.region_key,
+            )
+            .first()
+        )
+        evidence = {
+            **(item.evidence or {}),
+            "summary": item.summary,
+            "recommended_action": item.recommended_action,
+            "rank": item.rank,
+        }
+        if existing:
+            existing.score = item.score
+            existing.severity = item.severity
+            existing.evidence_json = encode_json(evidence)
+            existing.source = "event_heuristic"
+        else:
+            db.add(
+                WorkflowRegionHotspot(
+                    workflow_id=workflow_id,
+                    region_key=item.region_key,
+                    score=item.score,
+                    severity=item.severity,
+                    evidence_json=encode_json(evidence),
+                    source="event_heuristic",
+                )
+            )
+    db.commit()
+
+
 def _compute_impact_preview(
     workflow: WorkflowSession,
     events: List[WorkflowEvent],
@@ -403,6 +1155,8 @@ def _compute_impact_preview(
         "inference_started": 0,
         "inference_completed": 0,
         "inference_failed": 0,
+        "training_completed": 0,
+        "training_failed": 0,
         "proofreading_classified": 0,
         "proofreading_mask_saved": 0,
         "proofreading_masks_exported": 0,
@@ -415,6 +1169,10 @@ def _compute_impact_preview(
             signals["inference_completed"] += 1
         if event.event_type == "inference.failed":
             signals["inference_failed"] += 1
+        if event.event_type == "training.completed":
+            signals["training_completed"] += 1
+        if event.event_type == "training.failed":
+            signals["training_failed"] += 1
         if event.event_type == "proofreading.instance_classified":
             signals["proofreading_classified"] += 1
         if event.event_type == "proofreading.mask_saved":
@@ -468,24 +1226,31 @@ def _compute_impact_preview(
             "Export corrected masks from proofreading to create a retraining artifact."
         )
     elif can_stage_retraining:
-        next_actions.append("Approve or trigger retraining staging from corrected masks.")
+        next_actions.append(
+            "Approve or trigger retraining staging from corrected masks."
+        )
     if workflow.stage == "retraining_staged":
         next_actions.append(
             "Open Model Training and launch the next experiment using staged labels."
         )
-
-    if confidence == "low":
-        summary = (
-            "Correction evidence is still sparse; prioritize proofreading edits before retraining."
+    if workflow.stage == "evaluation":
+        next_actions.append(
+            "Run inference with the latest trained checkpoint to evaluate the new model iteration."
         )
-    elif can_stage_retraining:
-        summary = (
-            "Corrections are substantial enough to justify retraining staging for the next model iteration."
+        next_actions.append(
+            "Open TensorBoard if you want to inspect the completed training run before inference."
         )
+
+    if workflow.stage == "evaluation" and signals["training_completed"] > 0:
+        summary = "A new model iteration is ready. Run inference with the latest checkpoint and compare it against the prior result."
+    elif workflow.stage == "evaluation" and signals["training_failed"] > 0:
+        summary = "The last training run failed. Review the runtime log before launching another iteration."
+    elif confidence == "low":
+        summary = "Correction evidence is still sparse; prioritize proofreading edits before retraining."
+    elif can_stage_retraining:
+        summary = "Corrections are substantial enough to justify retraining staging for the next model iteration."
     else:
-        summary = (
-            "Correction evidence is accumulating; compare outcomes after the next staged loop."
-        )
+        summary = "Correction evidence is accumulating; compare outcomes after the next staged loop."
 
     return WorkflowImpactPreviewResponse(
         workflow_id=workflow.id,
@@ -508,102 +1273,7526 @@ def _recommendation_for_workflow(
     if workflow.stage == "setup":
         return "Start by loading an image volume and, if available, the current mask or label volume."
     if workflow.stage == "visualization":
-        return "The next useful step is to run inference or open proofreading on the current result."
+        return "Proofread the mask if it is ready; otherwise run the model to make one."
     if workflow.stage == "inference":
-        return "Review the inference output and send likely failure regions into proofreading."
+        return "Run the model, then proofread the result."
     if workflow.stage == "proofreading":
         has_export = any(
             event.event_type == "proofreading.masks_exported" for event in events
         )
         if has_export or workflow.corrected_mask_path:
-            return "Corrected masks are available. Stage them for retraining so the next model iteration is linked to the edits."
-        return "Continue classifying instances and save or export corrected masks before retraining."
+            return "Saved edits are available. Ask the agent to train from them."
+        return "Keep reviewing instances, then save or export edits before training."
     if workflow.stage == "retraining_staged":
-        return "The corrected masks are staged. Review the training configuration before launching retraining."
+        return "The saved edits are linked. Approve an agent-run training job."
+    if workflow.stage == "evaluation":
+        return "Training finished successfully. Use the latest checkpoint to run inference, and open TensorBoard only if you want to inspect the run."
     return "Review the workflow timeline and compare results before starting another iteration."
 
 
-@router.get("/current", response_model=WorkflowDetailResponse)
-def get_current_workflow(
-    user: auth_models.User = Depends(get_current_user),
-    db: Session = Depends(get_db),
-):
-    workflow = get_current_or_create_workflow(db, user_id=user.id)
-    return {
-        "workflow": _workflow_response(workflow),
-        "events": _event_list(db, workflow.id),
-    }
+def _client_effects_to_command(client_effects: Dict[str, Any]) -> str:
+    lines: List[str] = []
+    if client_effects.get("reset_workspace"):
+        lines.append("app workspace reset")
 
+    if client_effects.get("start_new_workflow"):
+        lines.append("workflow reset current session")
 
-@router.patch("/{workflow_id}", response_model=WorkflowResponse)
-async def update_workflow(
+    mount_project = client_effects.get("mount_project") or {}
+    if mount_project.get("directory_path"):
+        lines.append(
+            "app files mount " f"{json.dumps(str(mount_project.get('directory_path')))}"
+        )
+
+    navigate_to = client_effects.get("navigate_to")
+    if navigate_to:
+        lines.append(f"app open {navigate_to}")
+
+    training_config_preset = client_effects.get("set_training_config_preset")
+    if training_config_preset:
+        lines.append(
+            f"app training config auto-select {json.dumps(str(training_config_preset))}"
+        )
+
+    training_image_path = client_effects.get("set_training_image_path")
+    if training_image_path:
+        lines.append(f"app training image set {json.dumps(str(training_image_path))}")
+
+    training_label_path = client_effects.get("set_training_label_path")
+    if training_label_path:
+        lines.append(f"app training labels set {json.dumps(str(training_label_path))}")
+
+    training_output_path = client_effects.get("set_training_output_path")
+    if training_output_path:
+        lines.append(f"app training output set {json.dumps(str(training_output_path))}")
+
+    training_log_path = client_effects.get("set_training_log_path")
+    if training_log_path:
+        lines.append(f"app training logs set {json.dumps(str(training_log_path))}")
+
+    inference_output_path = client_effects.get("set_inference_output_path")
+    if inference_output_path:
+        lines.append(
+            f"app inference output set {json.dumps(str(inference_output_path))}"
+        )
+
+    inference_checkpoint_path = client_effects.get("set_inference_checkpoint_path")
+    if inference_checkpoint_path:
+        lines.append(
+            f"app inference checkpoint set {json.dumps(str(inference_checkpoint_path))}"
+        )
+
+    inference_config_preset = client_effects.get("set_inference_config_preset")
+    if inference_config_preset:
+        lines.append(
+            f"app inference config auto-select {json.dumps(str(inference_config_preset))}"
+        )
+
+    inference_image_path = client_effects.get("set_inference_image_path")
+    if inference_image_path:
+        lines.append(f"app inference image set {json.dumps(str(inference_image_path))}")
+
+    inference_label_path = client_effects.get("set_inference_label_path")
+    if inference_label_path:
+        lines.append(
+            f"app inference labels set {json.dumps(str(inference_label_path))}"
+        )
+
+    runtime_action = client_effects.get("runtime_action") or {}
+    runtime_kind = runtime_action.get("kind")
+    if runtime_kind == "start_inference":
+        lines.append("app inference run")
+    elif runtime_kind == "start_training":
+        lines.append("app training run")
+    elif runtime_kind == "start_proofreading":
+        lines.append("app proofreading start")
+    elif runtime_kind == "stop_inference":
+        lines.append("app inference stop")
+    elif runtime_kind == "stop_training":
+        lines.append("app training stop")
+
+    workflow_action = client_effects.get("workflow_action") or {}
+    workflow_action_kind = workflow_action.get("kind")
+    if workflow_action_kind == "compute_evaluation":
+        lines.append("workflow metrics compute")
+    elif workflow_action_kind == "export_bundle":
+        lines.append("workflow evidence export")
+    elif workflow_action_kind == "propose_retraining_stage":
+        lines.append("workflow retraining handoff propose")
+
+    if client_effects.get("show_workflow_context"):
+        lines.append("assistant status show")
+
+    if client_effects.get("refresh_insights"):
+        lines.append("workflow insights refresh")
+
+    return "\n".join(lines) or "# No app command is available for this action."
+
+
+def _infer_action_risk(client_effects: Optional[Dict[str, Any]]) -> str:
+    effects = client_effects or {}
+    runtime_kind = (effects.get("runtime_action") or {}).get("kind")
+    workflow_action_kind = (effects.get("workflow_action") or {}).get("kind")
+    if runtime_kind in {"start_inference", "start_training"}:
+        return "runs_job"
+    if runtime_kind in {"stop_inference", "stop_training"}:
+        return "controls_job"
+    if runtime_kind == "start_proofreading":
+        return "loads_editor"
+    if runtime_kind == "choose_project_data":
+        return "prefills_form"
+    if effects.get("mount_project") or effects.get("reset_workspace"):
+        return "modifies_workspace"
+    if effects.get("start_new_workflow"):
+        return "writes_workflow_record"
+    if workflow_action_kind == "export_bundle":
+        return "exports_evidence"
+    if workflow_action_kind in {"compute_evaluation", "propose_retraining_stage"}:
+        return "writes_workflow_record"
+    if any(key.startswith("set_") for key in effects):
+        return "prefills_form"
+    if effects.get("navigate_to") or effects.get("show_workflow_context"):
+        return "read_only"
+    if effects.get("refresh_insights"):
+        return "read_only"
+    return "read_only"
+
+
+def _requires_action_approval(client_effects: Optional[Dict[str, Any]]) -> bool:
+    risk = _infer_action_risk(client_effects)
+    return risk in {
+        "runs_job",
+        "controls_job",
+        "loads_editor",
+        "exports_evidence",
+        "writes_workflow_record",
+        "modifies_workspace",
+    }
+
+
+def _action_risk_tier(risk_level: str) -> str:
+    return {
+        "read_only": "R0_view",
+        "prefills_form": "R1_prefill",
+        "loads_editor": "R2_manual_handoff",
+        "writes_workflow_record": "R3_workflow_write",
+        "modifies_workspace": "R3_workflow_write",
+        "runs_job": "R4_runtime_job",
+        "controls_job": "R4_runtime_job",
+        "exports_evidence": "R5_export_or_workspace",
+    }.get(risk_level, "R0_view")
+
+
+ORCHESTRATOR_AGENT = {
+    "type": "project_manager",
+    "label": "Project Manager",
+    "short_label": "PM",
+    "color": "#111827",
+    "icon_key": "project",
+    "border_style": "solid",
+    "role": "Keeps project memory coherent, routes work to specialists, and gates risky actions.",
+}
+
+WORKFLOW_SUBAGENTS = {
+    "project_manager": ORCHESTRATOR_AGENT,
+    "data_agent": {
+        "type": "data_agent",
+        "label": "Data Scout",
+        "short_label": "Data",
+        "color": "#00843D",
+        "icon_key": "folder",
+        "border_style": "dotted",
+        "role": "Inspects mounted folders, pairs image/label artifacts, and refreshes project context.",
+    },
+    "visualization_agent": {
+        "type": "visualization_agent",
+        "label": "Visualization Agent",
+        "short_label": "Vis",
+        "color": "#0057B8",
+        "icon_key": "eye",
+        "border_style": "double",
+        "role": "Opens volumes, validates viewer paths, and checks spatial context.",
+    },
+    "proofreading_agent": {
+        "type": "proofreading_agent",
+        "label": "Proofreading Agent",
+        "short_label": "Proof",
+        "color": "#E0007A",
+        "icon_key": "bug",
+        "border_style": "dashed",
+        "role": "Queues draft masks and tracks review-to-ground-truth promotion.",
+    },
+    "training_agent": {
+        "type": "training_agent",
+        "label": "Training Agent",
+        "short_label": "Train",
+        "color": "#7B2CBF",
+        "icon_key": "experiment",
+        "border_style": "thick",
+        "role": "Builds trainable subsets, stages configs, and launches approved training jobs.",
+    },
+    "inference_agent": {
+        "type": "inference_agent",
+        "label": "Inference Agent",
+        "short_label": "Infer",
+        "color": "#D55E00",
+        "icon_key": "thunderbolt",
+        "border_style": "dashdot",
+        "role": "Runs checkpoints over image-only or selected target volumes.",
+    },
+    "evaluation_agent": {
+        "type": "evaluation_agent",
+        "label": "Evaluation Agent",
+        "short_label": "Eval",
+        "color": "#B58900",
+        "icon_key": "bar_chart",
+        "border_style": "top",
+        "role": "Compares predictions, metrics, and case-study evidence.",
+    },
+    "evidence_agent": {
+        "type": "evidence_agent",
+        "label": "Evidence Agent",
+        "short_label": "Evidence",
+        "color": "#00A6A6",
+        "icon_key": "file_done",
+        "border_style": "rail",
+        "role": "Exports provenance bundles and preserves action traces.",
+    },
+}
+
+
+def _agent_descriptor(agent_type: Optional[str]) -> Dict[str, Any]:
+    return dict(WORKFLOW_SUBAGENTS.get(str(agent_type or ""), ORCHESTRATOR_AGENT))
+
+
+def _agent_trace_kwargs(agent: Dict[str, Any]) -> Dict[str, str]:
+    return {
+        "agent_type": str(agent.get("type") or ORCHESTRATOR_AGENT["type"]),
+        "agent_label": str(agent.get("label") or ORCHESTRATOR_AGENT["label"]),
+        "agent_color": str(agent.get("color") or ORCHESTRATOR_AGENT["color"]),
+        "agent_icon_key": str(agent.get("icon_key") or ORCHESTRATOR_AGENT["icon_key"]),
+        "agent_border_style": str(
+            agent.get("border_style") or ORCHESTRATOR_AGENT["border_style"]
+        ),
+    }
+
+
+def _specialist_agent_for_action(
+    action_type: str, client_effects: Dict[str, Any]
+) -> Dict[str, Any]:
+    navigate_to = str((client_effects or {}).get("navigate_to") or "")
+    if action_type in {"start_training", "open_training"} or "training" in navigate_to:
+        return _agent_descriptor("training_agent")
+    if (
+        action_type in {"start_inference", "open_inference"}
+        or "inference" in navigate_to
+    ):
+        return _agent_descriptor("inference_agent")
+    if action_type in {"start_proofreading"} or "proofreading" in navigate_to:
+        return _agent_descriptor("proofreading_agent")
+    if "visualization" in navigate_to or action_type.startswith("open_visualization"):
+        return _agent_descriptor("visualization_agent")
+    if action_type in {"export_bundle"}:
+        return _agent_descriptor("evidence_agent")
+    if action_type in {"compute_evaluation"}:
+        return _agent_descriptor("evaluation_agent")
+    if (
+        action_type in {"mount_project", "choose_project_data"}
+        or navigate_to == "files"
+    ):
+        return _agent_descriptor("data_agent")
+    if action_type in {
+        "show_workflow_context",
+        "refresh_context",
+        "open_project-progress",
+    }:
+        return _agent_descriptor("project_manager")
+    return _agent_descriptor("project_manager")
+
+
+def _action_type_from_effects(
+    action_id: str,
+    client_effects: Optional[Dict[str, Any]],
+) -> str:
+    effects = client_effects or {}
+    runtime_kind = (effects.get("runtime_action") or {}).get("kind")
+    workflow_kind = (effects.get("workflow_action") or {}).get("kind")
+    if runtime_kind:
+        return str(runtime_kind)
+    if workflow_kind:
+        return str(workflow_kind)
+    if effects.get("mount_project"):
+        return "mount_project"
+    if effects.get("start_new_workflow"):
+        return "start_new_workflow"
+    if effects.get("show_workflow_context"):
+        return "show_workflow_context"
+    if effects.get("refresh_insights"):
+        return "refresh_context"
+    if effects.get("navigate_to"):
+        return f"open_{effects.get('navigate_to')}"
+    return action_id
+
+
+def _action_target_from_effects(
+    client_effects: Optional[Dict[str, Any]],
+) -> Optional[str]:
+    effects = client_effects or {}
+    runtime_action = effects.get("runtime_action") or {}
+    workflow_action = effects.get("workflow_action") or {}
+    for key in [
+        "set_training_image_path",
+        "set_training_label_path",
+        "set_inference_image_path",
+        "set_inference_label_path",
+        "set_visualization_image_path",
+        "set_visualization_label_path",
+        "set_proofreading_image_path",
+        "set_proofreading_label_path",
+    ]:
+        if effects.get(key):
+            return str(effects[key])
+    for source in [runtime_action, workflow_action, effects.get("mount_project") or {}]:
+        if isinstance(source, dict):
+            for key in ["image_path", "label_path", "corrected_mask_path", "path"]:
+                if source.get(key):
+                    return str(source[key])
+    return str(effects.get("navigate_to")) if effects.get("navigate_to") else None
+
+
+def _artifact_entries_from_effects(
+    client_effects: Optional[Dict[str, Any]],
+    *,
+    direction: str,
+) -> List[Dict[str, Any]]:
+    effects = client_effects or {}
+    input_keys = {
+        "set_training_config_preset": "config",
+        "set_training_image_path": "image",
+        "set_training_label_path": "label",
+        "set_inference_config_preset": "config",
+        "set_inference_checkpoint_path": "checkpoint",
+        "set_inference_image_path": "image",
+        "set_inference_label_path": "label",
+        "set_visualization_image_path": "image",
+        "set_visualization_label_path": "label",
+        "set_proofreading_image_path": "image",
+        "set_proofreading_label_path": "label",
+    }
+    output_keys = {
+        "set_training_output_path": "training_output",
+        "set_training_log_path": "training_log",
+        "set_inference_output_path": "prediction",
+    }
+    key_map = input_keys if direction == "input" else output_keys
+    entries = [
+        {"role": role, "path": str(value)}
+        for key, role in key_map.items()
+        for value in [effects.get(key)]
+        if value
+    ]
+    subset = effects.get("training_volume_subset")
+    if direction == "input" and isinstance(subset, dict):
+        manifest_path = subset.get("manifest_path")
+        if manifest_path:
+            entries.append(
+                {"role": "training_subset_manifest", "path": str(manifest_path)}
+            )
+    return entries
+
+
+def _summary_fields_from_effects(
+    client_effects: Optional[Dict[str, Any]],
+) -> List[Dict[str, Any]]:
+    effects = client_effects or {}
+    fields: List[Dict[str, Any]] = []
+    for key, label in [
+        ("navigate_to", "Opens"),
+        ("set_training_config_preset", "Config"),
+        ("set_training_image_path", "Images"),
+        ("set_training_label_path", "Labels"),
+        ("set_training_output_path", "Output"),
+        ("set_inference_checkpoint_path", "Checkpoint"),
+        ("set_inference_image_path", "Images"),
+        ("set_inference_output_path", "Output"),
+    ]:
+        if effects.get(key):
+            fields.append({"label": label, "value": str(effects[key])})
+    subset = effects.get("training_volume_subset")
+    if isinstance(subset, dict):
+        fields.extend(
+            [
+                {
+                    "label": "Training set",
+                    "value": f"{subset.get('train_volume_count', 0)} trusted volume(s)",
+                },
+                {
+                    "label": "Targets after training",
+                    "value": f"{subset.get('target_volume_count', 0)} image-only volume(s)",
+                },
+                {
+                    "label": "Left out",
+                    "value": f"{subset.get('review_volume_count', 0)} draft mask(s)",
+                },
+            ]
+        )
+    return fields
+
+
+def _expected_effects_from_client_effects(
+    client_effects: Optional[Dict[str, Any]],
+) -> List[str]:
+    effects = client_effects or {}
+    expected: List[str] = []
+    if effects.get("navigate_to"):
+        expected.append(f"Open the {effects['navigate_to']} view.")
+    if any(key.startswith("set_training_") for key in effects):
+        expected.append("Prefill the training form from project memory.")
+    if any(key.startswith("set_inference_") for key in effects):
+        expected.append("Prefill the inference form from project memory.")
+    runtime_kind = (effects.get("runtime_action") or {}).get("kind")
+    if runtime_kind == "start_training":
+        expected.append("Launch a training process after approval.")
+    elif runtime_kind == "start_inference":
+        expected.append("Launch an inference process after approval.")
+    elif runtime_kind == "start_proofreading":
+        expected.append("Open a proofreading session.")
+    workflow_kind = (effects.get("workflow_action") or {}).get("kind")
+    if workflow_kind == "export_bundle":
+        expected.append("Write a reproducibility bundle.")
+    if effects.get("refresh_insights"):
+        expected.append("Refresh project memory and recommendations.")
+    return expected or ["Perform the selected app step."]
+
+
+def _approval_reason_for_risk(risk_level: str) -> Optional[str]:
+    return {
+        "runs_job": "This starts compute and writes run artifacts.",
+        "controls_job": "This changes a running process.",
+        "loads_editor": "This opens an editing workflow that can produce new masks.",
+        "exports_evidence": "This writes an evidence bundle to disk.",
+        "writes_workflow_record": "This changes workflow state.",
+        "modifies_workspace": "This changes the active project/workspace.",
+    }.get(risk_level)
+
+
+def _reason_code_from_label(label: str) -> str:
+    normalized = re.sub(r"[^a-zA-Z0-9]+", "_", str(label).strip().lower())
+    return normalized.strip("_") or "item"
+
+
+def _policy_blocking_reason(
+    code: str,
+    message: str,
+    *,
+    scope: str = "input",
+    field: Optional[str] = None,
+    value: Optional[str] = None,
+) -> Dict[str, Any]:
+    payload: Dict[str, Any] = {
+        "code": code,
+        "message": message,
+        "scope": scope,
+    }
+    if field:
+        payload["field"] = field
+    if value:
+        payload["value"] = value
+    return payload
+
+
+def _policy_decision_payload(
+    decision: str,
+    *,
+    requires_approval: bool,
+    reason_code: Optional[str] = None,
+    reason: Optional[str] = None,
+    blocking_reasons: Optional[List[Dict[str, Any]]] = None,
+) -> Dict[str, Any]:
+    return {
+        "decision": decision,
+        "requires_approval": bool(requires_approval),
+        "reason_code": reason_code,
+        "reason": reason,
+        "blocking_reasons": blocking_reasons or [],
+    }
+
+
+def _resource_freshness_payload(
+    *,
+    scope: str,
+    required_fields: List[str],
+    missing_fields: List[str],
+    source: str = "workflow_state",
+) -> Dict[str, Any]:
+    return {
+        "scope": scope,
+        "state": "ready" if not missing_fields else "missing",
+        "required": required_fields,
+        "missing": missing_fields,
+        "source": source,
+    }
+
+
+def _project_context_freshness(workflow: WorkflowSession) -> Dict[str, Any]:
+    required_fields = ["imaging_modality", "target_structure"]
+    context = _workflow_project_context(workflow)
+    missing_fields = [field for field in required_fields if not context.get(field)]
+    if not missing_fields:
+        state = "fresh"
+        if (
+            not context.get("updated_at")
+            or context.get("source") == "initial_project_default"
+        ):
+            state = "stale"
+    else:
+        state = "missing"
+    return {
+        "scope": "project_context",
+        "state": state,
+        "required": required_fields,
+        "missing": missing_fields,
+        "present": [field for field in required_fields if context.get(field)],
+        "source": context.get("source")
+        or context.get("updated_at")
+        and "workflow_agent_context",
+    }
+
+
+def _build_action_card_payload(
+    *,
+    action_id: str,
+    label: str,
+    description: str,
+    client_effects: Dict[str, Any],
+    risk_level: str,
+    requires_approval: bool,
+    disabled_reason: Optional[str],
+) -> Dict[str, Any]:
+    action_type = _action_type_from_effects(action_id, client_effects)
+    specialist_agent = _specialist_agent_for_action(action_type, client_effects)
+    blockers = [disabled_reason] if disabled_reason else []
+    return {
+        "schema_version": "workflow.action_card/v2",
+        "action_id": action_id,
+        "action_type": action_type,
+        "orchestrator_agent": ORCHESTRATOR_AGENT,
+        "specialist_agent": specialist_agent,
+        "title": label,
+        "rationale": description,
+        "target": _action_target_from_effects(client_effects),
+        "risk_level": risk_level,
+        "risk_tier": _action_risk_tier(risk_level),
+        "requires_approval": requires_approval,
+        "approval_reason": _approval_reason_for_risk(risk_level),
+        "blockers": blockers,
+        "input_artifacts": _artifact_entries_from_effects(
+            client_effects, direction="input"
+        ),
+        "output_artifacts": _artifact_entries_from_effects(
+            client_effects, direction="output"
+        ),
+        "summary_fields": _summary_fields_from_effects(client_effects),
+        "expected_effects": _expected_effects_from_client_effects(client_effects),
+        "executor": "bounded_app_routine",
+    }
+
+
+def _one_app_suggestion(
+    actions: List[AgentChatAction],
+    commands: List[AgentCommandBlock],
+) -> tuple[List[AgentChatAction], List[AgentCommandBlock]]:
+    if actions:
+        primary = next(
+            (action for action in actions if action.variant == "primary"),
+            actions[0],
+        )
+        return [primary], []
+    if commands:
+        return [], [commands[0]]
+    return actions, commands
+
+
+def _query_is_informational_followup(lower_query: str) -> bool:
+    stripped = lower_query.strip()
+    if not stripped:
+        return False
+    question_like = "?" in stripped or stripped.startswith(
+        (
+            "why ",
+            "what ",
+            "which ",
+            "how ",
+            "can you explain",
+            "explain ",
+            "tell me more",
+        )
+    )
+    if not question_like:
+        return False
+    imperative_terms = [
+        "start ",
+        "run ",
+        "launch ",
+        "open ",
+        "show ",
+        "go to ",
+        "take me ",
+        "proofread",
+        "train now",
+        "start training",
+        "run training",
+        "segment now",
+        "run segmentation",
+    ]
+    return not any(term in stripped for term in imperative_terms)
+
+
+def _build_agent_chat_action(
+    action_id: str,
+    label: str,
+    description: str,
+    *,
+    variant: str = "default",
+    client_effects: Optional[Dict[str, Any]] = None,
+    risk_level: Optional[str] = None,
+    run_label: str = "Run in app",
+    requires_approval: Optional[bool] = None,
+    disabled_reason: Optional[str] = None,
+    policy_decision: Optional[Dict[str, Any]] = None,
+    blocking_reasons: Optional[List[Dict[str, Any]]] = None,
+    freshness: Optional[Dict[str, Any]] = None,
+) -> AgentChatAction:
+    effects = client_effects or {}
+    inferred_risk = risk_level or _infer_action_risk(effects)
+    approval_required = (
+        _requires_action_approval(effects)
+        if requires_approval is None
+        else requires_approval
+    )
+    computed_reasons = blocking_reasons or []
+    policy = policy_decision
+    if policy is None:
+        policy = _policy_decision_payload(
+            "allowed" if not computed_reasons else "blocked",
+            requires_approval=approval_required,
+            reason_code=(
+                _reason_code_from_label(inferred_risk) if computed_reasons else None
+            ),
+            reason=_approval_reason_for_risk(inferred_risk),
+            blocking_reasons=computed_reasons,
+        )
+    action_card = _build_action_card_payload(
+        action_id=action_id,
+        label=label,
+        description=description,
+        client_effects=effects,
+        risk_level=inferred_risk,
+        requires_approval=approval_required,
+        disabled_reason=disabled_reason,
+    )
+    specialist_agent = action_card.get("specialist_agent") or ORCHESTRATOR_AGENT
+    return AgentChatAction(
+        id=action_id,
+        label=label,
+        description=description,
+        orchestrator_agent=action_card.get("orchestrator_agent") or ORCHESTRATOR_AGENT,
+        specialist_agent=specialist_agent,
+        agent_type=str(specialist_agent.get("type") or "project_manager"),
+        agent_label=str(specialist_agent.get("label") or "Project Manager"),
+        agent_color=str(specialist_agent.get("color") or "#111827"),
+        agent_icon_key=str(specialist_agent.get("icon_key") or "project"),
+        agent_border_style=str(specialist_agent.get("border_style") or "solid"),
+        action_type=str(action_card.get("action_type") or action_id),
+        target=action_card.get("target"),
+        variant=variant,
+        run_label=run_label,
+        risk_level=inferred_risk,
+        risk_tier=str(action_card.get("risk_tier") or _action_risk_tier(inferred_risk)),
+        requires_approval=approval_required,
+        approval_reason=action_card.get("approval_reason"),
+        summary_fields=action_card.get("summary_fields") or [],
+        input_artifacts=action_card.get("input_artifacts") or [],
+        output_artifacts=action_card.get("output_artifacts") or [],
+        expected_effects=action_card.get("expected_effects") or [],
+        blockers=action_card.get("blockers") or [],
+        action_card=action_card,
+        disabled_reason=disabled_reason,
+        client_effects=effects,
+        policy_decision=policy,
+        blocking_reasons=computed_reasons,
+        freshness=freshness or {},
+    )
+
+
+def _build_agent_command_block(
+    command_id: str,
+    title: str,
+    description: str,
+    client_effects: Dict[str, Any],
+    *,
+    run_label: str = "Run in app",
+) -> AgentCommandBlock:
+    risk = _infer_action_risk(client_effects)
+    return AgentCommandBlock(
+        id=command_id,
+        title=title,
+        description=description,
+        command=_client_effects_to_command(client_effects),
+        run_label=run_label,
+        risk_level=risk,
+        requires_approval=_requires_action_approval(client_effects),
+        client_effects=client_effects,
+    )
+
+
+def _workflow_stage_to_tab(stage: Optional[str]) -> str:
+    return {
+        "setup": "files",
+        "visualization": "visualization",
+        "inference": "inference",
+        "proofreading": "mask-proofreading",
+        "retraining_staged": "training",
+        "evaluation": "inference",
+    }.get(stage or "", "files")
+
+
+def _build_start_inference_effects(workflow: WorkflowSession) -> Dict[str, Any]:
+    effects: Dict[str, Any] = {
+        "navigate_to": "inference",
+        "runtime_action": {"kind": "start_inference"},
+    }
+    if workflow.image_path or workflow.dataset_path:
+        effects["set_inference_image_path"] = (
+            workflow.image_path or workflow.dataset_path
+        )
+    if workflow.label_path or workflow.mask_path:
+        effects["set_inference_label_path"] = workflow.label_path or workflow.mask_path
+    config_preset = _choose_training_config_preset(workflow)
+    if config_preset:
+        effects["set_inference_config_preset"] = config_preset
+    if workflow.inference_output_path:
+        effects["set_inference_output_path"] = workflow.inference_output_path
+    if workflow.checkpoint_path:
+        effects["set_inference_checkpoint_path"] = workflow.checkpoint_path
+    return effects
+
+
+def _default_mount_project_path() -> str:
+    return os.getenv(
+        "PYTC_INITIAL_PROJECT_ROOT",
+        "/home/weidf/demo_data/mitoem2_progress_demo",
+    )
+
+
+def _build_mount_project_effects(
+    *,
+    directory_path: Optional[str] = None,
+    mount_name: Optional[str] = None,
+) -> Dict[str, Any]:
+    project_path = directory_path or _default_mount_project_path()
+    project_name = mount_name or os.path.basename(project_path.rstrip(os.sep))
+    return {
+        "navigate_to": "files",
+        "mount_project": {
+            "directory_path": project_path,
+            "mount_name": project_name or "Mounted project",
+            "destination_path": "root",
+            "workflow_patch": {
+                "title": project_name or "Mounted project",
+                "dataset_path": project_path,
+                "stage": "setup",
+                "metadata": {
+                    "project_context": {
+                        "project_directory": project_path,
+                        "task_goal": "segmentation",
+                    }
+                },
+            },
+        },
+        "refresh_insights": True,
+    }
+
+
+def _build_reset_workspace_effects() -> Dict[str, Any]:
+    return {
+        "navigate_to": "files",
+        "reset_workspace": True,
+        "refresh_insights": True,
+    }
+
+
+def _build_choose_data_effects() -> Dict[str, Any]:
+    return {
+        "navigate_to": "files",
+        "runtime_action": {"kind": "choose_project_data"},
+        "refresh_insights": True,
+    }
+
+
+def _split_path_parent(path: Optional[str]) -> str:
+    if not path:
+        return ""
+    normalized = str(path).replace("\\", "/").rstrip("/")
+    if not normalized:
+        return ""
+    if "/" not in normalized:
+        return ""
+    return normalized.rsplit("/", 1)[0]
+
+
+def _derive_workflow_root_path(workflow: WorkflowSession) -> str:
+    candidates = [
+        workflow.dataset_path,
+        workflow.image_path,
+        workflow.label_path,
+        workflow.mask_path,
+        workflow.corrected_mask_path,
+        workflow.training_output_path,
+    ]
+    for candidate in candidates:
+        if not candidate:
+            continue
+        normalized = str(candidate).replace("\\", "/")
+        if "/data/" in normalized:
+            return normalized.split("/data/", 1)[0]
+        parent = _split_path_parent(normalized)
+        if parent:
+            return parent
+    return ""
+
+
+def _derive_mount_project_path(workflow: WorkflowSession) -> str:
+    dataset_path = str(workflow.dataset_path or "").replace("\\", "/").rstrip("/")
+    if dataset_path and not pathlib.PurePosixPath(dataset_path).suffix:
+        return dataset_path
+    return _derive_workflow_root_path(workflow) or dataset_path
+
+
+def _derive_training_output_path(workflow: WorkflowSession) -> str:
+    if workflow.training_output_path:
+        return workflow.training_output_path
+    root = _derive_workflow_root_path(workflow)
+    if root:
+        return f"{root.rstrip('/')}/outputs/training"
+    return ""
+
+
+def _choose_training_config_preset(workflow: WorkflowSession) -> str:
+    if workflow.config_path:
+        return workflow.config_path
+    project_context = _workflow_project_context(workflow)
+    haystack = " ".join(
+        str(value or "")
+        for value in [
+            workflow.title,
+            workflow.dataset_path,
+            workflow.image_path,
+            workflow.label_path,
+            workflow.mask_path,
+            workflow.corrected_mask_path,
+            project_context.get("imaging_modality"),
+            project_context.get("target_structure"),
+            project_context.get("optimization_priority"),
+        ]
+    ).lower()
+    if "mito" in haystack:
+        return "configs/MitoEM/Mito25-Local-BC.yaml"
+    if "snemi" in haystack:
+        return "configs/SNEMI/SNEMI-Affinity-UNet.yaml"
+    if "cremi" in haystack:
+        return "configs/CREMI/CREMI-Foreground-UNet.yaml"
+    return "configs/Lucchi-Mitochondria.yaml"
+
+
+def _build_start_training_effects(
+    workflow: WorkflowSession,
+    corrected_mask_path: Optional[str],
+    *,
+    volume_subset_plan: Optional[Dict[str, Any]] = None,
+) -> Dict[str, Any]:
+    output_path = (
+        str(volume_subset_plan.get("output_path") or "")
+        if isinstance(volume_subset_plan, dict)
+        else ""
+    ) or _derive_training_output_path(workflow)
+    image_path = (
+        (
+            str(volume_subset_plan.get("image_path") or "")
+            if isinstance(volume_subset_plan, dict)
+            else ""
+        )
+        or workflow.image_path
+        or workflow.dataset_path
+        or ""
+    )
+    label_path = (
+        (
+            str(volume_subset_plan.get("label_path") or "")
+            if isinstance(volume_subset_plan, dict)
+            else ""
+        )
+        or corrected_mask_path
+        or ""
+    )
+    runtime_action: Dict[str, Any] = {
+        "kind": "start_training",
+        "autopick_parameters": True,
+        "parameter_mode": "agent_default",
+    }
+    if isinstance(volume_subset_plan, dict):
+        runtime_action["volume_subset"] = {
+            key: volume_subset_plan.get(key)
+            for key in [
+                "selection_basis",
+                "training_statuses",
+                "train_volume_count",
+                "target_volume_count",
+                "review_volume_count",
+                "manifest_path",
+            ]
+            if volume_subset_plan.get(key) is not None
+        }
+    effects: Dict[str, Any] = {
+        "navigate_to": "training",
+        "runtime_action": runtime_action,
+        "set_training_config_preset": _choose_training_config_preset(workflow),
+    }
+    if image_path:
+        effects["set_training_image_path"] = image_path
+    if label_path:
+        effects["set_training_label_path"] = label_path
+    if output_path:
+        effects["set_training_output_path"] = output_path
+        effects["set_training_log_path"] = output_path
+    if isinstance(volume_subset_plan, dict):
+        effects["training_volume_subset"] = {
+            key: volume_subset_plan.get(key)
+            for key in [
+                "run_slug",
+                "selection_basis",
+                "training_statuses",
+                "train_volume_count",
+                "target_volume_count",
+                "review_volume_count",
+                "manifest_path",
+                "train_pairs",
+                "target_images",
+                "review_pairs",
+            ]
+            if volume_subset_plan.get(key) is not None
+        }
+        effects["refresh_project_progress"] = True
+    return effects
+
+
+def _workflow_requires_trusted_masks(workflow: WorkflowSession) -> bool:
+    project_context = _workflow_project_context(workflow)
+    if not isinstance(project_context, dict):
+        return False
+    preset = _task_family_preset_for_context(project_context)
+    if preset.get("id") == "tapereader_xri_fiber":
+        return True
+    policy = str(project_context.get("training_policy") or "").lower()
+    if "confirmed" in policy and "ground" in policy:
+        return True
+    task_family = str(project_context.get("task_family") or "").lower()
+    return "xri" in task_family and "tape" in task_family
+
+
+def _preferred_training_mask_path(
+    workflow: WorkflowSession,
+    *,
+    require_trusted: bool = False,
+) -> Optional[str]:
+    if workflow.corrected_mask_path:
+        return workflow.corrected_mask_path
+    if workflow.label_path:
+        return workflow.label_path
+    if require_trusted:
+        return None
+    return workflow.mask_path
+
+
+def _training_run_effects_from_proposal(
+    workflow: WorkflowSession,
+    params: Dict[str, Any],
+) -> Dict[str, Any]:
+    client_effects = params.get("client_effects")
+    if (
+        isinstance(client_effects, dict)
+        and (client_effects.get("runtime_action") or {}).get("kind") == "start_training"
+    ):
+        return client_effects
+
+    corrected_mask_path = (
+        params.get("label_path")
+        or params.get("corrected_mask_path")
+        or workflow.corrected_mask_path
+        or workflow.label_path
+        or workflow.mask_path
+    )
+    effects = _build_start_training_effects(workflow, corrected_mask_path)
+    if params.get("config_preset"):
+        effects["set_training_config_preset"] = params["config_preset"]
+    if params.get("image_path"):
+        effects["set_training_image_path"] = params["image_path"]
+    if params.get("output_path"):
+        effects["set_training_output_path"] = params["output_path"]
+        effects["set_training_log_path"] = params["output_path"]
+    if isinstance(client_effects, dict):
+        for key, value in client_effects.items():
+            if key.startswith("set_training_") or key in {
+                "runtime_action",
+                "training_volume_subset",
+                "refresh_project_progress",
+            }:
+                effects[key] = value
+    return effects
+
+
+AGENT_ACTION_CLIENT_EFFECT_OVERRIDES: Dict[str, str] = {
+    "config_preset": "set_training_config_preset",
+    "image_path": "set_training_image_path",
+    "label_path": "set_training_label_path",
+    "output_path": "set_training_output_path",
+    "log_path": "set_training_log_path",
+    "inference_config_preset": "set_inference_config_preset",
+    "checkpoint_path": "set_inference_checkpoint_path",
+    "inference_image_path": "set_inference_image_path",
+    "inference_label_path": "set_inference_label_path",
+    "inference_output_path": "set_inference_output_path",
+    "visualization_image_path": "set_visualization_image_path",
+    "visualization_label_path": "set_visualization_label_path",
+    "visualization_scales": "set_visualization_scales",
+    "proofreading_dataset_path": "set_proofreading_dataset_path",
+    "proofreading_mask_path": "set_proofreading_mask_path",
+    "proofreading_project_name": "set_proofreading_project_name",
+}
+
+AGENT_ACTION_PARAM_OVERRIDES = set(AGENT_ACTION_CLIENT_EFFECT_OVERRIDES).union(
+    {
+        "corrected_mask_path",
+        "written_path",
+        "training_output_path",
+        "parameter_mode",
+        "autopick_parameters",
+    }
+)
+
+
+def _coerce_bool(value: Any) -> bool:
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        return value.strip().lower() in {"1", "true", "yes", "y", "on"}
+    return bool(value)
+
+
+def _clean_agent_action_overrides(
+    overrides: Optional[Dict[str, Any]],
+) -> Dict[str, Any]:
+    if not isinstance(overrides, dict):
+        return {}
+    cleaned: Dict[str, Any] = {}
+    for key, value in overrides.items():
+        if key not in AGENT_ACTION_PARAM_OVERRIDES:
+            continue
+        if isinstance(value, str):
+            cleaned[key] = value.strip()
+        else:
+            cleaned[key] = value
+    return cleaned
+
+
+def _apply_agent_action_overrides(
+    action: str,
+    params: Dict[str, Any],
+    overrides: Optional[Dict[str, Any]],
+) -> tuple[Dict[str, Any], Dict[str, Any]]:
+    applied = _clean_agent_action_overrides(overrides)
+    if not applied:
+        return params, {}
+
+    next_params = dict(params or {})
+    for key, value in applied.items():
+        next_params[key] = value
+
+    effects = dict(next_params.get("client_effects") or {})
+    for key, value in applied.items():
+        effect_key = AGENT_ACTION_CLIENT_EFFECT_OVERRIDES.get(key)
+        if effect_key:
+            effects[effect_key] = value
+
+    if action == "start_training_run":
+        if "output_path" in applied and "log_path" not in applied:
+            effects["set_training_log_path"] = applied["output_path"]
+        runtime_action = dict(effects.get("runtime_action") or {})
+        if runtime_action.get("kind") == "start_training":
+            if "parameter_mode" in applied:
+                runtime_action["parameter_mode"] = applied["parameter_mode"]
+            if "autopick_parameters" in applied:
+                runtime_action["autopick_parameters"] = _coerce_bool(
+                    applied["autopick_parameters"]
+                )
+            effects["runtime_action"] = runtime_action
+    if effects:
+        next_params["client_effects"] = effects
+    return next_params, applied
+
+
+def _agent_action_approval_payload(
+    proposal_id: int,
+    action: str,
+    user_edits: Optional[Dict[str, Any]] = None,
+) -> Dict[str, Any]:
+    payload: Dict[str, Any] = {"proposal_event_id": proposal_id, "action": action}
+    if user_edits:
+        payload["user_edits"] = user_edits
+    return payload
+
+
+def _build_start_proofreading_effects(workflow: WorkflowSession) -> Dict[str, Any]:
+    dataset_path = workflow.image_path or workflow.dataset_path or ""
+    mask_path = (
+        workflow.corrected_mask_path
+        or workflow.inference_output_path
+        or workflow.mask_path
+        or workflow.label_path
+        or ""
+    )
+    effects: Dict[str, Any] = {
+        "navigate_to": "mask-proofreading",
+        "runtime_action": {"kind": "start_proofreading"},
+        "refresh_insights": True,
+    }
+    if dataset_path:
+        effects["set_proofreading_dataset_path"] = dataset_path
+    if mask_path:
+        effects["set_proofreading_mask_path"] = mask_path
+    if workflow.title:
+        effects["set_proofreading_project_name"] = workflow.title
+    return effects
+
+
+def _workflow_source_volume_path(workflow: WorkflowSession) -> str:
+    return workflow.image_path or workflow.dataset_path or ""
+
+
+def _workflow_mask_like_path(workflow: WorkflowSession) -> str:
+    return (
+        workflow.corrected_mask_path
+        or workflow.inference_output_path
+        or workflow.mask_path
+        or workflow.label_path
+        or ""
+    )
+
+
+def _proofreading_input_blockers(workflow: WorkflowSession) -> List[str]:
+    blockers = []
+    if not _workflow_source_volume_path(workflow):
+        blockers.append("image volume")
+    if not _workflow_mask_like_path(workflow):
+        blockers.append("mask, label, or prediction")
+    return blockers
+
+
+def _inference_input_blockers(workflow: WorkflowSession) -> List[str]:
+    blockers = []
+    if not (workflow.image_path or workflow.dataset_path):
+        blockers.append("image volume")
+    if not workflow.checkpoint_path:
+        blockers.append("model checkpoint")
+    return blockers
+
+
+def _build_view_data_effects(
+    workflow: WorkflowSession,
+    *,
+    image_path: Optional[str] = None,
+    label_path: Optional[str] = None,
+) -> Dict[str, Any]:
+    image_path = image_path or workflow.image_path or workflow.dataset_path or ""
+    label_path = label_path or (
+        workflow.label_path
+        or workflow.mask_path
+        or workflow.inference_output_path
+        or workflow.corrected_mask_path
+        or ""
+    )
+    effects: Dict[str, Any] = {
+        "navigate_to": "visualization",
+        "runtime_action": {"kind": "load_visualization"},
+    }
+    if image_path:
+        effects["set_visualization_image_path"] = image_path
+    if label_path:
+        effects["set_visualization_label_path"] = label_path
+    return effects
+
+
+def _build_proofreading_action(
+    workflow: WorkflowSession,
+    *,
+    label: str = "Proofread this data",
+    variant: str = "primary",
+    policy_decision: Optional[Dict[str, Any]] = None,
+    blocking_reasons: Optional[List[Dict[str, Any]]] = None,
+    freshness: Optional[Dict[str, Any]] = None,
+) -> AgentChatAction:
+    return _build_agent_chat_action(
+        "start-proofreading",
+        label,
+        "Open the image and mask in the proofreading workbench.",
+        variant=variant,
+        client_effects=_build_start_proofreading_effects(workflow),
+        policy_decision=policy_decision,
+        blocking_reasons=blocking_reasons,
+        freshness=freshness,
+    )
+
+
+def _build_default_agent_actions(
+    workflow: WorkflowSession,
+    corrected_mask_path: Optional[str],
+) -> List[AgentChatAction]:
+    proofreading_blockers = _proofreading_input_blockers(workflow)
+    can_start_proofreading = not proofreading_blockers
+
+    if workflow.stage == "setup":
+        if can_start_proofreading:
+            return [
+                _build_proofreading_action(workflow, variant="primary"),
+                _build_agent_chat_action(
+                    "open-visualization",
+                    "View data",
+                    "Open the current image and mask in the viewer.",
+                    client_effects=_build_view_data_effects(workflow),
+                ),
+                _build_agent_chat_action(
+                    "open-inference",
+                    "Run Model",
+                    "Open model inference setup.",
+                    client_effects={"navigate_to": "inference"},
+                ),
+            ]
+        return [
+            _build_agent_chat_action(
+                "open-files",
+                "Choose data",
+                "Pick the image and mask for this segmentation loop.",
+                variant="primary",
+                client_effects=_build_choose_data_effects(),
+            ),
+            _build_agent_chat_action(
+                "open-visualization",
+                "View data",
+                "Open the image viewer after data is mounted.",
+                client_effects=_build_view_data_effects(workflow),
+            ),
+            _build_agent_chat_action(
+                "open-inference",
+                "Run Model",
+                "Open model inference setup.",
+                client_effects={"navigate_to": "inference"},
+            ),
+        ]
+
+    if workflow.stage == "visualization":
+        if not can_start_proofreading:
+            return [
+                _build_agent_chat_action(
+                    "open-files",
+                    "Choose data",
+                    f"Proofreading needs {', '.join(proofreading_blockers)}.",
+                    variant="primary",
+                    client_effects=_build_choose_data_effects(),
+                ),
+                _build_agent_chat_action(
+                    "open-inference",
+                    "Run Model",
+                    "Make a prediction for the current data.",
+                    client_effects={"navigate_to": "inference"},
+                ),
+            ]
+        return [
+            _build_proofreading_action(workflow, variant="primary"),
+            _build_agent_chat_action(
+                "open-inference",
+                "Run Model",
+                "Make a prediction for the current data.",
+                client_effects={"navigate_to": "inference"},
+            ),
+        ]
+
+    if workflow.stage == "inference":
+        if not workflow.inference_output_path:
+            return [
+                _build_agent_chat_action(
+                    "start-inference",
+                    "Run Model",
+                    "Start the model run with the current settings.",
+                    variant="primary",
+                    client_effects=_build_start_inference_effects(workflow),
+                ),
+                _build_agent_chat_action(
+                    "open-inference",
+                    "Check settings",
+                    "Review the checkpoint and output path before running.",
+                    client_effects={"navigate_to": "inference"},
+                ),
+            ]
+        return [
+            _build_proofreading_action(
+                workflow,
+                label="Proofread this result",
+                variant="primary",
+            ),
+            _build_agent_chat_action(
+                "refresh-insights",
+                "Refresh",
+                "Update the next-step recommendation.",
+                client_effects={"refresh_insights": True},
+            ),
+        ]
+
+    if workflow.stage == "proofreading":
+        actions = [
+            _build_proofreading_action(
+                workflow,
+                variant=(
+                    "primary" if not workflow.proofreading_session_id else "default"
+                ),
+            ),
+            _build_agent_chat_action(
+                "refresh-insights",
+                "Refresh",
+                "Update the recommendation using the latest edits.",
+                client_effects={"refresh_insights": True},
+            ),
+        ]
+        if corrected_mask_path:
+            actions.insert(
+                1,
+                _build_agent_chat_action(
+                    "propose-retraining-handoff",
+                    "Use edits for training",
+                    "Ask for approval before linking the saved edits to training.",
+                    variant="primary",
+                    client_effects={
+                        "workflow_action": {
+                            "kind": "propose_retraining_stage",
+                            "corrected_mask_path": corrected_mask_path,
+                        },
+                        "refresh_insights": True,
+                    },
+                ),
+            )
+            actions.insert(
+                2,
+                _build_agent_chat_action(
+                    "prime-training",
+                    "Set up training",
+                    "Open training with the saved edits already selected.",
+                    client_effects={
+                        "navigate_to": "training",
+                        "set_training_label_path": corrected_mask_path,
+                    },
+                ),
+            )
+        return actions
+
+    if workflow.stage == "retraining_staged":
+        training_effects = _build_start_training_effects(workflow, corrected_mask_path)
+        return [
+            _build_agent_chat_action(
+                "start-training",
+                "Train on edits",
+                "Start training with the saved mask edits.",
+                variant="primary",
+                run_label="Review run",
+                client_effects=training_effects,
+            ),
+            _build_agent_chat_action(
+                "refresh-insights",
+                "Refresh",
+                "Update the recommendation before training.",
+                client_effects={"refresh_insights": True},
+            ),
+        ]
+
+    if workflow.stage == "evaluation":
+        inference_effects = (
+            _build_start_inference_effects(workflow)
+            if workflow.checkpoint_path
+            else {"navigate_to": "inference"}
+        )
+        inference_label = "Run model" if workflow.checkpoint_path else "Check inference"
+        inference_description = (
+            "Run the model with the latest checkpoint."
+            if workflow.checkpoint_path
+            else "Open inference and review the latest checkpoint."
+        )
+        return [
+            _build_agent_chat_action(
+                "open-inference-ready-model",
+                inference_label,
+                inference_description,
+                variant="primary",
+                client_effects=inference_effects,
+            ),
+            _build_agent_chat_action(
+                "open-training-runtime",
+                "View training log",
+                "Open Train Model runtime details.",
+                client_effects={"navigate_to": "training"},
+            ),
+        ]
+
+    return [
+        _build_agent_chat_action(
+            "open-workflow-stage",
+            "Go to next step",
+            "Open the active workflow screen.",
+            variant="primary",
+            client_effects={"navigate_to": _workflow_stage_to_tab(workflow.stage)},
+        )
+    ]
+
+
+def _query_has(lower_query: str, terms: List[str]) -> bool:
+    for term in terms:
+        normalized = term.strip().lower()
+        if not normalized:
+            continue
+        if re.search(r"[^\w]", normalized):
+            if normalized in lower_query:
+                return True
+            continue
+        if re.search(
+            rf"(?<![a-z0-9_]){re.escape(normalized)}(?![a-z0-9_])",
+            lower_query,
+        ):
+            return True
+    return False
+
+
+def _casual_query_variant(lower_query: str) -> str:
+    squashed = re.sub(r"([a-z])\1{2,}", r"\1\1", lower_query)
+    return squashed.replace("datta", "data")
+
+
+def _query_has_relaxed(lower_query: str, terms: List[str]) -> bool:
+    return _query_has(lower_query, terms) or _query_has(
+        _casual_query_variant(lower_query),
+        terms,
+    )
+
+
+def _query_wants_inference_launch(lower_query: str) -> bool:
+    normalized = _casual_query_variant(lower_query)
+    if _query_has_relaxed(
+        lower_query,
+        [
+            "start inference",
+            "run inference",
+            "launch inference",
+            "infer",
+            "run model",
+            "run the model",
+            "start model",
+            "launch model",
+            "predict",
+            "prediction",
+            "make a prediction",
+            "make predictions",
+            "generate predictions",
+        ],
+    ):
+        return True
+    return bool(
+        re.search(
+            r"\b(make|create|generate|predict|produce)\b.{0,32}\b(mask|masks|label|labels|prediction|predictions)\b",
+            normalized,
+        )
+    )
+
+
+def _query_wants_segmentation_launch(lower_query: str) -> bool:
+    normalized = _casual_query_variant(lower_query)
+    if _query_has_relaxed(
+        lower_query,
+        [
+            "run segmentation",
+            "start segmentation",
+            "launch segmentation",
+            "segment this",
+            "segment my",
+            "segment volume",
+            "segment the volume",
+            "get my volume segmented",
+            "process volume",
+            "run this volume",
+            "predict masks",
+            "make a prediction",
+            "make predictions",
+            "segment data",
+            "segment some data",
+            "segment the data",
+            "segment my data",
+            "segment images",
+            "segment volume",
+            "make masks",
+            "create masks",
+            "generate masks",
+            "find mitochondria",
+            "detect mitochondria",
+            "label mitochondria",
+        ],
+    ):
+        return True
+    if re.search(r"\bseg+(?:ment(?:ation|ed|ing|s)?|mentation|s?)\b", normalized):
+        return True
+    return bool(
+        re.search(
+            r"\b(segment|find|detect|label)\b.{0,40}\b(data|volume|image|images|mitochondria|mito|mask|masks)\b",
+            normalized,
+        )
+    )
+
+
+def _query_wants_visualization_launch(lower_query: str) -> bool:
+    normalized = _casual_query_variant(lower_query)
+    if _query_has_relaxed(
+        lower_query,
+        [
+            "visualize",
+            "visualise",
+            "vis data",
+            "vis volume",
+            "vis volumes",
+            "vis labels",
+            "vis masks",
+            "viz data",
+            "viz volume",
+            "viz volumes",
+            "viz labels",
+            "viz masks",
+            "visualization",
+            "view data",
+            "view volume",
+            "view volumes",
+            "view labels",
+            "view masks",
+            "view segmentations",
+            "look at labels",
+            "look at my labels",
+            "look at masks",
+            "look at my masks",
+            "look at segmentations",
+            "show data",
+            "show volume",
+            "show labels",
+            "show masks",
+            "show segs",
+            "show segmentations",
+            "inspect data",
+            "inspect volume",
+            "inspect labels",
+            "inspect masks",
+            "look at data",
+            "look at volume",
+            "look at labels",
+            "look at masks",
+            "look at segs",
+            "open viewer",
+        ],
+    ):
+        return True
+    return bool(
+        re.search(
+            r"\b(show|see|view|vis|viz|visuali[sz]e|look at|inspect|open)\b.{0,36}\b(data|volume|volumes|image|images|label|labels|mask|masks|seg|segs|segmentation|segmentations)\b",
+            normalized,
+        )
+    )
+
+
+def _is_greeting_query(lower_query: str) -> bool:
+    stripped = lower_query.strip(" \t\n\r.!?,")
+    return stripped in {"hi", "hello", "hey", "yo", "sup", "hiya"}
+
+
+WORKFLOW_AGENT_COMMAND_ALIASES = {
+    "/status": "status",
+    "/next": "next step",
+    "/help": "what can the agent do",
+    "/infer": "run model",
+    "/inference": "run model",
+    "/segment": "run model to segment this volume",
+    "/proofread": "proofread this data",
+    "/train": "start training",
+    "/compare": "compare results and compute metrics",
+    "/metrics": "compare results and compute metrics",
+    "/export": "export evidence bundle",
+}
+
+
+def _normalize_workflow_agent_query(query: str) -> tuple[str, Optional[str]]:
+    stripped = query.strip()
+    if not stripped.startswith("/"):
+        return stripped, None
+    command, _, tail = stripped.partition(" ")
+    alias = WORKFLOW_AGENT_COMMAND_ALIASES.get(command.lower())
+    if not alias:
+        return stripped, None
+    normalized = f"{alias}: {tail.strip()}" if tail.strip() else alias
+    return normalized, command.lower()
+
+
+def _is_incomplete_work_intent(lower_query: str) -> bool:
+    stripped = lower_query.strip().lower().rstrip(". ")
+    return stripped in {
+        "i want",
+        "i wanna",
+        "i would like",
+        "i need",
+        "help",
+        "help me",
+        "what should i",
+    }
+
+
+def _is_repair_query(lower_query: str) -> bool:
+    stripped = lower_query.strip().lower().rstrip(".!? ")
+    return stripped in {
+        "bruh",
+        "bro",
+        "dude",
+        "what",
+        "what?",
+        "huh",
+        "no",
+        "nah",
+        "that makes no sense",
+        "this makes no sense",
+        "doesn't make sense",
+        "does not make sense",
+        "zero sense",
+    }
+
+
+def _build_navigation_action(
+    tab_key: str, label: str, description: str
+) -> AgentChatAction:
+    return _build_agent_chat_action(
+        f"open-{tab_key}",
+        label,
+        description,
+        variant="primary",
+        client_effects={"navigate_to": tab_key},
+    )
+
+
+def _target_tab_from_query(lower_query: str) -> Optional[Dict[str, str]]:
+    targets = [
+        (
+            [
+                "project progress",
+                "progress tracker",
+                "project tracker",
+                "volume tracker",
+                "progress",
+            ],
+            {
+                "tab": "project-progress",
+                "label": "Open Workflow",
+                "description": "Open the workflow overview and volume tracker.",
+            },
+        ),
+        (
+            [
+                "files",
+                "file management",
+                "mount",
+                "load data",
+                "choose data",
+                "project",
+            ],
+            {
+                "tab": "files",
+                "label": "Open Files",
+                "description": "Open project files and mounted datasets.",
+            },
+        ),
+        (
+            ["visualize", "visualization", "viewer", "view data"],
+            {
+                "tab": "visualization",
+                "label": "Open Visualize",
+                "description": "Open the image/label viewer.",
+            },
+        ),
+        (
+            [
+                "infer",
+                "inference",
+                "prediction",
+                "predict",
+                "run model",
+                "segment",
+                "segmentation",
+            ],
+            {
+                "tab": "inference",
+                "label": "Open Run Model",
+                "description": "Open model inference setup.",
+            },
+        ),
+        (
+            ["train", "training", "retrain"],
+            {
+                "tab": "training",
+                "label": "Open Train Model",
+                "description": "Open model training setup.",
+            },
+        ),
+        (
+            ["monitor", "tensorboard", "log"],
+            {
+                "tab": "training",
+                "label": "Open Train Model",
+                "description": "Open training runtime details and logs.",
+            },
+        ),
+        (
+            ["proofread", "proofreading", "fix mask", "review mask"],
+            {
+                "tab": "mask-proofreading",
+                "label": "Open Proofread",
+                "description": "Open the mask proofreading workbench.",
+            },
+        ),
+    ]
+    navigation_words = ["go to", "open", "show", "take me", "move me", "switch"]
+    if not _query_has(lower_query, navigation_words):
+        return None
+    for terms, target in targets:
+        if _query_has(lower_query, terms):
+            return target
+    return None
+
+
+SEMANTIC_WORKFLOW_INTENT_ORDER = (
+    "greeting",
+    "status",
+    "capabilities",
+    "style_feedback",
+    "project_context",
+    "project_context_update",
+    "project_files",
+    "project_progress",
+    "needed_from_user",
+    "navigate",
+    "export_evidence",
+    "compute_evaluation",
+    "view_data",
+    "set_visualization_scales",
+    "start_training",
+    "start_inference",
+    "start_segmentation",
+    "start_proofreading",
+    "stage_retraining",
+    "inspect_failure",
+    "mount_project",
+    "reset_workspace",
+    "validate_project",
+    "prepare_data",
+    "configure_training",
+    "configure_inference",
+    "monitor_jobs",
+    "stop_runtime",
+    "repair",
+    "clarify_next_job",
+)
+
+SEMANTIC_WORKFLOW_INTENTS = set(SEMANTIC_WORKFLOW_INTENT_ORDER)
+
+
+def _semantic_intent_enabled() -> bool:
+    if os.getenv("PYTC_WORKFLOW_SEMANTIC_ROUTER", "1").strip().lower() in {
+        "0",
+        "false",
+        "off",
+        "no",
+    }:
+        return False
+    if os.getenv("PYTEST_CURRENT_TEST"):
+        return False
+    return True
+
+
+def _semantic_workflow_state(workflow: WorkflowSession) -> Dict[str, Any]:
+    project_context = _workflow_project_context(workflow)
+    metadata = decode_json(workflow.metadata_json)
+    project_observation = (
+        metadata.get("project_observation") if isinstance(metadata, dict) else {}
+    )
+    if not isinstance(project_observation, dict):
+        project_observation = {}
+    project_progress = (
+        metadata.get("project_progress_snapshot") if isinstance(metadata, dict) else {}
+    )
+    if not isinstance(project_progress, dict):
+        project_progress = {}
+    progress_summary = project_progress.get("summary")
+    if not isinstance(progress_summary, dict):
+        progress_summary = {}
+    return {
+        "stage": workflow.stage,
+        "title": workflow.title,
+        "has_image": bool(workflow.image_path or workflow.dataset_path),
+        "has_label_or_mask": bool(workflow.label_path or workflow.mask_path),
+        "has_checkpoint": bool(workflow.checkpoint_path),
+        "has_prediction": bool(workflow.inference_output_path),
+        "has_corrected_mask": bool(workflow.corrected_mask_path),
+        "project_context": {
+            "imaging_modality": project_context.get("imaging_modality"),
+            "target_structure": project_context.get("target_structure"),
+            "task_family": project_context.get("task_family"),
+            "mask_status": project_context.get("mask_status"),
+            "image_only_strategy": project_context.get("image_only_strategy"),
+            "training_policy": project_context.get("training_policy"),
+            "optimization_priority": project_context.get("optimization_priority"),
+            "voxel_size_nm": project_context.get("voxel_size_nm"),
+        },
+        "project_progress": {
+            "total": progress_summary.get("tracked_total")
+            or progress_summary.get("total"),
+            "ground_truth": progress_summary.get("ground_truth"),
+            "needs_proofreading": progress_summary.get("needs_proofreading"),
+            "missing_segmentation": progress_summary.get("missing_segmentation"),
+        },
+        "project_observation": {
+            "root_count": len(project_observation.get("roots") or []),
+            "volume_set_count": len(project_observation.get("volume_sets") or []),
+            "volume_sets": [
+                {
+                    "name": item.get("name"),
+                    "image_root": item.get("image_root"),
+                    "label_root": item.get("label_root"),
+                    "pair_count": item.get("pair_count"),
+                    "is_current": item.get("is_current"),
+                }
+                for item in (project_observation.get("volume_sets") or [])[:6]
+                if isinstance(item, dict)
+            ],
+        },
+    }
+
+
+def _extract_json_object(text: str) -> Dict[str, Any]:
+    raw = str(text or "").strip()
+    if raw.startswith("```"):
+        raw = re.sub(r"^```(?:json)?\s*", "", raw, flags=re.IGNORECASE)
+        raw = re.sub(r"\s*```$", "", raw)
+    try:
+        parsed = json.loads(raw)
+        return parsed if isinstance(parsed, dict) else {}
+    except json.JSONDecodeError:
+        match = re.search(r"\{[\s\S]*\}", raw)
+        if not match:
+            return {}
+        try:
+            parsed = json.loads(match.group(0))
+            return parsed if isinstance(parsed, dict) else {}
+        except json.JSONDecodeError:
+            return {}
+
+
+def _semantic_intent_payload(query: str, workflow: WorkflowSession) -> Dict[str, Any]:
+    if not _semantic_intent_enabled():
+        return {}
+
+    base_url = os.getenv("OLLAMA_BASE_URL", "http://127.0.0.1:11434").rstrip("/")
+    model = os.getenv(
+        "PYTC_WORKFLOW_INTENT_MODEL",
+        os.getenv("OLLAMA_MODEL", "qwen3.6:27b"),
+    )
+    timeout = float(os.getenv("PYTC_WORKFLOW_INTENT_TIMEOUT", "8"))
+    workflow_state = _semantic_workflow_state(workflow)
+    prompt = f"""
+Classify a PyTC Client workflow chat message by meaning. Return ONLY JSON.
+
+Valid intents:
+{", ".join(SEMANTIC_WORKFLOW_INTENT_ORDER)}.
+
+Rules:
+- Interpret casual language semantically, not by exact wording.
+- "segment my data", "make mitochondria masks", "find cells", "label this volume"
+  mean start_segmentation.
+- "show/view/look at/see my labels/masks/segs/data" means view_data.
+- "fix/clean/check/proofread/review labels or masks" means start_proofreading.
+- "train/learn from labels/fit a model/use labels or edits" means start_training.
+- "train from ground truth", "use the fully good volumes", or
+  "train on good masks to segment the rest" means start_training, not project_progress.
+- If training and "segment the rest/remaining/no segmentation" appear together, choose
+  start_training and leave the segmentation targets in the reason.
+- "run model/infer/predict outputs" means start_inference.
+- "did it improve/compare/check metrics/report score" means compute_evaluation.
+- "package/export/report/evidence bundle" means export_evidence.
+- "mount/remount/open project/lucchi/prepilot/suggested project" means mount_project.
+- "what files/folders are here" or "list this directory" means project_files.
+- "project progress", "progress tracker", "how many volumes are done", "ground truth vs unproofread vs missing segmentation" means project_progress.
+- "reset/clear cached state/workspace/cache/context" means reset_workspace.
+- "validate/check folder/inspect project structure" means validate_project.
+- "prepare/convert/crop/split/normalize/downsample data" means prepare_data.
+- "configure training/training settings/augmentation/batch size" means configure_training.
+- "configure inference/inference settings/tiling/threshold" means configure_inference.
+- "logs/tensorboard/gpu/job status/monitor" means monitor_jobs.
+- "stop/cancel/kill the run/job/training/inference" means stop_runtime.
+- "too robotic", "less robotic", "sound more human", or feedback about chat tone
+  means style_feedback.
+- "go/open/switch to a screen" means navigate and set tab.
+- "what next/where are we/status/what is missing" means status.
+- If the user is only providing domain/context like "EM mitochondria accuracy",
+  use project_context_update and fill context.
+- Words like "quick" in "look at labels real quick" do NOT mean speed priority.
+- If the message is gibberish or truly unrelated, use clarify_next_job.
+
+Tabs for navigate: files, visualization, inference, training, project-progress, mask-proofreading.
+Context fields can be null: imaging_modality, target_structure, optimization_priority, voxel_size_nm, use_defaults.
+Voxel size is z,y,x nanometers, for example [40,4,4].
+
+Workflow state:
+{json.dumps(workflow_state, sort_keys=True)}
+
+User message:
+{query[:1000]!r}
+
+JSON schema:
+{{"intent":"...", "confidence":0.0, "tab":null, "context":{{"imaging_modality":null,"target_structure":null,"optimization_priority":null,"voxel_size_nm":null,"use_defaults":null}}, "reason":"short"}}
+""".strip()
+    try:
+        response = requests.post(
+            f"{base_url}/api/generate",
+            json={
+                "model": model,
+                "prompt": prompt,
+                "stream": False,
+                "think": False,
+                "format": "json",
+                "options": {"temperature": 0, "num_predict": 180},
+            },
+            timeout=timeout,
+        )
+        response.raise_for_status()
+        response_payload = response.json()
+        parsed = _extract_json_object(str(response_payload.get("response") or ""))
+    except Exception as exc:
+        append_app_event(
+            component="workflow_agent",
+            event="semantic_intent_failed",
+            level="WARNING",
+            message=str(exc),
+            workflow_id=workflow.id,
+            model=model,
+            query_preview=query[:160],
+        )
+        return {}
+
+    intent = str(parsed.get("intent") or "").strip().lower()
+    if intent not in SEMANTIC_WORKFLOW_INTENTS:
+        return {}
+    try:
+        confidence = float(parsed.get("confidence") or 0.0)
+    except (TypeError, ValueError):
+        confidence = 0.0
+    if confidence < float(os.getenv("PYTC_WORKFLOW_INTENT_MIN_CONFIDENCE", "0.45")):
+        return {}
+    context = parsed.get("context")
+    if not isinstance(context, dict):
+        context = {}
+    return {
+        "intent": intent,
+        "confidence": confidence,
+        "tab": parsed.get("tab"),
+        "context": {
+            key: value
+            for key, value in context.items()
+            if key
+            in {
+                "imaging_modality",
+                "target_structure",
+                "optimization_priority",
+                "voxel_size_nm",
+                "use_defaults",
+            }
+            and value is not None
+            and value != ""
+            and value != "null"
+        },
+        "reason": str(parsed.get("reason") or "")[:240],
+    }
+
+
+def _target_tab_from_semantic(
+    semantic_intent: Optional[str],
+    semantic_tab: Any,
+) -> Optional[Dict[str, str]]:
+    if semantic_intent != "navigate":
+        return None
+    tab = str(semantic_tab or "").strip().lower()
+    tab_specs = {
+        "files": ("Open Files", "Open project files and mounted datasets."),
+        "visualization": ("Open Visualize", "Open the image/label viewer."),
+        "inference": ("Open Run Model", "Open model inference setup."),
+        "training": ("Open Train Model", "Open model training setup."),
+        "monitoring": ("Open Train Model", "Open training runtime details and logs."),
+        "project-progress": (
+            "Open Workflow",
+            "Open the workflow overview and volume tracker.",
+        ),
+        "progress": ("Open Workflow", "Open the workflow overview and volume tracker."),
+        "mask-proofreading": (
+            "Open Proofread",
+            "Open the mask proofreading workbench.",
+        ),
+        "proofreading": ("Open Proofread", "Open the mask proofreading workbench."),
+    }
+    if tab not in tab_specs:
+        return None
+    normalized_tab = (
+        "mask-proofreading"
+        if tab == "proofreading"
+        else (
+            "project-progress"
+            if tab == "progress"
+            else "training" if tab == "monitoring" else tab
+        )
+    )
+    label, description = tab_specs[tab]
+    return {"tab": normalized_tab, "label": label, "description": description}
+
+
+def _latest_completed_inference_runs(
+    db: Session, workflow_id: int
+) -> List[WorkflowModelRun]:
+    return (
+        db.query(WorkflowModelRun)
+        .filter(
+            WorkflowModelRun.workflow_id == workflow_id,
+            WorkflowModelRun.run_type == "inference",
+            WorkflowModelRun.status == "completed",
+            WorkflowModelRun.output_path.isnot(None),
+        )
+        .order_by(WorkflowModelRun.created_at.asc(), WorkflowModelRun.id.asc())
+        .all()
+    )
+
+
+def _build_compute_evaluation_effects(
+    db: Session, workflow: WorkflowSession
+) -> tuple[Dict[str, Any], List[str]]:
+    inference_runs = _latest_completed_inference_runs(db, workflow.id)
+    baseline_run = inference_runs[0] if inference_runs else None
+    candidate_run = inference_runs[-1] if len(inference_runs) > 1 else None
+    baseline_path = baseline_run.output_path if baseline_run else None
+    candidate_path = (
+        candidate_run.output_path
+        if candidate_run
+        else (
+            workflow.inference_output_path
+            if workflow.inference_output_path != baseline_path
+            else None
+        )
+    )
+    ground_truth_path = (
+        workflow.corrected_mask_path or workflow.label_path or workflow.mask_path
+    )
+    missing = []
+    if not baseline_path:
+        missing.append("previous result")
+    if not candidate_path:
+        missing.append("new result")
+    if not ground_truth_path:
+        missing.append("reference mask")
+
+    effect = {
+        "show_workflow_context": True,
+        "workflow_action": {
+            "kind": "compute_evaluation",
+            "name": "workflow-before-after-evaluation",
+            "baseline_prediction_path": baseline_path,
+            "candidate_prediction_path": candidate_path,
+            "ground_truth_path": ground_truth_path,
+            "baseline_run_id": baseline_run.id if baseline_run else None,
+            "candidate_run_id": candidate_run.id if candidate_run else None,
+            "metadata": {"source": "workflow_agent"},
+        },
+        "refresh_insights": True,
+    }
+    return effect, missing
+
+
+def _build_export_bundle_effects() -> Dict[str, Any]:
+    return {
+        "show_workflow_context": True,
+        "workflow_action": {"kind": "export_bundle"},
+        "refresh_insights": True,
+    }
+
+
+def _format_greeting_response(
+    recommendation: WorkflowAgentRecommendationResponse,
+) -> str:
+    stage = recommendation.stage.replace("_", " ")
+    decision = _lower_first(_strip_sentence_period(recommendation.decision))
+    return (
+        f"Hey. We are still in {stage}. "
+        f"I would probably {decision}. "
+        "I can open the right screen, walk through what I am seeing, or help decide the next step."
+    )
+
+
+def _readiness_item(
+    item_id: str,
+    label: str,
+    complete: bool,
+    detail: str,
+    *,
+    severity: str = "default",
+) -> WorkflowReadinessItem:
+    return WorkflowReadinessItem(
+        id=item_id,
+        label=label,
+        complete=complete,
+        detail=detail,
+        severity=severity,
+    )
+
+
+def _event_count(events: List[WorkflowEvent], event_type: str) -> int:
+    return sum(1 for event in events if event.event_type == event_type)
+
+
+def _build_workflow_readiness(
+    workflow: WorkflowSession,
+    events: List[WorkflowEvent],
+    corrected_mask_path: Optional[str],
+) -> List[WorkflowReadinessItem]:
+    has_dataset = bool(
+        workflow.dataset_path
+        or workflow.image_path
+        or _event_count(events, "dataset.loaded") > 0
+    )
+    has_inference = bool(
+        workflow.inference_output_path
+        or _event_count(events, "inference.completed") > 0
+    )
+    has_proofreading = bool(
+        workflow.proofreading_session_id
+        or _event_count(events, "proofreading.session_loaded") > 0
+    )
+    has_edits = bool(
+        _event_count(events, "proofreading.mask_saved") > 0
+        or _event_count(events, "proofreading.instance_classified") > 0
+    )
+    has_corrections = bool(
+        corrected_mask_path or _event_count(events, "proofreading.masks_exported") > 0
+    )
+    has_training = bool(
+        workflow.training_output_path
+        or workflow.checkpoint_path
+        or _event_count(events, "training.completed") > 0
+    )
+    has_evaluation = bool(_event_count(events, "evaluation.completed") > 0)
+
+    return [
+        _readiness_item(
+            "dataset",
+            "Data mounted",
+            has_dataset,
+            workflow.dataset_path
+            or workflow.image_path
+            or "No source volume recorded.",
+            severity="warning",
+        ),
+        _readiness_item(
+            "inference",
+            "Prediction artifact",
+            has_inference,
+            workflow.inference_output_path or "Run inference or register a prediction.",
+            severity="warning",
+        ),
+        _readiness_item(
+            "proofreading",
+            "Proofreading session",
+            has_proofreading,
+            f"{_event_count(events, 'proofreading.instance_classified')} classifications logged.",
+        ),
+        _readiness_item(
+            "edits",
+            "Correction evidence",
+            has_edits,
+            f"{_event_count(events, 'proofreading.mask_saved')} mask saves logged.",
+        ),
+        _readiness_item(
+            "corrections",
+            "Corrected masks exported",
+            has_corrections,
+            corrected_mask_path or "Export masks before retraining.",
+            severity="warning",
+        ),
+        _readiness_item(
+            "training",
+            "Candidate model",
+            has_training,
+            workflow.checkpoint_path
+            or workflow.training_output_path
+            or "Launch retraining after corrections are staged.",
+        ),
+        _readiness_item(
+            "evaluation",
+            "Before/after evidence",
+            has_evaluation,
+            (
+                "Evaluation report recorded."
+                if has_evaluation
+                else "Run candidate inference and compare metrics."
+            ),
+        ),
+    ]
+
+
+def _workflow_agent_decision(
+    workflow: WorkflowSession,
+    readiness: List[WorkflowReadinessItem],
+    impact: WorkflowImpactPreviewResponse,
+    hotspots: List[WorkflowHotspotItem],
+    corrected_mask_path: Optional[str],
+) -> Dict[str, Any]:
+    incomplete = {item.id for item in readiness if not item.complete}
+    top_hotspot = hotspots[0] if hotspots else None
+    has_source_volume = bool(workflow.dataset_path or workflow.image_path)
+    has_mask_like = bool(
+        workflow.mask_path or workflow.label_path or workflow.inference_output_path
+    )
+    has_checkpoint = bool(workflow.checkpoint_path)
+
+    if "dataset" in incomplete and workflow.stage in {"setup", "visualization"}:
+        return {
+            "decision": "Choose the image and mask first.",
+            "rationale": "I need the data pair before I can route the next step.",
+            "next_stage": "setup",
+            "confidence": "high",
+        }
+    if workflow.stage in {"setup", "visualization"}:
+        if has_source_volume and has_mask_like:
+            return {
+                "decision": "Proofread this data.",
+                "rationale": "Image and mask-like data are ready for human review.",
+                "next_stage": "proofreading",
+                "confidence": "medium",
+            }
+        if has_source_volume and has_checkpoint:
+            return {
+                "decision": "Run the model on this image.",
+                "rationale": "Image and checkpoint are ready; I can infer routine settings.",
+                "next_stage": "inference",
+                "confidence": "medium",
+            }
+        if has_source_volume:
+            return {
+                "decision": "Add a checkpoint or mask/label.",
+                "rationale": "The project has an image volume, but no model output or editable mask yet.",
+                "next_stage": "setup",
+                "confidence": "high",
+            }
+        return {
+            "decision": "Proofread this data if the mask is ready.",
+            "rationale": "A human review pass is the fastest way to create useful edits.",
+            "next_stage": "proofreading",
+            "confidence": "medium",
+        }
+    if workflow.stage == "inference":
+        if "inference" in incomplete:
+            return {
+                "decision": "Run the model on this data.",
+                "rationale": "No prediction is recorded yet.",
+                "next_stage": "inference",
+                "confidence": "medium",
+            }
+        return {
+            "decision": "Proofread the model result.",
+            "rationale": "A prediction exists, so the useful next step is to review and fix it.",
+            "next_stage": "proofreading",
+            "confidence": "medium",
+        }
+    if workflow.stage == "proofreading":
+        if corrected_mask_path or impact.can_stage_retraining:
+            return {
+                "decision": "Use your saved edits for training.",
+                "rationale": "I can prepare the training step, but you approve it first.",
+                "next_stage": "retraining_staged",
+                "confidence": impact.confidence,
+            }
+        if top_hotspot:
+            return {
+                "decision": "Keep proofreading likely mistakes.",
+                "rationale": top_hotspot.summary,
+                "next_stage": "proofreading",
+                "confidence": impact.confidence,
+            }
+        return {
+            "decision": "Save or export edits before training.",
+            "rationale": "Training needs saved mask edits, not just a viewed slice.",
+            "next_stage": "proofreading",
+            "confidence": "low",
+        }
+    if workflow.stage == "retraining_staged":
+        return {
+            "decision": "Train on the saved edits.",
+            "rationale": "The edited masks are linked to the training screen.",
+            "next_stage": "evaluation",
+            "confidence": "medium",
+        }
+    if workflow.stage == "evaluation":
+        return {
+            "decision": "Compare the new result.",
+            "rationale": "The new checkpoint only matters if its prediction improves.",
+            "next_stage": "inference",
+            "confidence": "medium" if workflow.checkpoint_path else "low",
+        }
+    return {
+        "decision": "Check what is ready and choose the next step.",
+        "rationale": impact.summary,
+        "next_stage": workflow.stage,
+        "confidence": impact.confidence,
+    }
+
+
+def _build_workflow_agent_recommendation(
+    db: Session,
+    workflow: WorkflowSession,
+) -> WorkflowAgentRecommendationResponse:
+    event_rows = _event_rows(db, workflow.id)
+    event_responses = _event_list(db, workflow.id)
+    corrected_mask_path = workflow.corrected_mask_path or _latest_exported_mask_path(
+        db, workflow.id
+    )
+    hotspots = _compute_hotspots(workflow, event_rows)
+    impact = _compute_impact_preview(
+        workflow,
+        event_rows,
+        hotspots,
+        corrected_mask_path,
+    )
+    readiness = _build_workflow_readiness(workflow, event_rows, corrected_mask_path)
+    decision = _workflow_agent_decision(
+        workflow,
+        readiness,
+        impact,
+        hotspots,
+        corrected_mask_path,
+    )
+    actions = _build_default_agent_actions(workflow, corrected_mask_path)
+    primary_action = next(
+        (
+            action
+            for action in actions
+            if action.client_effects and action.variant == "primary"
+        ),
+        next((action for action in actions if action.client_effects), None),
+    )
+    commands = []
+    if primary_action:
+        commands.append(
+            _build_agent_command_block(
+                f"{primary_action.id}-command",
+                primary_action.label,
+                primary_action.description,
+                primary_action.client_effects,
+            )
+        )
+
+    blockers = [
+        item.detail
+        for item in readiness
+        if not item.complete and item.severity == "warning"
+    ]
+    if workflow.stage == "proofreading" and corrected_mask_path:
+        blockers = []
+    if workflow.stage == "retraining_staged":
+        blockers = []
+
+    return WorkflowAgentRecommendationResponse(
+        workflow_id=workflow.id,
+        generated_at=datetime.now(timezone.utc).isoformat(),
+        stage=workflow.stage,
+        decision=decision["decision"],
+        rationale=decision["rationale"],
+        confidence=decision["confidence"],
+        next_stage=decision["next_stage"],
+        can_act=bool(actions),
+        blockers=blockers[:3],
+        readiness=readiness,
+        top_hotspot=hotspots[0] if hotspots else None,
+        impact_preview=impact,
+        actions=actions,
+        commands=commands,
+    )
+
+
+def _workflow_path_present(value: Optional[str]) -> bool:
+    return bool(value and str(value).strip())
+
+
+def _latest_artifact_path(
+    artifacts: List[WorkflowArtifact],
+    *,
+    roles: Optional[set[str]] = None,
+    artifact_types: Optional[set[str]] = None,
+) -> Optional[str]:
+    for artifact in sorted(
+        artifacts,
+        key=lambda row: (
+            row.created_at or datetime.min.replace(tzinfo=timezone.utc),
+            row.id,
+        ),
+        reverse=True,
+    ):
+        if roles and artifact.role not in roles:
+            continue
+        if artifact_types and artifact.artifact_type not in artifact_types:
+            continue
+        if artifact.path:
+            return artifact.path
+        if artifact.uri:
+            return artifact.uri
+    return None
+
+
+def _latest_model_checkpoint(
+    model_versions: List[WorkflowModelVersion],
+    artifacts: List[WorkflowArtifact],
+) -> Optional[str]:
+    for version in sorted(
+        model_versions,
+        key=lambda row: (
+            row.created_at or datetime.min.replace(tzinfo=timezone.utc),
+            row.id,
+        ),
+        reverse=True,
+    ):
+        if version.checkpoint_path:
+            return version.checkpoint_path
+    return _latest_artifact_path(
+        artifacts,
+        roles={"candidate_checkpoint", "checkpoint"},
+        artifact_types={"model_checkpoint"},
+    )
+
+
+def _preflight_item(
+    item_id: str,
+    label: str,
+    *,
+    can_run: bool,
+    missing: Optional[List[str]] = None,
+    action: str,
+    risk_level: str = "normal",
+    status: Optional[str] = None,
+    policy_decision: Optional[Dict[str, Any]] = None,
+    blocking_reasons: Optional[List[Dict[str, Any]]] = None,
+    freshness: Optional[Dict[str, Any]] = None,
+) -> WorkflowPreflightItem:
+    missing = missing or []
+    resolved_status = status or ("ready" if can_run else "needs_input")
+    reasons = blocking_reasons or []
+    decision = policy_decision
+    if decision is None:
+        policy_blocking_required_approval = risk_level in {
+            "runs_job",
+            "controls_job",
+            "loads_editor",
+            "exports_evidence",
+            "writes_workflow_record",
+            "modifies_workspace",
+        }
+        decision = _policy_decision_payload(
+            "allowed" if can_run else "blocked",
+            requires_approval=policy_blocking_required_approval,
+            reason_code="ready" if can_run else "missing_inputs",
+            reason=(
+                "This action is ready" if can_run else "Required inputs are missing."
+            ),
+            blocking_reasons=reasons,
+        )
+    return WorkflowPreflightItem(
+        id=item_id,
+        label=label,
+        status=resolved_status,
+        can_run=can_run,
+        missing=missing,
+        action=action,
+        risk_level=risk_level,
+        policy_decision=decision,
+        blocking_reasons=reasons,
+        freshness=freshness or {},
+    )
+
+
+def _build_workflow_preflight(
+    db: Session,
+    workflow: WorkflowSession,
+) -> WorkflowPreflightResponse:
+    artifacts = (
+        db.query(WorkflowArtifact)
+        .filter(WorkflowArtifact.workflow_id == workflow.id)
+        .order_by(WorkflowArtifact.created_at.asc(), WorkflowArtifact.id.asc())
+        .all()
+    )
+    model_versions = (
+        db.query(WorkflowModelVersion)
+        .filter(WorkflowModelVersion.workflow_id == workflow.id)
+        .order_by(WorkflowModelVersion.created_at.asc(), WorkflowModelVersion.id.asc())
+        .all()
+    )
+    correction_sets = (
+        db.query(WorkflowCorrectionSet)
+        .filter(WorkflowCorrectionSet.workflow_id == workflow.id)
+        .order_by(
+            WorkflowCorrectionSet.created_at.asc(), WorkflowCorrectionSet.id.asc()
+        )
+        .all()
+    )
+    evaluation_results = (
+        db.query(WorkflowEvaluationResult)
+        .filter(WorkflowEvaluationResult.workflow_id == workflow.id)
+        .order_by(
+            WorkflowEvaluationResult.created_at.asc(), WorkflowEvaluationResult.id.asc()
+        )
+        .all()
+    )
+
+    completed_inference_runs = _latest_completed_inference_runs(db, workflow.id)
+    baseline_run = completed_inference_runs[0] if completed_inference_runs else None
+    candidate_run = (
+        completed_inference_runs[-1] if len(completed_inference_runs) > 1 else None
+    )
+
+    image_path = workflow.image_path or workflow.dataset_path
+    reference_path = workflow.label_path or workflow.mask_path
+    corrected_mask_path = (
+        workflow.corrected_mask_path
+        or _latest_exported_mask_path(db, workflow.id)
+        or (correction_sets[-1].corrected_mask_path if correction_sets else None)
+    )
+    checkpoint_path = workflow.checkpoint_path or _latest_model_checkpoint(
+        model_versions,
+        artifacts,
+    )
+    prediction_path = (
+        workflow.inference_output_path
+        or (
+            completed_inference_runs[-1].output_path
+            if completed_inference_runs
+            else None
+        )
+        or _latest_artifact_path(
+            artifacts,
+            roles={"prediction"},
+            artifact_types={"inference_output"},
+        )
+    )
+    baseline_path = baseline_run.output_path if baseline_run else prediction_path
+    candidate_path = (
+        candidate_run.output_path
+        if candidate_run
+        else (
+            workflow.inference_output_path
+            if workflow.inference_output_path
+            and workflow.inference_output_path != baseline_path
+            else None
+        )
+    )
+    ground_truth_path = reference_path or corrected_mask_path
+
+    has_image = _workflow_path_present(image_path)
+    requires_trusted_training = _workflow_requires_trusted_masks(workflow)
+    has_reference = _workflow_path_present(reference_path)
+    training_reference = _preferred_training_mask_path(
+        workflow,
+        require_trusted=requires_trusted_training,
+    )
+    has_mask_like = has_reference or _workflow_path_present(prediction_path)
+    has_checkpoint = _workflow_path_present(checkpoint_path)
+    has_correction = _workflow_path_present(corrected_mask_path)
+    has_training_target = _workflow_path_present(training_reference)
+    has_baseline = _workflow_path_present(baseline_path)
+    has_candidate = _workflow_path_present(candidate_path)
+    has_ground_truth = _workflow_path_present(ground_truth_path)
+    has_evaluation = bool(evaluation_results)
+
+    inference_missing = []
+    if not has_image:
+        inference_missing.append("image volume")
+    if not has_checkpoint:
+        inference_missing.append("checkpoint")
+
+    proofreading_missing = []
+    if not has_image:
+        proofreading_missing.append("image volume")
+    if not has_mask_like:
+        proofreading_missing.append("mask, label, or prediction")
+
+    training_missing = []
+    if not has_image:
+        training_missing.append("image volume")
+    if not has_training_target:
+        training_missing.append("label or corrected mask")
+
+    evaluation_missing = []
+    if not has_baseline:
+        evaluation_missing.append("previous result")
+    if not has_candidate:
+        evaluation_missing.append("new result")
+    if not has_ground_truth:
+        evaluation_missing.append("reference mask")
+
+    def _missing_reasons(
+        item_id: str, missing_fields: List[str]
+    ) -> List[Dict[str, Any]]:
+        return [
+            _policy_blocking_reason(
+                f"{item_id}.missing_{_reason_code_from_label(field)}",
+                f"{field.capitalize()} is required.",
+                scope="workflow_state",
+                field=field,
+            )
+            for field in missing_fields
+        ]
+
+    items = [
+        _preflight_item(
+            "project_setup",
+            "Project data",
+            can_run=has_image,
+            missing=[] if has_image else ["image volume"],
+            policy_decision=_policy_decision_payload(
+                "allowed" if has_image else "blocked",
+                requires_approval=False,
+                reason_code=(
+                    "project_data_ready" if has_image else "project_data_missing"
+                ),
+                reason=(
+                    "Project source is configured."
+                    if has_image
+                    else "Project image input is missing."
+                ),
+                blocking_reasons=_missing_reasons(
+                    "project_setup", [] if has_image else ["image volume"]
+                ),
+            ),
+            blocking_reasons=_missing_reasons(
+                "project_setup", [] if has_image else ["image volume"]
+            ),
+            freshness=_resource_freshness_payload(
+                scope="project_data",
+                required_fields=["image volume"],
+                missing_fields=[] if has_image else ["image volume"],
+            ),
+            action=(
+                "Use this project."
+                if has_image
+                else "Mount a folder or upload an image volume."
+            ),
+            risk_level="view_only",
+        ),
+        _preflight_item(
+            "visualization",
+            "Visualize data",
+            can_run=has_image,
+            missing=[] if has_image else ["image volume"],
+            policy_decision=_policy_decision_payload(
+                "allowed" if has_image else "blocked",
+                requires_approval=False,
+                reason_code=(
+                    "visualization_ready"
+                    if has_image
+                    else "visualization_missing_inputs"
+                ),
+                reason=(
+                    "Visualization inputs are available."
+                    if has_image
+                    else "Image input is missing for visualization."
+                ),
+                blocking_reasons=_missing_reasons(
+                    "visualization", [] if has_image else ["image volume"]
+                ),
+            ),
+            blocking_reasons=_missing_reasons(
+                "visualization", [] if has_image else ["image volume"]
+            ),
+            freshness=_resource_freshness_payload(
+                scope="visualization",
+                required_fields=["image volume"],
+                missing_fields=[] if has_image else ["image volume"],
+            ),
+            action="Open the image volume for inspection.",
+            risk_level="view_only",
+        ),
+        _preflight_item(
+            "inference",
+            "Run model",
+            can_run=has_image and has_checkpoint,
+            missing=inference_missing,
+            policy_decision=_policy_decision_payload(
+                "allowed" if has_image and has_checkpoint else "blocked",
+                requires_approval=True,
+                reason_code=(
+                    "inference_ready"
+                    if has_image and has_checkpoint
+                    else "inference_missing_inputs"
+                ),
+                reason=(
+                    "Inference inputs are complete."
+                    if has_image and has_checkpoint
+                    else "Image volume and checkpoint are required."
+                ),
+                blocking_reasons=_missing_reasons("inference", inference_missing),
+            ),
+            blocking_reasons=_missing_reasons("inference", inference_missing),
+            freshness=_resource_freshness_payload(
+                scope="inference",
+                required_fields=["image volume", "checkpoint"],
+                missing_fields=inference_missing,
+            ),
+            action=(
+                "Run inference with inferred defaults."
+                if has_image and has_checkpoint
+                else "Add a checkpoint before running inference."
+            ),
+            risk_level="runs_job",
+        ),
+        _preflight_item(
+            "proofreading",
+            "Proofread masks",
+            can_run=has_image and has_mask_like,
+            missing=proofreading_missing,
+            policy_decision=_policy_decision_payload(
+                "allowed" if has_image and has_mask_like else "blocked",
+                requires_approval=False,
+                reason_code=(
+                    "proofreading_ready"
+                    if has_image and has_mask_like
+                    else "proofreading_missing_inputs"
+                ),
+                reason=(
+                    "Image and mask data are available for proofreading."
+                    if has_image and has_mask_like
+                    else "Image and mask-like input are required."
+                ),
+                blocking_reasons=_missing_reasons("proofreading", proofreading_missing),
+            ),
+            blocking_reasons=_missing_reasons("proofreading", proofreading_missing),
+            freshness=_resource_freshness_payload(
+                scope="proofreading",
+                required_fields=["image volume", "mask, label, or prediction"],
+                missing_fields=proofreading_missing,
+            ),
+            action=(
+                "Open Proofread on the current image/mask pair."
+                if has_image and has_mask_like
+                else "Add a mask, label, or prediction to proofread."
+            ),
+            risk_level="writes_record",
+        ),
+        _preflight_item(
+            "training",
+            "Use edits for training",
+            can_run=has_image and has_training_target,
+            missing=training_missing,
+            policy_decision=_policy_decision_payload(
+                "allowed" if has_image and has_training_target else "blocked",
+                requires_approval=True,
+                reason_code=(
+                    "training_ready"
+                    if has_image and has_training_target
+                    else "training_missing_inputs"
+                ),
+                reason=(
+                    "Training inputs are complete."
+                    if has_image and has_training_target
+                    else "Image and labels or corrected masks are required."
+                ),
+                blocking_reasons=_missing_reasons("training", training_missing),
+            ),
+            blocking_reasons=_missing_reasons("training", training_missing),
+            freshness=_resource_freshness_payload(
+                scope="training",
+                required_fields=["image volume", "label or corrected mask"],
+                missing_fields=training_missing,
+            ),
+            action=(
+                "Train with inferred defaults from the current labels/corrections."
+                if has_image and has_training_target
+                else "Add a label or save corrected masks first."
+            ),
+            risk_level="runs_job",
+        ),
+        _preflight_item(
+            "evaluation",
+            "Compare results",
+            can_run=has_baseline and has_candidate and has_ground_truth,
+            missing=evaluation_missing,
+            policy_decision=_policy_decision_payload(
+                (
+                    "allowed"
+                    if has_baseline and has_candidate and has_ground_truth
+                    else "blocked"
+                ),
+                requires_approval=True,
+                reason_code=(
+                    "evaluation_ready"
+                    if has_baseline and has_candidate and has_ground_truth
+                    else "evaluation_missing_inputs"
+                ),
+                reason=(
+                    "Evaluation inputs are available."
+                    if has_baseline and has_candidate and has_ground_truth
+                    else "Previous result, new result, and reference mask are required."
+                ),
+                blocking_reasons=_missing_reasons("evaluation", evaluation_missing),
+            ),
+            blocking_reasons=_missing_reasons("evaluation", evaluation_missing),
+            freshness=_resource_freshness_payload(
+                scope="evaluation",
+                required_fields=["previous result", "new result", "reference mask"],
+                missing_fields=evaluation_missing,
+            ),
+            action=(
+                "Compute before/after metrics."
+                if has_baseline and has_candidate and has_ground_truth
+                else "Run two model outputs and select a reference mask."
+            ),
+            risk_level="view_only",
+            status="completed" if has_evaluation else None,
+        ),
+    ]
+
+    if not has_image:
+        overall_status = "needs_project"
+        summary = "Choose an image volume to start a workable project."
+    elif has_evaluation:
+        overall_status = "evaluated"
+        summary = "Before/after evaluation evidence is recorded."
+    elif has_baseline and has_candidate and has_ground_truth:
+        overall_status = "ready_to_compare"
+        summary = "Ready to compare previous and new segmentation results."
+    elif has_correction:
+        overall_status = "ready_to_train"
+        summary = "Corrected masks are available; training can use them next."
+    elif has_image and has_mask_like:
+        overall_status = "ready_to_proofread"
+        summary = "Image and mask-like data are ready for proofreading."
+    elif has_image and has_checkpoint:
+        overall_status = "ready_to_infer"
+        summary = "Image and checkpoint are ready for inference."
+    else:
+        overall_status = "image_only"
+        summary = "Image volume is loaded; add a checkpoint or mask/label next."
+
+    return WorkflowPreflightResponse(
+        workflow_id=workflow.id,
+        generated_at=datetime.now(timezone.utc).isoformat(),
+        overall_status=overall_status,
+        summary=summary,
+        items=items,
+    )
+
+
+def _format_workflow_agent_response(
+    recommendation: WorkflowAgentRecommendationResponse,
+) -> str:
+    ready_count = sum(1 for item in recommendation.readiness if item.complete)
+    total_count = len(recommendation.readiness)
+    decision = _strip_sentence_period(recommendation.decision)
+    rationale = _lower_first(_strip_sentence_period(recommendation.rationale))
+    lines = [f"I would probably start with {decision}."]
+    if rationale:
+        lines.append(f"That fits because {rationale}.")
+    if total_count:
+        lines.append(
+            f"I checked the workflow state: {ready_count}/{total_count} pieces look ready."
+        )
+    if recommendation.blockers:
+        lines.append(
+            f"The only catch is {_lower_first(_strip_sentence_period(recommendation.blockers[0]))}."
+        )
+    return " ".join(lines)
+
+
+def _strip_sentence_period(text: str) -> str:
+    return str(text or "").strip().rstrip(".")
+
+
+def _lower_first(text: str) -> str:
+    text = str(text or "").strip()
+    if not text:
+        return text
+    return text[:1].lower() + text[1:]
+
+
+def _humanize_agent_response(response: str) -> str:
+    lines = [line.strip() for line in str(response or "").splitlines() if line.strip()]
+    if not lines:
+        return response
+
+    buckets: Dict[str, List[str]] = {
+        "action": [],
+        "why": [],
+        "current": [],
+        "blocker": [],
+        "watch": [],
+        "ready": [],
+        "other": [],
+    }
+    for line in lines:
+        lowered = line.lower()
+        if lowered.startswith("do this:"):
+            buckets["action"].append(line.split(":", 1)[1].strip())
+        elif lowered.startswith("why:"):
+            buckets["why"].append(line.split(":", 1)[1].strip())
+        elif lowered.startswith("current read:"):
+            buckets["current"].append(line.split(":", 1)[1].strip())
+        elif lowered.startswith("blocker:") or lowered.startswith("current gap:"):
+            buckets["blocker"].append(line.split(":", 1)[1].strip())
+        elif lowered.startswith("watch out:"):
+            buckets["watch"].append(line.split(":", 1)[1].strip())
+        elif lowered.startswith("ready:"):
+            buckets["ready"].append(line)
+        else:
+            buckets["other"].append(line)
+
+    if not any(
+        buckets[key]
+        for key in ("action", "why", "current", "blocker", "watch", "ready")
+    ):
+        return response
+
+    parts: List[str] = []
+    if buckets["current"]:
+        current = _lower_first(_strip_sentence_period(buckets["current"][0]))
+        parts.append(f"Right now I would focus on {current}.")
+    if buckets["action"]:
+        action = _strip_sentence_period(buckets["action"][0])
+        if action.lower().startswith(
+            (
+                "open ",
+                "show ",
+                "view ",
+                "run ",
+                "proofread ",
+                "train ",
+                "compute ",
+                "export ",
+                "stop ",
+            )
+        ):
+            parts.append(f"I can {_lower_first(action)}.")
+        else:
+            parts.append(f"I would probably start with {action}.")
+    if buckets["why"]:
+        parts.append(
+            f"That fits because {_lower_first(_strip_sentence_period(buckets['why'][0]))}."
+        )
+    if buckets["watch"]:
+        parts.append(f"One caveat: {_strip_sentence_period(buckets['watch'][0])}.")
+    if buckets["blocker"]:
+        parts.append(
+            f"The thing blocking that is {_lower_first(_strip_sentence_period(buckets['blocker'][0]))}."
+        )
+    if buckets["ready"]:
+        ready = buckets["ready"][0].split(":", 1)[-1].strip()
+        parts.append(f"Readiness: {ready}")
+    parts.extend(buckets["other"])
+    return " ".join(parts)
+
+
+def _short_path_label(path: Optional[str]) -> str:
+    if not path:
+        return "not set"
+    parts = str(path).rstrip("/").split("/")
+    return parts[-1] or str(path)
+
+
+def _workflow_volume_pair_discovery(workflow: WorkflowSession) -> Dict[str, Any]:
+    metadata = decode_json(workflow.metadata_json)
+    stored_discovery = (
+        metadata.get("volume_pair_discovery") if isinstance(metadata, dict) else None
+    )
+    image_path = workflow.image_path or workflow.dataset_path
+    label_path = (
+        workflow.label_path
+        or workflow.mask_path
+        or workflow.inference_output_path
+        or workflow.corrected_mask_path
+    )
+    if not image_path:
+        return {"pair_count": 0, "pairs": []}
+    try:
+        image = pathlib.Path(str(image_path))
+        label = pathlib.Path(str(label_path)) if label_path else None
+        if not image.exists() or (label is not None and not label.exists()):
+            return (
+                stored_discovery
+                if isinstance(stored_discovery, dict)
+                else {"pair_count": 0, "pairs": []}
+            )
+        discovery = discover_neuroglancer_volume_pairs(image, label, max_pairs=12)
+        if isinstance(discovery, dict) and discovery.get("pair_count"):
+            return discovery
+        return (
+            stored_discovery
+            if isinstance(stored_discovery, dict)
+            else {"pair_count": 0, "pairs": []}
+        )
+    except Exception as exc:
+        append_app_event(
+            component="workflow_agent",
+            event="workflow_volume_pair_discovery_failed",
+            level="WARNING",
+            message=str(exc),
+            workflow_id=workflow.id,
+            image_path=str(image_path),
+            label_path=str(label_path) if label_path else None,
+        )
+        return (
+            stored_discovery
+            if isinstance(stored_discovery, dict)
+            else {"pair_count": 0, "pairs": []}
+        )
+
+
+def _normalize_volume_path_for_match(path_value: Optional[str]) -> str:
+    if not path_value:
+        return ""
+    return os.path.normcase(os.path.abspath(str(path_value)))
+
+
+def _looks_like_file_path(path_value: Optional[str]) -> bool:
+    text = str(path_value or "").strip()
+    if not text or text.endswith("/"):
+        return False
+    suffix = pathlib.Path(text).suffix
+    return bool(suffix)
+
+
+def _find_matching_volume_pair(
+    pairs: List[Dict[str, Any]],
+    *,
+    image_path: Optional[str],
+    label_path: Optional[str],
+) -> Optional[Dict[str, Any]]:
+    image_norm = _normalize_volume_path_for_match(image_path)
+    label_norm = _normalize_volume_path_for_match(label_path)
+    for pair in pairs:
+        pair_image = _normalize_volume_path_for_match(pair.get("image_path"))
+        pair_label = _normalize_volume_path_for_match(pair.get("label_path"))
+        if image_norm and pair_image and image_norm == pair_image:
+            return pair
+        if label_norm and pair_label and label_norm == pair_label:
+            return pair
+    return None
+
+
+def _select_visualization_pair(
+    workflow: WorkflowSession,
+    pair_discovery: Dict[str, Any],
+) -> Optional[Dict[str, Any]]:
+    pairs = pair_discovery.get("pairs") or []
+    image_path = workflow.image_path or workflow.dataset_path
+    label_path = (
+        workflow.label_path
+        or workflow.mask_path
+        or workflow.inference_output_path
+        or workflow.corrected_mask_path
+    )
+    if _looks_like_file_path(image_path) and _looks_like_file_path(label_path):
+        return {"image_path": str(image_path), "label_path": str(label_path)}
+    if _looks_like_file_path(image_path):
+        matched_pair = _find_matching_volume_pair(
+            pairs,
+            image_path=str(image_path),
+            label_path=label_path if _looks_like_file_path(label_path) else None,
+        )
+        if matched_pair:
+            return matched_pair
+        return {"image_path": str(image_path), "label_path": label_path}
+    if _looks_like_file_path(label_path):
+        matched_pair = _find_matching_volume_pair(
+            pairs,
+            image_path=image_path,
+            label_path=str(label_path),
+        )
+        if matched_pair:
+            return matched_pair
+        return {"image_path": image_path, "label_path": str(label_path)}
+    return _find_matching_volume_pair(
+        pairs,
+        image_path=image_path,
+        label_path=label_path,
+    ) or (pairs[0] if pairs else None)
+
+
+def _normalize_absolute_path(value: Optional[str]) -> str:
+    if not value:
+        return ""
+    return os.path.abspath(os.path.expanduser(str(value)))
+
+
+def _absolute_project_path(root_path: str, path_value: Optional[str]) -> str:
+    if not path_value:
+        return ""
+    text = str(path_value)
+    if os.path.isabs(text):
+        return _normalize_absolute_path(text)
+    return _normalize_absolute_path(os.path.join(root_path, text))
+
+
+def _path_is_within(path_value: Optional[str], root_value: Optional[str]) -> bool:
+    path = _normalize_absolute_path(path_value)
+    root = _normalize_absolute_path(root_value)
+    if not path or not root:
+        return False
+    try:
+        return os.path.commonpath([path, root]) == root
+    except ValueError:
+        return False
+
+
+def _workflow_path_values(workflow: WorkflowSession) -> List[str]:
+    return [
+        str(value)
+        for value in [
+            workflow.dataset_path,
+            workflow.image_path,
+            workflow.label_path,
+            workflow.mask_path,
+            workflow.inference_output_path,
+            workflow.corrected_mask_path,
+            workflow.checkpoint_path,
+            workflow.config_path,
+        ]
+        if value
+    ]
+
+
+def _mounted_project_roots(db: Session, user_id: int) -> List[Dict[str, Any]]:
+    rows = (
+        db.query(auth_models.File)
+        .filter(
+            auth_models.File.user_id == user_id,
+            auth_models.File.path == "root",
+            auth_models.File.is_folder.is_(True),
+            auth_models.File.physical_path.isnot(None),
+        )
+        .order_by(auth_models.File.name.asc())
+        .all()
+    )
+    roots = []
+    for row in rows:
+        root_path = _normalize_absolute_path(row.physical_path)
+        if root_path and os.path.isdir(root_path):
+            roots.append(
+                {
+                    "path": root_path,
+                    "name": row.name,
+                    "mounted_root_id": row.id,
+                    "source": "mounted_root",
+                }
+            )
+    return roots
+
+
+def _workflow_project_root_candidates(
+    db: Session, workflow: WorkflowSession, user_id: int
+) -> List[Dict[str, Any]]:
+    candidates: List[Dict[str, Any]] = []
+    seen_paths: set[str] = set()
+
+    def add_candidate(path_value: Optional[str], source: str, **extra: Any) -> None:
+        root_path = _normalize_absolute_path(path_value)
+        if not root_path or root_path in seen_paths or not os.path.isdir(root_path):
+            return
+        seen_paths.add(root_path)
+        candidates.append({"path": root_path, "source": source, **extra})
+
+    if workflow.dataset_path and os.path.isdir(
+        _normalize_absolute_path(workflow.dataset_path)
+    ):
+        add_candidate(workflow.dataset_path, "workflow_dataset_path")
+
+    derived_root = _derive_mount_project_path(workflow)
+    if derived_root and os.path.isdir(_normalize_absolute_path(derived_root)):
+        add_candidate(derived_root, "derived_workflow_root")
+
+    mounted_roots = _mounted_project_roots(db, user_id)
+    workflow_paths = [
+        _normalize_absolute_path(path) for path in _workflow_path_values(workflow)
+    ]
+    for root in mounted_roots:
+        root_path = root["path"]
+        if any(_path_is_within(path, root_path) for path in workflow_paths):
+            add_candidate(
+                root_path,
+                "mounted_root_match",
+                name=root.get("name"),
+                mounted_root_id=root.get("mounted_root_id"),
+            )
+
+    if not candidates and len(mounted_roots) == 1:
+        root = mounted_roots[0]
+        add_candidate(
+            root["path"],
+            "single_mounted_root",
+            name=root.get("name"),
+            mounted_root_id=root.get("mounted_root_id"),
+        )
+
+    return candidates[:3]
+
+
+def _observed_volume_sets_from_profile(
+    root_path: str, profile: Dict[str, Any]
+) -> List[Dict[str, Any]]:
+    volume_sets = profile.get("volume_sets") or profile.get("schema", {}).get(
+        "volume_sets"
+    )
+    if not isinstance(volume_sets, list):
+        return []
+
+    observed_sets: List[Dict[str, Any]] = []
+    for item in volume_sets[:8]:
+        if not isinstance(item, dict):
+            continue
+        examples = []
+        for example in item.get("examples") or []:
+            if not isinstance(example, dict):
+                continue
+            image_path = _absolute_project_path(root_path, example.get("image"))
+            label_path = _absolute_project_path(root_path, example.get("label"))
+            examples.append(
+                {
+                    "image": example.get("image"),
+                    "label": example.get("label"),
+                    "image_path": image_path,
+                    "label_path": label_path,
+                }
+            )
+        image_root_path = _absolute_project_path(root_path, item.get("image_root"))
+        label_root_path = _absolute_project_path(root_path, item.get("label_root"))
+        primary_example = examples[0] if examples else {}
+        observed_sets.append(
+            {
+                "id": item.get("id") or f"set-{len(observed_sets) + 1}",
+                "name": item.get("name") or item.get("image_root") or "volume set",
+                "project_root": root_path,
+                "image_root": item.get("image_root"),
+                "label_root": item.get("label_root"),
+                "image_root_path": image_root_path,
+                "label_root_path": label_root_path,
+                "image_path": primary_example.get("image_path") or image_root_path,
+                "label_path": primary_example.get("label_path") or label_root_path,
+                "image_count": int(item.get("image_count") or 0),
+                "label_count": int(item.get("label_count") or 0),
+                "pair_count": int(item.get("pair_count") or 0),
+                "examples": examples[:3],
+            }
+        )
+    return observed_sets
+
+
+def _project_top_level_entries(
+    root_path: str, *, max_entries: int = 12
+) -> List[Dict[str, Any]]:
+    try:
+        children = sorted(
+            pathlib.Path(root_path).iterdir(),
+            key=lambda item: (not item.is_dir(), item.name.lower()),
+        )
+    except OSError:
+        return []
+    entries = []
+    for child in children[:max_entries]:
+        entries.append(
+            {
+                "name": child.name,
+                "kind": "folder" if child.is_dir() else "file",
+            }
+        )
+    return entries
+
+
+def _is_current_observed_volume_set(
+    workflow: WorkflowSession, volume_set: Dict[str, Any]
+) -> bool:
+    image_path = workflow.image_path or workflow.dataset_path
+    label_path = workflow.label_path or workflow.mask_path
+    if image_path:
+        return _path_is_within(
+            image_path, volume_set.get("image_root_path")
+        ) or _normalize_absolute_path(image_path) == _normalize_absolute_path(
+            volume_set.get("image_path")
+        )
+    if label_path and volume_set.get("label_root_path"):
+        return _path_is_within(label_path, volume_set.get("label_root_path"))
+    return False
+
+
+def _observe_workflow_project(
+    db: Session, workflow: WorkflowSession, user_id: int
+) -> Dict[str, Any]:
+    roots = _workflow_project_root_candidates(db, workflow, user_id)
+    observed_roots: List[Dict[str, Any]] = []
+    observed_sets: List[Dict[str, Any]] = []
+    errors: List[Dict[str, str]] = []
+
+    for root in roots:
+        root_path = root["path"]
+        try:
+            profile = _scan_project_profile(root_path)
+        except Exception as exc:
+            errors.append({"path": root_path, "error": type(exc).__name__})
+            append_app_event(
+                component="workflow_agent",
+                event="project_observation_scan_failed",
+                level="WARNING",
+                message=str(exc),
+                workflow_id=workflow.id,
+                project_root=root_path,
+            )
+            continue
+
+        root_sets = _observed_volume_sets_from_profile(root_path, profile)
+        for volume_set in root_sets:
+            volume_set["is_current"] = _is_current_observed_volume_set(
+                workflow, volume_set
+            )
+        observed_sets.extend(root_sets)
+        observed_roots.append(
+            {
+                "path": root_path,
+                "name": root.get("name") or pathlib.Path(root_path).name,
+                "source": root.get("source"),
+                "mounted_root_id": root.get("mounted_root_id"),
+                "counts": profile.get("counts") or {},
+                "volume_set_count": len(root_sets),
+                "top_level_entries": _project_top_level_entries(root_path),
+                "context_hints": profile.get("context_hints") or {},
+            }
+        )
+
+    observation = {
+        "observed_at": datetime.now(timezone.utc).isoformat(),
+        "roots": observed_roots,
+        "volume_sets": observed_sets,
+        "errors": errors,
+    }
+    metadata = decode_json(workflow.metadata_json)
+    metadata["project_observation"] = {
+        "observed_at": observation["observed_at"],
+        "roots": observed_roots,
+        "volume_sets": [
+            {
+                key: volume_set.get(key)
+                for key in [
+                    "id",
+                    "name",
+                    "project_root",
+                    "image_root",
+                    "label_root",
+                    "image_path",
+                    "label_path",
+                    "image_count",
+                    "label_count",
+                    "pair_count",
+                    "is_current",
+                ]
+            }
+            for volume_set in observed_sets[:8]
+        ],
+        "errors": errors,
+    }
+    workflow.metadata_json = encode_json(metadata)
+    append_app_event(
+        component="workflow_agent",
+        event="project_observed",
+        level="INFO",
+        message="Workflow agent refreshed read-only project observation.",
+        workflow_id=workflow.id,
+        root_count=len(observed_roots),
+        volume_set_count=len(observed_sets),
+        roots=[root.get("path") for root in observed_roots],
+    )
+    return observation
+
+
+def _query_wants_alternate_volume_set(lower_query: str) -> bool:
+    if re.search(
+        r"\b(?:another|other|different|alternate|next|second)\b.{0,48}\b(?:set|pair|volume set|image/seg|image and seg)\b",
+        lower_query,
+    ):
+        return True
+    return _query_has_relaxed(
+        lower_query,
+        [
+            "another set",
+            "another pair",
+            "other set",
+            "other pair",
+            "different set",
+            "different pair",
+            "alternate set",
+            "alternate pair",
+            "next set",
+            "next pair",
+            "second set",
+            "second pair",
+            "look for another",
+            "find another",
+        ],
+    )
+
+
+def _select_observed_volume_set(
+    observation: Dict[str, Any],
+    *,
+    prefer_alternate: bool = False,
+) -> Optional[Dict[str, Any]]:
+    volume_sets = [
+        item for item in observation.get("volume_sets") or [] if isinstance(item, dict)
+    ]
+    if not volume_sets:
+        return None
+    if prefer_alternate:
+        for volume_set in volume_sets:
+            if not volume_set.get("is_current"):
+                return volume_set
+        return None
+    for volume_set in volume_sets:
+        if volume_set.get("is_current"):
+            return volume_set
+    return volume_sets[0]
+
+
+def _query_wants_project_file_overview(lower_query: str) -> bool:
+    return bool(
+        re.search(r"\bwhat\b.{0,40}\bfiles?\b", lower_query)
+        or re.search(r"\bwhat\b.{0,40}\b(?:folder|directory)\b", lower_query)
+        or re.search(
+            r"\b(?:list|show|describe|explain)\b.{0,40}\bfiles?\b", lower_query
+        )
+        or re.search(r"\b(?:inside|in)\b.{0,24}\b(?:folder|directory)\b", lower_query)
+    )
+
+
+def _format_project_files_response(observation: Dict[str, Any]) -> str:
+    roots = observation.get("roots") or []
+    volume_sets = observation.get("volume_sets") or []
+    if not roots:
+        return (
+            "I do not see a mounted project folder yet. Mount or choose a project "
+            "directory and I can inspect the files from there."
+        )
+
+    root = roots[0]
+    root_name = root.get("name") or pathlib.Path(str(root.get("path") or "")).name
+    entries = root.get("top_level_entries") or []
+    entry_names = [
+        (
+            f"{entry.get('name')}/"
+            if entry.get("kind") == "folder"
+            else str(entry.get("name"))
+        )
+        for entry in entries[:8]
+        if entry.get("name")
+    ]
+    counts = root.get("counts") or {}
+
+    lines = [
+        f"I checked `{root_name}`. At the top level I see {', '.join(entry_names) or 'no indexed files yet'}."
+    ]
+    useful_bits = []
+    if counts.get("image"):
+        useful_bits.append(f"{counts.get('image')} image volume(s)")
+    if counts.get("label"):
+        useful_bits.append(f"{counts.get('label')} mask/label volume(s)")
+    if counts.get("prediction"):
+        useful_bits.append(f"{counts.get('prediction')} prediction/output file(s)")
+    if counts.get("config"):
+        useful_bits.append(f"{counts.get('config')} config file(s)")
+    if counts.get("checkpoint"):
+        useful_bits.append(f"{counts.get('checkpoint')} checkpoint(s)")
+    if useful_bits:
+        lines.append(
+            "The useful workflow pieces look like " + ", ".join(useful_bits) + "."
+        )
+
+    if volume_sets:
+        set_summaries = []
+        for item in volume_sets[:3]:
+            set_summaries.append(
+                f"{item.get('name') or 'volume set'}"
+                f" ({item.get('image_count') or 0} images, {item.get('label_count') or 0} labels)"
+            )
+        lines.append("I also found " + "; ".join(set_summaries) + ".")
+    lines.append(
+        "Ask me to open one of those sets and I can route it straight into Visualize."
+    )
+    return "\n".join(lines)
+
+
+PROJECT_PROGRESS_STATUS_DEFINITIONS = {
+    "ground_truth": "Fully good: has a proofread, corrected, curated, or ground-truth segmentation.",
+    "needs_proofreading": "Has a segmentation or mask, but it is not confirmed as proofread ground truth.",
+    "missing_segmentation": "Has image data, but no matching segmentation was found.",
+    "ignored": "Excluded from the active progress denominator.",
+}
+PROJECT_PROGRESS_CANONICAL_STATUS = {
+    "ground_truth": {
+        "status": "proofread_ground_truth",
+        "label": "Proofread ground truth",
+    },
+    "needs_proofreading": {
+        "status": "draft_needs_proofreading",
+        "label": "Draft mask needs proofreading",
+    },
+    "missing_segmentation": {
+        "status": "image_only",
+        "label": "Image only",
+    },
+    "ignored": {
+        "status": "ignored",
+        "label": "Ignored",
+    },
+}
+WORKFLOW_VOLUME_STATE_SCHEMA_VERSION = "workflow-volume-state/v2"
+WORKFLOW_VOLUME_ANNOTATION_STATES = {
+    "proofread_ground_truth": "Proofread ground truth",
+    "draft_needs_proofreading": "Draft mask needs proofreading",
+    "image_only": "Image only",
+    "prediction_available": "Prediction available",
+    "ignored": "Ignored",
+}
+WORKFLOW_VOLUME_ROLE_STATES = {
+    "training_source": "Training source",
+    "proofreading_target": "Proofreading target",
+    "inference_target": "Inference target",
+    "evaluation_target": "Evaluation target",
+    "excluded": "Excluded",
+    "unassigned": "Unassigned",
+}
+WORKFLOW_VOLUME_EXECUTION_STATES = {
+    "idle": "Idle",
+    "ready": "Ready",
+    "queued": "Queued",
+    "running": "Running",
+    "completed": "Completed",
+    "failed": "Failed",
+    "blocked": "Blocked",
+}
+PROJECT_PROGRESS_LEGACY_TO_COMPOSITE = {
+    "ground_truth": {
+        "annotation_state": "proofread_ground_truth",
+        "role_state": "training_source",
+        "execution_state": "ready",
+    },
+    "needs_proofreading": {
+        "annotation_state": "draft_needs_proofreading",
+        "role_state": "proofreading_target",
+        "execution_state": "ready",
+    },
+    "missing_segmentation": {
+        "annotation_state": "image_only",
+        "role_state": "inference_target",
+        "execution_state": "ready",
+    },
+    "ignored": {
+        "annotation_state": "ignored",
+        "role_state": "excluded",
+        "execution_state": "idle",
+    },
+}
+PROJECT_PROGRESS_COMPOSITE_TO_LEGACY = {
+    "proofread_ground_truth": "ground_truth",
+    "draft_needs_proofreading": "needs_proofreading",
+    "image_only": "missing_segmentation",
+    "prediction_available": "needs_proofreading",
+    "ignored": "ignored",
+}
+PROJECT_PROGRESS_GROUND_TRUTH_MARKERS = {
+    "corrected",
+    "curated",
+    "expert",
+    "ground",
+    "groundtruth",
+    "gt",
+    "proofread",
+    "proofreaded",
+    "truth",
+    "verified",
+}
+
+
+def _project_progress_pair_key(path_value: Optional[str]) -> str:
+    name = pathlib.Path(str(path_value or "")).name.lower()
+    extension = _project_extension(name)
+    if extension:
+        name = name[: -len(extension)]
+    replacements = (
+        "ground_truth",
+        "groundtruth",
+        "proofread",
+        "corrected",
+        "curated",
+        "expert",
+        "consensus",
+        "image",
+        "images",
+        "im",
+        "img",
+        "raw",
+        "volume",
+        "vol",
+        "label",
+        "labels",
+        "mask",
+        "masks",
+        "segmentation",
+        "seg",
+        "mito",
+        "gt",
+    )
+    for token in replacements:
+        name = re.sub(rf"(^|[_\-\s]){re.escape(token)}([_\-\s]|$)", "_", name)
+    return re.sub(r"[^a-z0-9]+", "_", name).strip("_")
+
+
+def _project_progress_relpath(path_value: str, root_path: str) -> str:
+    try:
+        return os.path.relpath(path_value, root_path)
+    except ValueError:
+        return path_value
+
+
+def _project_progress_volume_id(image_path: str, root_path: str) -> str:
+    return _project_progress_relpath(image_path, root_path).replace(os.sep, "/")
+
+
+def _project_progress_tokens(path_value: Optional[str]) -> set[str]:
+    return {
+        token
+        for token in re.split(r"[^a-z0-9]+", str(path_value or "").lower())
+        if token
+    }
+
+
+def _project_progress_has_ground_truth_marker(path_value: Optional[str]) -> bool:
+    tokens = _project_progress_tokens(path_value)
+    normalized = re.sub(r"[^a-z0-9]+", "_", str(path_value or "").lower())
+    return bool(
+        tokens & PROJECT_PROGRESS_GROUND_TRUTH_MARKERS
+        or "ground_truth" in normalized
+        or "groundtruth" in normalized
+    )
+
+
+def _project_progress_volume_candidates(
+    path_value: Optional[str],
+    *,
+    project_root: str,
+    roles: set[str],
+    max_candidates: int = 500,
+) -> List[str]:
+    if not path_value:
+        return []
+    absolute = pathlib.Path(path_value)
+    if not absolute.is_absolute():
+        absolute = pathlib.Path(project_root) / absolute
+    try:
+        absolute = absolute.expanduser().resolve()
+    except OSError:
+        absolute = absolute.expanduser()
+    if absolute.is_file() or (
+        absolute.is_dir() and _project_extension(absolute.name) in {".zarr", ".n5"}
+    ):
+        relative = _project_progress_relpath(str(absolute), project_root)
+        role = _role_for_project_file(relative)
+        return [str(absolute)] if role in roles or role == "volume" else []
+    if not absolute.is_dir():
+        return []
+
+    def is_candidate(child: pathlib.Path) -> bool:
+        if any(part.startswith(".") or part == "__pycache__" for part in child.parts):
+            return False
+        if not child.is_file() and not (
+            child.is_dir() and _project_extension(child.name) in {".zarr", ".n5"}
+        ):
+            return False
+        relative = _project_progress_relpath(str(child), project_root)
+        role = _role_for_project_file(relative)
+        return role in roles or role == "volume"
+
+    direct = [
+        str(child)
+        for child in sorted(absolute.iterdir(), key=lambda item: item.name.lower())
+        if is_candidate(child)
+    ]
+    if direct:
+        return direct[:max_candidates]
+
+    candidates: List[str] = []
+    for child in sorted(absolute.rglob("*"), key=lambda item: str(item).lower()):
+        if is_candidate(child):
+            candidates.append(str(child))
+            if len(candidates) >= max_candidates:
+                break
+    return candidates
+
+
+def _project_progress_match_segmentation(
+    image_path: str,
+    segmentation_paths: List[str],
+    *,
+    project_root: str,
+    single_image: bool,
+) -> Optional[str]:
+    if not segmentation_paths:
+        return None
+    image_relative = _project_progress_relpath(image_path, project_root)
+    image_key = _project_progress_pair_key(image_path)
+    by_key = {
+        _project_progress_pair_key(segmentation_path): segmentation_path
+        for segmentation_path in segmentation_paths
+    }
+    if image_key and image_key in by_key:
+        return by_key[image_key]
+    for segmentation_path in segmentation_paths:
+        segmentation_relative = _project_progress_relpath(
+            segmentation_path,
+            project_root,
+        )
+        if _looks_like_image_label_pair(image_relative, segmentation_relative):
+            return segmentation_path
+        image_parent = pathlib.Path(image_relative).parent.name.lower()
+        segmentation_parent = pathlib.Path(segmentation_relative).parent.name.lower()
+        if (
+            image_parent
+            and image_parent not in {".", "image", "images", "raw", "volume", "volumes"}
+            and image_parent == segmentation_parent
+        ):
+            return segmentation_path
+    if single_image and len(segmentation_paths) == 1:
+        return segmentation_paths[0]
+    return None
+
+
+def _project_progress_correction_evidence(
+    db: Session,
+    workflow: WorkflowSession,
+) -> Dict[str, Any]:
+    paths = {
+        _normalize_absolute_path(path)
+        for path in [workflow.corrected_mask_path]
+        if path
+    }
+    correction_sets = (
+        db.query(WorkflowCorrectionSet)
+        .filter(WorkflowCorrectionSet.workflow_id == workflow.id)
+        .all()
+    )
+    for correction_set in correction_sets:
+        for value in [
+            correction_set.corrected_mask_path,
+            correction_set.source_mask_path,
+        ]:
+            if value:
+                paths.add(_normalize_absolute_path(value))
+    keys = {_project_progress_pair_key(path) for path in paths if path}
+    return {"paths": paths, "keys": {key for key in keys if key}}
+
+
+def _project_progress_status_for_volume(
+    *,
+    image_path: str,
+    segmentation_path: Optional[str],
+    correction_evidence: Dict[str, Any],
+) -> tuple[str, str, List[str]]:
+    evidence: List[str] = []
+    if not segmentation_path:
+        return "missing_segmentation", "derived", ["No matching segmentation found."]
+
+    normalized_segmentation = _normalize_absolute_path(segmentation_path)
+    segmentation_key = _project_progress_pair_key(segmentation_path)
+    image_key = _project_progress_pair_key(image_path)
+    correction_paths = correction_evidence.get("paths") or set()
+    correction_keys = correction_evidence.get("keys") or set()
+    if (
+        normalized_segmentation in correction_paths
+        or segmentation_key in correction_keys
+    ):
+        evidence.append("Matches a saved proofreading correction set.")
+        return "ground_truth", "correction_set", evidence
+    if image_key and image_key in correction_keys:
+        evidence.append("Image volume has a saved correction-set key.")
+        return "ground_truth", "correction_set", evidence
+    if _project_progress_has_ground_truth_marker(segmentation_path):
+        evidence.append("Segmentation path looks like ground truth or proofread data.")
+        return "ground_truth", "path_marker", evidence
+    evidence.append(
+        "Segmentation exists, but it is not marked as proofread ground truth."
+    )
+    return "needs_proofreading", "derived", evidence
+
+
+def _project_progress_status_label(status: str) -> str:
+    return {
+        "ground_truth": "Fully good",
+        "needs_proofreading": "Needs proofreading",
+        "missing_segmentation": "No segmentation",
+        "ignored": "Ignored",
+    }.get(status, status.replace("_", " ").title())
+
+
+def _canonical_project_progress_status(status: Optional[str]) -> Dict[str, str]:
+    if status in PROJECT_PROGRESS_CANONICAL_STATUS:
+        return PROJECT_PROGRESS_CANONICAL_STATUS[str(status)]
+    fallback = str(status or "unknown")
+    return {
+        "status": fallback,
+        "label": fallback.replace("_", " ").title(),
+    }
+
+
+def _state_label(value: Optional[str], labels: Dict[str, str]) -> str:
+    text = str(value or "unknown")
+    return labels.get(text, text.replace("_", " ").title())
+
+
+def _composite_state_from_legacy_status(status: Optional[str]) -> Dict[str, str]:
+    legacy = str(status or "missing_segmentation")
+    state = PROJECT_PROGRESS_LEGACY_TO_COMPOSITE.get(legacy)
+    if state:
+        return dict(state)
+    return dict(PROJECT_PROGRESS_LEGACY_TO_COMPOSITE["missing_segmentation"])
+
+
+def _legacy_status_from_composite_state(
+    annotation_state: Optional[str],
+    role_state: Optional[str] = None,
+) -> str:
+    annotation = str(annotation_state or "")
+    if annotation in PROJECT_PROGRESS_COMPOSITE_TO_LEGACY:
+        return PROJECT_PROGRESS_COMPOSITE_TO_LEGACY[annotation]
+    if role_state == "excluded":
+        return "ignored"
+    if role_state == "training_source":
+        return "ground_truth"
+    if role_state == "proofreading_target":
+        return "needs_proofreading"
+    if role_state == "inference_target":
+        return "missing_segmentation"
+    return "missing_segmentation"
+
+
+def _normalize_region_scope(value: Optional[Dict[str, Any]]) -> Dict[str, Any]:
+    scope = value if isinstance(value, dict) else {}
+    scope_type = str(scope.get("scope_type") or "full_volume")
+    normalized = {
+        "scope_type": scope_type,
+        "coordinate_space": str(scope.get("coordinate_space") or "voxel"),
+        "bounds": scope.get("bounds"),
+        "regions": (
+            scope.get("regions") if isinstance(scope.get("regions"), list) else []
+        ),
+        "source": str(scope.get("source") or "project_scan"),
+    }
+    return normalized
+
+
+def _row_region_scope(row: WorkflowVolumeState) -> Dict[str, Any]:
+    return _normalize_region_scope(decode_json(getattr(row, "region_scope_json", None)))
+
+
+def _set_row_composite_state(
+    row: WorkflowVolumeState,
+    *,
+    status: Optional[str] = None,
+    annotation_state: Optional[str] = None,
+    role_state: Optional[str] = None,
+    execution_state: Optional[str] = None,
+    region_scope: Optional[Dict[str, Any]] = None,
+) -> None:
+    legacy_status = status or row.status or None
+    composite = _composite_state_from_legacy_status(legacy_status)
+    if annotation_state:
+        composite["annotation_state"] = annotation_state
+    if role_state:
+        composite["role_state"] = role_state
+    if execution_state:
+        composite["execution_state"] = execution_state
+    if status is None and annotation_state:
+        legacy_status = _legacy_status_from_composite_state(
+            composite.get("annotation_state"),
+            composite.get("role_state"),
+        )
+    row.status = legacy_status or _legacy_status_from_composite_state(
+        composite.get("annotation_state"),
+        composite.get("role_state"),
+    )
+    row.annotation_state = composite.get("annotation_state")
+    row.role_state = composite.get("role_state")
+    row.execution_state = composite.get("execution_state")
+    if region_scope is not None or not getattr(row, "region_scope_json", None):
+        row.region_scope_json = encode_json(_normalize_region_scope(region_scope))
+    row.state_schema_version = WORKFLOW_VOLUME_STATE_SCHEMA_VERSION
+
+
+def _ensure_row_composite_state(row: WorkflowVolumeState) -> None:
+    if (
+        row.annotation_state
+        and row.role_state
+        and row.execution_state
+        and row.region_scope_json
+        and row.state_schema_version
+    ):
+        return
+    _set_row_composite_state(
+        row, status=row.status, region_scope=_row_region_scope(row)
+    )
+
+
+def _validate_composite_status_patch(
+    *,
+    status: Optional[str],
+    annotation_state: Optional[str],
+    role_state: Optional[str],
+    execution_state: Optional[str],
+) -> None:
+    if annotation_state and annotation_state not in WORKFLOW_VOLUME_ANNOTATION_STATES:
+        raise HTTPException(
+            status_code=400,
+            detail=f"annotation_state must be one of {sorted(WORKFLOW_VOLUME_ANNOTATION_STATES)}",
+        )
+    if role_state and role_state not in WORKFLOW_VOLUME_ROLE_STATES:
+        raise HTTPException(
+            status_code=400,
+            detail=f"role_state must be one of {sorted(WORKFLOW_VOLUME_ROLE_STATES)}",
+        )
+    if execution_state and execution_state not in WORKFLOW_VOLUME_EXECUTION_STATES:
+        raise HTTPException(
+            status_code=400,
+            detail=f"execution_state must be one of {sorted(WORKFLOW_VOLUME_EXECUTION_STATES)}",
+        )
+    if status and annotation_state:
+        projected = _legacy_status_from_composite_state(annotation_state, role_state)
+        if projected != status:
+            raise HTTPException(
+                status_code=400,
+                detail=(
+                    "status and annotation_state disagree: "
+                    f"{status!r} does not match {annotation_state!r}"
+                ),
+            )
+
+
+def _volume_eligible_for_training_state(
+    *,
+    annotation_state: Optional[str],
+    role_state: Optional[str],
+    label_path: Optional[str],
+    corrected_mask_path: Optional[str] = None,
+) -> bool:
+    return (
+        annotation_state == "proofread_ground_truth"
+        and role_state == "training_source"
+        and bool(label_path or corrected_mask_path)
+    )
+
+
+def _volume_eligible_for_inference_state(
+    *,
+    annotation_state: Optional[str],
+    role_state: Optional[str],
+    image_path: Optional[str],
+) -> bool:
+    return (
+        annotation_state == "image_only"
+        and role_state == "inference_target"
+        and bool(image_path)
+    )
+
+
+def _canonical_volume_state_item(row: WorkflowVolumeState) -> Dict[str, Any]:
+    _ensure_row_composite_state(row)
+    item = volume_state_to_dict(row)
+    canonical = _canonical_project_progress_status(item.get("status"))
+    item["legacy_status"] = item.get("status")
+    item["canonical_status"] = canonical["status"]
+    item["canonical_status_label"] = canonical["label"]
+    item["annotation_state_label"] = _state_label(
+        item.get("annotation_state"),
+        WORKFLOW_VOLUME_ANNOTATION_STATES,
+    )
+    item["role_state_label"] = _state_label(
+        item.get("role_state"),
+        WORKFLOW_VOLUME_ROLE_STATES,
+    )
+    item["execution_state_label"] = _state_label(
+        item.get("execution_state"),
+        WORKFLOW_VOLUME_EXECUTION_STATES,
+    )
+    return item
+
+
+def _canonical_volume_state_summary(rows: List[WorkflowVolumeState]) -> Dict[str, Any]:
+    counts: Dict[str, int] = {}
+    labels: Dict[str, str] = {}
+    for row in rows:
+        _ensure_row_composite_state(row)
+        status = (
+            row.annotation_state
+            or _canonical_project_progress_status(row.status)["status"]
+        )
+        counts[status] = counts.get(status, 0) + 1
+        labels[status] = _state_label(status, WORKFLOW_VOLUME_ANNOTATION_STATES)
+    return {
+        "counts": counts,
+        "labels": labels,
+        "training_ready": sum(1 for row in rows if row.eligible_for_training),
+        "inference_ready": sum(1 for row in rows if row.eligible_for_inference),
+    }
+
+
+VOLUME_STATE_MANUAL_SOURCES = {
+    "manual",
+    "manual_override",
+    "user",
+    "proofreading",
+    "agent_confirmed",
+}
+
+
+def _workflow_volume_state_map(
+    db: Session,
+    workflow_id: int,
+) -> Dict[str, WorkflowVolumeState]:
+    rows = (
+        db.query(WorkflowVolumeState)
+        .filter(WorkflowVolumeState.workflow_id == workflow_id)
+        .all()
+    )
+    return {row.volume_id: row for row in rows}
+
+
+def _workflow_volume_state_is_manual(row: Optional[WorkflowVolumeState]) -> bool:
+    if not row:
+        return False
+    return str(row.status_source or "").lower() in VOLUME_STATE_MANUAL_SOURCES
+
+
+def _status_confidence_for_source(status_source: Optional[str]) -> float:
+    source = str(status_source or "").lower()
+    if source in VOLUME_STATE_MANUAL_SOURCES:
+        return 1.0
+    if source in {"correction_set", "path_marker"}:
+        return 0.9
+    return 0.65
+
+
+def _volume_eligible_for_training(
+    status: str,
+    *,
+    label_path: Optional[str],
+    corrected_mask_path: Optional[str] = None,
+) -> bool:
+    composite = _composite_state_from_legacy_status(status)
+    return _volume_eligible_for_training_state(
+        annotation_state=composite.get("annotation_state"),
+        role_state=composite.get("role_state"),
+        label_path=label_path,
+        corrected_mask_path=corrected_mask_path,
+    )
+
+
+def _volume_eligible_for_inference(
+    status: str,
+    *,
+    image_path: Optional[str],
+) -> bool:
+    composite = _composite_state_from_legacy_status(status)
+    return _volume_eligible_for_inference_state(
+        annotation_state=composite.get("annotation_state"),
+        role_state=composite.get("role_state"),
+        image_path=image_path,
+    )
+
+
+def _volume_state_response(row: WorkflowVolumeState) -> WorkflowVolumeStateResponse:
+    data = _canonical_volume_state_item(row)
+    return WorkflowVolumeStateResponse(
+        **data,
+        status_label=_project_progress_status_label(row.status),
+    )
+
+
+def _volume_state_summary(rows: List[WorkflowVolumeState]) -> Dict[str, Any]:
+    counts = {status: 0 for status in PROJECT_PROGRESS_STATUS_DEFINITIONS}
+    for row in rows:
+        counts[row.status] = counts.get(row.status, 0) + 1
+    tracked_total = len(rows) - counts.get("ignored", 0)
+    return {
+        "total": len(rows),
+        "tracked_total": tracked_total,
+        "ground_truth": counts.get("ground_truth", 0),
+        "needs_proofreading": counts.get("needs_proofreading", 0),
+        "missing_segmentation": counts.get("missing_segmentation", 0),
+        "ignored": counts.get("ignored", 0),
+        "training_ready": sum(1 for row in rows if row.eligible_for_training),
+        "inference_ready": sum(1 for row in rows if row.eligible_for_inference),
+        "canonical": _canonical_volume_state_summary(rows),
+    }
+
+
+def _volume_state_metadata_from_progress(volume: Dict[str, Any]) -> Dict[str, Any]:
+    return {
+        "schema_version": WORKFLOW_VOLUME_STATE_SCHEMA_VERSION,
+        "status_label": volume.get("status_label"),
+        "annotation_state": volume.get("annotation_state"),
+        "role_state": volume.get("role_state"),
+        "execution_state": volume.get("execution_state"),
+        "region_scope": volume.get("region_scope"),
+        "segmentation_kind": volume.get("segmentation_kind"),
+        "evidence": volume.get("evidence") or [],
+        "volume_set_id": volume.get("volume_set_id"),
+        "volume_set_name": volume.get("volume_set_name"),
+        "last_synced_from": "project_progress",
+        "last_synced_at": datetime.now(timezone.utc).isoformat(),
+    }
+
+
+def _apply_persisted_volume_state(
+    volume: Dict[str, Any],
+    persisted_states: Dict[str, WorkflowVolumeState],
+) -> Dict[str, Any]:
+    row = persisted_states.get(volume.get("id"))
+    if not row:
+        composite = _composite_state_from_legacy_status(volume.get("status"))
+        volume["legacy_status"] = volume.get("status")
+        canonical = _canonical_project_progress_status(volume.get("status"))
+        volume["canonical_status"] = canonical["status"]
+        volume["canonical_status_label"] = canonical["label"]
+        volume["annotation_state"] = composite.get("annotation_state")
+        volume["annotation_state_label"] = _state_label(
+            volume.get("annotation_state"),
+            WORKFLOW_VOLUME_ANNOTATION_STATES,
+        )
+        volume["role_state"] = composite.get("role_state")
+        volume["role_state_label"] = _state_label(
+            volume.get("role_state"),
+            WORKFLOW_VOLUME_ROLE_STATES,
+        )
+        volume["execution_state"] = composite.get("execution_state")
+        volume["execution_state_label"] = _state_label(
+            volume.get("execution_state"),
+            WORKFLOW_VOLUME_EXECUTION_STATES,
+        )
+        volume["region_scope"] = _normalize_region_scope(volume.get("region_scope"))
+        volume["state_schema_version"] = WORKFLOW_VOLUME_STATE_SCHEMA_VERSION
+        volume["eligible_for_training"] = _volume_eligible_for_training(
+            volume.get("status"),
+            label_path=volume.get("segmentation_path"),
+        )
+        volume["eligible_for_inference"] = _volume_eligible_for_inference(
+            volume.get("status"),
+            image_path=volume.get("image_path"),
+        )
+        return volume
+
+    _ensure_row_composite_state(row)
+    volume["volume_state_id"] = row.id
+    if _workflow_volume_state_is_manual(row):
+        volume["status"] = row.status
+        volume["status_label"] = _project_progress_status_label(row.status)
+        volume["status_source"] = row.status_source
+    volume["legacy_status"] = volume.get("status")
+    canonical = _canonical_project_progress_status(volume.get("status"))
+    volume["canonical_status"] = canonical["status"]
+    volume["canonical_status_label"] = canonical["label"]
+    volume["annotation_state"] = row.annotation_state
+    volume["annotation_state_label"] = _state_label(
+        row.annotation_state,
+        WORKFLOW_VOLUME_ANNOTATION_STATES,
+    )
+    volume["role_state"] = row.role_state
+    volume["role_state_label"] = _state_label(
+        row.role_state, WORKFLOW_VOLUME_ROLE_STATES
+    )
+    volume["execution_state"] = row.execution_state
+    volume["execution_state_label"] = _state_label(
+        row.execution_state,
+        WORKFLOW_VOLUME_EXECUTION_STATES,
+    )
+    volume["region_scope"] = _row_region_scope(row)
+    volume["state_schema_version"] = row.state_schema_version
+    volume["eligible_for_training"] = bool(row.eligible_for_training)
+    volume["eligible_for_inference"] = bool(row.eligible_for_inference)
+    if row.note:
+        volume["note"] = row.note
+    return volume
+
+
+def _sync_volume_states_from_progress(
+    db: Session,
+    workflow: WorkflowSession,
+    progress: Dict[str, Any],
+) -> Dict[str, WorkflowVolumeState]:
+    existing = _workflow_volume_state_map(db, workflow.id)
+    synced: Dict[str, WorkflowVolumeState] = dict(existing)
+    for volume in progress.get("volumes") or []:
+        volume_id = str(volume.get("id") or "")
+        if not volume_id:
+            continue
+        row = existing.get(volume_id)
+        if row is None:
+            row = WorkflowVolumeState(
+                workflow_id=workflow.id,
+                volume_id=volume_id,
+            )
+            db.add(row)
+            db.flush()
+        manual_status = _workflow_volume_state_is_manual(row)
+        status_source = str(volume.get("status_source") or "derived")
+        if not manual_status:
+            _set_row_composite_state(
+                row,
+                status=volume.get("status") or "missing_segmentation",
+                annotation_state=volume.get("annotation_state"),
+                role_state=volume.get("role_state"),
+                execution_state=volume.get("execution_state"),
+                region_scope=volume.get("region_scope"),
+            )
+            row.status_source = status_source
+            row.status_confidence = _status_confidence_for_source(status_source)
+        else:
+            _ensure_row_composite_state(row)
+        row.name = volume.get("name")
+        row.project_root = volume.get("project_root")
+        row.volume_set_id = volume.get("volume_set_id")
+        row.volume_set_name = volume.get("volume_set_name")
+        row.image_path = volume.get("image_path")
+
+        segmentation_path = volume.get("segmentation_path")
+        if volume.get("segmentation_kind") == "prediction":
+            row.prediction_path = segmentation_path
+        else:
+            row.label_path = segmentation_path
+        metadata = decode_json(row.metadata_json)
+        metadata = {
+            **metadata,
+            **_volume_state_metadata_from_progress(volume),
+        }
+        if "note" in volume and volume.get("note") is not None and not row.note:
+            row.note = str(volume.get("note") or "")
+        if metadata.get("eligibility_source") != "manual":
+            _ensure_row_composite_state(row)
+            row.eligible_for_training = _volume_eligible_for_training_state(
+                annotation_state=row.annotation_state,
+                role_state=row.role_state,
+                label_path=row.label_path,
+                corrected_mask_path=row.corrected_mask_path,
+            )
+            row.eligible_for_inference = _volume_eligible_for_inference_state(
+                annotation_state=row.annotation_state,
+                role_state=row.role_state,
+                image_path=row.image_path,
+            )
+        row.metadata_json = encode_json(metadata)
+        synced[volume_id] = row
+    return synced
+
+
+def _apply_project_progress_overrides(
+    volume: Dict[str, Any],
+    overrides: Dict[str, Any],
+) -> Dict[str, Any]:
+    override = overrides.get(volume["id"])
+    if not isinstance(override, dict):
+        return volume
+    status = override.get("status")
+    if status in PROJECT_PROGRESS_STATUS_DEFINITIONS:
+        volume["status"] = status
+        volume["status_label"] = _project_progress_status_label(status)
+        volume["status_source"] = "manual_override"
+    if "note" in override:
+        volume["note"] = str(override.get("note") or "")
+    return volume
+
+
+def _build_workflow_project_progress(
+    db: Session,
+    workflow: WorkflowSession,
+    *,
+    user_id: int,
+    project_observation: Optional[Dict[str, Any]] = None,
+    persist_snapshot: bool = True,
+) -> Dict[str, Any]:
+    observation = project_observation or _observe_workflow_project(
+        db, workflow, user_id
+    )
+    metadata = decode_json(workflow.metadata_json)
+    overrides = metadata.get("project_progress_overrides")
+    overrides = overrides if isinstance(overrides, dict) else {}
+    correction_evidence = _project_progress_correction_evidence(db, workflow)
+    persisted_states = _workflow_volume_state_map(db, workflow.id)
+    volumes: List[Dict[str, Any]] = []
+    seen_volume_ids: set[str] = set()
+
+    for volume_set in observation.get("volume_sets") or []:
+        if not isinstance(volume_set, dict):
+            continue
+        project_root = _normalize_absolute_path(volume_set.get("project_root"))
+        if not project_root:
+            continue
+        image_candidates = _project_progress_volume_candidates(
+            volume_set.get("image_root_path") or volume_set.get("image_path"),
+            project_root=project_root,
+            roles={"image", "volume"},
+        )
+        segmentation_candidates = _project_progress_volume_candidates(
+            volume_set.get("label_root_path") or volume_set.get("label_path"),
+            project_root=project_root,
+            roles={"label", "prediction"},
+        )
+        if not image_candidates and volume_set.get("image_path"):
+            image_candidates = [volume_set["image_path"]]
+        if not segmentation_candidates and volume_set.get("label_path"):
+            segmentation_candidates = [volume_set["label_path"]]
+
+        for image_path in image_candidates:
+            volume_id = _project_progress_volume_id(image_path, project_root)
+            if volume_id in seen_volume_ids:
+                continue
+            seen_volume_ids.add(volume_id)
+            segmentation_path = _project_progress_match_segmentation(
+                image_path,
+                segmentation_candidates,
+                project_root=project_root,
+                single_image=len(image_candidates) == 1,
+            )
+            status, status_source, evidence = _project_progress_status_for_volume(
+                image_path=image_path,
+                segmentation_path=segmentation_path,
+                correction_evidence=correction_evidence,
+            )
+            segmentation_kind = (
+                _role_for_project_file(
+                    _project_progress_relpath(segmentation_path, project_root)
+                )
+                if segmentation_path
+                else None
+            )
+            volume = {
+                "id": volume_id,
+                "name": pathlib.Path(image_path).name,
+                "status": status,
+                "status_label": _project_progress_status_label(status),
+                "status_source": status_source,
+                **_composite_state_from_legacy_status(status),
+                "region_scope": _normalize_region_scope(None),
+                "state_schema_version": WORKFLOW_VOLUME_STATE_SCHEMA_VERSION,
+                "project_root": project_root,
+                "volume_set_id": volume_set.get("id"),
+                "volume_set_name": volume_set.get("name"),
+                "image_path": image_path,
+                "segmentation_path": segmentation_path,
+                "segmentation_kind": segmentation_kind,
+                "evidence": evidence,
+                "note": None,
+            }
+            volume = _apply_project_progress_overrides(volume, overrides)
+            volume = _apply_persisted_volume_state(volume, persisted_states)
+            volumes.append(volume)
+
+    if not volumes and (workflow.image_path or workflow.dataset_path):
+        image_path = _normalize_absolute_path(
+            workflow.image_path or workflow.dataset_path
+        )
+        project_root = _normalize_absolute_path(workflow.dataset_path) or str(
+            pathlib.Path(image_path).parent
+        )
+        segmentation_path = (
+            workflow.label_path or workflow.mask_path or workflow.inference_output_path
+        )
+        segmentation_path = (
+            _normalize_absolute_path(segmentation_path) if segmentation_path else None
+        )
+        status, status_source, evidence = _project_progress_status_for_volume(
+            image_path=image_path,
+            segmentation_path=segmentation_path,
+            correction_evidence=correction_evidence,
+        )
+        fallback = {
+            "id": _project_progress_volume_id(image_path, project_root),
+            "name": pathlib.Path(image_path).name,
+            "status": status,
+            "status_label": _project_progress_status_label(status),
+            "status_source": status_source,
+            **_composite_state_from_legacy_status(status),
+            "region_scope": _normalize_region_scope(None),
+            "state_schema_version": WORKFLOW_VOLUME_STATE_SCHEMA_VERSION,
+            "project_root": project_root,
+            "volume_set_id": "workflow-current",
+            "volume_set_name": "Current workflow",
+            "image_path": image_path,
+            "segmentation_path": segmentation_path,
+            "segmentation_kind": "label" if segmentation_path else None,
+            "evidence": evidence,
+            "note": None,
+        }
+        fallback = _apply_project_progress_overrides(fallback, overrides)
+        fallback = _apply_persisted_volume_state(fallback, persisted_states)
+        volumes.append(fallback)
+
+    counts = {status: 0 for status in PROJECT_PROGRESS_STATUS_DEFINITIONS}
+    for volume in volumes:
+        counts[volume["status"]] = counts.get(volume["status"], 0) + 1
+    tracked_total = len(volumes) - counts.get("ignored", 0)
+    good_count = counts.get("ground_truth", 0)
+    segmented_count = good_count + counts.get("needs_proofreading", 0)
+    summary = {
+        "total": len(volumes),
+        "tracked_total": tracked_total,
+        "ground_truth": good_count,
+        "needs_proofreading": counts.get("needs_proofreading", 0),
+        "missing_segmentation": counts.get("missing_segmentation", 0),
+        "ignored": counts.get("ignored", 0),
+        "remaining": counts.get("needs_proofreading", 0)
+        + counts.get("missing_segmentation", 0),
+        "completion_pct": (
+            round((good_count / tracked_total) * 100, 1) if tracked_total else 0
+        ),
+        "segmentation_coverage_pct": (
+            round((segmented_count / tracked_total) * 100, 1) if tracked_total else 0
+        ),
+    }
+    project_name = workflow.title
+    roots = observation.get("roots") or []
+    if roots:
+        project_name = project_name or roots[0].get("name")
+    generated_at = datetime.now(timezone.utc).isoformat()
+    progress = {
+        "workflow_id": workflow.id,
+        "generated_at": generated_at,
+        "project_name": project_name,
+        "project_roots": roots,
+        "summary": summary,
+        "status_definitions": PROJECT_PROGRESS_STATUS_DEFINITIONS,
+        "composite_state_definitions": {
+            "annotation_state": WORKFLOW_VOLUME_ANNOTATION_STATES,
+            "role_state": WORKFLOW_VOLUME_ROLE_STATES,
+            "execution_state": WORKFLOW_VOLUME_EXECUTION_STATES,
+        },
+        "volumes": volumes,
+    }
+    if persist_snapshot:
+        persisted_states = _sync_volume_states_from_progress(db, workflow, progress)
+        for volume in volumes:
+            _apply_persisted_volume_state(volume, persisted_states)
+        metadata["project_progress_snapshot"] = {
+            "generated_at": generated_at,
+            "summary": summary,
+            "volume_count": len(volumes),
+            "volumes": [
+                {
+                    key: volume.get(key)
+                    for key in [
+                        "id",
+                        "name",
+                        "status",
+                        "annotation_state",
+                        "role_state",
+                        "execution_state",
+                        "image_path",
+                        "segmentation_path",
+                        "volume_set_name",
+                    ]
+                }
+                for volume in volumes[:100]
+            ],
+        }
+        workflow.metadata_json = encode_json(metadata)
+    return progress
+
+
+def _format_project_progress_response(progress: Dict[str, Any]) -> str:
+    summary = progress.get("summary") or {}
+    total = int(summary.get("tracked_total") or summary.get("total") or 0)
+    if not total:
+        return (
+            "I do not see tracked image volumes yet. Mount a project or choose data, "
+            "then the workflow overview can count proofread, unproofread, and missing segmentations."
+        )
+    volumes = progress.get("volumes") or []
+
+    def names_for(status: str, limit: int = 8) -> str:
+        names = [
+            str(volume.get("name") or volume.get("id") or "").strip()
+            for volume in volumes
+            if volume.get("status") == status
+        ]
+        names = [name for name in names if name]
+        if not names:
+            return ""
+        suffix = "" if len(names) <= limit else f", plus {len(names) - limit} more"
+        return ", ".join(names[:limit]) + suffix
+
+    ground_truth_names = names_for("ground_truth")
+    proofread_names = names_for("needs_proofreading")
+    missing_names = names_for("missing_segmentation")
+    grouped = []
+    if ground_truth_names:
+        grouped.append(f"ready for training: {ground_truth_names}")
+    if proofread_names:
+        grouped.append(f"proofread before training: {proofread_names}")
+    if missing_names:
+        grouped.append(f"image-only/inference targets: {missing_names}")
+    grouped_text = " " + "; ".join(grouped) + "." if grouped else ""
+    return (
+        "I checked the workflow overview. "
+        f"It has {total} tracked image volume(s): "
+        f"{summary.get('ground_truth', 0)} fully good ground-truth volume(s), "
+        f"{summary.get('needs_proofreading', 0)} with segmentations that still need proofreading, "
+        f"and {summary.get('missing_segmentation', 0)} with no segmentation yet. "
+        f"Completion is {summary.get('completion_pct', 0)}%."
+        f"{grouped_text}"
+    )
+
+
+WORKFLOW_OVERVIEW_PHASES = [
+    ("setup", "Setup", "files"),
+    ("inspect", "Inspect", "visualization"),
+    ("proofread", "Proofread", "mask-proofreading"),
+    ("train", "Train", "training"),
+    ("infer", "Infer", "inference"),
+    ("evaluate", "Evaluate", "project-progress"),
+]
+
+
+def _workflow_overview_active_runs(
+    db: Session,
+    workflow_id: int,
+) -> List[WorkflowModelRun]:
+    return (
+        db.query(WorkflowModelRun)
+        .filter(
+            WorkflowModelRun.workflow_id == workflow_id,
+            WorkflowModelRun.status.in_(["pending", "running", "submitted"]),
+        )
+        .order_by(WorkflowModelRun.updated_at.desc(), WorkflowModelRun.id.desc())
+        .all()
+    )
+
+
+def _workflow_overview_recent_events(
+    db: Session,
+    workflow_id: int,
+    *,
+    limit: int = 8,
+) -> List[WorkflowEvent]:
+    return (
+        db.query(WorkflowEvent)
+        .filter(WorkflowEvent.workflow_id == workflow_id)
+        .order_by(WorkflowEvent.created_at.desc(), WorkflowEvent.id.desc())
+        .limit(limit)
+        .all()
+    )
+
+
+def _workflow_overview_phase(
+    workflow: WorkflowSession,
+    progress: Dict[str, Any],
+    active_runs: List[WorkflowModelRun],
+    events: List[WorkflowEvent],
+) -> Dict[str, Any]:
+    summary = progress.get("summary") or {}
+    total = int(summary.get("tracked_total") or summary.get("total") or 0)
+    ground_truth = int(summary.get("ground_truth") or 0)
+    needs_proofreading = int(summary.get("needs_proofreading") or 0)
+    missing_segmentation = int(summary.get("missing_segmentation") or 0)
+
+    active_training = next(
+        (run for run in active_runs if run.run_type == "training"),
+        None,
+    )
+    active_inference = next(
+        (run for run in active_runs if run.run_type == "inference"),
+        None,
+    )
+    if active_training:
+        return {
+            "phase": "train",
+            "reason": "A training run is active.",
+        }
+    if active_inference:
+        return {
+            "phase": "infer",
+            "reason": "An inference run is active.",
+        }
+
+    if not (workflow.dataset_path or workflow.image_path):
+        return {
+            "phase": "setup",
+            "reason": "No project data is mounted yet.",
+        }
+    if total <= 0:
+        return {
+            "phase": "inspect",
+            "reason": "Project data is mounted, but no tracked volumes are confirmed yet.",
+        }
+    if workflow.stage == "proofreading" or needs_proofreading > 0:
+        return {
+            "phase": "proofread",
+            "reason": f"{needs_proofreading} volume(s) still need proofreading.",
+        }
+    if workflow.stage == "retraining_staged" or (
+        ground_truth > 0 and missing_segmentation > 0
+    ):
+        return {
+            "phase": "train",
+            "reason": f"{ground_truth} ground-truth volume(s) can train a model for {missing_segmentation} image-only target(s).",
+        }
+    if workflow.stage == "inference" or missing_segmentation > 0:
+        return {
+            "phase": "infer",
+            "reason": f"{missing_segmentation} volume(s) need model predictions.",
+        }
+    if workflow.stage == "evaluation" or any(
+        event.event_type.startswith("evaluation.") for event in events
+    ):
+        return {
+            "phase": "evaluate",
+            "reason": "Predictions and workflow evidence are ready to compare.",
+        }
+    return {
+        "phase": "inspect",
+        "reason": "The project has tracked volumes and is ready for inspection.",
+    }
+
+
+def _workflow_overview_blockers(
+    workflow: WorkflowSession,
+    progress: Dict[str, Any],
+    active_runs: List[WorkflowModelRun],
+) -> List[WorkflowOverviewBlocker]:
+    summary = progress.get("summary") or {}
+    total = int(summary.get("tracked_total") or summary.get("total") or 0)
+    ground_truth = int(summary.get("ground_truth") or 0)
+    needs_proofreading = int(summary.get("needs_proofreading") or 0)
+    missing_segmentation = int(summary.get("missing_segmentation") or 0)
+    blockers: List[WorkflowOverviewBlocker] = []
+
+    if not (workflow.dataset_path or workflow.image_path):
+        blockers.append(
+            WorkflowOverviewBlocker(
+                id="project_missing",
+                label="No project mounted",
+                detail="Mount or choose a project directory before the workflow can inspect volumes.",
+                severity="blocking",
+                target_view="files",
+            )
+        )
+    elif total <= 0:
+        blockers.append(
+            WorkflowOverviewBlocker(
+                id="no_tracked_volumes",
+                label="No tracked volumes",
+                detail="The mounted project did not produce volume-level image entries yet.",
+                severity="blocking",
+                target_view="files",
+            )
+        )
+    if missing_segmentation > 0 and not workflow.checkpoint_path and ground_truth <= 0:
+        blockers.append(
+            WorkflowOverviewBlocker(
+                id="no_checkpoint_or_training_data",
+                label="Missing checkpoint or ground truth",
+                detail="Image-only volumes need either a checkpoint for inference or proofread ground truth for training.",
+                severity="blocking",
+                target_view="training",
+            )
+        )
+    elif missing_segmentation > 0 and not workflow.checkpoint_path:
+        blockers.append(
+            WorkflowOverviewBlocker(
+                id="checkpoint_missing",
+                label="No checkpoint selected",
+                detail="Train a model or select a checkpoint before running inference on image-only volumes.",
+                severity="warning",
+                target_view="training",
+            )
+        )
+    if needs_proofreading > 0:
+        blockers.append(
+            WorkflowOverviewBlocker(
+                id="draft_masks_need_review",
+                label="Draft masks need review",
+                detail=f"{needs_proofreading} volume(s) have masks or segmentations that are not marked ground truth.",
+                severity="warning",
+                target_view="mask-proofreading",
+            )
+        )
+    if active_runs:
+        blockers.append(
+            WorkflowOverviewBlocker(
+                id="runtime_active",
+                label="Run in progress",
+                detail="Wait for the active run to finish before launching another expensive job.",
+                severity="info",
+                target_view=(
+                    "training" if active_runs[0].run_type == "training" else "inference"
+                ),
+            )
+        )
+    return blockers
+
+
+def _workflow_overview_actions(
+    workflow: WorkflowSession,
+    progress: Dict[str, Any],
+    active_runs: List[WorkflowModelRun],
+) -> List[WorkflowOverviewAction]:
+    if active_runs:
+        target_view = (
+            "training" if active_runs[0].run_type == "training" else "inference"
+        )
+        return [
+            WorkflowOverviewAction(
+                id="check-active-run",
+                label="Check active run",
+                detail=f"Open {active_runs[0].run_type} runtime details.",
+                target_view=target_view,
+                priority="high",
+                client_effects={"navigate_to": target_view},
+            )
+        ]
+    summary = progress.get("summary") or {}
+    total = int(summary.get("tracked_total") or summary.get("total") or 0)
+    ground_truth = int(summary.get("ground_truth") or 0)
+    needs_proofreading = int(summary.get("needs_proofreading") or 0)
+    missing_segmentation = int(summary.get("missing_segmentation") or 0)
+    actions: List[WorkflowOverviewAction] = []
+    if not (workflow.dataset_path or workflow.image_path):
+        actions.append(
+            WorkflowOverviewAction(
+                id="mount-project",
+                label="Mount a project",
+                detail="Choose a project directory so the app can inspect images, masks, and configs.",
+                target_view="files",
+                priority="high",
+                client_effects={"navigate_to": "files"},
+            )
+        )
+    elif total <= 0:
+        actions.append(
+            WorkflowOverviewAction(
+                id="inspect-files",
+                label="Inspect files",
+                detail="Open the file view and confirm which folders contain image and mask data.",
+                target_view="files",
+                priority="high",
+                client_effects={"navigate_to": "files"},
+            )
+        )
+    if needs_proofreading > 0:
+        actions.append(
+            WorkflowOverviewAction(
+                id="proofread-draft-masks",
+                label="Proofread draft masks",
+                detail=f"Review {needs_proofreading} volume(s) before treating them as ground truth.",
+                target_view="mask-proofreading",
+                priority="high" if ground_truth <= 0 else "normal",
+                client_effects={"navigate_to": "mask-proofreading"},
+            )
+        )
+    if ground_truth > 0 and missing_segmentation > 0:
+        actions.append(
+            WorkflowOverviewAction(
+                id="train-from-ground-truth",
+                label="Train from ground truth",
+                detail=f"Use {ground_truth} ground-truth volume(s), then infer {missing_segmentation} image-only target(s).",
+                target_view="training",
+                priority="high",
+                client_effects={"navigate_to": "training"},
+            )
+        )
+    if workflow.checkpoint_path and missing_segmentation > 0:
+        actions.append(
+            WorkflowOverviewAction(
+                id="run-inference-on-missing",
+                label="Run inference on missing masks",
+                detail=f"Use the selected checkpoint for {missing_segmentation} image-only volume(s).",
+                target_view="inference",
+                priority="high",
+                client_effects={"navigate_to": "inference"},
+            )
+        )
+    if total > 0:
+        actions.append(
+            WorkflowOverviewAction(
+                id="review-workflow-map",
+                label="Review workflow map",
+                detail="Open the volume table and update statuses or next actions.",
+                target_view="project-progress",
+                priority="normal",
+                client_effects={"navigate_to": "project-progress"},
+            )
+        )
+    return actions[:4]
+
+
+def _workflow_overview_stages(
+    phase: str,
+    workflow: WorkflowSession,
+    progress: Dict[str, Any],
+    active_runs: List[WorkflowModelRun],
+    events: List[WorkflowEvent],
+) -> List[WorkflowOverviewStage]:
+    summary = progress.get("summary") or {}
+    total = int(summary.get("tracked_total") or summary.get("total") or 0)
+    ground_truth = int(summary.get("ground_truth") or 0)
+    missing_segmentation = int(summary.get("missing_segmentation") or 0)
+    needs_proofreading = int(summary.get("needs_proofreading") or 0)
+    phase_ids = [item[0] for item in WORKFLOW_OVERVIEW_PHASES]
+    current_index = phase_ids.index(phase) if phase in phase_ids else 0
+    training_seen = any(
+        run.run_type == "training" and run.status in {"running", "completed"}
+        for run in active_runs
+    ) or any(event.event_type.startswith("training.") for event in events)
+    inference_seen = (
+        any(
+            run.run_type == "inference" and run.status in {"running", "completed"}
+            for run in active_runs
+        )
+        or bool(workflow.inference_output_path)
+        or any(event.event_type.startswith("inference.") for event in events)
+    )
+    evaluation_seen = any(
+        event.event_type.startswith("evaluation.") for event in events
+    )
+    complete_by_phase = {
+        "setup": bool(workflow.dataset_path or workflow.image_path),
+        "inspect": total > 0,
+        "proofread": total > 0 and needs_proofreading == 0 and ground_truth > 0,
+        "train": bool(
+            workflow.checkpoint_path or workflow.training_output_path or training_seen
+        ),
+        "infer": missing_segmentation == 0 or inference_seen,
+        "evaluate": evaluation_seen,
+    }
+    stages: List[WorkflowOverviewStage] = []
+    for index, (stage_id, label, target_view) in enumerate(WORKFLOW_OVERVIEW_PHASES):
+        complete = bool(complete_by_phase.get(stage_id))
+        blocked = index < current_index and not complete
+        stages.append(
+            WorkflowOverviewStage(
+                id=stage_id,
+                label=label,
+                target_view=target_view,
+                complete=complete,
+                current=stage_id == phase,
+                blocked=blocked,
+                detail=None,
+            )
+        )
+    return stages
+
+
+def _build_workflow_overview(
+    db: Session,
+    workflow: WorkflowSession,
+    *,
+    user_id: int,
+    refresh: bool = True,
+) -> WorkflowOverviewResponse:
+    progress = _build_workflow_project_progress(
+        db,
+        workflow,
+        user_id=user_id,
+        persist_snapshot=refresh,
+    )
+    active_runs = _workflow_overview_active_runs(db, workflow.id)
+    recent_events = _workflow_overview_recent_events(db, workflow.id)
+    phase_data = _workflow_overview_phase(
+        workflow, progress, active_runs, recent_events
+    )
+    phase = phase_data["phase"]
+    phase_lookup = {item[0]: item for item in WORKFLOW_OVERVIEW_PHASES}
+    phase_item = phase_lookup.get(phase, WORKFLOW_OVERVIEW_PHASES[0])
+    phase_index = [item[0] for item in WORKFLOW_OVERVIEW_PHASES].index(phase_item[0])
+    return WorkflowOverviewResponse(
+        workflow_id=workflow.id,
+        generated_at=datetime.now(timezone.utc).isoformat(),
+        project_name=progress.get("project_name") or workflow.title,
+        workflow_stage=workflow.stage,
+        phase=phase,
+        phase_label=phase_item[1],
+        phase_reason=phase_data["reason"],
+        phase_index=phase_index,
+        volume_summary=progress.get("summary") or {},
+        project_progress=WorkflowProjectProgressResponse(**progress),
+        stages=_workflow_overview_stages(
+            phase,
+            workflow,
+            progress,
+            active_runs,
+            recent_events,
+        ),
+        blockers=_workflow_overview_blockers(workflow, progress, active_runs),
+        recommended_next_actions=_workflow_overview_actions(
+            workflow,
+            progress,
+            active_runs,
+        ),
+        active_runs=[
+            WorkflowOverviewRun(**model_run_to_dict(run)) for run in active_runs
+        ],
+        recent_events=[_event_response(event) for event in reversed(recent_events)],
+    )
+
+
+TASK_FAMILY_PRESETS = {
+    "tapereader_xri_fiber": {
+        "label": "TapeReader XRI fibre instance segmentation",
+        "aliases": ["xri fibre", "xri fiber", "cytotape", "tapereader"],
+        "expected_inputs": ["XRI raw TIFF stacks", "fibre instance masks"],
+        "workflow_loop": [
+            "inspect XRI volumes",
+            "train on confirmed fibre masks",
+            "infer image-only volumes",
+            "proofread draft or predicted masks",
+            "promote proofread masks back to training",
+        ],
+        "training_rule": "Use only confirmed ground-truth/proofread masks as labels.",
+        "caveat": "The paper-faithful PyTC barcode target requires the TapeReader barcode branch.",
+    },
+    "mitoem_instance": {
+        "label": "Mitochondria instance segmentation",
+        "aliases": ["mitochondria instance", "mitoem", "mitochondria"],
+        "expected_inputs": ["EM raw volumes", "mitochondria instance masks"],
+        "workflow_loop": [
+            "inspect raw and mask pairs",
+            "train on ground-truth masks",
+            "run inference on image-only volumes",
+            "proofread instance errors",
+            "evaluate and retrain",
+        ],
+        "training_rule": "Use ground-truth or explicitly proofread masks as labels.",
+    },
+    "generic_volumetric": {
+        "label": "Volumetric segmentation",
+        "aliases": [],
+        "expected_inputs": ["image volumes", "optional labels or predictions"],
+        "workflow_loop": [
+            "inspect files",
+            "confirm labels",
+            "visualize data",
+            "train or infer after approval",
+        ],
+        "training_rule": "Ask the user before treating masks as training labels.",
+    },
+}
+
+
+def _task_family_preset_for_context(context: Dict[str, Any]) -> Dict[str, Any]:
+    text = " ".join(
+        str(context.get(key) or "")
+        for key in (
+            "task_family",
+            "target_structure",
+            "imaging_modality",
+            "freeform_note",
+        )
+    ).lower()
+    for key, preset in TASK_FAMILY_PRESETS.items():
+        if any(alias in text for alias in preset.get("aliases", [])):
+            return {"id": key, **preset}
+    return {"id": "generic_volumetric", **TASK_FAMILY_PRESETS["generic_volumetric"]}
+
+
+def _workflow_memory_artifact_index(workflow: WorkflowSession) -> Dict[str, Any]:
+    paths = {
+        "dataset": workflow.dataset_path,
+        "image": workflow.image_path,
+        "label": workflow.label_path,
+        "mask": workflow.mask_path,
+        "prediction": workflow.inference_output_path,
+        "checkpoint": workflow.checkpoint_path,
+        "config": workflow.config_path,
+        "corrected_mask": workflow.corrected_mask_path,
+        "training_output": workflow.training_output_path,
+    }
+    return {
+        "canonical_paths": {key: value for key, value in paths.items() if value},
+        "registered_artifacts": [
+            artifact_to_dict(artifact)
+            for artifact in getattr(workflow, "artifacts", []) or []
+        ],
+    }
+
+
+def _dedupe_user_status_events(events: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+    deduped: List[Dict[str, Any]] = []
+    last_stage: Optional[str] = None
+    for event in events:
+        stage = event.get("stage")
+        if stage == last_stage:
+            continue
+        deduped.append(event)
+        last_stage = stage
+    return deduped
+
+
+def _build_workflow_project_memory(
+    db: Session,
+    workflow: WorkflowSession,
+    *,
+    user_id: int,
+    refresh: bool = True,
+) -> Dict[str, Any]:
+    generated_at = datetime.now(timezone.utc).isoformat()
+    progress = _build_workflow_project_progress(
+        db,
+        workflow,
+        user_id=user_id,
+        persist_snapshot=refresh,
+    )
+    volume_rows = (
+        db.query(WorkflowVolumeState)
+        .filter(WorkflowVolumeState.workflow_id == workflow.id)
+        .order_by(WorkflowVolumeState.volume_id.asc())
+        .all()
+    )
+    runs = (
+        db.query(WorkflowModelRun)
+        .filter(WorkflowModelRun.workflow_id == workflow.id)
+        .order_by(WorkflowModelRun.created_at.asc(), WorkflowModelRun.id.asc())
+        .all()
+    )
+    versions = (
+        db.query(WorkflowModelVersion)
+        .filter(WorkflowModelVersion.workflow_id == workflow.id)
+        .order_by(WorkflowModelVersion.created_at.asc(), WorkflowModelVersion.id.asc())
+        .all()
+    )
+    evaluation_results = (
+        db.query(WorkflowEvaluationResult)
+        .filter(WorkflowEvaluationResult.workflow_id == workflow.id)
+        .order_by(
+            WorkflowEvaluationResult.created_at.asc(), WorkflowEvaluationResult.id.asc()
+        )
+        .all()
+    )
+    recent_events = _workflow_overview_recent_events(db, workflow.id, limit=20)
+    metadata = decode_json(workflow.metadata_json)
+    project_context = _workflow_project_context(workflow)
+    preset = _task_family_preset_for_context(project_context)
+    recent_event_dicts = [event_to_dict(event) for event in reversed(recent_events)]
+    recent_event_ids = [
+        int(event.get("id"))
+        for event in recent_event_dicts
+        if isinstance(event.get("id"), int)
+    ]
+    progress_generated_at = (
+        progress.get("generated_at") if isinstance(progress, dict) else None
+    )
+    memory = {
+        "schema_version": "pytc-project-memory/v1",
+        "workflow_id": workflow.id,
+        "generated_at": generated_at,
+        "freshness": {
+            "project_progress": {
+                "state": "fresh" if refresh else "read_only",
+                "generated_at": progress_generated_at or generated_at,
+                "source": "project_progress_builder",
+            },
+            "volume_states": {
+                "state": "fresh",
+                "generated_at": generated_at,
+                "row_count": len(volume_rows),
+                "source": "workflow_volume_states",
+            },
+            "assistant_context": {
+                "state": "fresh",
+                "generated_at": generated_at,
+                "recent_event_count": len(recent_event_dicts),
+                "source_event_high_watermark": (
+                    max(recent_event_ids) if recent_event_ids else None
+                ),
+            },
+        },
+        "project_facts": {
+            "project_name": workflow.title,
+            "stage": workflow.stage,
+            "dataset_path": workflow.dataset_path,
+            "project_context": project_context,
+            "task_family_preset": preset,
+            "context_facts": metadata.get("context_facts") or [],
+            "project_audit": metadata.get("project_audit"),
+        },
+        "artifact_index": _workflow_memory_artifact_index(workflow),
+        "volume_states": {
+            "summary": _volume_state_summary(volume_rows),
+            "items": [_canonical_volume_state_item(row) for row in volume_rows],
+            "progress_snapshot": progress,
+        },
+        "run_history": [model_run_to_dict(run) for run in runs],
+        "model_versions": [model_version_to_dict(version) for version in versions],
+        "evaluation_results": [
+            evaluation_result_to_dict(result) for result in evaluation_results
+        ],
+        "user_status_changes": [
+            {
+                "at": event["at"],
+                "event_id": event["event_id"],
+                "stage": event["stage"],
+                "event_type": event["event_type"],
+                "summary": event["summary"],
+            }
+            for event in _dedupe_user_status_events(
+                [
+                    {
+                        "at": (
+                            event.created_at.isoformat()
+                            if hasattr(event, "created_at")
+                            else None
+                        ),
+                        "event_id": event.id,
+                        "stage": event.stage,
+                        "event_type": event.event_type,
+                        "summary": event.summary,
+                    }
+                    for event in reversed(
+                        sorted(
+                            recent_events,
+                            key=lambda item: (item.created_at or datetime.min, item.id),
+                        )
+                    )
+                    if event.actor == "user" and event.stage
+                ]
+            )
+        ],
+        "evidence_events": recent_event_dicts,
+    }
+    return memory
+
+
+def _query_wants_progress_based_training(lower_query: str) -> bool:
+    if not _query_has_relaxed(
+        lower_query,
+        [
+            "train",
+            "training",
+            "fit model",
+            "learn from",
+            "use labels",
+            "use masks",
+            "ground truth",
+            "ground-truth",
+        ],
+    ):
+        return False
+    return _query_has_relaxed(
+        lower_query,
+        [
+            "ground truth",
+            "ground-truth",
+            "fully good",
+            "good masks",
+            "good labels",
+            "good volumes",
+            "done volumes",
+            "proofread",
+            "proofreaded",
+            "curated",
+            "verified",
+            "segment the rest",
+            "segment rest",
+            "remaining volumes",
+            "rest of",
+            "unsegmented",
+            "no segmentation",
+            "missing segmentation",
+        ],
+    )
+
+
+def _query_wants_train_all_available_labels(lower_query: str) -> bool:
+    return _query_has_relaxed(
+        lower_query,
+        [
+            "all labels",
+            "all masks",
+            "all segmentations",
+            "all labeled",
+            "include unproofread",
+            "include draft",
+            "draft masks",
+            "draft labels",
+            "use every label",
+            "use all labels",
+        ],
+    )
+
+
+def _query_wants_segment_remaining_after_training(lower_query: str) -> bool:
+    return _query_has_relaxed(
+        lower_query,
+        [
+            "segment the rest",
+            "segment rest",
+            "segment remaining",
+            "rest of the volumes",
+            "remaining volumes",
+            "the rest",
+            "unsegmented",
+            "no segmentation",
+            "missing segmentation",
+        ],
+    )
+
+
+def _safe_subset_token(value: Any, *, fallback: str = "item") -> str:
+    token = re.sub(r"[^A-Za-z0-9_.-]+", "_", str(value or "")).strip("._-")
+    return (token or fallback)[:96]
+
+
+def _training_subset_base_dir(project_root: str) -> pathlib.Path:
+    configured = os.getenv("PYTC_TRAINING_SUBSET_ROOT")
+    if not configured:
+        return pathlib.Path(project_root).expanduser() / ".pytc_training_subsets"
+    project_token = _safe_subset_token(
+        pathlib.Path(project_root).name,
+        fallback="project",
+    )
+    return pathlib.Path(configured).expanduser() / project_token
+
+
+def _link_or_copy_subset_file(source_path: str, destination_path: pathlib.Path) -> str:
+    destination_path.parent.mkdir(parents=True, exist_ok=True)
+    if destination_path.exists() or destination_path.is_symlink():
+        return str(destination_path)
+    try:
+        os.symlink(source_path, destination_path)
+    except OSError:
+        shutil.copy2(source_path, destination_path)
+    return str(destination_path)
+
+
+def _subset_public_volume(volume: Dict[str, Any]) -> Dict[str, Any]:
+    return {
+        "id": volume.get("id"),
+        "name": volume.get("name"),
+        "status": volume.get("status"),
+        "image_path": volume.get("image_path"),
+        "segmentation_path": volume.get("segmentation_path"),
+    }
+
+
+def _build_progress_training_subset_plan(
+    workflow: WorkflowSession,
+    progress: Dict[str, Any],
+    *,
+    lower_query: str,
+) -> Optional[Dict[str, Any]]:
+    volumes = [
+        volume
+        for volume in progress.get("volumes") or []
+        if isinstance(volume, dict) and volume.get("status") != "ignored"
+    ]
+    if not volumes:
+        return None
+
+    include_draft_labels = _query_wants_train_all_available_labels(lower_query)
+    training_statuses = ["ground_truth"]
+    if include_draft_labels:
+        training_statuses.append("needs_proofreading")
+
+    train_volumes = [
+        volume
+        for volume in volumes
+        if volume.get("status") in training_statuses
+        and volume.get("image_path")
+        and volume.get("segmentation_path")
+    ]
+    if not train_volumes and include_draft_labels:
+        train_volumes = [
+            volume
+            for volume in volumes
+            if volume.get("status") == "needs_proofreading"
+            and volume.get("image_path")
+            and volume.get("segmentation_path")
+        ]
+        training_statuses = ["needs_proofreading"]
+    if not train_volumes:
+        return None
+
+    target_volumes = [
+        volume
+        for volume in volumes
+        if volume.get("status") == "missing_segmentation" and volume.get("image_path")
+    ]
+    review_volumes = [
+        volume
+        for volume in volumes
+        if volume.get("status") == "needs_proofreading"
+        and volume.get("image_path")
+        and volume.get("segmentation_path")
+    ]
+    if include_draft_labels:
+        review_volumes = []
+
+    project_root = (
+        _normalize_absolute_path(train_volumes[0].get("project_root"))
+        or _derive_workflow_root_path(workflow)
+        or _normalize_absolute_path(workflow.dataset_path)
+    )
+    if not project_root:
+        return None
+
+    run_slug = (
+        f"workflow_{workflow.id}_"
+        f"{datetime.now(timezone.utc).strftime('%Y%m%dT%H%M%S%fZ')}"
+    )
+    subset_root = _training_subset_base_dir(project_root) / run_slug
+    image_dir = subset_root / "image"
+    label_dir = subset_root / "seg"
+    linked_pairs: List[Dict[str, Any]] = []
+    used_image_names: set[str] = set()
+    used_label_names: set[str] = set()
+
+    for index, volume in enumerate(train_volumes, start=1):
+        image_source = _normalize_absolute_path(volume.get("image_path"))
+        label_source = _normalize_absolute_path(volume.get("segmentation_path"))
+        if not image_source or not label_source:
+            continue
+        image_name = pathlib.Path(image_source).name
+        label_name = pathlib.Path(label_source).name
+        if image_name in used_image_names:
+            image_name = f"{index:03d}_{image_name}"
+        if label_name in used_label_names:
+            label_name = f"{index:03d}_{label_name}"
+        used_image_names.add(image_name)
+        used_label_names.add(label_name)
+        linked_image = _link_or_copy_subset_file(image_source, image_dir / image_name)
+        linked_label = _link_or_copy_subset_file(label_source, label_dir / label_name)
+        linked_pairs.append(
+            {
+                **_subset_public_volume(volume),
+                "subset_image_path": linked_image,
+                "subset_segmentation_path": linked_label,
+            }
+        )
+
+    if not linked_pairs:
+        return None
+
+    output_path = pathlib.Path(project_root) / "outputs" / "training" / run_slug
+    output_path.mkdir(parents=True, exist_ok=True)
+    manifest_path = subset_root / "volume_subset_manifest.json"
+    manifest = {
+        "schema_version": 1,
+        "created_at": datetime.now(timezone.utc).isoformat(),
+        "workflow_id": workflow.id,
+        "project_root": project_root,
+        "selection_basis": "project_progress",
+        "training_statuses": training_statuses,
+        "train_pairs": linked_pairs,
+        "target_images": [_subset_public_volume(volume) for volume in target_volumes],
+        "review_pairs": [_subset_public_volume(volume) for volume in review_volumes],
+        "source_progress_summary": progress.get("summary") or {},
+    }
+    manifest_path.parent.mkdir(parents=True, exist_ok=True)
+    manifest_path.write_text(
+        json.dumps(manifest, indent=2, sort_keys=True),
+        encoding="utf-8",
+    )
+
+    return {
+        "run_slug": run_slug,
+        "selection_basis": "project_progress",
+        "training_statuses": training_statuses,
+        "image_path": str(image_dir),
+        "label_path": str(label_dir),
+        "output_path": str(output_path),
+        "manifest_path": str(manifest_path),
+        "train_volume_count": len(linked_pairs),
+        "target_volume_count": len(target_volumes),
+        "review_volume_count": len(review_volumes),
+        "train_pairs": linked_pairs[:20],
+        "target_images": [
+            _subset_public_volume(volume) for volume in target_volumes[:20]
+        ],
+        "review_pairs": [
+            _subset_public_volume(volume) for volume in review_volumes[:20]
+        ],
+    }
+
+
+def _format_progress_training_response(
+    subset_plan: Dict[str, Any],
+    *,
+    include_segment_rest: bool,
+) -> str:
+    train_count = int(subset_plan.get("train_volume_count") or 0)
+    target_count = int(subset_plan.get("target_volume_count") or 0)
+    review_count = int(subset_plan.get("review_volume_count") or 0)
+    statuses = subset_plan.get("training_statuses") or []
+    source = (
+        "fully good ground-truth volume"
+        if statuses == ["ground_truth"]
+        else "labeled volume"
+    )
+    response = (
+        f"Yes. I found {train_count} {source}{'' if train_count == 1 else 's'} "
+        "that can be used for this training run, and I staged them as a clean subset "
+        "so draft or missing masks do not leak into the labels."
+    )
+    if include_segment_rest and target_count:
+        response += (
+            f" After training, the {target_count} image-only volume"
+            f"{'' if target_count == 1 else 's'} should be the first inference target."
+        )
+    if review_count:
+        response += (
+            f" I left {review_count} draft segmentation volume"
+            f"{'' if review_count == 1 else 's'} out of training until you mark them good."
+        )
+    response += " Review the run card before launching it."
+    return response
+
+
+def _build_agent_trace(
+    *,
+    workflow: WorkflowSession,
+    project_observation: Dict[str, Any],
+    intent: str,
+    actions: List[AgentChatAction],
+) -> List[AgentTraceItem]:
+    trace: List[AgentTraceItem] = [
+        AgentTraceItem(
+            label="Read workflow state",
+            detail=(
+                f"Stage: {workflow.stage}; "
+                f"image {'set' if workflow.image_path or workflow.dataset_path else 'missing'}; "
+                f"mask/label {'set' if workflow.label_path or workflow.mask_path else 'missing'}."
+            ),
+            category="checked",
+            **_agent_trace_kwargs(ORCHESTRATOR_AGENT),
+            data={
+                "schema_version": "agent_trace/v1",
+                "workflow_id": workflow.id,
+                "stage": workflow.stage,
+                "has_image": bool(workflow.image_path or workflow.dataset_path),
+                "has_label": bool(workflow.label_path or workflow.mask_path),
+                "has_checkpoint": bool(workflow.checkpoint_path),
+                "config_path": workflow.config_path,
+            },
+            evidence_refs=[
+                {"kind": "workflow_session", "id": workflow.id},
+            ],
+        )
+    ]
+    roots = project_observation.get("roots") or []
+    volume_sets = project_observation.get("volume_sets") or []
+    if roots:
+        root_names = ", ".join(
+            str(root.get("name") or root.get("path")) for root in roots[:2]
+        )
+        trace.append(
+            AgentTraceItem(
+                label="Checked project files",
+                detail=(
+                    f"Scanned {root_names}; found {len(volume_sets)} image/seg set(s)."
+                ),
+                category="checked",
+                **_agent_trace_kwargs(WORKFLOW_SUBAGENTS["data_agent"]),
+                data={
+                    "root_count": len(roots),
+                    "roots": [
+                        {
+                            "name": root.get("name"),
+                            "path": root.get("path"),
+                            "entry_count": root.get("entry_count"),
+                        }
+                        for root in roots[:5]
+                    ],
+                    "volume_set_count": len(volume_sets),
+                    "volume_sets": [
+                        {
+                            "id": item.get("id"),
+                            "name": item.get("name"),
+                            "image_count": item.get("image_count"),
+                            "label_count": item.get("label_count"),
+                        }
+                        for item in volume_sets[:5]
+                    ],
+                },
+                evidence_refs=[
+                    {"kind": "project_observation", "path": root.get("path")}
+                    for root in roots[:5]
+                    if root.get("path")
+                ],
+            )
+        )
+    elif project_observation.get("errors"):
+        trace.append(
+            AgentTraceItem(
+                label="Checked project files",
+                detail="Tried to inspect the project folder, but the scan failed.",
+                status="warning",
+                category="blocked_by",
+                **_agent_trace_kwargs(WORKFLOW_SUBAGENTS["data_agent"]),
+                data={"errors": project_observation.get("errors") or []},
+            )
+        )
+    else:
+        trace.append(
+            AgentTraceItem(
+                label="Checked project files",
+                detail="No mounted project root was available to scan.",
+                status="missing",
+                category="blocked_by",
+                **_agent_trace_kwargs(WORKFLOW_SUBAGENTS["data_agent"]),
+                data={"reason": "no_mounted_project_root"},
+            )
+        )
+    trace.append(
+        AgentTraceItem(
+            label="Prepared response",
+            detail=(
+                f"Intent: {intent}; " f"{len(actions)} runnable app card(s) prepared."
+            ),
+            category="proposed" if actions else "inferred",
+            **_agent_trace_kwargs(ORCHESTRATOR_AGENT),
+            data={
+                "intent": intent,
+                "orchestrator_agent": ORCHESTRATOR_AGENT,
+                "action_count": len(actions),
+                "actions": [
+                    {
+                        "id": action.id,
+                        "specialist_agent": action.specialist_agent,
+                        "action_type": action.action_type,
+                        "risk_tier": action.risk_tier,
+                        "requires_approval": action.requires_approval,
+                        "target": action.target,
+                    }
+                    for action in actions
+                ],
+            },
+            evidence_refs=[
+                {"kind": "action_card", "id": action.id} for action in actions
+            ],
+        )
+    )
+    return trace
+
+
+def _workflow_project_context(workflow: WorkflowSession) -> Dict[str, Any]:
+    metadata = decode_json(workflow.metadata_json)
+    context = metadata.get("project_context") if isinstance(metadata, dict) else {}
+    return context if isinstance(context, dict) else {}
+
+
+def _format_scale_number(value: float) -> str:
+    return str(int(value)) if float(value).is_integer() else f"{value:g}"
+
+
+def _format_scales(scales: List[float]) -> str:
+    return ",".join(_format_scale_number(value) for value in scales)
+
+
+def _format_voxel_size_nm(value: Any) -> str:
+    if not isinstance(value, list) or len(value) < 3:
+        return ""
+    try:
+        return (
+            " x ".join(_format_scale_number(float(item)) for item in value[:3]) + " nm"
+        )
+    except (TypeError, ValueError):
+        return ""
+
+
+def _parse_visualization_scales_from_query(query: str) -> Optional[List[float]]:
+    lower = query.lower()
+    values = [float(value) for value in re.findall(r"\d+(?:\.\d+)?", query)]
+    unit_multiplier = (
+        1000.0
+        if any(term in lower for term in ["µm", "um", "micron", "microns"])
+        else 1.0
+    )
+    if len(values) >= 3:
+        return [value * unit_multiplier for value in values[:3]]
+    if len(values) == 1 and any(
+        term in lower for term in ["isotropic", "same scale", "same voxel"]
+    ):
+        value = values[0] * unit_multiplier
+        return [value, value, value]
+    return None
+
+
+def _query_mentions_volume_id(lower_query: str) -> bool:
+    return bool(re.search(r"\b\d+_\d+\b", lower_query))
+
+
+def _query_explicitly_mutates_project_context(lower_query: str) -> bool:
+    explicit_phrases = [
+        "set project context",
+        "update project context",
+        "change project context",
+        "save project context",
+        "use project context",
+        "set context",
+        "update context",
+        "change context",
+        "save context",
+        "set voxel",
+        "update voxel",
+        "change voxel",
+        "use voxel",
+        "voxel size is",
+        "voxel spacing is",
+        "resolution is",
+        "set resolution",
+        "update resolution",
+        "change resolution",
+        "use resolution",
+        "this is ",
+        "these are ",
+        "we are ",
+        "we're ",
+        "the dataset is",
+        "the project is",
+    ]
+    return any(phrase in lower_query for phrase in explicit_phrases)
+
+
+def _query_wants_visualization_scales(lower_query: str) -> bool:
+    if not any(
+        term in lower_query
+        for term in [
+            "reload",
+            "load",
+            "open",
+            "show",
+            "view",
+            "visualize",
+            "visualise",
+            "set",
+            "change",
+            "update viewer",
+            "use scales",
+            "with scales",
+            "with voxel",
+            "viewer",
+        ]
+    ):
+        return False
+    explicit_scale_language = _query_has(
+        lower_query,
+        [
+            "scales",
+            "voxel size",
+            "voxel spacing",
+            "spacing",
+            "resolution",
+            "nanometer",
+            "nanometers",
+            "micron",
+            "microns",
+        ],
+    )
+    singular_scale_language = bool(
+        re.search(r"(?<![a-z0-9_-])scale(?![a-z0-9_-])", lower_query)
+    )
+    reload_with_values = (
+        "reload" in lower_query
+        and bool(re.search(r"\d", lower_query))
+        and any(marker in lower_query for marker in [",", "-", "nm", "um", "µm"])
+    )
+    return explicit_scale_language or singular_scale_language or reload_with_values
+
+
+def _store_visualization_scales(
+    db: Session,
+    workflow: WorkflowSession,
+    scales_nm: List[float],
+    *,
+    source_query: str,
+) -> None:
+    metadata = decode_json(workflow.metadata_json)
+    if not isinstance(metadata, dict):
+        metadata = {}
+    metadata["visualization_scales"] = scales_nm
+    metadata["visualization_scales_source"] = "workflow_agent"
+    project_context = metadata.get("project_context")
+    if not isinstance(project_context, dict):
+        project_context = {}
+    project_context["voxel_size_nm"] = scales_nm
+    project_context["voxel_size_source"] = "workflow_agent_visualization_scales"
+    metadata["project_context"] = project_context
+    update_workflow_fields(db, workflow, {"metadata": metadata}, commit=True)
+    append_workflow_event(
+        db,
+        workflow_id=workflow.id,
+        actor="agent",
+        event_type="visualization.scales_updated",
+        stage=workflow.stage,
+        summary=f"Saved visualization voxel scale {_format_scales(scales_nm)} nm.",
+        payload={
+            "scales_nm": scales_nm,
+            "source": "workflow_agent",
+            "query_preview": source_query[:240],
+        },
+        commit=True,
+    )
+
+
+def _extract_project_context_from_query(query: str) -> Dict[str, Any]:
+    lower = query.lower()
+    context: Dict[str, Any] = {}
+    modality_terms = [
+        ("X-ray / XRI volumetric microscopy", ["xri", "x-ray", "xray"]),
+        ("electron microscopy", ["electron microscopy", "electron microscope"]),
+        ("EM", [" em ", "em ", "sem", "tem", "fib-sem", "fib sem"]),
+        ("confocal microscopy", ["confocal"]),
+        ("light-sheet microscopy", ["light sheet", "light-sheet"]),
+        ("fluorescence microscopy", ["fluorescence", "fluorescent"]),
+        ("brightfield microscopy", ["brightfield", "bright-field"]),
+        ("MRI", [" mri ", "mri"]),
+        ("CT", [" ct ", "micro-ct", "micro ct"]),
+    ]
+    padded_lower = f" {lower} "
+    for label, terms in modality_terms:
+        if any(term in padded_lower for term in terms):
+            context["imaging_modality"] = label
+            break
+
+    target_terms = [
+        ("CytoTape fibres", ["cytotape", "fiber", "fibers", "fibre", "fibres"]),
+        ("mitochondria", ["mitochondria", "mitochondrion", "mito"]),
+        ("membranes", ["membrane", "membranes"]),
+        ("synapses", ["synapse", "synapses"]),
+        ("nuclei", ["nucleus", "nuclei"]),
+        ("cells", ["cell", "cells"]),
+        ("neurites", ["neurite", "neurites", "axon", "dendrite"]),
+        ("vasculature", ["vessel", "vasculature", "blood vessel"]),
+        ("organelle", ["organelle", "organelles"]),
+    ]
+    for label, terms in target_terms:
+        if any(term in lower for term in terms):
+            context["target_structure"] = label
+            break
+
+    if any(term in lower for term in ["xri", "x-ray", "xray"]) and any(
+        term in lower for term in ["cytotape", "fiber", "fibers", "fibre", "fibres"]
+    ):
+        context["task_family"] = "XRI fibre instance segmentation"
+    elif any(term in lower for term in ["mitochondria", "mitochondrion", "mito"]):
+        context["task_family"] = "mitochondria instance segmentation"
+    elif any(term in lower for term in ["synapse", "synapses", "cleft", "clefts"]):
+        context["task_family"] = "synapse segmentation"
+    elif any(term in lower for term in ["nucleus", "nuclei"]):
+        context["task_family"] = "nuclei instance segmentation"
+
+    if any(
+        phrase in lower
+        for phrase in [
+            "mixed masks",
+            "some masks",
+            "some image-only",
+            "some image only",
+            "partial masks",
+            "partially labeled",
+            "partially labelled",
+        ]
+    ):
+        context["mask_status"] = "mixed: some masks, some image-only volumes"
+    elif any(
+        phrase in lower
+        for phrase in [
+            "ground truth",
+            "ground-truth",
+            "fully proofread",
+            "curated masks",
+        ]
+    ):
+        context["mask_status"] = "ground-truth masks available"
+
+    if any(
+        phrase in lower
+        for phrase in [
+            "train only on ground truth",
+            "train only on ground-truth",
+            "only train on confirmed",
+            "only use confirmed",
+        ]
+    ):
+        context["training_policy"] = "train only on confirmed ground-truth masks"
+
+    if any(
+        term in lower
+        for term in ["fast", "quick", "smoke", "prototype", "speed", "care about speed"]
+    ):
+        context["optimization_priority"] = "speed"
+    elif any(term in lower for term in ["accurate", "accuracy", "quality", "best"]):
+        context["optimization_priority"] = "accuracy"
+
+    voxel_size_nm = (
+        _parse_visualization_scales_from_query(query)
+        if _query_wants_visualization_scales(lower)
+        or _query_explicitly_mutates_project_context(lower)
+        else None
+    )
+    if voxel_size_nm and not _query_mentions_volume_id(lower):
+        context["voxel_size_nm"] = voxel_size_nm
+        context["voxel_size_source"] = "workflow_agent_context"
+
+    if context:
+        context["freeform_note"] = query[:500]
+    return context
+
+
+def _merge_project_context(
+    db: Session,
+    workflow: WorkflowSession,
+    context_update: Dict[str, Any],
+) -> None:
+    if not context_update:
+        return
+    metadata = decode_json(workflow.metadata_json)
+    project_context = metadata.get("project_context")
+    if not isinstance(project_context, dict):
+        project_context = {}
+    project_context = {
+        **project_context,
+        **context_update,
+        "updated_at": datetime.now(timezone.utc).isoformat(),
+        "source": "workflow_agent_context",
+    }
+    metadata["project_context"] = project_context
+    voxel_size_nm = project_context.get("voxel_size_nm")
+    if isinstance(voxel_size_nm, list) and len(voxel_size_nm) >= 3:
+        metadata["visualization_scales"] = voxel_size_nm[:3]
+        metadata["visualization_scales_source"] = project_context.get(
+            "voxel_size_source",
+            "workflow_agent_context",
+        )
+    update_workflow_fields(db, workflow, {"metadata": metadata}, commit=False)
+
+
+def _project_context_missing_fields(workflow: WorkflowSession) -> List[str]:
+    context = _workflow_project_context(workflow)
+    if context.get("use_defaults"):
+        return []
+    missing = []
+    if not context.get("imaging_modality"):
+        missing.append("imaging modality")
+    if not context.get("target_structure"):
+        missing.append("target structure")
+    return missing
+
+
+def _format_project_context_prompt(
+    workflow: WorkflowSession,
+    action_label: str,
+) -> str:
+    missing = _project_context_missing_fields(workflow)
+    if not missing:
+        missing = [
+            "imaging modality",
+            "target structure",
+            "workflow type",
+        ]
+    return (
+        f"Before I {action_label}, I need one or two project details first: "
+        f"{', '.join(missing[:3])}. "
+        "A casual answer is fine, like: XRI fibres at 40 x 16.3 x 16.3 nm, "
+        "or EM mitochondria instance masks."
+    )
+
+
+def _format_project_context_saved_response(
+    workflow: WorkflowSession,
+    recommendation: WorkflowAgentRecommendationResponse,
+) -> str:
+    context = _workflow_project_context(workflow)
+    summary = []
+    if context.get("imaging_modality"):
+        summary.append(context["imaging_modality"])
+    if context.get("target_structure"):
+        summary.append(context["target_structure"])
+    if context.get("optimization_priority"):
+        summary.append(f"{context['optimization_priority']} priority")
+    if context.get("task_family"):
+        summary.append(context["task_family"])
+    voxel_size = _format_voxel_size_nm(context.get("voxel_size_nm"))
+    if voxel_size:
+        summary.append(f"{voxel_size} resolution")
+    missing = _project_context_missing_fields(workflow)
+    if missing:
+        return (
+            f"Got it, I saved {', '.join(summary) or 'that partial context'}. "
+            f"I still need {', '.join(missing)} before I choose the next workflow step."
+        )
+    summary_text = ", ".join(summary) if summary else "the project defaults"
+    return (
+        f"Got it, I saved {summary_text}. "
+        f"From here I would probably {_lower_first(_strip_sentence_period(recommendation.decision))}."
+    )
+
+
+def _format_project_context_response(
+    workflow: WorkflowSession,
+    recommendation: WorkflowAgentRecommendationResponse,
+) -> str:
+    project_context = _workflow_project_context(workflow)
+    project_name = workflow.title or f"Workflow #{workflow.id}"
+    image_label = _short_path_label(workflow.image_path or workflow.dataset_path)
+    mask_label = _short_path_label(
+        workflow.mask_path or workflow.label_path or workflow.inference_output_path
+    )
+    lines = [f"We are working in `{project_name}`."]
+    if image_label != "not set":
+        if mask_label != "not set":
+            lines.append(
+                f"I have image data at `{image_label}` and mask/result data at `{mask_label}`."
+            )
+        else:
+            lines.append(
+                f"I have image data at `{image_label}`, but no mask/result path is set yet."
+            )
+    if project_context.get("imaging_modality") or project_context.get(
+        "target_structure"
+    ):
+        context_bits = [
+            project_context.get("imaging_modality"),
+            project_context.get("target_structure"),
+            project_context.get("task_family"),
+            project_context.get("optimization_priority"),
+            _format_voxel_size_nm(project_context.get("voxel_size_nm")),
+        ]
+        lines.append(
+            "The project context I am using is "
+            + ", ".join(str(bit) for bit in context_bits if bit)
+            + "."
+        )
+    metadata = decode_json(workflow.metadata_json)
+    progress = (
+        metadata.get("project_progress_snapshot") if isinstance(metadata, dict) else {}
+    )
+    summary = progress.get("summary") if isinstance(progress, dict) else {}
+    if isinstance(summary, dict) and (
+        summary.get("tracked_total") or summary.get("total")
+    ):
+        total = summary.get("tracked_total") or summary.get("total")
+        lines.append(
+            f"The workflow tracker has {total} volume(s): "
+            f"{summary.get('ground_truth', 0)} fully good, "
+            f"{summary.get('needs_proofreading', 0)} needing proofreading, "
+            f"{summary.get('missing_segmentation', 0)} without segmentation."
+        )
+    lines.append(
+        f"My next useful move would be to {_lower_first(_strip_sentence_period(recommendation.decision))}."
+    )
+    return "\n".join(lines)
+
+
+def _format_informational_followup_response(
+    workflow: WorkflowSession,
+    recommendation: WorkflowAgentRecommendationResponse,
+) -> str:
+    context = _workflow_project_context(workflow)
+    lines = [
+        f"I would probably {_lower_first(_strip_sentence_period(recommendation.decision))}.",
+    ]
+    if recommendation.rationale:
+        lines.append(
+            f"The reason is pretty simple: {_lower_first(_strip_sentence_period(recommendation.rationale))}."
+        )
+    context_bits = [
+        context.get("imaging_modality"),
+        context.get("target_structure"),
+        context.get("task_family"),
+        context.get("optimization_priority"),
+        _format_voxel_size_nm(context.get("voxel_size_nm")),
+    ]
+    if any(context_bits):
+        lines.append(
+            "I am using: " + ", ".join(str(bit) for bit in context_bits if bit) + "."
+        )
+    if recommendation.blockers:
+        lines.append(
+            f"The current blocker is {_lower_first(_strip_sentence_period(recommendation.blockers[0]))}."
+        )
+    lines.append("When you want, I can turn that into a reviewable app action.")
+    return " ".join(lines)
+
+
+def _format_style_feedback_response(
+    workflow: WorkflowSession,
+    recommendation: WorkflowAgentRecommendationResponse,
+) -> str:
+    context = _workflow_project_context(workflow)
+    context_bits = [
+        context.get("imaging_modality"),
+        context.get("target_structure"),
+    ]
+    context_text = ", ".join(str(bit) for bit in context_bits if bit)
+    next_step = _lower_first(_strip_sentence_period(recommendation.decision))
+    if context_text:
+        return (
+            "Yeah, agreed. I will keep the chat answer more conversational and put the mechanical stuff behind the trace. "
+            f"For this {context_text} project, I would probably {next_step} next."
+        )
+    return (
+        "Yeah, agreed. I will keep the chat answer more conversational and put the mechanical stuff behind the trace. "
+        f"I would probably {next_step} next."
+    )
+
+
+def _format_needed_from_user_response(
+    recommendation: WorkflowAgentRecommendationResponse,
+) -> str:
+    if recommendation.stage == "proofreading":
+        gap = recommendation.blockers[0] if recommendation.blockers else "Save edits."
+        return (
+            "I need your mask judgment here. "
+            "Proofread the likely mistakes, save the fixes, then export masks. "
+            f"The current gap is {_lower_first(_strip_sentence_period(gap))}."
+        )
+
+    blocker = recommendation.blockers[0] if recommendation.blockers else None
+    if blocker:
+        return (
+            f"I am missing one workflow input: {_lower_first(_strip_sentence_period(blocker))}. "
+            f"Once that is set, I would probably {_lower_first(_strip_sentence_period(recommendation.decision))}."
+        )
+    return (
+        "I need your approval before changing artifacts. "
+        f"The app step I would run is {_lower_first(_strip_sentence_period(recommendation.decision))}."
+    )
+
+
+def _format_capabilities_response() -> str:
+    return "\n".join(
+        [
+            "I can run approved app steps: open data, infer, proofread, train on curated masks, compare metrics, export evidence, and move screens.",
+            "You can ask naturally, like 'show me another volume', 'train on the good masks', or 'segment the image-only volumes'.",
+            "For anything expensive or project-changing, I will stage a card first so you can review it.",
+        ]
+    )
+
+
+def _format_repair_response(
+    recommendation: WorkflowAgentRecommendationResponse,
+) -> str:
+    return "\n".join(
+        [
+            "That was too generic; I need a little more detail.",
+            "Say what you want to do next, or ask 'status' for what is ready.",
+            f"Current next step: {recommendation.decision}",
+        ]
+    )
+
+
+def _format_unknown_workflow_query_response(
+    recommendation: WorkflowAgentRecommendationResponse,
+) -> str:
+    return "\n".join(
+        [
+            "I am not sure which app step that maps to.",
+            f"Current next step: {recommendation.decision}",
+            "You can say it casually, e.g. 'segment this data', 'show my labels', 'proofread this', or 'train a model'.",
+        ]
+    )
+
+
+def _workflow_agent_tasks_from_readiness(
+    readiness: List[WorkflowReadinessItem],
+) -> List[AgentTaskItem]:
+    tasks: List[AgentTaskItem] = []
+    for index, item in enumerate(readiness, start=1):
+        status = "done" if item.complete else "blocked"
+        if not item.complete and item.severity != "warning":
+            status = "pending"
+        tasks.append(
+            AgentTaskItem(
+                id=item.id,
+                label=item.label,
+                status=status,
+                detail=item.detail,
+                priority="high" if index <= 2 and not item.complete else "normal",
+            )
+        )
+    return tasks
+
+
+@router.get("/current", response_model=WorkflowDetailResponse)
+def get_current_workflow(
+    user: auth_models.User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    workflow = get_current_or_create_workflow(db, user_id=user.id)
+    return {
+        "workflow": _workflow_response(workflow),
+        "events": _event_list(db, workflow.id),
+    }
+
+
+@router.post("/current/reset", response_model=WorkflowDetailResponse)
+def reset_current_workflow(
+    body: Optional[WorkflowResetRequest] = None,
+    user: auth_models.User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    body = body or WorkflowResetRequest()
+    workflow = create_workflow_session(
+        db,
+        user_id=user.id,
+        title=body.title or "Segmentation Workflow",
+        metadata={
+            **body.metadata,
+            "created_from": body.metadata.get("created_from", "workflow_reset"),
+        },
+    )
+    return {
+        "workflow": _workflow_response(workflow),
+        "events": _event_list(db, workflow.id),
+    }
+
+
+@router.patch("/{workflow_id}", response_model=WorkflowResponse)
+async def update_workflow(
+    workflow_id: int,
+    body: WorkflowUpdateRequest,
+    user: auth_models.User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    workflow = get_user_workflow_or_404(db, workflow_id=workflow_id, user_id=user.id)
+    updates = body.model_dump(exclude_unset=True)
+    workflow = update_workflow_fields(db, workflow, updates, commit=True)
+    return _workflow_response(workflow)
+
+
+@router.get("/{workflow_id}/events", response_model=List[WorkflowEventResponse])
+def list_workflow_events(
+    workflow_id: int,
+    user: auth_models.User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    get_user_workflow_or_404(db, workflow_id=workflow_id, user_id=user.id)
+    return _event_list(db, workflow_id)
+
+
+@router.get("/{workflow_id}/commands", response_model=List[WorkflowCommandResponse])
+def list_workflow_commands(
+    workflow_id: int,
+    user: auth_models.User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    get_user_workflow_or_404(db, workflow_id=workflow_id, user_id=user.id)
+    commands = (
+        db.query(WorkflowCommand)
+        .filter(WorkflowCommand.workflow_id == workflow_id)
+        .order_by(WorkflowCommand.created_at.asc(), WorkflowCommand.id.asc())
+        .all()
+    )
+    return [_command_response(command) for command in commands]
+
+
+@router.get("/{workflow_id}/hotspots", response_model=WorkflowHotspotsResponse)
+def get_workflow_hotspots(
+    workflow_id: int,
+    user: auth_models.User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    workflow = get_user_workflow_or_404(db, workflow_id=workflow_id, user_id=user.id)
+    events = _event_rows(db, workflow.id)
+    hotspots = _compute_hotspots(workflow, events)
+    _persist_computed_hotspots(db, workflow_id=workflow.id, hotspots=hotspots)
+    return WorkflowHotspotsResponse(
+        workflow_id=workflow.id,
+        generated_at=datetime.now(timezone.utc).isoformat(),
+        hotspots=hotspots,
+    )
+
+
+@router.get(
+    "/{workflow_id}/impact-preview",
+    response_model=WorkflowImpactPreviewResponse,
+)
+def get_workflow_impact_preview(
+    workflow_id: int,
+    user: auth_models.User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    workflow = get_user_workflow_or_404(db, workflow_id=workflow_id, user_id=user.id)
+    events = _event_rows(db, workflow.id)
+    hotspots = _compute_hotspots(workflow, events)
+    corrected_mask_path = workflow.corrected_mask_path or _latest_exported_mask_path(
+        db, workflow.id
+    )
+    return _compute_impact_preview(workflow, events, hotspots, corrected_mask_path)
+
+
+@router.get("/{workflow_id}/metrics", response_model=WorkflowMetricsResponse)
+def get_workflow_metrics(
+    workflow_id: int,
+    user: auth_models.User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    workflow = get_user_workflow_or_404(db, workflow_id=workflow_id, user_id=user.id)
+    events = _event_rows(db, workflow.id)
+    return WorkflowMetricsResponse(
+        workflow_id=workflow.id,
+        metrics=compute_workflow_metrics(events),
+    )
+
+
+@router.get(
+    "/{workflow_id}/project-progress",
+    response_model=WorkflowProjectProgressResponse,
+)
+def get_workflow_project_progress(
+    workflow_id: int,
+    user: auth_models.User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    workflow = get_user_workflow_or_404(db, workflow_id=workflow_id, user_id=user.id)
+    progress = _build_workflow_project_progress(db, workflow, user_id=user.id)
+    db.commit()
+    append_app_event(
+        component="workflow_project_progress",
+        event="project_progress_refreshed",
+        level="INFO",
+        message="Workflow project progress tracker refreshed.",
+        workflow_id=workflow.id,
+        user_id=user.id,
+        total=progress["summary"].get("total"),
+        ground_truth=progress["summary"].get("ground_truth"),
+        needs_proofreading=progress["summary"].get("needs_proofreading"),
+        missing_segmentation=progress["summary"].get("missing_segmentation"),
+    )
+    return progress
+
+
+@router.get(
+    "/{workflow_id}/memory",
+    response_model=Dict[str, Any],
+)
+def get_workflow_project_memory(
+    workflow_id: int,
+    refresh: bool = True,
+    user: auth_models.User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    workflow = get_user_workflow_or_404(db, workflow_id=workflow_id, user_id=user.id)
+    memory = _build_workflow_project_memory(
+        db,
+        workflow,
+        user_id=user.id,
+        refresh=refresh,
+    )
+    if refresh:
+        db.commit()
+    append_app_event(
+        component="workflow_project_memory",
+        event="project_memory_refreshed",
+        level="INFO",
+        message="Workflow project memory refreshed.",
+        workflow_id=workflow.id,
+        user_id=user.id,
+        task_family=memory["project_facts"]["task_family_preset"].get("id"),
+        tracked_total=memory["volume_states"]["summary"].get("total"),
+        event_count=len(memory["evidence_events"]),
+    )
+    return memory
+
+
+@router.get(
+    "/{workflow_id}/overview",
+    response_model=WorkflowOverviewResponse,
+)
+def get_workflow_overview(
+    workflow_id: int,
+    refresh: bool = True,
+    user: auth_models.User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    workflow = get_user_workflow_or_404(db, workflow_id=workflow_id, user_id=user.id)
+    overview = _build_workflow_overview(
+        db,
+        workflow,
+        user_id=user.id,
+        refresh=refresh,
+    )
+    if refresh:
+        db.commit()
+    append_app_event(
+        component="workflow_overview",
+        event="workflow_overview_refreshed",
+        level="INFO",
+        message="Workflow overview refreshed.",
+        workflow_id=workflow.id,
+        user_id=user.id,
+        phase=overview.phase,
+        tracked_total=overview.volume_summary.get("tracked_total"),
+        blockers=len(overview.blockers),
+        active_runs=len(overview.active_runs),
+    )
+    return overview
+
+
+@router.get(
+    "/{workflow_id}/volumes",
+    response_model=WorkflowVolumeStateListResponse,
+)
+def list_workflow_volume_states(
+    workflow_id: int,
+    refresh: bool = True,
+    user: auth_models.User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    workflow = get_user_workflow_or_404(db, workflow_id=workflow_id, user_id=user.id)
+    if refresh:
+        _build_workflow_project_progress(db, workflow, user_id=user.id)
+        db.commit()
+    rows = (
+        db.query(WorkflowVolumeState)
+        .filter(WorkflowVolumeState.workflow_id == workflow.id)
+        .order_by(WorkflowVolumeState.volume_id.asc())
+        .all()
+    )
+    return WorkflowVolumeStateListResponse(
+        workflow_id=workflow.id,
+        generated_at=datetime.now(timezone.utc).isoformat(),
+        summary=_volume_state_summary(rows),
+        volumes=[_volume_state_response(row) for row in rows],
+    )
+
+
+@router.patch(
+    "/{workflow_id}/volumes",
+    response_model=WorkflowVolumeStateResponse,
+)
+def update_workflow_volume_state(
+    workflow_id: int,
+    body: WorkflowVolumeStateUpdateRequest,
+    user: auth_models.User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    workflow = get_user_workflow_or_404(db, workflow_id=workflow_id, user_id=user.id)
+    if not body.volume_id:
+        raise HTTPException(status_code=400, detail="volume_id is required")
+    provided_fields = getattr(body, "model_fields_set", set()) or getattr(
+        body,
+        "__fields_set__",
+        set(),
+    )
+    if (
+        "status" in provided_fields
+        and body.status not in PROJECT_PROGRESS_STATUS_DEFINITIONS
+    ):
+        raise HTTPException(
+            status_code=400,
+            detail=f"status must be one of {sorted(PROJECT_PROGRESS_STATUS_DEFINITIONS)}",
+        )
+    _validate_composite_status_patch(
+        status=body.status if "status" in provided_fields else None,
+        annotation_state=(
+            body.annotation_state if "annotation_state" in provided_fields else None
+        ),
+        role_state=body.role_state if "role_state" in provided_fields else None,
+        execution_state=(
+            body.execution_state if "execution_state" in provided_fields else None
+        ),
+    )
+
+    row = (
+        db.query(WorkflowVolumeState)
+        .filter(
+            WorkflowVolumeState.workflow_id == workflow.id,
+            WorkflowVolumeState.volume_id == body.volume_id,
+        )
+        .first()
+    )
+    if row is None:
+        row = WorkflowVolumeState(
+            workflow_id=workflow.id,
+            volume_id=body.volume_id,
+            status=body.status or "missing_segmentation",
+            status_source="manual",
+            status_confidence=1.0,
+        )
+        db.add(row)
+        db.flush()
+
+    if "status" in provided_fields and body.status:
+        _set_row_composite_state(
+            row,
+            status=body.status,
+            annotation_state=(
+                body.annotation_state if "annotation_state" in provided_fields else None
+            ),
+            role_state=body.role_state if "role_state" in provided_fields else None,
+            execution_state=(
+                body.execution_state if "execution_state" in provided_fields else None
+            ),
+            region_scope=(
+                body.region_scope if "region_scope" in provided_fields else None
+            ),
+        )
+        row.status_source = "manual"
+        row.status_confidence = 1.0
+    elif any(
+        field in provided_fields
+        for field in [
+            "annotation_state",
+            "role_state",
+            "execution_state",
+            "region_scope",
+        ]
+    ):
+        _set_row_composite_state(
+            row,
+            annotation_state=(
+                body.annotation_state if "annotation_state" in provided_fields else None
+            ),
+            role_state=body.role_state if "role_state" in provided_fields else None,
+            execution_state=(
+                body.execution_state if "execution_state" in provided_fields else None
+            ),
+            region_scope=(
+                body.region_scope if "region_scope" in provided_fields else None
+            ),
+        )
+        row.status_source = "manual"
+        row.status_confidence = 1.0
+    else:
+        _ensure_row_composite_state(row)
+    if "note" in provided_fields:
+        row.note = body.note or ""
+    if "image_path" in provided_fields:
+        row.image_path = _normalize_absolute_path(body.image_path)
+    if "label_path" in provided_fields:
+        row.label_path = _normalize_absolute_path(body.label_path)
+    if "prediction_path" in provided_fields:
+        row.prediction_path = _normalize_absolute_path(body.prediction_path)
+    if "corrected_mask_path" in provided_fields:
+        row.corrected_mask_path = _normalize_absolute_path(body.corrected_mask_path)
+
+    metadata = decode_json(row.metadata_json)
+    if body.metadata is not None:
+        metadata = {**metadata, **body.metadata}
+    if "eligible_for_training" in provided_fields:
+        row.eligible_for_training = bool(body.eligible_for_training)
+        metadata["eligibility_source"] = "manual"
+    elif metadata.get("eligibility_source") != "manual":
+        _ensure_row_composite_state(row)
+        row.eligible_for_training = _volume_eligible_for_training_state(
+            annotation_state=row.annotation_state,
+            role_state=row.role_state,
+            label_path=row.label_path,
+            corrected_mask_path=row.corrected_mask_path,
+        )
+    if "eligible_for_inference" in provided_fields:
+        row.eligible_for_inference = bool(body.eligible_for_inference)
+        metadata["eligibility_source"] = "manual"
+    elif metadata.get("eligibility_source") != "manual":
+        _ensure_row_composite_state(row)
+        row.eligible_for_inference = _volume_eligible_for_inference_state(
+            annotation_state=row.annotation_state,
+            role_state=row.role_state,
+            image_path=row.image_path,
+        )
+    metadata["updated_from"] = "volume_state_api"
+    metadata["updated_at"] = datetime.now(timezone.utc).isoformat()
+    row.metadata_json = encode_json(metadata)
+
+    append_workflow_event(
+        db,
+        workflow_id=workflow.id,
+        actor="user",
+        event_type="project_volume.state_updated",
+        stage=workflow.stage,
+        summary=f"Updated project volume state for {body.volume_id}.",
+        payload={
+            "volume_id": body.volume_id,
+            "status": row.status,
+            "annotation_state": row.annotation_state,
+            "role_state": row.role_state,
+            "execution_state": row.execution_state,
+            "eligible_for_training": row.eligible_for_training,
+            "eligible_for_inference": row.eligible_for_inference,
+            "source": "volume_state_api",
+        },
+        commit=False,
+    )
+    db.commit()
+    db.refresh(row)
+    return _volume_state_response(row)
+
+
+@router.post(
+    "/{workflow_id}/project-progress/volume-status",
+    response_model=WorkflowProjectProgressResponse,
+)
+def update_workflow_project_progress_volume_status(
+    workflow_id: int,
+    body: WorkflowProjectProgressVolumeUpdate,
+    user: auth_models.User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    workflow = get_user_workflow_or_404(db, workflow_id=workflow_id, user_id=user.id)
+    provided_fields = getattr(body, "model_fields_set", set()) or getattr(
+        body,
+        "__fields_set__",
+        set(),
+    )
+    if not body.volume_id:
+        raise HTTPException(status_code=400, detail="volume_id is required")
+    if (
+        "status" in provided_fields
+        and body.status not in PROJECT_PROGRESS_STATUS_DEFINITIONS
+    ):
+        raise HTTPException(
+            status_code=400,
+            detail=f"status must be one of {sorted(PROJECT_PROGRESS_STATUS_DEFINITIONS)}",
+        )
+    metadata = decode_json(workflow.metadata_json)
+    overrides = metadata.get("project_progress_overrides")
+    overrides = overrides if isinstance(overrides, dict) else {}
+    current = overrides.get(body.volume_id)
+    current = current if isinstance(current, dict) else {}
+    if "status" in provided_fields:
+        current["status"] = body.status
+    if "note" in provided_fields:
+        current["note"] = body.note or ""
+    if not current.get("status") and not current.get("note"):
+        overrides.pop(body.volume_id, None)
+    else:
+        overrides[body.volume_id] = current
+    metadata["project_progress_overrides"] = overrides
+    workflow.metadata_json = encode_json(metadata)
+
+    row = (
+        db.query(WorkflowVolumeState)
+        .filter(
+            WorkflowVolumeState.workflow_id == workflow.id,
+            WorkflowVolumeState.volume_id == body.volume_id,
+        )
+        .first()
+    )
+    if row is None:
+        row = WorkflowVolumeState(
+            workflow_id=workflow.id,
+            volume_id=body.volume_id,
+            status=body.status or "missing_segmentation",
+            status_source="manual_override",
+            status_confidence=1.0,
+        )
+        db.add(row)
+        db.flush()
+    if "status" in provided_fields and body.status:
+        _set_row_composite_state(row, status=body.status)
+        row.status_source = "manual_override"
+        row.status_confidence = 1.0
+    else:
+        _ensure_row_composite_state(row)
+    if "note" in provided_fields:
+        row.note = body.note or ""
+
+    progress = _build_workflow_project_progress(db, workflow, user_id=user.id)
+    append_workflow_event(
+        db,
+        workflow_id=workflow.id,
+        actor="user",
+        event_type="project_volume.status_updated",
+        stage=workflow.stage,
+        summary=f"Updated project volume {body.volume_id} status.",
+        payload={
+            "volume_id": body.volume_id,
+            "status": row.status,
+            "annotation_state": row.annotation_state,
+            "role_state": row.role_state,
+            "execution_state": row.execution_state,
+            "note": row.note,
+            "source": "progress_page",
+        },
+        commit=False,
+    )
+    db.commit()
+    append_app_event(
+        component="workflow_project_progress",
+        event="project_progress_volume_status_updated",
+        level="INFO",
+        message="Workflow project progress volume status override updated.",
+        workflow_id=workflow.id,
+        user_id=user.id,
+        volume_id=body.volume_id,
+        status=current.get("status"),
+    )
+    return progress
+
+
+@router.get(
+    "/{workflow_id}/agent/recommendation",
+    response_model=WorkflowAgentRecommendationResponse,
+)
+def get_workflow_agent_recommendation(
+    workflow_id: int,
+    user: auth_models.User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    workflow = get_user_workflow_or_404(db, workflow_id=workflow_id, user_id=user.id)
+    return _build_workflow_agent_recommendation(db, workflow)
+
+
+@router.get(
+    "/{workflow_id}/preflight",
+    response_model=WorkflowPreflightResponse,
+)
+def get_workflow_preflight(
+    workflow_id: int,
+    user: auth_models.User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    workflow = get_user_workflow_or_404(db, workflow_id=workflow_id, user_id=user.id)
+    return _build_workflow_preflight(db, workflow)
+
+
+@router.get(
+    "/{workflow_id}/artifacts",
+    response_model=List[WorkflowArtifactResponse],
+)
+def list_workflow_artifacts(
+    workflow_id: int,
+    artifact_type: Optional[str] = None,
+    user: auth_models.User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    get_user_workflow_or_404(db, workflow_id=workflow_id, user_id=user.id)
+    query = db.query(WorkflowArtifact).filter(
+        WorkflowArtifact.workflow_id == workflow_id
+    )
+    if artifact_type:
+        query = query.filter(WorkflowArtifact.artifact_type == artifact_type)
+    rows = query.order_by(
+        WorkflowArtifact.created_at.asc(), WorkflowArtifact.id.asc()
+    ).all()
+    return [_artifact_response(row) for row in rows]
+
+
+@router.post(
+    "/{workflow_id}/artifacts",
+    response_model=WorkflowArtifactResponse,
+)
+def create_artifact(
+    workflow_id: int,
+    body: WorkflowArtifactCreateRequest,
+    user: auth_models.User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    workflow = get_user_workflow_or_404(db, workflow_id=workflow_id, user_id=user.id)
+    artifact = create_workflow_artifact(
+        db,
+        workflow_id=workflow.id,
+        artifact_type=body.artifact_type,
+        role=body.role,
+        path=body.path,
+        uri=body.uri,
+        name=body.name,
+        checksum=body.checksum,
+        metadata=body.metadata,
+        commit=True,
+    )
+    return _artifact_response(artifact)
+
+
+@router.get(
+    "/{workflow_id}/model-runs",
+    response_model=List[WorkflowModelRunResponse],
+)
+def list_model_runs(
+    workflow_id: int,
+    run_type: Optional[str] = None,
+    user: auth_models.User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    get_user_workflow_or_404(db, workflow_id=workflow_id, user_id=user.id)
+    query = db.query(WorkflowModelRun).filter(
+        WorkflowModelRun.workflow_id == workflow_id
+    )
+    if run_type:
+        query = query.filter(WorkflowModelRun.run_type == run_type)
+    rows = query.order_by(
+        WorkflowModelRun.created_at.asc(), WorkflowModelRun.id.asc()
+    ).all()
+    return [_model_run_response(row) for row in rows]
+
+
+@router.post(
+    "/{workflow_id}/model-runs",
+    response_model=WorkflowModelRunResponse,
+)
+def create_model_run(
+    workflow_id: int,
+    body: WorkflowModelRunCreateRequest,
+    user: auth_models.User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    workflow = get_user_workflow_or_404(db, workflow_id=workflow_id, user_id=user.id)
+    run = WorkflowModelRun(
+        workflow_id=workflow.id,
+        run_id=body.run_id,
+        run_type=body.run_type,
+        status=body.status,
+        name=body.name,
+        config_path=body.config_path,
+        log_path=body.log_path,
+        output_path=body.output_path,
+        checkpoint_path=body.checkpoint_path,
+        input_artifact_id=body.input_artifact_id,
+        output_artifact_id=body.output_artifact_id,
+        metrics_json=encode_json(body.metrics),
+        metadata_json=encode_json(body.metadata),
+    )
+    db.add(run)
+    db.commit()
+    db.refresh(run)
+    return _model_run_response(run)
+
+
+@router.get(
+    "/{workflow_id}/model-versions",
+    response_model=List[WorkflowModelVersionResponse],
+)
+def list_model_versions(
+    workflow_id: int,
+    user: auth_models.User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    get_user_workflow_or_404(db, workflow_id=workflow_id, user_id=user.id)
+    rows = (
+        db.query(WorkflowModelVersion)
+        .filter(WorkflowModelVersion.workflow_id == workflow_id)
+        .order_by(WorkflowModelVersion.created_at.asc(), WorkflowModelVersion.id.asc())
+        .all()
+    )
+    return [_model_version_response(row) for row in rows]
+
+
+@router.post(
+    "/{workflow_id}/model-versions",
+    response_model=WorkflowModelVersionResponse,
+)
+def create_model_version(
+    workflow_id: int,
+    body: WorkflowModelVersionCreateRequest,
+    user: auth_models.User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    workflow = get_user_workflow_or_404(db, workflow_id=workflow_id, user_id=user.id)
+    version = WorkflowModelVersion(
+        workflow_id=workflow.id,
+        version_label=body.version_label,
+        status=body.status,
+        checkpoint_path=body.checkpoint_path,
+        training_run_id=body.training_run_id,
+        checkpoint_artifact_id=body.checkpoint_artifact_id,
+        correction_set_id=body.correction_set_id,
+        metrics_json=encode_json(body.metrics),
+        metadata_json=encode_json(body.metadata),
+    )
+    db.add(version)
+    db.commit()
+    db.refresh(version)
+    return _model_version_response(version)
+
+
+@router.get(
+    "/{workflow_id}/correction-sets",
+    response_model=List[WorkflowCorrectionSetResponse],
+)
+def list_correction_sets(
+    workflow_id: int,
+    user: auth_models.User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    get_user_workflow_or_404(db, workflow_id=workflow_id, user_id=user.id)
+    rows = (
+        db.query(WorkflowCorrectionSet)
+        .filter(WorkflowCorrectionSet.workflow_id == workflow_id)
+        .order_by(
+            WorkflowCorrectionSet.created_at.asc(), WorkflowCorrectionSet.id.asc()
+        )
+        .all()
+    )
+    return [_correction_set_response(row) for row in rows]
+
+
+@router.get(
+    "/{workflow_id}/evaluation-results",
+    response_model=List[WorkflowEvaluationResponse],
+)
+def list_evaluation_results(
+    workflow_id: int,
+    user: auth_models.User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    get_user_workflow_or_404(db, workflow_id=workflow_id, user_id=user.id)
+    rows = (
+        db.query(WorkflowEvaluationResult)
+        .filter(WorkflowEvaluationResult.workflow_id == workflow_id)
+        .order_by(
+            WorkflowEvaluationResult.created_at.asc(),
+            WorkflowEvaluationResult.id.asc(),
+        )
+        .all()
+    )
+    return [_evaluation_response(row) for row in rows]
+
+
+@router.post(
+    "/{workflow_id}/evaluation-results",
+    response_model=WorkflowEvaluationResponse,
+)
+def create_evaluation_result(
+    workflow_id: int,
+    body: WorkflowEvaluationCreateRequest,
+    user: auth_models.User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    workflow = get_user_workflow_or_404(db, workflow_id=workflow_id, user_id=user.id)
+    report_artifact = None
+    if body.report_path:
+        report_artifact = create_workflow_artifact(
+            db,
+            workflow_id=workflow.id,
+            artifact_type="evaluation_report",
+            role="case_study_evidence",
+            path=body.report_path,
+            metadata={"source": "manual_evaluation_result"},
+            commit=False,
+        )
+    result = WorkflowEvaluationResult(
+        workflow_id=workflow.id,
+        name=body.name,
+        baseline_run_id=body.baseline_run_id,
+        candidate_run_id=body.candidate_run_id,
+        model_version_id=body.model_version_id,
+        report_artifact_id=report_artifact.id if report_artifact else None,
+        report_path=body.report_path,
+        summary=body.summary,
+        metrics_json=encode_json(body.metrics),
+        metadata_json=encode_json(body.metadata),
+    )
+    db.add(result)
+    db.commit()
+    db.refresh(result)
+    return _evaluation_response(result)
+
+
+@router.post(
+    "/{workflow_id}/evaluation-results/compute",
+    response_model=WorkflowEvaluationResponse,
+)
+def compute_evaluation_result(
+    workflow_id: int,
+    body: WorkflowEvaluationComputeRequest,
+    user: auth_models.User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    workflow = get_user_workflow_or_404(db, workflow_id=workflow_id, user_id=user.id)
+    try:
+        metrics = compute_before_after_evaluation(
+            baseline_prediction_path=body.baseline_prediction_path,
+            candidate_prediction_path=body.candidate_prediction_path,
+            ground_truth_path=body.ground_truth_path,
+            baseline_dataset=body.baseline_dataset,
+            candidate_dataset=body.candidate_dataset,
+            ground_truth_dataset=body.ground_truth_dataset,
+            crop=body.crop,
+            baseline_channel=body.baseline_channel,
+            candidate_channel=body.candidate_channel,
+            ground_truth_channel=body.ground_truth_channel,
+        )
+    except FileNotFoundError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+    except RuntimeError as exc:
+        raise HTTPException(status_code=500, detail=str(exc)) from exc
+
+    metadata = {
+        **body.metadata,
+        "baseline_prediction_path": body.baseline_prediction_path,
+        "candidate_prediction_path": body.candidate_prediction_path,
+        "ground_truth_path": body.ground_truth_path,
+        "baseline_dataset": body.baseline_dataset,
+        "candidate_dataset": body.candidate_dataset,
+        "ground_truth_dataset": body.ground_truth_dataset,
+        "crop": body.crop,
+        "baseline_channel": body.baseline_channel,
+        "candidate_channel": body.candidate_channel,
+        "ground_truth_channel": body.ground_truth_channel,
+    }
+    summary = (
+        "Before/after evaluation computed. "
+        f"Dice delta: {metrics.get('summary', {}).get('dice_delta')}."
+    )
+    report_path = body.report_path
+    if report_path:
+        report_payload = {
+            "workflow_id": workflow.id,
+            "name": body.name,
+            "summary": summary,
+            "metrics": metrics,
+            "metadata": metadata,
+        }
+        report_path = write_evaluation_report(report_path, report_payload)
+
+    report_artifact = None
+    if report_path:
+        report_artifact = create_workflow_artifact(
+            db,
+            workflow_id=workflow.id,
+            artifact_type="evaluation_report",
+            role="case_study_evidence",
+            path=report_path,
+            metadata={"source": "computed_evaluation_result"},
+            commit=False,
+        )
+
+    result = WorkflowEvaluationResult(
+        workflow_id=workflow.id,
+        name=body.name or "before-after-evaluation",
+        baseline_run_id=body.baseline_run_id,
+        candidate_run_id=body.candidate_run_id,
+        model_version_id=body.model_version_id,
+        report_artifact_id=report_artifact.id if report_artifact else None,
+        report_path=report_path,
+        summary=summary,
+        metrics_json=encode_json(metrics),
+        metadata_json=encode_json(metadata),
+    )
+    db.add(result)
+    db.commit()
+    db.refresh(result)
+    return _evaluation_response(result)
+
+
+@router.get(
+    "/{workflow_id}/persisted-hotspots",
+    response_model=List[WorkflowRegionHotspotResponse],
+)
+def list_persisted_hotspots(
+    workflow_id: int,
+    user: auth_models.User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    get_user_workflow_or_404(db, workflow_id=workflow_id, user_id=user.id)
+    rows = (
+        db.query(WorkflowRegionHotspot)
+        .filter(WorkflowRegionHotspot.workflow_id == workflow_id)
+        .order_by(WorkflowRegionHotspot.score.desc(), WorkflowRegionHotspot.id.asc())
+        .all()
+    )
+    return [_region_hotspot_response(row) for row in rows]
+
+
+def _has_event(events: List[WorkflowEvent], event_type: str) -> bool:
+    return any(event.event_type == event_type for event in events)
+
+
+def _case_study_readiness_gates(
+    workflow: WorkflowSession, events: List[WorkflowEvent]
+) -> List[Dict[str, Any]]:
+    artifacts = list(getattr(workflow, "artifacts", []) or [])
+    runs = list(getattr(workflow, "model_runs", []) or [])
+    versions = list(getattr(workflow, "model_versions", []) or [])
+    correction_sets = list(getattr(workflow, "correction_sets", []) or [])
+    evaluations = list(getattr(workflow, "evaluation_results", []) or [])
+    agent_plans = list(getattr(workflow, "agent_plans", []) or [])
+    inference_completed = [
+        run for run in runs if run.run_type == "inference" and run.status == "completed"
+    ]
+    proposal_audit_complete = bool(
+        _has_event(events, "agent.proposal_created")
+        and (
+            _has_event(events, "agent.proposal_approved")
+            or _has_event(events, "agent.proposal_rejected")
+        )
+    )
+    agent_plan_created = bool(agent_plans or _has_event(events, "agent.plan_created"))
+    agent_plan_decisioned = bool(
+        any(
+            plan.approval_status in {"approved", "rejected"}
+            or plan.status in {"approved", "interrupted", "rejected"}
+            for plan in agent_plans
+        )
+        or _has_event(events, "agent.plan_approved")
+        or _has_event(events, "agent.plan_rejected")
+        or _has_event(events, "agent.plan_interrupted")
+        or _has_event(events, "agent.plan_resumed")
+    )
+
+    gates = [
+        {
+            "id": "workflow_context",
+            "label": "Workflow context exists",
+            "complete": bool(workflow.id and _has_event(events, "workflow.created")),
+            "required_for": ["CS1", "CS7"],
+        },
+        {
+            "id": "data_loaded",
+            "label": "Dataset/image artifacts are linked",
+            "complete": bool(
+                workflow.image_path
+                or any(
+                    a.artifact_type in {"dataset", "image_volume"} for a in artifacts
+                )
+                or _has_event(events, "dataset.loaded")
+                or _has_event(events, "viewer.created")
+            ),
+            "required_for": ["CS1"],
+        },
+        {
+            "id": "baseline_inference",
+            "label": "Baseline inference run/output is captured",
+            "complete": bool(
+                workflow.inference_output_path
+                or any(run.run_type == "inference" for run in runs)
+                or _has_event(events, "inference.completed")
+            ),
+            "required_for": ["CS1", "CS4"],
+        },
+        {
+            "id": "proofreading_corrections",
+            "label": "Proofreading corrections are saved/exported",
+            "complete": bool(
+                workflow.corrected_mask_path
+                or correction_sets
+                or _has_event(events, "proofreading.masks_exported")
+            ),
+            "required_for": ["CS2", "CS3"],
+        },
+        {
+            "id": "retraining_handoff",
+            "label": "Corrections can be staged for retraining",
+            "complete": bool(
+                workflow.stage in {"retraining_staged", "evaluation"}
+                or _has_event(events, "retraining.staged")
+            ),
+            "required_for": ["CS3", "CS5"],
+        },
+        {
+            "id": "training_completion",
+            "label": "Retraining produces a terminal run record",
+            "complete": bool(
+                any(
+                    run.run_type == "training" and run.status in {"completed", "failed"}
+                    for run in runs
+                )
+                or _has_event(events, "training.completed")
+                or _has_event(events, "training.failed")
+            ),
+            "required_for": ["CS3", "CS6"],
+        },
+        {
+            "id": "model_version",
+            "label": "A versioned candidate model exists",
+            "complete": bool(versions or workflow.checkpoint_path),
+            "required_for": ["CS3", "CS4"],
+        },
+        {
+            "id": "post_retraining_inference",
+            "label": "Post-retraining inference is captured",
+            "complete": len(inference_completed) >= 2,
+            "required_for": ["CS4"],
+        },
+        {
+            "id": "evaluation_result",
+            "label": "Before/after evaluation evidence exists",
+            "complete": bool(evaluations),
+            "required_for": ["CS4", "CS7"],
+        },
+        {
+            "id": "agent_plan_preview",
+            "label": "Bounded agent plan is previewed and decisioned",
+            "complete": bool(agent_plan_created and agent_plan_decisioned),
+            "required_for": ["CS5", "CS6"],
+        },
+        {
+            "id": "agent_audit",
+            "label": "Agent proposal decisions are auditable",
+            "complete": bool(
+                proposal_audit_complete
+                or (agent_plan_created and agent_plan_decisioned)
+            ),
+            "required_for": ["CS5", "CS6"],
+        },
+    ]
+    return gates
+
+
+@router.get(
+    "/{workflow_id}/case-study-readiness",
+    response_model=WorkflowReadinessResponse,
+)
+def get_case_study_readiness(
     workflow_id: int,
-    body: WorkflowUpdateRequest,
     user: auth_models.User = Depends(get_current_user),
     db: Session = Depends(get_db),
 ):
     workflow = get_user_workflow_or_404(db, workflow_id=workflow_id, user_id=user.id)
-    updates = body.model_dump(exclude_unset=True)
-    workflow = update_workflow_fields(db, workflow, updates, commit=True)
-    return _workflow_response(workflow)
+    events = _event_rows(db, workflow.id)
+    gates = _case_study_readiness_gates(workflow, events)
+    completed_count = len([gate for gate in gates if gate["complete"]])
+    next_required_items = [gate["label"] for gate in gates if not gate["complete"]][:4]
+    return WorkflowReadinessResponse(
+        workflow_id=workflow.id,
+        ready_for_case_study=completed_count == len(gates),
+        completed_count=completed_count,
+        total_count=len(gates),
+        gates=gates,
+        next_required_items=next_required_items,
+    )
 
 
-@router.get("/{workflow_id}/events", response_model=List[WorkflowEventResponse])
-def list_workflow_events(
+def _create_agent_plan_preview(
+    db: Session,
+    *,
+    workflow: WorkflowSession,
+    events: List[WorkflowEvent],
+    body: WorkflowAgentPlanCreateRequest,
+) -> WorkflowAgentPlan:
+    gates = _case_study_readiness_gates(workflow, events)
+    graph = build_case_study_plan_graph(
+        workflow=workflow,
+        events=events,
+        gates=gates,
+        title=body.title,
+        goal=body.goal,
+    )
+    plan = WorkflowAgentPlan(
+        workflow_id=workflow.id,
+        title=graph["title"],
+        status="draft",
+        risk_level="medium",
+        approval_status="pending",
+        goal=graph["goal"],
+        graph_json=encode_json(graph),
+        metadata_json=encode_json(
+            {
+                **body.metadata,
+                "plan_type": body.plan_type,
+                "source": "case_study_plan_preview",
+            }
+        ),
+    )
+    db.add(plan)
+    db.flush()
+
+    for node in graph.get("nodes", []):
+        step = WorkflowAgentStep(
+            plan_id=plan.id,
+            step_index=int(node.get("index", 0)),
+            action=str(node.get("action")),
+            status=str(node.get("status") or "blocked"),
+            requires_approval=bool(node.get("requires_approval")),
+            summary=node.get("summary"),
+            params_json=encode_json(
+                {
+                    "title": node.get("title"),
+                    "stage": node.get("stage"),
+                    "gate_id": node.get("gate_id"),
+                    "dependencies": node.get("dependencies") or [],
+                    "client_effects": node.get("client_effects") or {},
+                    "required_for": node.get("required_for") or [],
+                }
+            ),
+        )
+        db.add(step)
+
+    db.flush()
+    event = append_workflow_event(
+        db,
+        workflow_id=workflow.id,
+        actor="agent",
+        event_type="agent.plan_created",
+        stage=workflow.stage,
+        summary=f"Created bounded agent plan: {plan.title}",
+        payload={
+            "plan_id": plan.id,
+            "plan_type": body.plan_type,
+            "ready_steps": len(
+                [
+                    node
+                    for node in graph.get("nodes", [])
+                    if node.get("status") == "ready"
+                ]
+            ),
+            "blocked_steps": len(
+                [
+                    node
+                    for node in graph.get("nodes", [])
+                    if node.get("status") == "blocked"
+                ]
+            ),
+            "graph_spec_version": graph.get("graph_spec_version"),
+        },
+        approval_status="pending",
+        commit=False,
+    )
+    plan.source_event_id = event.id if event else None
+    db.commit()
+    db.refresh(plan)
+    return plan
+
+
+@router.get(
+    "/{workflow_id}/agent-plans",
+    response_model=List[WorkflowAgentPlanResponse],
+)
+def list_agent_plans(
     workflow_id: int,
     user: auth_models.User = Depends(get_current_user),
     db: Session = Depends(get_db),
 ):
     get_user_workflow_or_404(db, workflow_id=workflow_id, user_id=user.id)
-    return _event_list(db, workflow_id)
+    rows = (
+        db.query(WorkflowAgentPlan)
+        .filter(WorkflowAgentPlan.workflow_id == workflow_id)
+        .order_by(WorkflowAgentPlan.created_at.asc(), WorkflowAgentPlan.id.asc())
+        .all()
+    )
+    return [_agent_plan_response(row) for row in rows]
 
 
-@router.get("/{workflow_id}/hotspots", response_model=WorkflowHotspotsResponse)
-def get_workflow_hotspots(
+@router.post(
+    "/{workflow_id}/agent-plans",
+    response_model=WorkflowAgentPlanResponse,
+)
+def create_agent_plan(
     workflow_id: int,
+    body: WorkflowAgentPlanCreateRequest,
     user: auth_models.User = Depends(get_current_user),
     db: Session = Depends(get_db),
 ):
     workflow = get_user_workflow_or_404(db, workflow_id=workflow_id, user_id=user.id)
     events = _event_rows(db, workflow.id)
-    hotspots = _compute_hotspots(workflow, events)
-    return WorkflowHotspotsResponse(
-        workflow_id=workflow.id,
-        generated_at=datetime.now(timezone.utc).isoformat(),
-        hotspots=hotspots,
+    plan = _create_agent_plan_preview(
+        db,
+        workflow=workflow,
+        events=events,
+        body=body,
     )
+    return _agent_plan_response(plan)
 
 
 @router.get(
-    "/{workflow_id}/impact-preview",
-    response_model=WorkflowImpactPreviewResponse,
+    "/{workflow_id}/agent-plans/{plan_id}",
+    response_model=WorkflowAgentPlanResponse,
 )
-def get_workflow_impact_preview(
+def get_agent_plan(
+    workflow_id: int,
+    plan_id: int,
+    user: auth_models.User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    get_user_workflow_or_404(db, workflow_id=workflow_id, user_id=user.id)
+    plan = _get_agent_plan_or_404(db, workflow_id=workflow_id, plan_id=plan_id)
+    return _agent_plan_response(plan)
+
+
+@router.post(
+    "/{workflow_id}/agent-plans/{plan_id}/approve",
+    response_model=WorkflowAgentPlanResponse,
+)
+def approve_agent_plan(
     workflow_id: int,
+    plan_id: int,
     user: auth_models.User = Depends(get_current_user),
     db: Session = Depends(get_db),
 ):
     workflow = get_user_workflow_or_404(db, workflow_id=workflow_id, user_id=user.id)
-    events = _event_rows(db, workflow.id)
-    hotspots = _compute_hotspots(workflow, events)
-    corrected_mask_path = workflow.corrected_mask_path or _latest_exported_mask_path(
-        db, workflow.id
+    plan = _get_agent_plan_or_404(db, workflow_id=workflow.id, plan_id=plan_id)
+    if plan.approval_status == "rejected":
+        raise HTTPException(status_code=400, detail="Rejected plans cannot be approved")
+    plan.approval_status = "approved"
+    plan.status = "approved"
+    append_workflow_event(
+        db,
+        workflow_id=workflow.id,
+        actor="user",
+        event_type="agent.plan_approved",
+        stage=workflow.stage,
+        summary=f"Approved bounded agent plan: {plan.title}",
+        payload={"plan_id": plan.id},
+        commit=False,
     )
-    return _compute_impact_preview(workflow, events, hotspots, corrected_mask_path)
+    db.commit()
+    db.refresh(plan)
+    return _agent_plan_response(plan)
 
 
-@router.get("/{workflow_id}/metrics", response_model=WorkflowMetricsResponse)
-def get_workflow_metrics(
+@router.post(
+    "/{workflow_id}/agent-plans/{plan_id}/reject",
+    response_model=WorkflowAgentPlanResponse,
+)
+def reject_agent_plan(
     workflow_id: int,
+    plan_id: int,
     user: auth_models.User = Depends(get_current_user),
     db: Session = Depends(get_db),
 ):
     workflow = get_user_workflow_or_404(db, workflow_id=workflow_id, user_id=user.id)
-    events = _event_rows(db, workflow.id)
-    return WorkflowMetricsResponse(
+    plan = _get_agent_plan_or_404(db, workflow_id=workflow.id, plan_id=plan_id)
+    plan.approval_status = "rejected"
+    plan.status = "rejected"
+    append_workflow_event(
+        db,
         workflow_id=workflow.id,
-        metrics=compute_workflow_metrics(events),
+        actor="user",
+        event_type="agent.plan_rejected",
+        stage=workflow.stage,
+        summary=f"Rejected bounded agent plan: {plan.title}",
+        payload={"plan_id": plan.id},
+        commit=False,
+    )
+    db.commit()
+    db.refresh(plan)
+    return _agent_plan_response(plan)
+
+
+@router.post(
+    "/{workflow_id}/agent-plans/{plan_id}/interrupt",
+    response_model=WorkflowAgentPlanResponse,
+)
+def interrupt_agent_plan(
+    workflow_id: int,
+    plan_id: int,
+    user: auth_models.User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    workflow = get_user_workflow_or_404(db, workflow_id=workflow_id, user_id=user.id)
+    plan = _get_agent_plan_or_404(db, workflow_id=workflow.id, plan_id=plan_id)
+    if plan.status == "rejected":
+        raise HTTPException(
+            status_code=400, detail="Rejected plans cannot be interrupted"
+        )
+    plan.status = "interrupted"
+    append_workflow_event(
+        db,
+        workflow_id=workflow.id,
+        actor="user",
+        event_type="agent.plan_interrupted",
+        stage=workflow.stage,
+        summary=f"Interrupted bounded agent plan: {plan.title}",
+        payload={"plan_id": plan.id},
+        commit=False,
+    )
+    db.commit()
+    db.refresh(plan)
+    return _agent_plan_response(plan)
+
+
+@router.post(
+    "/{workflow_id}/agent-plans/{plan_id}/resume",
+    response_model=WorkflowAgentPlanResponse,
+)
+def resume_agent_plan(
+    workflow_id: int,
+    plan_id: int,
+    user: auth_models.User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    workflow = get_user_workflow_or_404(db, workflow_id=workflow_id, user_id=user.id)
+    plan = _get_agent_plan_or_404(db, workflow_id=workflow.id, plan_id=plan_id)
+    if plan.status != "interrupted":
+        raise HTTPException(
+            status_code=400, detail="Only interrupted plans can be resumed"
+        )
+    plan.status = "approved" if plan.approval_status == "approved" else "draft"
+    append_workflow_event(
+        db,
+        workflow_id=workflow.id,
+        actor="user",
+        event_type="agent.plan_resumed",
+        stage=workflow.stage,
+        summary=f"Resumed bounded agent plan: {plan.title}",
+        payload={"plan_id": plan.id},
+        commit=False,
+    )
+    db.commit()
+    db.refresh(plan)
+    return _agent_plan_response(plan)
+
+
+@router.post(
+    "/{workflow_id}/agent-plans/{plan_id}/steps/{step_id}/approve",
+    response_model=WorkflowAgentStepResponse,
+)
+def approve_agent_plan_step(
+    workflow_id: int,
+    plan_id: int,
+    step_id: int,
+    user: auth_models.User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    workflow = get_user_workflow_or_404(db, workflow_id=workflow_id, user_id=user.id)
+    plan = _get_agent_plan_or_404(db, workflow_id=workflow.id, plan_id=plan_id)
+    step = _get_agent_step_or_404(db, plan_id=plan.id, step_id=step_id)
+    if not step.requires_approval:
+        raise HTTPException(
+            status_code=400, detail="This step does not require approval"
+        )
+    if step.status == "completed":
+        raise HTTPException(
+            status_code=400, detail="Completed steps cannot be approved"
+        )
+    step.status = "approved"
+    append_workflow_event(
+        db,
+        workflow_id=workflow.id,
+        actor="user",
+        event_type="agent.plan_step_approved",
+        stage=workflow.stage,
+        summary=f"Approved plan step: {step.action}",
+        payload={"plan_id": plan.id, "step_id": step.id, "action": step.action},
+        commit=False,
+    )
+    db.commit()
+    db.refresh(step)
+    return _agent_step_response(step)
+
+
+@router.post(
+    "/{workflow_id}/agent-plans/{plan_id}/steps/{step_id}/complete",
+    response_model=WorkflowAgentStepResponse,
+)
+def complete_agent_plan_step(
+    workflow_id: int,
+    plan_id: int,
+    step_id: int,
+    body: WorkflowAgentStepCompleteRequest,
+    user: auth_models.User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    workflow = get_user_workflow_or_404(db, workflow_id=workflow_id, user_id=user.id)
+    plan = _get_agent_plan_or_404(db, workflow_id=workflow.id, plan_id=plan_id)
+    step = _get_agent_step_or_404(db, plan_id=plan.id, step_id=step_id)
+    if body.status not in {"completed", "failed", "skipped"}:
+        raise HTTPException(
+            status_code=400,
+            detail="status must be one of: completed, failed, skipped",
+        )
+    step.status = body.status
+    step.result_json = encode_json(body.result)
+    append_workflow_event(
+        db,
+        workflow_id=workflow.id,
+        actor="system",
+        event_type=f"agent.plan_step_{body.status}",
+        stage=workflow.stage,
+        summary=f"Plan step {body.status}: {step.action}",
+        payload={
+            "plan_id": plan.id,
+            "step_id": step.id,
+            "action": step.action,
+            "result": body.result,
+        },
+        commit=False,
     )
+    db.commit()
+    db.refresh(step)
+    return _agent_step_response(step)
 
 
 @router.post(
@@ -612,12 +8801,117 @@ def get_workflow_metrics(
 )
 def export_workflow_bundle(
     workflow_id: int,
+    copy_max_bytes: int | None = None,
+    raw_copy_max_bytes: int | None = None,
+    copy_manifest_only: bool = False,
     user: auth_models.User = Depends(get_current_user),
     db: Session = Depends(get_db),
 ):
     workflow = get_user_workflow_or_404(db, workflow_id=workflow_id, user_id=user.id)
     events = _event_rows(db, workflow.id)
-    return WorkflowExportBundleResponse(**build_export_bundle(workflow, events))
+    bundle = build_export_bundle(workflow, events)
+    bundle["project_memory"] = json.loads(
+        json.dumps(
+            _build_workflow_project_memory(
+                db,
+                workflow,
+                user_id=user.id,
+                refresh=False,
+            ),
+            default=str,
+        )
+    )
+    agent_messages = (
+        db.query(auth_models.ChatMessage)
+        .filter(auth_models.ChatMessage.workflow_id == workflow.id)
+        .order_by(
+            auth_models.ChatMessage.created_at.asc(), auth_models.ChatMessage.id.asc()
+        )
+        .all()
+    )
+    bundle["agent_messages"] = [
+        {
+            "id": message.id,
+            "conversation_id": message.conversation_id,
+            "role": message.role,
+            "source": message.source,
+            "content": message.content,
+            "actions": message.actions,
+            "commands": message.commands,
+            "proposals": message.proposals,
+            "trace": message.trace,
+            "created_at": (
+                message.created_at.isoformat()
+                if hasattr(message.created_at, "isoformat")
+                else message.created_at
+            ),
+        }
+        for message in agent_messages
+    ]
+    bundle["action_card_index"] = [
+        {
+            "message_id": message.id,
+            "conversation_id": message.conversation_id,
+            "action_id": action.get("id"),
+            "action_type": action.get("action_type"),
+            "risk_tier": action.get("risk_tier"),
+            "requires_approval": action.get("requires_approval"),
+            "action_card": action.get("action_card") or {},
+        }
+        for message in agent_messages
+        for action in (message.actions or [])
+    ]
+    bundle["trace_index"] = [
+        {
+            "message_id": message.id,
+            "conversation_id": message.conversation_id,
+            "label": item.get("label"),
+            "category": item.get("category"),
+            "status": item.get("status"),
+            "data": item.get("data") or {},
+            "evidence_refs": item.get("evidence_refs") or [],
+        }
+        for message in agent_messages
+        for item in (message.trace or [])
+    ]
+    try:
+        bundle = write_export_bundle_directory(
+            bundle,
+            copy_max_bytes=copy_max_bytes,
+            raw_copy_max_bytes=raw_copy_max_bytes,
+            copy_manifest_only=copy_manifest_only,
+        )
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+    append_workflow_event(
+        db,
+        workflow_id=workflow.id,
+        actor="system",
+        event_type="workflow.bundle_exported",
+        stage=workflow.stage,
+        summary="Exported workflow evidence bundle.",
+        payload={
+            "artifact_count": len(bundle.get("artifacts") or []),
+            "model_run_count": len(bundle.get("model_runs") or []),
+            "model_version_count": len(bundle.get("model_versions") or []),
+            "correction_set_count": len(bundle.get("correction_sets") or []),
+            "evaluation_result_count": len(bundle.get("evaluation_results") or []),
+            "bundle_directory": bundle.get("bundle_directory"),
+            "bundle_manifest_path": bundle.get("bundle_manifest_path"),
+            "copied_artifact_count": len(bundle.get("copied_artifacts") or []),
+            "skipped_artifact_count": len(bundle.get("skipped_artifacts") or []),
+            "copy_settings": bundle.get("copy_settings") or {},
+            "missing_artifact_path_count": len(
+                [
+                    path_info
+                    for path_info in bundle.get("artifact_paths") or []
+                    if not path_info.get("exists")
+                ]
+            ),
+        },
+        commit=True,
+    )
+    return WorkflowExportBundleResponse(**bundle)
 
 
 @router.post("/{workflow_id}/events", response_model=WorkflowEventResponse)
@@ -637,6 +8931,8 @@ async def create_workflow_event(
         stage=stage,
         summary=body.summary,
         payload=body.payload,
+        schema_version=body.schema_version,
+        idempotency_key=body.idempotency_key,
         approval_status=body.approval_status,
         commit=True,
     )
@@ -666,26 +8962,167 @@ async def create_agent_action(
     return _event_response(event)
 
 
-@router.post(
-    "/{workflow_id}/agent-actions/{event_id}/approve",
-    response_model=AgentActionResult,
-)
-async def approve_agent_action(
-    workflow_id: int,
-    event_id: int,
-    user: auth_models.User = Depends(get_current_user),
-    db: Session = Depends(get_db),
-):
-    workflow = get_user_workflow_or_404(db, workflow_id=workflow_id, user_id=user.id)
-    proposal = _get_pending_proposal_or_404(
-        db, workflow_id=workflow.id, event_id=event_id
-    )
-    action_payload = _proposal_action_payload(proposal)
-    action = action_payload.get("action")
-    params = action_payload.get("params", {})
+@router.post(
+    "/{workflow_id}/agent-actions/{event_id}/approve",
+    response_model=AgentActionResult,
+)
+async def approve_agent_action(
+    workflow_id: int,
+    event_id: int,
+    body: Optional[AgentActionApprovalRequest] = None,
+    user: auth_models.User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    workflow = get_user_workflow_or_404(db, workflow_id=workflow_id, user_id=user.id)
+    proposal = _get_pending_proposal_or_404(
+        db, workflow_id=workflow.id, event_id=event_id
+    )
+    action_payload = _proposal_action_payload(proposal)
+    action = action_payload.get("action")
+    params = action_payload.get("params", {})
+    if not isinstance(params, dict):
+        params = {}
+    params, applied_overrides = _apply_agent_action_overrides(
+        str(action or ""),
+        params,
+        body.overrides if body else None,
+    )
+
+    if action not in {
+        "stage_retraining_from_corrections",
+        "start_training_run",
+        "run_client_effects",
+    }:
+        raise HTTPException(status_code=400, detail=f"Unsupported action: {action}")
+
+    if action == "start_training_run":
+        client_effects = _training_run_effects_from_proposal(workflow, params)
+        corrected_mask_path = (
+            client_effects.get("set_training_label_path")
+            or params.get("label_path")
+            or workflow.corrected_mask_path
+            or workflow.label_path
+            or workflow.mask_path
+            or _latest_exported_mask_path(db, workflow.id)
+        )
+        proposal.approval_status = "approved"
+        update_payload: Dict[str, Any] = {"stage": "retraining_staged"}
+        if corrected_mask_path:
+            update_payload["corrected_mask_path"] = corrected_mask_path
+        if client_effects.get("set_training_output_path"):
+            update_payload["training_output_path"] = client_effects[
+                "set_training_output_path"
+            ]
+        update_workflow_fields(db, workflow, update_payload, commit=False)
+        db.commit()
+        db.refresh(workflow)
+        db.refresh(proposal)
+
+        approved = append_workflow_event(
+            db,
+            workflow_id=workflow.id,
+            actor="user",
+            event_type="agent.proposal_approved",
+            stage=workflow.stage,
+            summary=f"Approved agent proposal: {proposal.summary}",
+            payload=_agent_action_approval_payload(
+                proposal.id,
+                action,
+                applied_overrides,
+            ),
+            commit=True,
+        )
+        staged = append_workflow_event(
+            db,
+            workflow_id=workflow.id,
+            actor="system",
+            event_type="training.run_approved",
+            stage=workflow.stage,
+            summary="Training run approved from chat.",
+            payload={
+                "proposal_event_id": proposal.id,
+                "config_preset": client_effects.get("set_training_config_preset"),
+                "image_path": client_effects.get("set_training_image_path"),
+                "label_path": client_effects.get("set_training_label_path"),
+                "output_path": client_effects.get("set_training_output_path"),
+                "runtime_action": client_effects.get("runtime_action"),
+                "user_edits": applied_overrides,
+            },
+            commit=True,
+        )
+        command = create_workflow_command(
+            db,
+            workflow_id=workflow.id,
+            command_type="start_training",
+            idempotency_key=f"agent-proposal:{proposal.id}:start_training",
+            actor="agent",
+            source_event_id=proposal.id,
+            approval_event_id=approved.id,
+            input_payload={
+                "client_effects": client_effects,
+                "workflow_stage": workflow.stage,
+                "proposal_event_id": proposal.id,
+            },
+            commit=True,
+        )
+        return AgentActionResult(
+            workflow=_workflow_response(workflow),
+            proposal=_event_response(proposal),
+            events=[_event_response(approved), _event_response(staged)],
+            client_effects={**client_effects, "workflow_stage": workflow.stage},
+            commands=[_command_response(command)],
+        )
+
+    if action == "run_client_effects":
+        client_effects = params.get("client_effects")
+        if not isinstance(client_effects, dict) or not client_effects:
+            raise HTTPException(
+                status_code=400,
+                detail="Approved client-effect action is missing client_effects.",
+            )
+        proposal.approval_status = "approved"
+        db.commit()
+        db.refresh(proposal)
 
-    if action != "stage_retraining_from_corrections":
-        raise HTTPException(status_code=400, detail=f"Unsupported action: {action}")
+        approved = append_workflow_event(
+            db,
+            workflow_id=workflow.id,
+            actor="user",
+            event_type="agent.proposal_approved",
+            stage=workflow.stage,
+            summary=f"Approved agent proposal: {proposal.summary}",
+            payload=_agent_action_approval_payload(
+                proposal.id,
+                action,
+                applied_overrides,
+            ),
+            commit=True,
+        )
+        staged = append_workflow_event(
+            db,
+            workflow_id=workflow.id,
+            actor="system",
+            event_type="agent.client_effects_approved",
+            stage=workflow.stage,
+            summary="Approved in-app assistant action for client execution.",
+            payload={
+                "proposal_event_id": proposal.id,
+                "item_id": params.get("item_id"),
+                "item_label": params.get("item_label"),
+                "risk_level": params.get("risk_level"),
+                "runtime_action": client_effects.get("runtime_action"),
+                "workflow_action": client_effects.get("workflow_action"),
+                "user_edits": applied_overrides,
+            },
+            commit=True,
+        )
+        return AgentActionResult(
+            workflow=_workflow_response(workflow),
+            proposal=_event_response(proposal),
+            events=[_event_response(approved), _event_response(staged)],
+            client_effects={**client_effects, "workflow_stage": workflow.stage},
+            commands=[],
+        )
 
     corrected_mask_path = (
         params.get("corrected_mask_path")
@@ -722,7 +9159,11 @@ async def approve_agent_action(
         event_type="agent.proposal_approved",
         stage=workflow.stage,
         summary=f"Approved agent proposal: {proposal.summary}",
-        payload={"proposal_event_id": proposal.id, "action": action},
+        payload=_agent_action_approval_payload(
+            proposal.id,
+            action,
+            applied_overrides,
+        ),
         commit=True,
     )
     staged = append_workflow_event(
@@ -736,6 +9177,7 @@ async def approve_agent_action(
             "corrected_mask_path": corrected_mask_path,
             "source": "agent_action",
             "proposal_event_id": proposal.id,
+            "user_edits": applied_overrides,
         },
         commit=True,
     )
@@ -781,6 +9223,155 @@ async def reject_agent_action(
     return _event_response(event)
 
 
+def _workflow_agent_conversation_for_query(
+    db: Session,
+    *,
+    user_id: int,
+    conversation_id: Optional[int],
+    query: str,
+) -> auth_models.Conversation:
+    if conversation_id:
+        conversation = (
+            db.query(auth_models.Conversation)
+            .filter(
+                auth_models.Conversation.id == conversation_id,
+                auth_models.Conversation.user_id == user_id,
+            )
+            .first()
+        )
+        if not conversation:
+            raise HTTPException(status_code=404, detail="Conversation not found")
+        if conversation.title == "New Chat":
+            conversation.title = query[:120].strip() or "Workflow assistant"
+        return conversation
+
+    conversation = auth_models.Conversation(
+        user_id=user_id,
+        title=query[:120].strip() or "Workflow assistant",
+    )
+    db.add(conversation)
+    db.flush()
+    return conversation
+
+
+def _jsonable_agent_items(items: List[Any]) -> str:
+    encoded_items = []
+    for item in items:
+        if hasattr(item, "model_dump"):
+            encoded_items.append(item.model_dump(mode="json"))
+        elif isinstance(item, dict):
+            encoded_items.append(item)
+    return json.dumps(encoded_items)
+
+
+def _persist_workflow_agent_chat_exchange(
+    db: Session,
+    *,
+    workflow_id: int,
+    conversation: auth_models.Conversation,
+    query: str,
+    response: str,
+    actions: List[AgentChatAction],
+    commands: List[AgentCommandBlock],
+    proposals: List[WorkflowEventResponse],
+    trace: List[AgentTraceItem],
+) -> None:
+    conversation.updated_at = datetime.now(timezone.utc)
+    db.add(
+        auth_models.ChatMessage(
+            conversation_id=conversation.id,
+            workflow_id=workflow_id,
+            role="user",
+            content=query,
+        )
+    )
+    db.add(
+        auth_models.ChatMessage(
+            conversation_id=conversation.id,
+            workflow_id=workflow_id,
+            role="assistant",
+            content=response,
+            source="workflow_orchestrator",
+            actions_json=_jsonable_agent_items(actions),
+            commands_json=_jsonable_agent_items(commands),
+            proposals_json=_jsonable_agent_items(proposals),
+            trace_json=_jsonable_agent_items(trace),
+        )
+    )
+
+
+def _agent_conversation_message_response(
+    message: auth_models.ChatMessage,
+) -> AgentConversationMessage:
+    return AgentConversationMessage(
+        id=message.id,
+        workflow_id=message.workflow_id,
+        role=message.role,
+        content=message.content,
+        source=message.source,
+        actions=message.actions,
+        commands=message.commands,
+        proposals=message.proposals,
+        trace=message.trace,
+        created_at=message.created_at,
+    )
+
+
+@router.get(
+    "/{workflow_id}/agent/conversation",
+    response_model=AgentConversationResponse,
+)
+def get_workflow_agent_conversation(
+    workflow_id: int,
+    user: auth_models.User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+):
+    workflow = get_user_workflow_or_404(db, workflow_id=workflow_id, user_id=user.id)
+    latest_message = (
+        db.query(auth_models.ChatMessage)
+        .join(auth_models.Conversation)
+        .filter(
+            auth_models.ChatMessage.workflow_id == workflow.id,
+            auth_models.Conversation.user_id == user.id,
+        )
+        .order_by(
+            auth_models.ChatMessage.created_at.desc(), auth_models.ChatMessage.id.desc()
+        )
+        .first()
+    )
+    if not latest_message:
+        return AgentConversationResponse()
+
+    conversation = (
+        db.query(auth_models.Conversation)
+        .filter(
+            auth_models.Conversation.id == latest_message.conversation_id,
+            auth_models.Conversation.user_id == user.id,
+        )
+        .first()
+    )
+    if not conversation:
+        return AgentConversationResponse()
+
+    messages = (
+        db.query(auth_models.ChatMessage)
+        .filter(
+            auth_models.ChatMessage.conversation_id == conversation.id,
+            auth_models.ChatMessage.workflow_id == workflow.id,
+        )
+        .order_by(auth_models.ChatMessage.created_at, auth_models.ChatMessage.id)
+        .all()
+    )
+    return AgentConversationResponse(
+        conversation_id=conversation.id,
+        conversationId=conversation.id,
+        title=conversation.title,
+        messages=[
+            _agent_conversation_message_response(message) for message in messages
+        ],
+    )
+
+
 @router.post("/{workflow_id}/agent/query", response_model=AgentQueryResponse)
 async def query_workflow_agent(
     workflow_id: int,
@@ -788,21 +9379,513 @@ async def query_workflow_agent(
     user: auth_models.User = Depends(get_current_user),
     db: Session = Depends(get_db),
 ):
-    if not body.query.strip():
+    raw_query = body.query.strip()
+    if not raw_query:
         raise HTTPException(status_code=400, detail="query must be non-empty")
+    query, command_alias = _normalize_workflow_agent_query(raw_query)
 
     workflow = get_user_workflow_or_404(db, workflow_id=workflow_id, user_id=user.id)
+    conversation = _workflow_agent_conversation_for_query(
+        db,
+        user_id=user.id,
+        conversation_id=body.conversation_id or body.conversationId,
+        query=raw_query,
+    )
     event_rows = _event_rows(db, workflow.id)
-    events = _event_list(db, workflow.id)
-    recommendation = _recommendation_for_workflow(workflow, events)
+    agent_recommendation = _build_workflow_agent_recommendation(db, workflow)
     proposals: List[WorkflowEventResponse] = []
-    lower_query = body.query.lower()
-    wants_retraining = any(
-        term in lower_query for term in ["retrain", "training", "stage", "corrected"]
+    actions: List[AgentChatAction] = []
+    commands: List[AgentCommandBlock] = []
+    tasks = _workflow_agent_tasks_from_readiness(agent_recommendation.readiness)
+    intent = "recommendation"
+    lower_query = query.lower()
+    project_observation = _observe_workflow_project(db, workflow, user.id)
+    semantic_intent = {} if command_alias else _semantic_intent_payload(query, workflow)
+    semantic_name = semantic_intent.get("intent")
+    semantic_tab = semantic_intent.get("tab")
+    wants_greeting = _is_greeting_query(lower_query) or semantic_name == "greeting"
+    wants_style_feedback = (
+        _query_has(
+            lower_query,
+            [
+                "robotic",
+                "less robot",
+                "less robotic",
+                "too formal",
+                "more human",
+                "normal chatbot",
+                "normal human",
+                "sound human",
+                "frontfacing language",
+                "front-facing language",
+                "stiff response",
+                "stiff",
+            ],
+        )
+        or semantic_name == "style_feedback"
+    )
+    wants_repair = _is_repair_query(lower_query) or semantic_name == "repair"
+    wants_informational_followup = _query_is_informational_followup(lower_query)
+    wants_incomplete_intent = (
+        _is_incomplete_work_intent(lower_query) or semantic_name == "clarify_next_job"
+    )
+    target_tab = _target_tab_from_query(lower_query) or _target_tab_from_semantic(
+        semantic_name,
+        semantic_tab,
+    )
+    wants_capabilities = (
+        any(
+            phrase in lower_query
+            for phrase in [
+                "what can you do",
+                "what can the agent do",
+                "what can the assistant do",
+                "what can it do",
+                "help me through",
+                "run things",
+                "guide me",
+            ]
+        )
+        or semantic_name == "capabilities"
+    )
+    wants_project_context = (
+        any(
+            phrase in lower_query
+            for phrase in [
+                "what project",
+                "which project",
+                "current project",
+                "project am i",
+                "project i am",
+                "what data",
+                "what dataset",
+                "what volume",
+            ]
+        )
+        or semantic_name == "project_context"
+    )
+    wants_project_files = (
+        _query_wants_project_file_overview(lower_query)
+        or semantic_name == "project_files"
+    )
+    wants_project_progress = (
+        _query_has(
+            lower_query,
+            [
+                "project progress",
+                "progress tracker",
+                "project tracker",
+                "project manager",
+                "volume tracker",
+                "open progress",
+                "show progress",
+                "how many volumes",
+                "ready for training",
+                "left out",
+                "leave out",
+                "excluded",
+                "exclude",
+                "human attention",
+                "need attention",
+                "needs attention",
+                "need human",
+                "needs human",
+                "what is left",
+                "what's left",
+                "what remains",
+                "remaining",
+                "volumes are done",
+                "volumes are fully good",
+                "fully proofread",
+                "ground truth",
+                "ground-truth",
+                "unproofread",
+                "without segmentation",
+                "no segmentation",
+                "missing segmentation",
+            ],
+        )
+        or semantic_name == "project_progress"
+    )
+    wants_user_need = (
+        any(
+            phrase in lower_query
+            for phrase in [
+                "what do you need",
+                "what you need",
+                "need from me",
+                "need me to",
+                "what should i provide",
+                "what should i do for you",
+            ]
+        )
+        or semantic_name == "needed_from_user"
+    )
+    wants_status = (
+        _query_has(
+            lower_query,
+            [
+                "status",
+                "where am i",
+                "what now",
+                "what's next",
+                "next step",
+                "what should i do",
+                "what is left",
+                "what remains",
+                "missing",
+                "blocker",
+                "ready",
+            ],
+        )
+        or semantic_name == "status"
+    )
+    wants_evaluation = (
+        _query_has(
+            lower_query,
+            [
+                "evaluate",
+                "evaluation",
+                "compare",
+                "comparison",
+                "metric",
+                "metrics",
+                "dice",
+                "iou",
+                "before after",
+                "before/after",
+            ],
+        )
+        or semantic_name == "compute_evaluation"
+    )
+    wants_export = (
+        _query_has(
+            lower_query,
+            [
+                "export bundle",
+                "export evidence",
+                "export report",
+                "evidence bundle",
+                "research bundle",
+                "download bundle",
+            ],
+        )
+        or semantic_name == "export_evidence"
+    )
+    wants_visualization_launch = (
+        _query_wants_visualization_launch(lower_query) or semantic_name == "view_data"
+    )
+    wants_alternate_volume_set = _query_wants_alternate_volume_set(lower_query)
+    if wants_alternate_volume_set:
+        wants_visualization_launch = True
+    wants_visualization_scales = (
+        _query_wants_visualization_scales(lower_query)
+        or semantic_name == "set_visualization_scales"
+    )
+    wants_retraining = (
+        any(
+            term in lower_query
+            for term in ["retrain", "training", "stage", "corrected"]
+        )
+        or semantic_name == "stage_retraining"
+    )
+    wants_training_launch = (
+        _query_has(
+            lower_query,
+            [
+                "train",
+                "start training",
+                "run training",
+                "launch training",
+                "retrain now",
+                "train model",
+                "train a model",
+                "train the model",
+                "train for me",
+                "train on saved edits",
+                "run a training job",
+                "run training job",
+            ],
+        )
+        or semantic_name == "start_training"
+    )
+    wants_inference_launch = (
+        _query_wants_inference_launch(lower_query) or semantic_name == "start_inference"
+    )
+    wants_segmentation_launch = (
+        _query_wants_segmentation_launch(lower_query)
+        or semantic_name == "start_segmentation"
+    )
+    if wants_visualization_launch and semantic_name != "start_segmentation":
+        wants_segmentation_launch = False
+        wants_inference_launch = False
+    if wants_alternate_volume_set:
+        wants_segmentation_launch = False
+        wants_inference_launch = False
+        wants_training_launch = False
+    if wants_segmentation_launch and semantic_name != "start_inference":
+        wants_inference_launch = False
+    wants_progress_based_training = wants_training_launch and (
+        _query_wants_progress_based_training(lower_query)
+        or _query_wants_segment_remaining_after_training(lower_query)
+    )
+    if wants_training_launch:
+        wants_project_progress = False
+    wants_proofreading_launch = (
+        _query_has(
+            lower_query,
+            [
+                "proofread",
+                "proofreading",
+                "review mask",
+                "review masks",
+                "review segmentation",
+                "review segmentations",
+                "fix mask",
+                "fix masks",
+                "fix segmentation",
+                "inspect segmentation",
+                "check segmentation",
+                "check segmentations",
+                "curate segmentation",
+                "curate segmentations",
+                "human review",
+            ],
+        )
+        or semantic_name == "start_proofreading"
+    )
+    wants_failure_analysis = (
+        any(
+            term in lower_query
+            for term in ["fail", "failure", "error", "hotspot", "where"]
+        )
+        or semantic_name == "inspect_failure"
+    )
+    wants_mount_project = (
+        _query_has(
+            lower_query,
+            [
+                "mount project",
+                "remount",
+                "remount project",
+                "open project",
+                "use suggested project",
+                "mount lucchi",
+                "open lucchi",
+                "prepilot lucchi",
+                "lucchi directory",
+                "project directory",
+            ],
+        )
+        or semantic_name == "mount_project"
+    )
+    wants_reset_workspace = (
+        _query_has(
+            lower_query,
+            [
+                "reset workspace",
+                "clear workspace",
+                "clear cache",
+                "reset cache",
+                "clear cached",
+                "reset cached",
+                "clean state",
+                "fresh state",
+                "start over",
+                "new workflow",
+            ],
+        )
+        or semantic_name == "reset_workspace"
+    )
+    if wants_reset_workspace:
+        wants_mount_project = False
+    wants_validate_project = (
+        _query_has(
+            lower_query,
+            [
+                "validate project",
+                "check project",
+                "inspect project",
+                "project structure",
+                "detect roles",
+                "role mapping",
+                "what files",
+                "what volumes",
+            ],
+        )
+        or semantic_name == "validate_project"
+    )
+    if wants_project_files and semantic_name != "validate_project":
+        wants_validate_project = False
+    wants_prepare_data = (
+        _query_has(
+            lower_query,
+            [
+                "prepare data",
+                "convert data",
+                "normalize",
+                "normalise",
+                "crop",
+                "downsample",
+                "split train",
+                "train val split",
+                "preprocess",
+                "pre-process",
+            ],
+        )
+        or semantic_name == "prepare_data"
+    )
+    wants_configure_training = (
+        _query_has(
+            lower_query,
+            [
+                "configure training",
+                "training settings",
+                "training config",
+                "batch size",
+                "augmentation",
+                "epochs",
+                "learning rate",
+                "pick architecture",
+            ],
+        )
+        or semantic_name == "configure_training"
+    )
+    wants_configure_inference = (
+        _query_has(
+            lower_query,
+            [
+                "configure inference",
+                "inference settings",
+                "inference config",
+                "tiling",
+                "threshold",
+                "checkpoint",
+                "set checkpoint",
+            ],
+        )
+        or semantic_name == "configure_inference"
+    )
+    wants_monitor_jobs = (
+        _query_has(
+            lower_query,
+            [
+                "monitor",
+                "logs",
+                "tensorboard",
+                "job status",
+                "runtime status",
+                "gpu",
+                "memory",
+                "training log",
+            ],
+        )
+        or semantic_name == "monitor_jobs"
+    )
+    wants_stop_runtime = (
+        _query_has(
+            lower_query,
+            [
+                "stop",
+                "cancel",
+                "kill",
+                "stop run",
+                "stop job",
+                "cancel run",
+                "cancel job",
+                "kill run",
+                "kill job",
+                "stop training",
+                "stop inference",
+                "cancel training",
+                "cancel inference",
+            ],
+        )
+        or semantic_name == "stop_runtime"
+    )
+    wants_use_defaults = any(
+        phrase in lower_query
+        for phrase in [
+            "use defaults",
+            "use safe defaults",
+            "default settings",
+            "safe defaults",
+        ]
     )
-    wants_failure_analysis = any(
-        term in lower_query for term in ["fail", "failure", "error", "hotspot", "where"]
+    action_needs_context = (
+        wants_training_launch or wants_inference_launch or wants_segmentation_launch
     )
+    workflow_action_requested = any(
+        [
+            action_needs_context,
+            wants_visualization_launch,
+            wants_visualization_scales,
+            wants_proofreading_launch,
+            wants_evaluation,
+            wants_export,
+            wants_status,
+            wants_capabilities,
+            wants_project_context,
+            wants_project_files,
+            wants_project_progress,
+            wants_user_need,
+            wants_incomplete_intent,
+            wants_failure_analysis,
+            wants_mount_project,
+            wants_reset_workspace,
+            wants_validate_project,
+            wants_prepare_data,
+            wants_configure_training,
+            wants_configure_inference,
+            wants_monitor_jobs,
+            wants_stop_runtime,
+            bool(target_tab),
+        ]
+    )
+    context_update = {
+        **_extract_project_context_from_query(query),
+        **(semantic_intent.get("context") or {}),
+    }
+    if wants_use_defaults:
+        context_update = {
+            **context_update,
+            "use_defaults": True,
+            "freeform_note": query[:500],
+        }
+    explicit_context_mutation = _query_explicitly_mutates_project_context(lower_query)
+    protected_volume_question = _query_mentions_volume_id(lower_query) and any(
+        marker in lower_query
+        for marker in [
+            "why",
+            "which",
+            "what",
+            "how",
+            "leave out",
+            "left out",
+            "exclude",
+            "excluded",
+            "training",
+            "train",
+        ]
+    )
+    context_should_update = bool(context_update) and (
+        not command_alias
+        and not protected_volume_question
+        and (
+            explicit_context_mutation
+            or semantic_name == "project_context_update"
+            or wants_use_defaults
+            or action_needs_context
+        )
+    )
+    if context_should_update:
+        _merge_project_context(db, workflow, context_update)
+    if wants_training_launch:
+        context_action_label = "choose a training preset"
+    elif wants_inference_launch or wants_segmentation_launch:
+        context_action_label = "choose and run a segmentation model"
+    else:
+        context_action_label = "prioritize proofreading work"
     corrected_mask_path = workflow.corrected_mask_path or _latest_exported_mask_path(
         db, workflow.id
     )
@@ -813,8 +9896,1485 @@ async def query_workflow_agent(
         hotspots,
         corrected_mask_path,
     )
+    proofreading_blockers = _proofreading_input_blockers(workflow)
+    query_policy_decision: Optional[Dict[str, Any]] = None
+    query_blocking_reasons: List[Dict[str, Any]] = []
+    query_freshness: Optional[Dict[str, Any]] = None
 
-    if wants_retraining and corrected_mask_path:
+    if wants_visualization_scales:
+        intent = "set_visualization_scales"
+        parsed_scales = _parse_visualization_scales_from_query(query)
+        if not parsed_scales:
+            response = (
+                "I can reload with new voxel scales, but I need three values in z,y,x.\n"
+                "Example: reload with 1,1,1 nm."
+            )
+            actions = [
+                _build_agent_chat_action(
+                    "open-visualization",
+                    "Open viewer",
+                    "Open the visualization screen so you can set the voxel scales.",
+                    variant="primary",
+                    client_effects={"navigate_to": "visualization"},
+                )
+            ]
+            commands = []
+        else:
+            _store_visualization_scales(
+                db,
+                workflow,
+                parsed_scales,
+                source_query=query,
+            )
+            scale_text = _format_scales(parsed_scales)
+            view_effects = _build_view_data_effects(workflow)
+            view_effects["set_visualization_scales"] = parsed_scales
+            view_effects["runtime_action"] = {"kind": "load_visualization"}
+            response = (
+                f"Do this: reload the viewer with {scale_text} nm voxel scales.\n"
+                "Why: I saved that z,y,x scale in project context for this workflow."
+            )
+            actions = [
+                _build_agent_chat_action(
+                    "reload-visualization-scales",
+                    "Reload viewer",
+                    f"Reload the current volume view with {scale_text} nm scales.",
+                    variant="primary",
+                    client_effects=view_effects,
+                )
+            ]
+            if not workflow.image_path and not workflow.dataset_path:
+                actions.append(
+                    _build_agent_chat_action(
+                        "choose-data",
+                        "Choose data",
+                        "Pick an image and mask before loading the viewer.",
+                        client_effects=_build_choose_data_effects(),
+                    )
+                )
+            commands = []
+    elif (
+        wants_informational_followup
+        and not command_alias
+        and not action_needs_context
+        and not any(
+            [
+                wants_status,
+                wants_style_feedback,
+                wants_capabilities,
+                wants_project_context,
+                wants_project_files,
+                wants_project_progress,
+                wants_user_need,
+                wants_visualization_launch,
+                wants_visualization_scales,
+                wants_evaluation,
+                wants_export,
+                wants_mount_project,
+                wants_reset_workspace,
+                wants_validate_project,
+                wants_prepare_data,
+                wants_configure_training,
+                wants_configure_inference,
+                wants_monitor_jobs,
+                wants_stop_runtime,
+            ]
+        )
+    ):
+        intent = "project_context_updated" if context_should_update else "followup"
+        response = (
+            _format_project_context_saved_response(workflow, agent_recommendation)
+            if context_should_update
+            else _format_informational_followup_response(workflow, agent_recommendation)
+        )
+        actions = []
+        commands = []
+    elif action_needs_context and _project_context_missing_fields(workflow):
+        intent = "collect_project_context"
+        missing_context_fields = _project_context_missing_fields(workflow)
+        query_blocking_reasons = [
+            _policy_blocking_reason(
+                f"project_context.missing_{_reason_code_from_label(field)}",
+                f"Project context is missing: {field}.",
+                scope="project_context",
+                field=field,
+            )
+            for field in missing_context_fields
+        ]
+        query_policy_decision = _policy_decision_payload(
+            "blocked",
+            requires_approval=False,
+            reason_code="project_context_missing",
+            reason="Project context fields are required before this action.",
+            blocking_reasons=query_blocking_reasons,
+        )
+        query_freshness = _project_context_freshness(workflow)
+        response = _format_project_context_prompt(workflow, context_action_label)
+        actions = []
+        commands = []
+    elif (
+        context_should_update
+        and not action_needs_context
+        and not workflow_action_requested
+    ):
+        intent = "project_context_updated"
+        response = _format_project_context_saved_response(
+            workflow,
+            agent_recommendation,
+        )
+        actions = []
+        commands = []
+    elif wants_style_feedback:
+        intent = "style_feedback"
+        response = _format_style_feedback_response(workflow, agent_recommendation)
+        actions = []
+        commands = []
+    elif wants_greeting:
+        intent = "greeting"
+        response = _format_greeting_response(agent_recommendation)
+        actions = []
+        commands = []
+    elif wants_repair:
+        intent = "repair"
+        response = _format_repair_response(agent_recommendation)
+        actions = []
+        commands = []
+    elif wants_mount_project:
+        intent = "mount_project"
+        effects = _build_mount_project_effects(
+            directory_path=_derive_mount_project_path(workflow)
+            or _default_mount_project_path(),
+            mount_name=workflow.title,
+        )
+        response = (
+            "Do this: mount the project directory.\n"
+            "Why: remote browser access needs the server to mount the project path, then the app can inspect files and roles."
+        )
+        actions = [
+            _build_agent_chat_action(
+                "mount-project",
+                "Mount project",
+                "Mount the current or suggested server-side project directory.",
+                variant="primary",
+                client_effects=effects,
+            ),
+            _build_agent_chat_action(
+                "open-files",
+                "Open Files",
+                "Inspect mounted project files.",
+                client_effects={"navigate_to": "files"},
+            ),
+        ]
+        commands = [
+            _build_agent_command_block(
+                "mount-project-command",
+                "Mount project in app",
+                "Mount the project directory from chat.",
+                effects,
+            )
+        ]
+    elif wants_reset_workspace:
+        intent = "reset_workspace"
+        effects = _build_mount_project_effects(
+            directory_path=_derive_mount_project_path(workflow)
+            or _default_mount_project_path(),
+            mount_name=workflow.title,
+        )
+        effects["reset_workspace"] = True
+        response = (
+            "Do this: clear cached workspace file state, then remount the current project.\n"
+            "Why: this resets stale client/file indexes while preserving the project directory on disk."
+        )
+        actions = [
+            _build_agent_chat_action(
+                "reset-workspace-remount-project",
+                "Reset and remount",
+                "Clear indexed workspace state and remount the current project directory.",
+                variant="primary",
+                client_effects=effects,
+            ),
+            _build_agent_chat_action(
+                "show-status",
+                "Show status",
+                "Inspect workflow state after the reset.",
+                client_effects={"show_workflow_context": True},
+            ),
+        ]
+        commands = [
+            _build_agent_command_block(
+                "reset-workspace-remount-command",
+                "Reset workspace in app",
+                "Clear cached file state and remount the current project.",
+                effects,
+            )
+        ]
+    elif wants_validate_project:
+        intent = "validate_project"
+        response = (
+            "Do this: inspect the mounted project and detected file roles.\n"
+            "Why: project validation checks whether image, label/mask, config, checkpoint, and output paths are ready."
+        )
+        actions = [
+            _build_agent_chat_action(
+                "open-files",
+                "Inspect files",
+                "Open Files to review detected project structure and role mapping.",
+                variant="primary",
+                client_effects={"navigate_to": "files"},
+            ),
+            _build_agent_chat_action(
+                "show-workflow-status",
+                "Show status",
+                "Open the workflow readiness panel.",
+                client_effects={
+                    "show_workflow_context": True,
+                    "refresh_insights": True,
+                },
+            ),
+        ]
+        if workflow.image_path or workflow.dataset_path:
+            actions.append(
+                _build_agent_chat_action(
+                    "open-visualization",
+                    "View data",
+                    "Open the detected image and mask pair.",
+                    client_effects=_build_view_data_effects(workflow),
+                )
+            )
+        commands = []
+    elif wants_prepare_data:
+        intent = "prepare_data"
+        response = (
+            "Do this: open Files and verify the data mapping before preprocessing.\n"
+            "Why: conversion, cropping, normalization, and train/val splits need explicit source and output choices."
+        )
+        actions = [
+            _build_agent_chat_action(
+                "open-files",
+                "Prepare data",
+                "Open Files to choose sources and inspect project structure.",
+                variant="primary",
+                client_effects={"navigate_to": "files"},
+            ),
+            _build_agent_chat_action(
+                "show-workflow-status",
+                "Show status",
+                "Show the current data readiness and blockers.",
+                client_effects={
+                    "show_workflow_context": True,
+                    "refresh_insights": True,
+                },
+            ),
+        ]
+        commands = []
+    elif wants_configure_training:
+        intent = "configure_training"
+        training_requires_trusted_masks = _workflow_requires_trusted_masks(workflow)
+        training_label_path = _preferred_training_mask_path(
+            workflow,
+            require_trusted=training_requires_trusted_masks,
+        )
+        effects = _build_start_training_effects(workflow, training_label_path)
+        if (
+            training_requires_trusted_masks
+            and not training_label_path
+            and not corrected_mask_path
+        ):
+            effects = {
+                "navigate_to": "training",
+                "set_training_config_preset": _choose_training_config_preset(workflow),
+            }
+            if workflow.image_path or workflow.dataset_path:
+                effects["set_training_image_path"] = (
+                    workflow.image_path or workflow.dataset_path
+                )
+        effects.pop("runtime_action", None)
+        response = (
+            "Do this: open training with inferred defaults filled in.\n"
+            "Why: you can review config, image, labels, output, batch settings, and augmentation before launching."
+        )
+        actions = [
+            _build_agent_chat_action(
+                "configure-training",
+                "Configure training",
+                "Prefill training inputs and open the training screen without starting a job.",
+                variant="primary",
+                client_effects=effects,
+            )
+        ]
+        commands = [
+            _build_agent_command_block(
+                "configure-training-command",
+                "Configure training in app",
+                "Open training with agent-inferred paths and preset.",
+                effects,
+            )
+        ]
+    elif wants_configure_inference:
+        intent = "configure_inference"
+        effects = _build_start_inference_effects(workflow)
+        effects.pop("runtime_action", None)
+        response = (
+            "Do this: open Run Model with inferred inputs filled in.\n"
+            "Why: you can review checkpoint, config, image, and output settings before launching inference."
+        )
+        actions = [
+            _build_agent_chat_action(
+                "configure-inference",
+                "Configure inference",
+                "Prefill inference settings and open Run Model without starting a job.",
+                variant="primary",
+                client_effects=effects,
+            )
+        ]
+        commands = [
+            _build_agent_command_block(
+                "configure-inference-command",
+                "Configure inference in app",
+                "Open Run Model with agent-inferred paths and preset.",
+                effects,
+            )
+        ]
+    elif wants_monitor_jobs:
+        intent = "monitor_jobs"
+        response = (
+            "Do this: open Train Model.\n"
+            "Why: training logs, TensorBoard links, runtime status, and job health live with the training run now."
+        )
+        actions = [
+            _build_agent_chat_action(
+                "open-training-runtime",
+                "Open Train Model",
+                "Open training runtime details and logs.",
+                variant="primary",
+                client_effects={"navigate_to": "training"},
+            ),
+            _build_agent_chat_action(
+                "show-status",
+                "Show status",
+                "Show workflow readiness and recent events.",
+                client_effects={"show_workflow_context": True},
+            ),
+        ]
+        commands = []
+    elif wants_stop_runtime:
+        intent = "stop_runtime"
+        response = (
+            "Do this: stop the active runtime.\n"
+            "Why: stopping a run is explicit because it interrupts compute work."
+        )
+        actions = [
+            _build_agent_chat_action(
+                "stop-inference",
+                "Stop inference",
+                "Request cancellation of the current inference process.",
+                variant="primary",
+                client_effects={"runtime_action": {"kind": "stop_inference"}},
+            ),
+            _build_agent_chat_action(
+                "stop-training",
+                "Stop training",
+                "Request cancellation of the current training process.",
+                client_effects={"runtime_action": {"kind": "stop_training"}},
+            ),
+            _build_agent_chat_action(
+                "open-training-runtime",
+                "Open Train Model",
+                "Check runtime state after stopping.",
+                client_effects={"navigate_to": "training"},
+            ),
+        ]
+        commands = []
+    elif wants_project_progress:
+        intent = "project_progress"
+        progress = _build_workflow_project_progress(
+            db,
+            workflow,
+            user_id=user.id,
+            project_observation=project_observation,
+        )
+        response = _format_project_progress_response(progress)
+        actions = [
+            _build_agent_chat_action(
+                "open-project-progress",
+                "Open progress",
+                "Open the project progress tracker for volume-level ground-truth status.",
+                variant="primary",
+                client_effects={
+                    "navigate_to": "project-progress",
+                    "refresh_project_progress": True,
+                },
+            )
+        ]
+        commands = []
+    elif wants_project_files:
+        intent = "project_files"
+        response = _format_project_files_response(project_observation)
+        actions = []
+        commands = []
+    elif wants_project_context:
+        intent = "project_context"
+        response = _format_project_context_response(workflow, agent_recommendation)
+        actions = [
+            _build_agent_chat_action(
+                "show-workflow-status",
+                "Show status",
+                "Open the workflow evidence and readiness panel.",
+                client_effects={
+                    "show_workflow_context": True,
+                    "refresh_insights": True,
+                },
+            )
+        ]
+        commands = []
+    elif wants_user_need:
+        intent = "needed_from_user"
+        response = _format_needed_from_user_response(agent_recommendation)
+        actions = agent_recommendation.actions[:2]
+        commands = agent_recommendation.commands[:1]
+    elif wants_incomplete_intent:
+        intent = "clarify_next_job"
+        response = (
+            "Tell me what you want to do next.\n"
+            "Options: run model, proofread, use edits for training, or compare results.\n"
+            f"Current suggestion: {agent_recommendation.decision}"
+        )
+        actions = agent_recommendation.actions
+        commands = []
+    elif target_tab:
+        intent = "navigate"
+        navigation_action = _build_navigation_action(
+            target_tab["tab"],
+            target_tab["label"],
+            target_tab["description"],
+        )
+        response = (
+            f"Do this: {target_tab['label']}.\n" f"Why: {target_tab['description']}"
+        )
+        actions = [navigation_action]
+        commands = [
+            _build_agent_command_block(
+                f"{navigation_action.id}-command",
+                target_tab["label"],
+                target_tab["description"],
+                navigation_action.client_effects,
+            )
+        ]
+    elif wants_export:
+        intent = "export_evidence"
+        export_effects = _build_export_bundle_effects()
+        query_policy_decision = _policy_decision_payload(
+            "allowed",
+            requires_approval=True,
+            reason_code="export_ready",
+            reason="An evidence export action is ready.",
+            blocking_reasons=[],
+        )
+        query_freshness = {"scope": "export", "state": "ready"}
+        response = (
+            "Do this: export the workflow evidence bundle.\n"
+            "Why: it captures the current artifacts, runs, corrections, metrics, and audit trail."
+        )
+        actions = [
+            _build_agent_chat_action(
+                "export-workflow-bundle",
+                "Export evidence",
+                "Export the workflow evidence bundle.",
+                variant="primary",
+                policy_decision=query_policy_decision,
+                freshness={"scope": "export", "state": "ready"},
+                client_effects=export_effects,
+            ),
+            _build_agent_chat_action(
+                "show-status",
+                "Show status",
+                "Open the workflow evidence panel first.",
+                client_effects={"show_workflow_context": True},
+            ),
+        ]
+        commands = [
+            _build_agent_command_block(
+                "export-workflow-bundle-command",
+                "Export evidence in app",
+                "Run this in-app command block to export the workflow evidence bundle.",
+                export_effects,
+            )
+        ]
+    elif wants_evaluation:
+        intent = "compute_evaluation"
+        evaluation_effects, missing_eval_inputs = _build_compute_evaluation_effects(
+            db, workflow
+        )
+        eval_blocking_reasons = [
+            _policy_blocking_reason(
+                f"evaluation.missing_{_reason_code_from_label(field)}",
+                f"Evaluation is blocked because {field} is missing.",
+                scope="evaluation_inputs",
+                field=field,
+            )
+            for field in missing_eval_inputs
+        ]
+        if missing_eval_inputs:
+            query_blocking_reasons = eval_blocking_reasons
+            query_policy_decision = _policy_decision_payload(
+                "blocked",
+                requires_approval=False,
+                reason_code="evaluation_missing_inputs",
+                reason="Evaluation input artifacts are incomplete.",
+                blocking_reasons=query_blocking_reasons,
+            )
+            query_freshness = _resource_freshness_payload(
+                scope="evaluation",
+                required_fields=[
+                    "previous result",
+                    "new result",
+                    "reference mask",
+                ],
+                missing_fields=missing_eval_inputs,
+            )
+            response = (
+                f"Do this: collect {missing_eval_inputs[0]} first.\n"
+                "Why: before/after metrics need a previous result, a new result, and a reference mask."
+            )
+            actions = [
+                _build_agent_chat_action(
+                    "show-evaluation-status",
+                    "Show status",
+                    "Open the evidence panel and inspect missing comparison inputs.",
+                    variant="primary",
+                    client_effects={"show_workflow_context": True},
+                    policy_decision=_policy_decision_payload(
+                        "blocked",
+                        requires_approval=False,
+                        reason_code="evaluation_missing_inputs",
+                        reason="Evaluation inputs are incomplete.",
+                        blocking_reasons=eval_blocking_reasons,
+                    ),
+                    freshness=_resource_freshness_payload(
+                        scope="evaluation",
+                        required_fields=[
+                            "previous result",
+                            "new result",
+                            "reference mask",
+                        ],
+                        missing_fields=missing_eval_inputs,
+                    ),
+                ),
+                _build_agent_chat_action(
+                    "open-inference",
+                    "Open Run Model",
+                    "Run or register model outputs for comparison.",
+                    client_effects={"navigate_to": "inference"},
+                    policy_decision=_policy_decision_payload(
+                        "blocked",
+                        requires_approval=False,
+                        reason_code="evaluation_missing_inputs",
+                        reason="Evaluation inputs are incomplete.",
+                        blocking_reasons=eval_blocking_reasons,
+                    ),
+                    freshness=_resource_freshness_payload(
+                        scope="evaluation",
+                        required_fields=[
+                            "previous result",
+                            "new result",
+                            "reference mask",
+                        ],
+                        missing_fields=missing_eval_inputs,
+                    ),
+                ),
+            ]
+            commands = []
+        else:
+            eval_freshness = _resource_freshness_payload(
+                scope="evaluation",
+                required_fields=[
+                    "previous result",
+                    "new result",
+                    "reference mask",
+                ],
+                missing_fields=[],
+            )
+            response = (
+                "Do this: compute before/after metrics.\n"
+                "Why: this checks whether the new result improved against the reference mask."
+            )
+            query_policy_decision = _policy_decision_payload(
+                "allowed",
+                requires_approval=True,
+                reason_code="evaluation_ready",
+                reason="Evaluation inputs are complete.",
+                blocking_reasons=[],
+            )
+            query_freshness = _resource_freshness_payload(
+                scope="evaluation",
+                required_fields=[
+                    "previous result",
+                    "new result",
+                    "reference mask",
+                ],
+                missing_fields=[],
+            )
+            actions = [
+                _build_agent_chat_action(
+                    "compute-evaluation",
+                    "Compute metrics",
+                    "Compare the previous and new segmentation results.",
+                    variant="primary",
+                    client_effects=evaluation_effects,
+                    policy_decision=_policy_decision_payload(
+                        "allowed",
+                        requires_approval=True,
+                        reason_code="evaluation_ready",
+                        reason="All comparison inputs are available.",
+                        blocking_reasons=[],
+                    ),
+                    freshness=eval_freshness,
+                ),
+                _build_agent_chat_action(
+                    "export-workflow-bundle",
+                    "Export evidence",
+                    "Export the workflow evidence bundle after metrics are recorded.",
+                    client_effects=_build_export_bundle_effects(),
+                    policy_decision=_policy_decision_payload(
+                        "allowed",
+                        requires_approval=True,
+                        reason_code="export_ready",
+                        reason="Evidence export requires approval before creating the bundle.",
+                        blocking_reasons=[],
+                    ),
+                    freshness={"scope": "export", "state": "ready"},
+                ),
+            ]
+            commands = [
+                _build_agent_command_block(
+                    "compute-evaluation-command",
+                    "Compute metrics in app",
+                    "Run this in-app command block to compute before/after metrics.",
+                    evaluation_effects,
+                )
+            ]
+    elif wants_visualization_launch:
+        intent = "view_data"
+        observed_volume_set = _select_observed_volume_set(
+            project_observation,
+            prefer_alternate=wants_alternate_volume_set,
+        )
+        image_path = workflow.image_path or workflow.dataset_path or ""
+        label_path = (
+            workflow.label_path
+            or workflow.mask_path
+            or workflow.inference_output_path
+            or workflow.corrected_mask_path
+            or ""
+        )
+        if observed_volume_set and (wants_alternate_volume_set or not image_path):
+            image_path = observed_volume_set.get("image_path") or image_path
+            label_path = observed_volume_set.get("label_path") or label_path
+        if not image_path:
+            response = (
+                "I can visualize this, but I need the image volume first.\n"
+                "Do this: confirm the image and mask/label paths in Files."
+            )
+            actions = [
+                _build_agent_chat_action(
+                    "open-files",
+                    "Choose data",
+                    "Confirm the image and mask/label paths before viewing.",
+                    variant="primary",
+                    client_effects=_build_choose_data_effects(),
+                )
+            ]
+            commands = []
+        else:
+            pair_discovery = _workflow_volume_pair_discovery(workflow)
+            detected_pairs = pair_discovery.get("pairs") or []
+            selected_pair = _select_visualization_pair(workflow, pair_discovery)
+            selected_image_path = image_path
+            selected_label_path = label_path
+            if observed_volume_set and (
+                wants_alternate_volume_set or not selected_pair
+            ):
+                selected_image_path = (
+                    observed_volume_set.get("image_path") or selected_image_path
+                )
+                selected_label_path = (
+                    observed_volume_set.get("label_path") or selected_label_path
+                )
+            elif selected_pair:
+                selected_image_path = selected_pair.get("image_path") or image_path
+                selected_label_path = selected_pair.get("label_path") or label_path
+            view_effects = _build_view_data_effects(
+                workflow,
+                image_path=selected_image_path,
+                label_path=selected_label_path,
+            )
+            observed_set_count = len(project_observation.get("volume_sets") or [])
+            pair_count = int(pair_discovery.get("pair_count") or 0)
+            if observed_volume_set:
+                pair_count = max(
+                    pair_count, int(observed_volume_set.get("pair_count") or 0)
+                )
+            pair_line = ""
+            if wants_alternate_volume_set and observed_volume_set:
+                pair_line = (
+                    f"\nI inspected the project tree and found another image/seg set: "
+                    f"{observed_volume_set.get('name') or 'volume set'} "
+                    f"({observed_volume_set.get('image_count') or 0} images, "
+                    f"{observed_volume_set.get('label_count') or 0} labels"
+                    f"{'; ' + str(observed_volume_set.get('pair_count')) + ' matched pairs' if observed_volume_set.get('pair_count') else ''})."
+                )
+            elif observed_set_count > 1:
+                pair_line = (
+                    f"\nI inspected the project tree and found {observed_set_count} image/seg sets. "
+                    f"I will open {observed_volume_set.get('name') if observed_volume_set else 'the current set'} first."
+                )
+            elif pair_count > 1:
+                pair_line = (
+                    f"\nI found {pair_count} clear image/seg pairs and will open "
+                    f"{_short_path_label(selected_image_path)} first. "
+                    "Tell me if there are more folders or pairs I should include."
+                )
+            elif pair_count == 1:
+                pair_line = (
+                    f"\nI found one clear image/seg pair: "
+                    f"{_short_path_label(selected_image_path)}"
+                    f"{' with ' + _short_path_label(selected_label_path) if selected_label_path else ''}."
+                )
+            response = (
+                f"Do this: view {_short_path_label(selected_image_path)}"
+                f"{' with ' + _short_path_label(selected_label_path) if selected_label_path else ''}.\n"
+                "Why: the workflow has a source volume"
+                f"{' and a mask/label' if selected_label_path else ''} ready for inspection."
+                f"{pair_line}"
+            )
+            actions = [
+                _build_agent_chat_action(
+                    "open-visualization",
+                    "View data",
+                    "Open the selected image and mask in the viewer.",
+                    variant="primary",
+                    client_effects=view_effects,
+                )
+            ]
+            if not proofreading_blockers:
+                actions.append(_build_proofreading_action(workflow, variant="default"))
+            commands = []
+    elif wants_status and not (
+        wants_training_launch
+        or wants_inference_launch
+        or wants_segmentation_launch
+        or wants_proofreading_launch
+        or wants_visualization_launch
+    ):
+        intent = "status"
+        response = _format_workflow_agent_response(agent_recommendation)
+        actions = [
+            _build_agent_chat_action(
+                "show-workflow-status",
+                "Show status",
+                "Open the workflow evidence and readiness panel.",
+                variant="primary",
+                client_effects={
+                    "show_workflow_context": True,
+                    "refresh_insights": True,
+                },
+            ),
+            *agent_recommendation.actions[:2],
+        ]
+        commands = []
+    elif wants_capabilities:
+        intent = "capabilities"
+        response = _format_capabilities_response()
+        actions = []
+        commands = []
+    elif wants_training_launch and workflow.stage == "retraining_staged":
+        intent = "start_training"
+        training_requires_trusted_masks = _workflow_requires_trusted_masks(workflow)
+        training_label_path = _preferred_training_mask_path(
+            workflow,
+            require_trusted=training_requires_trusted_masks,
+        )
+        training_missing = []
+        if not (workflow.image_path or workflow.dataset_path):
+            training_missing.append("image volume")
+        if not training_label_path:
+            training_missing.append("labels")
+        training_blocking_reasons = [
+            _policy_blocking_reason(
+                f"training.missing_{_reason_code_from_label(field)}",
+                f"Training is blocked because {field} is missing.",
+                scope="training_inputs",
+                field=field,
+            )
+            for field in training_missing
+        ]
+        if training_missing:
+            query_blocking_reasons = training_blocking_reasons
+            query_policy_decision = _policy_decision_payload(
+                "blocked",
+                requires_approval=False,
+                reason_code="training_missing_inputs",
+                reason="Training inputs are incomplete.",
+                blocking_reasons=query_blocking_reasons,
+            )
+            query_freshness = _resource_freshness_payload(
+                scope="training",
+                required_fields=["image volume", "label path"],
+                missing_fields=training_missing,
+            )
+            response = (
+                "I can train from the saved edits, but I need image and labels first.\n"
+                "Do this: choose the image and label folders in Files."
+            )
+            actions = [
+                _build_agent_chat_action(
+                    "open-files",
+                    "Choose data",
+                    "Select image and label data needed for retraining.",
+                    variant="primary",
+                    client_effects=_build_choose_data_effects(),
+                    policy_decision=query_policy_decision,
+                    freshness=query_freshness,
+                )
+            ]
+            commands = []
+        else:
+            subset_plan = None
+            if wants_progress_based_training:
+                progress = _build_workflow_project_progress(
+                    db,
+                    workflow,
+                    user_id=user.id,
+                    project_observation=project_observation,
+                )
+                subset_plan = _build_progress_training_subset_plan(
+                    workflow,
+                    progress,
+                    lower_query=lower_query,
+                )
+            training_effects = _build_start_training_effects(
+                workflow,
+                training_label_path,
+                volume_subset_plan=subset_plan,
+            )
+            response = (
+                _format_progress_training_response(
+                    subset_plan,
+                    include_segment_rest=_query_wants_segment_remaining_after_training(
+                        lower_query
+                    ),
+                )
+                if subset_plan
+                else (
+                    "Yes. I can train from the saved edits with the current image and mask paths. "
+                    "I’ll use the project config and safe defaults, then you can review the run before it launches."
+                )
+            )
+            query_policy_decision = _policy_decision_payload(
+                "allowed",
+                requires_approval=True,
+                reason_code="training_ready",
+                reason="Training inputs are available.",
+                blocking_reasons=[],
+            )
+            query_freshness = _resource_freshness_payload(
+                scope="training",
+                required_fields=["image volume", "label path"],
+                missing_fields=[],
+            )
+            actions = [
+                _build_agent_chat_action(
+                    "start-training",
+                    "Train on edits",
+                    "Start training with the selected labels and safe defaults.",
+                    variant="primary",
+                    client_effects=training_effects,
+                    policy_decision=query_policy_decision,
+                    freshness=query_freshness,
+                ),
+                _build_agent_chat_action(
+                    "refresh-insights",
+                    "Refresh",
+                    "Update the recommendation before training.",
+                    client_effects={"refresh_insights": True},
+                ),
+            ]
+            commands = [
+                _build_agent_command_block(
+                    "start-training-command",
+                    "Start training in app",
+                    "Review the proposed preset, inputs, and safe defaults before launching retraining from chat.",
+                    training_effects,
+                    run_label="Review run",
+                )
+            ]
+    elif wants_training_launch:
+        intent = "start_training"
+        training_requires_trusted_masks = _workflow_requires_trusted_masks(workflow)
+        training_label_path = _preferred_training_mask_path(
+            workflow,
+            require_trusted=training_requires_trusted_masks,
+        )
+        image_path = workflow.image_path or workflow.dataset_path or ""
+        if not image_path:
+            query_blocking_reasons = [
+                _policy_blocking_reason(
+                    "training.missing_image_volume",
+                    "Training is blocked because image data is missing.",
+                    scope="training_inputs",
+                    field="image volume",
+                )
+            ]
+            query_policy_decision = _policy_decision_payload(
+                "blocked",
+                requires_approval=False,
+                reason_code="training_missing_inputs",
+                reason="Training inputs are incomplete.",
+                blocking_reasons=query_blocking_reasons,
+            )
+            query_freshness = _resource_freshness_payload(
+                scope="training",
+                required_fields=["image volume", "label path"],
+                missing_fields=["image volume"],
+            )
+            response = (
+                "I can train a model, but I need image data first.\n"
+                "Do this: choose the project image and label folders in Files."
+            )
+            actions = [
+                _build_agent_chat_action(
+                    "open-files",
+                    "Choose data",
+                    "Select the image and label data needed for training.",
+                    variant="primary",
+                    client_effects=_build_choose_data_effects(),
+                    policy_decision=query_policy_decision,
+                    freshness=query_freshness,
+                    blocking_reasons=query_blocking_reasons,
+                )
+            ]
+            commands = []
+        elif not training_label_path:
+            if training_requires_trusted_masks:
+                response = (
+                    "I can train a model, but this project needs confirmed labels or saved proofreading edits first.\n"
+                    "Do this: choose corrected labels, run proofreading, or restore a ground-truth mask."
+                )
+            else:
+                response = (
+                    "I can train a model, but I need labels or saved proofreading edits first.\n"
+                    "Do this: choose label data, proofread a mask, or run the model to create a prediction."
+                )
+            training_blocking_reasons = [
+                _policy_blocking_reason(
+                    "training.missing_labels",
+                    "Training is blocked because labels are missing.",
+                    scope="training_inputs",
+                    field="labels",
+                )
+            ]
+            query_blocking_reasons = training_blocking_reasons
+            query_policy_decision = _policy_decision_payload(
+                "blocked",
+                requires_approval=False,
+                reason_code="training_missing_inputs",
+                reason="Training inputs are incomplete.",
+                blocking_reasons=query_blocking_reasons,
+            )
+            query_freshness = _resource_freshness_payload(
+                scope="training",
+                required_fields=["image volume", "label path"],
+                missing_fields=["labels"],
+            )
+            actions = [
+                _build_agent_chat_action(
+                    "open-files",
+                    "Choose labels",
+                    "Select label data or saved edits for training.",
+                    variant="primary",
+                    client_effects=_build_choose_data_effects(),
+                    policy_decision=query_policy_decision,
+                    freshness=query_freshness,
+                    blocking_reasons=training_blocking_reasons,
+                ),
+                _build_agent_chat_action(
+                    "open-proofreading",
+                    "Proofread",
+                    "Create saved edits before training.",
+                    client_effects={"navigate_to": "mask-proofreading"},
+                    policy_decision=_policy_decision_payload(
+                        "allowed",
+                        requires_approval=True,
+                        reason_code="training_can_start_after_proofreading",
+                        reason="Proofreading is available to produce trusted masks.",
+                        blocking_reasons=[],
+                    ),
+                    freshness=_resource_freshness_payload(
+                        scope="proofreading",
+                        required_fields=["image volume", "mask, label, or prediction"],
+                        missing_fields=[],
+                    ),
+                ),
+            ]
+            commands = []
+        else:
+            query_policy_decision = _policy_decision_payload(
+                "allowed",
+                requires_approval=True,
+                reason_code="training_ready",
+                reason="Training inputs are available.",
+                blocking_reasons=[],
+            )
+            query_freshness = _resource_freshness_payload(
+                scope="training",
+                required_fields=["image volume", "label path"],
+                missing_fields=[],
+            )
+            subset_plan = None
+            if wants_progress_based_training or project_observation.get("volume_sets"):
+                progress = _build_workflow_project_progress(
+                    db,
+                    workflow,
+                    user_id=user.id,
+                    project_observation=project_observation,
+                )
+                subset_plan = _build_progress_training_subset_plan(
+                    workflow,
+                    progress,
+                    lower_query=lower_query,
+                )
+            training_effects = _build_start_training_effects(
+                workflow,
+                training_label_path,
+                volume_subset_plan=subset_plan,
+            )
+            response = (
+                _format_progress_training_response(
+                    subset_plan,
+                    include_segment_rest=_query_wants_segment_remaining_after_training(
+                        lower_query
+                    ),
+                )
+                if subset_plan
+                else (
+                    "Yes. I found image and label data, so I can train a model "
+                    "with the project config and safe defaults. Review the inputs before it launches."
+                )
+            )
+            actions = [
+                _build_agent_chat_action(
+                    "start-training",
+                    "Train model",
+                    "Start training with the current image and label data.",
+                    variant="primary",
+                    run_label="Review run",
+                    client_effects=training_effects,
+                    policy_decision=query_policy_decision,
+                    freshness=query_freshness,
+                )
+            ]
+            commands = [
+                _build_agent_command_block(
+                    "start-training-command",
+                    "Start training in app",
+                    "Review the proposed preset, inputs, and safe defaults before launching training from chat.",
+                    training_effects,
+                    run_label="Review run",
+                )
+            ]
+    elif wants_inference_launch:
+        intent = "start_inference"
+        inference_blockers = _inference_input_blockers(workflow)
+        if inference_blockers:
+            missing = ", ".join(inference_blockers)
+            inference_blocking_reasons = [
+                _policy_blocking_reason(
+                    f"inference.missing_{_reason_code_from_label(field)}",
+                    f"Inference is blocked because {field} is missing.",
+                    scope="inference_inputs",
+                    field=field,
+                )
+                for field in inference_blockers
+            ]
+            query_blocking_reasons = inference_blocking_reasons
+            query_policy_decision = _policy_decision_payload(
+                "blocked",
+                requires_approval=False,
+                reason_code="inference_missing_inputs",
+                reason="Inference inputs are incomplete.",
+                blocking_reasons=query_blocking_reasons,
+            )
+            query_freshness = _resource_freshness_payload(
+                scope="inference",
+                required_fields=["image volume", "model checkpoint"],
+                missing_fields=inference_blockers,
+            )
+            response = (
+                f"I can run a model, but I need {missing} first.\n"
+                "Do this: confirm the input image and checkpoint, or use the existing labels for proofreading/training."
+            )
+            actions = [
+                _build_agent_chat_action(
+                    "open-inference",
+                    "Check Run Model",
+                    f"Inference needs {missing}.",
+                    variant="primary",
+                    client_effects={"navigate_to": "inference"},
+                    policy_decision=_policy_decision_payload(
+                        "blocked",
+                        requires_approval=False,
+                        reason_code="inference_missing_inputs",
+                        reason="Inference inputs are incomplete.",
+                        blocking_reasons=inference_blocking_reasons,
+                    ),
+                    freshness=_resource_freshness_payload(
+                        scope="inference",
+                        required_fields=["image volume", "model checkpoint"],
+                        missing_fields=inference_blockers,
+                    ),
+                )
+            ]
+            if not (workflow.image_path or workflow.dataset_path):
+                actions.append(
+                    _build_agent_chat_action(
+                        "open-files",
+                        "Choose data",
+                        "Pick an image volume before running a model.",
+                        client_effects=_build_choose_data_effects(),
+                        policy_decision=_policy_decision_payload(
+                            "blocked",
+                            requires_approval=False,
+                            reason_code="inference_missing_inputs",
+                            reason="Inference inputs are incomplete.",
+                            blocking_reasons=inference_blocking_reasons,
+                        ),
+                        freshness=_resource_freshness_payload(
+                            scope="inference",
+                            required_fields=["image volume", "model checkpoint"],
+                            missing_fields=inference_blockers,
+                        ),
+                    )
+                )
+            if not proofreading_blockers:
+                actions.append(
+                    _build_proofreading_action(
+                        workflow,
+                        variant="default",
+                        policy_decision=_policy_decision_payload(
+                            "allowed",
+                            requires_approval=True,
+                            reason_code="proofreading_ready",
+                            reason="Proofreading is available with existing inputs.",
+                            blocking_reasons=[],
+                        ),
+                        freshness=_resource_freshness_payload(
+                            scope="proofreading",
+                            required_fields=[
+                                "image volume",
+                                "mask, label, or prediction",
+                            ],
+                            missing_fields=[],
+                        ),
+                    )
+                )
+            commands = []
+        else:
+            inference_effects = _build_start_inference_effects(workflow)
+            response = (
+                "Do this: run the model.\n"
+                "Why: this creates the mask result you can inspect and fix."
+            )
+            query_policy_decision = _policy_decision_payload(
+                "allowed",
+                requires_approval=True,
+                reason_code="inference_ready",
+                reason="Inference inputs are complete.",
+                blocking_reasons=[],
+            )
+            query_freshness = _resource_freshness_payload(
+                scope="inference",
+                required_fields=["image volume", "model checkpoint"],
+                missing_fields=[],
+            )
+            actions = [
+                _build_agent_chat_action(
+                    "start-inference",
+                    "Run model",
+                    "Start the model run with the current settings.",
+                    variant="primary",
+                    policy_decision=_policy_decision_payload(
+                        "allowed",
+                        requires_approval=True,
+                        reason_code="inference_ready",
+                        reason="Inference inputs are available.",
+                        blocking_reasons=[],
+                    ),
+                    freshness=_resource_freshness_payload(
+                        scope="inference",
+                        required_fields=["image volume", "model checkpoint"],
+                        missing_fields=[],
+                    ),
+                    client_effects=inference_effects,
+                ),
+                _build_agent_chat_action(
+                    "start-proofreading",
+                    "Proofread this data",
+                    "Open the image and mask in the proofreading workbench.",
+                    client_effects=_build_start_proofreading_effects(workflow),
+                    policy_decision=_policy_decision_payload(
+                        "allowed",
+                        requires_approval=True,
+                        reason_code="proofreading_ready",
+                        reason="Proofreading is available with existing inputs.",
+                        blocking_reasons=[],
+                    ),
+                    freshness=_resource_freshness_payload(
+                        scope="proofreading",
+                        required_fields=["image volume", "mask, label, or prediction"],
+                        missing_fields=[],
+                    ),
+                ),
+            ]
+            commands = [
+                _build_agent_command_block(
+                    "start-inference-command",
+                    "Start inference in app",
+                    "Run this in-app command block to launch inference from chat.",
+                    inference_effects,
+                )
+            ]
+    elif wants_proofreading_launch:
+        intent = "start_proofreading"
+        if proofreading_blockers:
+            missing = ", ".join(proofreading_blockers)
+            response = (
+                f"I can proofread this, but I need {missing} first.\n"
+                "Do this: confirm the image and mask/label paths in Files."
+            )
+            actions = [
+                _build_agent_chat_action(
+                    "open-files",
+                    "Choose data",
+                    f"Proofreading needs {missing}.",
+                    variant="primary",
+                    client_effects=_build_choose_data_effects(),
+                )
+            ]
+            if "mask, label, or prediction" in proofreading_blockers:
+                actions.append(
+                    _build_agent_chat_action(
+                        "open-inference",
+                        "Run model",
+                        "Create a prediction if no editable mask/label exists.",
+                        client_effects={"navigate_to": "inference"},
+                    )
+                )
+            commands = []
+        else:
+            proofreading_effects = _build_start_proofreading_effects(workflow)
+            response = (
+                "Do this: proofread this data.\n"
+                "Why: I found the current image/mask paths in the workflow."
+            )
+            actions = [
+                _build_proofreading_action(workflow, variant="primary"),
+                _build_agent_chat_action(
+                    "refresh-insights",
+                    "Refresh",
+                    "Update the recommendation using the latest edits.",
+                    client_effects={"refresh_insights": True},
+                ),
+            ]
+            commands = [
+                _build_agent_command_block(
+                    "start-proofreading-command",
+                    "Start proofreading in app",
+                    "Open the current image/mask pair in proofreading.",
+                    proofreading_effects,
+                )
+            ]
+    elif wants_segmentation_launch:
+        intent = "start_segmentation"
+        inference_blockers = _inference_input_blockers(workflow)
+        if inference_blockers:
+            missing = ", ".join(inference_blockers)
+            segmentation_blocking_reasons = [
+                _policy_blocking_reason(
+                    f"inference.missing_{_reason_code_from_label(field)}",
+                    f"Segmentation is blocked because {field} is required for inference.",
+                    scope="inference_inputs",
+                    field=field,
+                )
+                for field in inference_blockers
+            ]
+            query_blocking_reasons = segmentation_blocking_reasons
+            query_policy_decision = _policy_decision_payload(
+                "blocked",
+                requires_approval=False,
+                reason_code="segmentation_blocked",
+                reason="Segmentation requires a complete inference setup.",
+                blocking_reasons=query_blocking_reasons,
+            )
+            query_freshness = _resource_freshness_payload(
+                scope="inference",
+                required_fields=["image volume", "model checkpoint"],
+                missing_fields=inference_blockers,
+            )
+            response = (
+                f"I can help segment this data, but running inference needs {missing}.\n"
+                "Why: a checkpoint is required to produce a new model prediction. Useful next step: use the existing labels for proofreading or training, or add a checkpoint before running inference."
+            )
+            actions = []
+            if not proofreading_blockers:
+                actions.append(
+                    _build_proofreading_action(
+                        workflow,
+                        variant="primary",
+                        policy_decision=_policy_decision_payload(
+                            "allowed",
+                            requires_approval=True,
+                            reason_code="proofreading_ready",
+                            reason="Proofreading is available with existing inputs.",
+                            blocking_reasons=[],
+                        ),
+                        freshness=_resource_freshness_payload(
+                            scope="proofreading",
+                            required_fields=[
+                                "image volume",
+                                "mask, label, or prediction",
+                            ],
+                            missing_fields=[],
+                        ),
+                    )
+                )
+            training_requires_trusted_masks = _workflow_requires_trusted_masks(workflow)
+            training_label_path = _preferred_training_mask_path(
+                workflow,
+                require_trusted=training_requires_trusted_masks,
+            )
+            if (workflow.image_path or workflow.dataset_path) and training_label_path:
+                training_effects = _build_start_training_effects(
+                    workflow,
+                    training_label_path,
+                )
+                actions.append(
+                    _build_agent_chat_action(
+                        "start-training",
+                        "Train model",
+                        "Train from the current image and label data.",
+                        client_effects=training_effects,
+                        policy_decision=_policy_decision_payload(
+                            "allowed",
+                            requires_approval=True,
+                            reason_code="training_ready",
+                            reason="Training inputs are available.",
+                            blocking_reasons=[],
+                        ),
+                        freshness=_resource_freshness_payload(
+                            scope="training",
+                            required_fields=["image volume", "label path"],
+                            missing_fields=[],
+                        ),
+                    )
+                )
+            actions.append(
+                _build_agent_chat_action(
+                    "open-inference",
+                    "Check Run Model",
+                    f"Running segmentation needs {missing}.",
+                    variant="primary" if not actions else "default",
+                    client_effects={"navigate_to": "inference"},
+                    policy_decision=query_policy_decision,
+                    freshness=query_freshness,
+                    blocking_reasons=segmentation_blocking_reasons,
+                )
+            )
+            if not (workflow.image_path or workflow.dataset_path):
+                actions.append(
+                    _build_agent_chat_action(
+                        "open-files",
+                        "Choose data",
+                        "Pick an image volume before segmenting.",
+                        client_effects=_build_choose_data_effects(),
+                        policy_decision=_policy_decision_payload(
+                            "blocked",
+                            requires_approval=False,
+                            reason_code="inference_missing_inputs",
+                            reason="Inference inputs are incomplete.",
+                            blocking_reasons=segmentation_blocking_reasons,
+                        ),
+                        freshness=query_freshness,
+                    )
+                )
+            commands = []
+        else:
+            inference_effects = _build_start_inference_effects(workflow)
+            proofreading_effects = _build_start_proofreading_effects(workflow)
+            response = (
+                "Do this: run the model to segment the volume.\n"
+                "Why: inference creates the mask result; proofreading is for fixing it afterward."
+            )
+            query_policy_decision = _policy_decision_payload(
+                "allowed",
+                requires_approval=True,
+                reason_code="segmentation_ready",
+                reason="Segmentation is ready to run with inference inputs.",
+                blocking_reasons=[],
+            )
+            query_freshness = _resource_freshness_payload(
+                scope="inference",
+                required_fields=["image volume", "model checkpoint"],
+                missing_fields=[],
+            )
+            actions = [
+                _build_agent_chat_action(
+                    "start-inference",
+                    "Run model",
+                    "Start segmentation from the current inference settings.",
+                    variant="primary",
+                    client_effects=inference_effects,
+                    policy_decision=_policy_decision_payload(
+                        "allowed",
+                        requires_approval=True,
+                        reason_code="inference_ready",
+                        reason="Inference inputs are available.",
+                        blocking_reasons=[],
+                    ),
+                    freshness=_resource_freshness_payload(
+                        scope="inference",
+                        required_fields=["image volume", "model checkpoint"],
+                        missing_fields=[],
+                    ),
+                ),
+                _build_agent_chat_action(
+                    "start-proofreading",
+                    "Proofread this data",
+                    "Open the current image/mask pair in proofreading.",
+                    client_effects=proofreading_effects,
+                    policy_decision=_policy_decision_payload(
+                        "allowed",
+                        requires_approval=True,
+                        reason_code="proofreading_ready",
+                        reason="Proofreading is available with existing inputs.",
+                        blocking_reasons=[],
+                    ),
+                    freshness=_resource_freshness_payload(
+                        scope="proofreading",
+                        required_fields=["image volume", "mask, label, or prediction"],
+                        missing_fields=[],
+                    ),
+                ),
+            ]
+            commands = [
+                _build_agent_command_block(
+                    "start-segmentation-command",
+                    "Run model in app",
+                    "Run segmentation from chat using the current app settings.",
+                    inference_effects,
+                )
+            ]
+    elif wants_retraining and corrected_mask_path:
+        intent = "stage_retraining"
         proposal = append_workflow_event(
             db,
             workflow_id=workflow.id,
@@ -831,18 +11391,143 @@ async def query_workflow_agent(
         )
         proposals.append(_event_response(proposal))
         response = (
-            "I found a corrected mask artifact and prepared a retraining-stage "
-            "proposal. Approve it when you want the app to link those corrections "
-            "to the next training configuration."
+            "Do this: approve using these edits for training.\n"
+            "Why: I created a reviewable proposal instead of changing state silently."
         )
+        training_effects = {
+            "navigate_to": "training",
+            "set_training_label_path": corrected_mask_path,
+        }
+        actions = [
+            _build_agent_chat_action(
+                "open-training",
+                "Set up training",
+                "Open training with the saved edits selected.",
+                variant="primary",
+                client_effects=training_effects,
+            ),
+            _build_agent_chat_action(
+                "refresh-insights",
+                "Refresh",
+                "Update the recommendation before approving training.",
+                client_effects={"refresh_insights": True},
+            ),
+        ]
+        commands = [
+            _build_agent_command_block(
+                "prime-training",
+                "Prime the training screen",
+                "Run this in-app command block to move directly into the next training setup.",
+                training_effects,
+            )
+        ]
     elif wants_failure_analysis and hotspots:
+        intent = "inspect_failure"
         top_hotspot = hotspots[0]
         response = (
-            f"Top hotspot: {top_hotspot.summary} "
-            f"Recommended action: {top_hotspot.recommended_action} "
-            f"Impact preview: {impact.summary}"
+            f"Do this: {top_hotspot.recommended_action}\n"
+            f"Why: {top_hotspot.summary}\n"
+            f"Confidence: {impact.confidence}."
         )
+        proofreading_effects = _build_start_proofreading_effects(workflow)
+        visualization_effects = {"navigate_to": "visualization"}
+        actions = [
+            _build_agent_chat_action(
+                "start-proofreading",
+                "Proofread this data",
+                "Open the image and mask in the proofreading workbench.",
+                variant="primary",
+                client_effects=proofreading_effects,
+            ),
+            _build_agent_chat_action(
+                "open-visualization",
+                "View data",
+                "Inspect the region before editing.",
+                client_effects=visualization_effects,
+            ),
+        ]
+        commands = [
+            _build_agent_command_block(
+                "inspect-hotspot",
+                "Inspect hotspot in app",
+                "Run this in-app command block to pivot the UI into hotspot review mode.",
+                proofreading_effects,
+            )
+        ]
     else:
-        response = recommendation
+        intent = "clarify_next_job"
+        response = _format_unknown_workflow_query_response(agent_recommendation)
+        actions = []
+        commands = []
+
+    actions, commands = _one_app_suggestion(actions, commands)
+    response = _humanize_agent_response(response)
+    trace = _build_agent_trace(
+        workflow=workflow,
+        project_observation=project_observation,
+        intent=intent,
+        actions=actions,
+    )
 
-    return AgentQueryResponse(response=response, proposals=proposals)
+    _persist_workflow_agent_chat_exchange(
+        db,
+        workflow_id=workflow.id,
+        conversation=conversation,
+        query=raw_query,
+        response=response,
+        actions=actions,
+        commands=commands,
+        proposals=proposals,
+        trace=trace,
+    )
+    db.commit()
+    append_app_event(
+        component="workflow_agent",
+        event="query_completed",
+        level="INFO",
+        message="Workflow agent query persisted",
+        workflow_id=workflow.id,
+        conversation_id=conversation.id,
+        user_id=user.id,
+        query_preview=raw_query[:160],
+        normalized_query_preview=query[:160],
+        command_alias=command_alias,
+        query_len=len(query),
+        response_len=len(response),
+        response_source="workflow_orchestrator",
+        intent=intent,
+        semantic_intent=semantic_name,
+        semantic_confidence=semantic_intent.get("confidence"),
+        semantic_reason=semantic_intent.get("reason"),
+        recommendation_decision=agent_recommendation.decision,
+        recommendation_stage=agent_recommendation.next_stage,
+        action_ids=[action.id for action in actions],
+        action_labels=[action.label for action in actions],
+        command_ids=[command.id for command in commands],
+        command_titles=[command.title for command in commands],
+        proofreading_blockers=proofreading_blockers,
+        action_count=len(actions),
+        command_count=len(commands),
+        proposal_count=len(proposals),
+        task_count=len(tasks),
+        trace_count=len(trace),
+    )
+
+    return AgentQueryResponse(
+        response=response,
+        source="workflow_orchestrator",
+        intent=intent,
+        permission_mode="approval_required_for_runtime",
+        orchestrator_agent=ORCHESTRATOR_AGENT,
+        subagents=list(WORKFLOW_SUBAGENTS.values()),
+        policy_decision=query_policy_decision,
+        blocking_reasons=query_blocking_reasons,
+        freshness=query_freshness,
+        conversation_id=conversation.id,
+        conversationId=conversation.id,
+        proposals=proposals,
+        actions=actions,
+        commands=commands,
+        tasks=tasks,
+        trace=trace,
+    )
diff --git a/server_api/workflows/service.py b/server_api/workflows/service.py
index 850a5852..6745f0c2 100644
--- a/server_api/workflows/service.py
+++ b/server_api/workflows/service.py
@@ -1,10 +1,25 @@
 import json
-from typing import Any, Dict, Optional
+import os
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
 
 from fastapi import HTTPException
 from sqlalchemy.orm import Session
 
-from .db_models import WorkflowEvent, WorkflowSession
+from .db_models import (
+    WorkflowAgentPlan,
+    WorkflowAgentStep,
+    WorkflowArtifact,
+    WorkflowCommand,
+    WorkflowCorrectionSet,
+    WorkflowEvaluationResult,
+    WorkflowEvent,
+    WorkflowModelRun,
+    WorkflowModelVersion,
+    WorkflowRegionHotspot,
+    WorkflowSession,
+    WorkflowVolumeState,
+)
 
 ALLOWED_STAGES = {
     "setup",
@@ -17,6 +32,109 @@
 
 ALLOWED_ACTORS = {"user", "agent", "system"}
 ALLOWED_APPROVAL_STATUSES = {"not_required", "pending", "approved", "rejected"}
+ALLOWED_COMMAND_STATUSES = {
+    "queued",
+    "claimed",
+    "running",
+    "submitted",
+    "completed",
+    "failed",
+    "canceled",
+    "retry_pending",
+}
+DEFAULT_EVENT_SCHEMA_VERSION = 1
+
+INITIAL_PROJECT_ROOT = os.getenv("PYTC_INITIAL_PROJECT_ROOT", "").rstrip("/")
+
+
+def _initial_project_defaults() -> Dict[str, Any]:
+    if not INITIAL_PROJECT_ROOT:
+        return {}
+    normalized_root = INITIAL_PROJECT_ROOT.lower()
+    if (
+        "yixiao" in normalized_root
+        or "tapereader" in normalized_root
+        or "xri" in normalized_root
+    ):
+        image_path = os.getenv(
+            "PYTC_INITIAL_IMAGE_PATH",
+            os.path.join(INITIAL_PROJECT_ROOT, "data/raw/1/1-xri_raw.tif"),
+        )
+        label_path = os.getenv(
+            "PYTC_INITIAL_LABEL_PATH",
+            os.path.join(INITIAL_PROJECT_ROOT, "data/seg/1/1-mask.tif"),
+        )
+        config_path = os.getenv(
+            "PYTC_INITIAL_CONFIG_PATH",
+            os.path.join(
+                INITIAL_PROJECT_ROOT,
+                "configs/TapeReader-Fiber-BCS-AppCompat-Sanity.yaml",
+            ),
+        )
+        return {
+            "title": os.getenv(
+                "PYTC_INITIAL_PROJECT_TITLE",
+                "Yixiao TapeReader XRI Case Study",
+            ),
+            "dataset_path": INITIAL_PROJECT_ROOT,
+            "image_path": image_path,
+            "label_path": label_path,
+            "mask_path": os.getenv("PYTC_INITIAL_MASK_PATH", label_path),
+            "config_path": config_path,
+            "metadata": {
+                "created_from": "initial_project_default",
+                "project_context": {
+                    "imaging_modality": "X-ray / XRI volumetric microscopy",
+                    "target_structure": "CytoTape fibres",
+                    "task_family": "XRI fibre instance segmentation",
+                    "task_goal": "instance segmentation, proofreading, and model retraining",
+                    "optimization_priority": "paper-faithful workflow coordination",
+                    "mask_status": "6 confirmed ground-truth volumes, 2 draft masks for proofreading, 2 image-only inference targets",
+                    "training_policy": "train only on confirmed ground-truth masks",
+                    "image_only_strategy": "run inference on image-only volumes later",
+                    "voxel_size_nm": [40, 16.3, 16.3],
+                    "voxel_size_source": "project_manifest.json",
+                },
+                "visualization_scales": [40, 16.3, 16.3],
+                "visualization_scales_source": "project_manifest.json",
+            },
+        }
+    return {
+        "title": os.getenv("PYTC_INITIAL_PROJECT_TITLE", "MitoEM2.0 Progress Demo"),
+        "dataset_path": INITIAL_PROJECT_ROOT,
+        "image_path": os.getenv(
+            "PYTC_INITIAL_IMAGE_PATH",
+            os.path.join(INITIAL_PROJECT_ROOT, "data/image"),
+        ),
+        "label_path": os.getenv(
+            "PYTC_INITIAL_LABEL_PATH",
+            os.path.join(INITIAL_PROJECT_ROOT, "data/seg"),
+        ),
+        "mask_path": os.getenv(
+            "PYTC_INITIAL_MASK_PATH",
+            os.path.join(INITIAL_PROJECT_ROOT, "data/seg"),
+        ),
+        "config_path": os.getenv(
+            "PYTC_INITIAL_CONFIG_PATH",
+            os.path.join(
+                INITIAL_PROJECT_ROOT,
+                "configs/MitoEM2-Pyra-Demo-BC.yaml",
+            ),
+        ),
+        "metadata": {
+            "created_from": "initial_project_default",
+            "project_context": {
+                "imaging_modality": "EM / ssSEM",
+                "target_structure": "mitochondria",
+                "task_goal": "segmentation",
+                "optimization_priority": "accuracy",
+                "voxel_size_nm": [30, 8, 8],
+                "voxel_size_source": "MitoEM2.0 Dataset006_ME2-Pyra metadata",
+            },
+            "visualization_scales": [30, 8, 8],
+            "visualization_scales_source": "initial_project_default",
+        },
+    }
 
 
 def encode_json(value: Optional[Dict[str, Any]]) -> Optional[str]:
@@ -35,6 +153,37 @@ def decode_json(value: Optional[str]) -> Dict[str, Any]:
     return parsed if isinstance(parsed, dict) else {}
 
 
+def _now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def _merge_dicts(
+    base: Optional[Dict[str, Any]], patch: Optional[Dict[str, Any]]
+) -> Dict[str, Any]:
+    merged: Dict[str, Any] = dict(base or {})
+    for key, value in (patch or {}).items():
+        if isinstance(value, dict) and isinstance(merged.get(key), dict):
+            merged[key] = _merge_dicts(merged[key], value)
+        else:
+            merged[key] = value
+    return merged
+
+
+def _basename(value: Optional[str]) -> Optional[str]:
+    if not value:
+        return None
+    return os.path.basename(str(value).rstrip("/")) or str(value)
+
+
+def _path_size(value: Optional[str]) -> Optional[int]:
+    if not value:
+        return None
+    try:
+        return os.path.getsize(value)
+    except OSError:
+        return None
+
+
 def validate_stage(stage: Optional[str]) -> Optional[str]:
     if stage is None:
         return None
@@ -67,6 +216,18 @@ def validate_approval_status(status: str) -> str:
     return status
 
 
+def validate_command_status(status: str) -> str:
+    if status not in ALLOWED_COMMAND_STATUSES:
+        raise HTTPException(
+            status_code=400,
+            detail=(
+                "command status must be one of: "
+                f"{', '.join(sorted(ALLOWED_COMMAND_STATUSES))}"
+            ),
+        )
+    return status
+
+
 def event_to_dict(event: WorkflowEvent) -> Dict[str, Any]:
     return {
         "id": event.id,
@@ -77,11 +238,229 @@ def event_to_dict(event: WorkflowEvent) -> Dict[str, Any]:
         "summary": event.summary,
         "payload_json": event.payload_json,
         "payload": decode_json(event.payload_json),
+        "schema_version": getattr(
+            event, "schema_version", DEFAULT_EVENT_SCHEMA_VERSION
+        ),
+        "idempotency_key": getattr(event, "idempotency_key", None),
         "approval_status": event.approval_status,
         "created_at": event.created_at,
     }
 
 
+def artifact_to_dict(artifact: WorkflowArtifact) -> Dict[str, Any]:
+    return {
+        "id": artifact.id,
+        "workflow_id": artifact.workflow_id,
+        "artifact_type": artifact.artifact_type,
+        "role": artifact.role,
+        "name": artifact.name,
+        "path": artifact.path,
+        "uri": artifact.uri,
+        "checksum": artifact.checksum,
+        "size_bytes": artifact.size_bytes,
+        "source_event_id": artifact.source_event_id,
+        "metadata_json": artifact.metadata_json,
+        "metadata": decode_json(artifact.metadata_json),
+        "created_at": artifact.created_at,
+        "exists": bool(artifact.path and os.path.exists(artifact.path)),
+    }
+
+
+def volume_state_to_dict(volume_state: WorkflowVolumeState) -> Dict[str, Any]:
+    return {
+        "id": volume_state.id,
+        "workflow_id": volume_state.workflow_id,
+        "volume_id": volume_state.volume_id,
+        "name": volume_state.name,
+        "status": volume_state.status,
+        "annotation_state": getattr(volume_state, "annotation_state", None),
+        "role_state": getattr(volume_state, "role_state", None),
+        "execution_state": getattr(volume_state, "execution_state", None),
+        "region_scope_json": getattr(volume_state, "region_scope_json", None),
+        "region_scope": decode_json(getattr(volume_state, "region_scope_json", None)),
+        "state_schema_version": getattr(volume_state, "state_schema_version", None),
+        "status_source": volume_state.status_source,
+        "status_confidence": volume_state.status_confidence,
+        "project_root": volume_state.project_root,
+        "volume_set_id": volume_state.volume_set_id,
+        "volume_set_name": volume_state.volume_set_name,
+        "image_path": volume_state.image_path,
+        "label_path": volume_state.label_path,
+        "prediction_path": volume_state.prediction_path,
+        "corrected_mask_path": volume_state.corrected_mask_path,
+        "eligible_for_training": bool(volume_state.eligible_for_training),
+        "eligible_for_inference": bool(volume_state.eligible_for_inference),
+        "note": volume_state.note,
+        "metadata_json": volume_state.metadata_json,
+        "metadata": decode_json(volume_state.metadata_json),
+        "source_event_id": volume_state.source_event_id,
+        "created_at": volume_state.created_at,
+        "updated_at": volume_state.updated_at,
+    }
+
+
+def model_run_to_dict(run: WorkflowModelRun) -> Dict[str, Any]:
+    return {
+        "id": run.id,
+        "workflow_id": run.workflow_id,
+        "run_id": getattr(run, "run_id", None),
+        "run_type": run.run_type,
+        "status": run.status,
+        "name": run.name,
+        "config_path": run.config_path,
+        "log_path": run.log_path,
+        "output_path": run.output_path,
+        "checkpoint_path": run.checkpoint_path,
+        "input_artifact_id": run.input_artifact_id,
+        "output_artifact_id": run.output_artifact_id,
+        "source_event_id": run.source_event_id,
+        "metrics_json": run.metrics_json,
+        "metrics": decode_json(run.metrics_json),
+        "metadata_json": run.metadata_json,
+        "metadata": decode_json(run.metadata_json),
+        "started_at": run.started_at,
+        "completed_at": run.completed_at,
+        "created_at": run.created_at,
+        "updated_at": run.updated_at,
+    }
+
+
+def model_version_to_dict(version: WorkflowModelVersion) -> Dict[str, Any]:
+    return {
+        "id": version.id,
+        "workflow_id": version.workflow_id,
+        "version_label": version.version_label,
+        "status": version.status,
+        "checkpoint_path": version.checkpoint_path,
+        "training_run_id": version.training_run_id,
+        "checkpoint_artifact_id": version.checkpoint_artifact_id,
+        "correction_set_id": version.correction_set_id,
+        "metrics_json": version.metrics_json,
+        "metrics": decode_json(version.metrics_json),
+        "metadata_json": version.metadata_json,
+        "metadata": decode_json(version.metadata_json),
+        "created_at": version.created_at,
+    }
+
+
+def correction_set_to_dict(correction_set: WorkflowCorrectionSet) -> Dict[str, Any]:
+    return {
+        "id": correction_set.id,
+        "workflow_id": correction_set.workflow_id,
+        "artifact_id": correction_set.artifact_id,
+        "corrected_mask_path": correction_set.corrected_mask_path,
+        "source_mask_path": correction_set.source_mask_path,
+        "proofreading_session_id": correction_set.proofreading_session_id,
+        "edit_count": correction_set.edit_count,
+        "region_count": correction_set.region_count,
+        "source_event_id": correction_set.source_event_id,
+        "metadata_json": correction_set.metadata_json,
+        "metadata": decode_json(correction_set.metadata_json),
+        "created_at": correction_set.created_at,
+    }
+
+
+def evaluation_result_to_dict(
+    result: WorkflowEvaluationResult,
+) -> Dict[str, Any]:
+    return {
+        "id": result.id,
+        "workflow_id": result.workflow_id,
+        "name": result.name,
+        "baseline_run_id": result.baseline_run_id,
+        "candidate_run_id": result.candidate_run_id,
+        "model_version_id": result.model_version_id,
+        "report_artifact_id": result.report_artifact_id,
+        "report_path": result.report_path,
+        "summary": result.summary,
+        "metrics_json": result.metrics_json,
+        "metrics": decode_json(result.metrics_json),
+        "metadata_json": result.metadata_json,
+        "metadata": decode_json(result.metadata_json),
+        "created_at": result.created_at,
+    }
+
+
+def region_hotspot_to_dict(hotspot: WorkflowRegionHotspot) -> Dict[str, Any]:
+    return {
+        "id": hotspot.id,
+        "workflow_id": hotspot.workflow_id,
+        "region_key": hotspot.region_key,
+        "score": hotspot.score,
+        "severity": hotspot.severity,
+        "status": hotspot.status,
+        "source": hotspot.source,
+        "evidence_json": hotspot.evidence_json,
+        "evidence": decode_json(hotspot.evidence_json),
+        "created_at": hotspot.created_at,
+        "updated_at": hotspot.updated_at,
+    }
+
+
+def agent_step_to_dict(step: WorkflowAgentStep) -> Dict[str, Any]:
+    return {
+        "id": step.id,
+        "plan_id": step.plan_id,
+        "step_index": step.step_index,
+        "action": step.action,
+        "status": step.status,
+        "requires_approval": step.requires_approval,
+        "summary": step.summary,
+        "params_json": step.params_json,
+        "params": decode_json(step.params_json),
+        "result_json": step.result_json,
+        "result": decode_json(step.result_json),
+        "created_at": step.created_at,
+        "updated_at": step.updated_at,
+    }
+
+
+def agent_plan_to_dict(plan: WorkflowAgentPlan) -> Dict[str, Any]:
+    return {
+        "id": plan.id,
+        "workflow_id": plan.workflow_id,
+        "title": plan.title,
+        "status": plan.status,
+        "risk_level": plan.risk_level,
+        "approval_status": plan.approval_status,
+        "goal": plan.goal,
+        "graph_json": plan.graph_json,
+        "graph": decode_json(plan.graph_json),
+        "metadata_json": plan.metadata_json,
+        "metadata": decode_json(plan.metadata_json),
+        "source_event_id": plan.source_event_id,
+        "created_at": plan.created_at,
+        "updated_at": plan.updated_at,
+        "steps": [agent_step_to_dict(step) for step in getattr(plan, "steps", [])],
+    }
+
+
+def command_to_dict(command: WorkflowCommand) -> Dict[str, Any]:
+    return {
+        "id": command.id,
+        "workflow_id": command.workflow_id,
+        "command_type": command.command_type,
+        "status": command.status,
+        "idempotency_key": command.idempotency_key,
+        "actor": command.actor,
+        "source_event_id": command.source_event_id,
+        "approval_event_id": command.approval_event_id,
+        "input_json": command.input_json,
+        "input": decode_json(command.input_json),
+        "result_json": command.result_json,
+        "result": decode_json(command.result_json),
+        "error_json": command.error_json,
+        "error": decode_json(command.error_json),
+        "attempt_count": command.attempt_count,
+        "lease_owner": command.lease_owner,
+        "lease_expires_at": command.lease_expires_at,
+        "started_at": command.started_at,
+        "completed_at": command.completed_at,
+        "created_at": command.created_at,
+        "updated_at": command.updated_at,
+    }
+
+
 def workflow_to_dict(workflow: WorkflowSession) -> Dict[str, Any]:
     return {
         "id": workflow.id,
@@ -95,6 +474,7 @@ def workflow_to_dict(workflow: WorkflowSession) -> Dict[str, Any]:
         "neuroglancer_url": workflow.neuroglancer_url,
         "inference_output_path": workflow.inference_output_path,
         "checkpoint_path": workflow.checkpoint_path,
+        "config_path": workflow.config_path,
         "proofreading_session_id": workflow.proofreading_session_id,
         "corrected_mask_path": workflow.corrected_mask_path,
         "training_output_path": workflow.training_output_path,
@@ -105,6 +485,532 @@ def workflow_to_dict(workflow: WorkflowSession) -> Dict[str, Any]:
     }
 
 
+def create_workflow_artifact(
+    db: Session,
+    *,
+    workflow_id: int,
+    artifact_type: str,
+    role: Optional[str] = None,
+    path: Optional[str] = None,
+    uri: Optional[str] = None,
+    name: Optional[str] = None,
+    checksum: Optional[str] = None,
+    metadata: Optional[Dict[str, Any]] = None,
+    source_event_id: Optional[int] = None,
+    commit: bool = False,
+) -> WorkflowArtifact:
+    normalized_path = str(path) if path else None
+    existing = None
+    if normalized_path:
+        existing = (
+            db.query(WorkflowArtifact)
+            .filter(
+                WorkflowArtifact.workflow_id == workflow_id,
+                WorkflowArtifact.artifact_type == artifact_type,
+                WorkflowArtifact.role == role,
+                WorkflowArtifact.path == normalized_path,
+            )
+            .order_by(WorkflowArtifact.id.desc())
+            .first()
+        )
+    if existing:
+        changed = False
+        if metadata:
+            merged = _merge_dicts(decode_json(existing.metadata_json), metadata)
+            existing.metadata_json = encode_json(merged)
+            changed = True
+        if source_event_id and not existing.source_event_id:
+            existing.source_event_id = source_event_id
+            changed = True
+        if changed:
+            db.flush()
+            if commit:
+                db.commit()
+                db.refresh(existing)
+        return existing
+
+    artifact = WorkflowArtifact(
+        workflow_id=workflow_id,
+        artifact_type=artifact_type,
+        role=role,
+        name=name or _basename(normalized_path or uri),
+        path=normalized_path,
+        uri=uri,
+        checksum=checksum,
+        size_bytes=_path_size(normalized_path),
+        source_event_id=source_event_id,
+        metadata_json=encode_json(metadata),
+    )
+    db.add(artifact)
+    db.flush()
+    if commit:
+        db.commit()
+        db.refresh(artifact)
+    return artifact
+
+
+def _correction_region_key(payload: Dict[str, Any]) -> Optional[str]:
+    for key in ("region_key", "region_id", "region"):
+        value = payload.get(key)
+        if isinstance(value, (str, int, float)):
+            return str(value)
+    instance_id = payload.get("instance_id")
+    if isinstance(instance_id, (str, int)):
+        return f"instance:{instance_id}"
+    z_index = payload.get("z_index")
+    if z_index is not None:
+        axis = payload.get("axis") or "z"
+        return f"{axis}:{z_index}"
+    return None
+
+
+def _correction_stats_from_events(
+    db: Session,
+    *,
+    workflow_id: int,
+    metadata: Optional[Dict[str, Any]] = None,
+) -> Dict[str, int]:
+    def to_int(value: Any, fallback: int = 0) -> int:
+        try:
+            return int(value)
+        except (TypeError, ValueError):
+            return fallback
+
+    metadata = metadata or {}
+    explicit_edit_count = metadata.get("edit_count")
+    explicit_region_count = metadata.get("region_count")
+    if explicit_edit_count is not None and explicit_region_count is not None:
+        return {
+            "edit_count": int(explicit_edit_count or 0),
+            "region_count": int(explicit_region_count or 0),
+        }
+
+    events = (
+        db.query(WorkflowEvent)
+        .filter(
+            WorkflowEvent.workflow_id == workflow_id,
+            WorkflowEvent.event_type.in_(
+                [
+                    "proofreading.instance_classified",
+                    "proofreading.mask_saved",
+                    "proofreading.masks_exported",
+                ]
+            ),
+        )
+        .all()
+    )
+    edit_count = 0
+    region_keys = set()
+    for event in events:
+        payload = decode_json(event.payload_json)
+        region_key = _correction_region_key(payload)
+        if region_key:
+            region_keys.add(region_key)
+        if event.event_type == "proofreading.mask_saved":
+            edit_count += 1
+
+    return {
+        "edit_count": (
+            to_int(explicit_edit_count, edit_count)
+            if explicit_edit_count is not None
+            else edit_count
+        ),
+        "region_count": (
+            to_int(explicit_region_count, len(region_keys))
+            if explicit_region_count is not None
+            else len(region_keys)
+        ),
+    }
+
+
+def create_or_update_correction_set(
+    db: Session,
+    *,
+    workflow: WorkflowSession,
+    corrected_mask_path: str,
+    source_event_id: Optional[int] = None,
+    metadata: Optional[Dict[str, Any]] = None,
+    commit: bool = False,
+) -> WorkflowCorrectionSet:
+    correction_stats = _correction_stats_from_events(
+        db,
+        workflow_id=workflow.id,
+        metadata=metadata,
+    )
+    artifact = create_workflow_artifact(
+        db,
+        workflow_id=workflow.id,
+        artifact_type="correction_set",
+        role="corrected_mask",
+        path=corrected_mask_path,
+        metadata=metadata,
+        source_event_id=source_event_id,
+        commit=False,
+    )
+    existing = (
+        db.query(WorkflowCorrectionSet)
+        .filter(
+            WorkflowCorrectionSet.workflow_id == workflow.id,
+            WorkflowCorrectionSet.corrected_mask_path == corrected_mask_path,
+        )
+        .order_by(WorkflowCorrectionSet.id.desc())
+        .first()
+    )
+    if existing:
+        existing.artifact_id = artifact.id
+        existing.source_mask_path = workflow.mask_path
+        existing.proofreading_session_id = workflow.proofreading_session_id
+        existing.source_event_id = existing.source_event_id or source_event_id
+        existing.edit_count = correction_stats["edit_count"]
+        existing.region_count = correction_stats["region_count"]
+        existing.metadata_json = encode_json(
+            _merge_dicts(decode_json(existing.metadata_json), metadata)
+        )
+        db.flush()
+        if commit:
+            db.commit()
+            db.refresh(existing)
+        return existing
+
+    correction_set = WorkflowCorrectionSet(
+        workflow_id=workflow.id,
+        artifact_id=artifact.id,
+        corrected_mask_path=corrected_mask_path,
+        source_mask_path=workflow.mask_path,
+        proofreading_session_id=workflow.proofreading_session_id,
+        edit_count=correction_stats["edit_count"],
+        region_count=correction_stats["region_count"],
+        source_event_id=source_event_id,
+        metadata_json=encode_json(metadata),
+    )
+    db.add(correction_set)
+    db.flush()
+    if commit:
+        db.commit()
+        db.refresh(correction_set)
+    return correction_set
+
+
+def _latest_incomplete_run(
+    db: Session, *, workflow_id: int, run_type: str
+) -> Optional[WorkflowModelRun]:
+    return (
+        db.query(WorkflowModelRun)
+        .filter(
+            WorkflowModelRun.workflow_id == workflow_id,
+            WorkflowModelRun.run_type == run_type,
+            WorkflowModelRun.status.in_(["pending", "running"]),
+        )
+        .order_by(WorkflowModelRun.created_at.desc(), WorkflowModelRun.id.desc())
+        .first()
+    )
+
+
+def _payload_run_id(payload: Dict[str, Any]) -> Optional[str]:
+    for key in ("run_id", "runId", "job_id", "jobId", "execution_id", "executionId"):
+        value = payload.get(key)
+        if value is not None:
+            return str(value)
+    return None
+
+
+def _find_model_run_for_event(
+    db: Session,
+    *,
+    workflow_id: int,
+    run_type: str,
+    run_id: Optional[str],
+    output_path: Optional[str],
+    fallback_latest: bool = True,
+) -> Optional[WorkflowModelRun]:
+    if run_id:
+        run = (
+            db.query(WorkflowModelRun)
+            .filter(
+                WorkflowModelRun.workflow_id == workflow_id,
+                WorkflowModelRun.run_id == run_id,
+            )
+            .first()
+        )
+        if run:
+            return run
+    if output_path:
+        run = (
+            db.query(WorkflowModelRun)
+            .filter(
+                WorkflowModelRun.workflow_id == workflow_id,
+                WorkflowModelRun.run_type == run_type,
+                WorkflowModelRun.status.in_(["pending", "running"]),
+                WorkflowModelRun.output_path == output_path,
+            )
+            .order_by(WorkflowModelRun.created_at.desc(), WorkflowModelRun.id.desc())
+            .first()
+        )
+        if run:
+            return run
+    if not fallback_latest:
+        return None
+    return _latest_incomplete_run(db, workflow_id=workflow_id, run_type=run_type)
+
+
+def create_or_update_model_run_from_event(
+    db: Session,
+    *,
+    workflow: WorkflowSession,
+    event: WorkflowEvent,
+    payload: Dict[str, Any],
+) -> Optional[WorkflowModelRun]:
+    event_type = event.event_type
+    run_type = None
+    status = None
+    if event_type == "training.started":
+        run_type, status = "training", "running"
+    elif event_type == "training.completed":
+        run_type, status = "training", "completed"
+    elif event_type == "training.failed":
+        run_type, status = "training", "failed"
+    elif event_type == "inference.started":
+        run_type, status = "inference", "running"
+    elif event_type == "inference.completed":
+        run_type, status = "inference", "completed"
+    elif event_type == "inference.failed":
+        run_type, status = "inference", "failed"
+    if not run_type:
+        return None
+
+    output_path = (
+        payload.get("outputPath")
+        or payload.get("output_path")
+        or payload.get("training_output_path")
+        or payload.get("inference_output_path")
+    )
+    checkpoint_path = (
+        payload.get("checkpointPath")
+        or payload.get("checkpoint_path")
+        or payload.get("checkpoint")
+    )
+    config_path = payload.get("configOriginPath") or payload.get("config_path")
+    log_path = payload.get("logPath") or payload.get("log_path")
+    now = _now()
+    run_id = _payload_run_id(payload)
+
+    run = (
+        _find_model_run_for_event(
+            db,
+            workflow_id=workflow.id,
+            run_type=run_type,
+            run_id=run_id,
+            output_path=output_path,
+            fallback_latest=not bool(run_id),
+        )
+        if status in {"completed", "failed"}
+        else None
+    )
+    if status == "running" and run_id:
+        run = _find_model_run_for_event(
+            db,
+            workflow_id=workflow.id,
+            run_type=run_type,
+            run_id=run_id,
+            output_path=output_path,
+            fallback_latest=False,
+        )
+    if run is None:
+        run_id = run_id or f"{run_type}-{event.id}"
+        run = WorkflowModelRun(
+            workflow_id=workflow.id,
+            run_id=run_id,
+            run_type=run_type,
+            status=status,
+            source_event_id=event.id,
+            started_at=now if status == "running" else None,
+        )
+        db.add(run)
+    elif run_id and not getattr(run, "run_id", None):
+        run.run_id = run_id
+    run_id = getattr(run, "run_id", None) or run_id
+    if run_id and payload.get("run_id") != run_id:
+        payload["run_id"] = run_id
+        event.payload_json = encode_json(payload)
+
+    run.status = status
+    run.config_path = config_path or run.config_path
+    run.log_path = log_path or run.log_path
+    run.output_path = output_path or run.output_path
+    run.checkpoint_path = checkpoint_path or run.checkpoint_path
+    run.source_event_id = run.source_event_id or event.id
+    run.metadata_json = encode_json(
+        _merge_dicts(
+            decode_json(run.metadata_json),
+            {
+                "last_event_type": event_type,
+                "last_event_id": event.id,
+                "run_id": run_id,
+            },
+        )
+    )
+    if status == "running" and not run.started_at:
+        run.started_at = now
+    if status in {"completed", "failed"}:
+        run.completed_at = now
+
+    if output_path and run_type == "inference":
+        run.output_artifact = create_workflow_artifact(
+            db,
+            workflow_id=workflow.id,
+            artifact_type="inference_output",
+            role="prediction",
+            path=output_path,
+            source_event_id=event.id,
+            metadata={"run_type": run_type, "status": status},
+            commit=False,
+        )
+    elif output_path and run_type == "training":
+        run.output_artifact = create_workflow_artifact(
+            db,
+            workflow_id=workflow.id,
+            artifact_type="training_output",
+            role="run_directory",
+            path=output_path,
+            source_event_id=event.id,
+            metadata={"run_type": run_type, "status": status},
+            commit=False,
+        )
+
+    db.flush()
+
+    if run_type == "training" and status == "completed" and checkpoint_path:
+        checkpoint_artifact = create_workflow_artifact(
+            db,
+            workflow_id=workflow.id,
+            artifact_type="model_checkpoint",
+            role="candidate_checkpoint",
+            path=checkpoint_path,
+            source_event_id=event.id,
+            metadata={"model_run_id": run.id},
+            commit=False,
+        )
+        label = payload.get("checkpointName") or _basename(checkpoint_path)
+        version = WorkflowModelVersion(
+            workflow_id=workflow.id,
+            version_label=label or f"model-run-{run.id}",
+            status="candidate",
+            checkpoint_path=checkpoint_path,
+            training_run_id=run.id,
+            checkpoint_artifact_id=checkpoint_artifact.id,
+            metrics_json=encode_json(payload.get("metrics") or {}),
+            metadata_json=encode_json({"source_event_id": event.id}),
+        )
+        db.add(version)
+        db.flush()
+
+    return run
+
+
+def _artifact_specs_for_event(
+    event_type: str, payload: Dict[str, Any]
+) -> List[Dict[str, Any]]:
+    specs: List[Dict[str, Any]] = []
+
+    def add_non_copy_path(path_key: str, artifact_type: str, role: str) -> None:
+        path = payload.get(path_key)
+        if path:
+            specs.append(
+                {
+                    "artifact_type": artifact_type,
+                    "role": role,
+                    "path": str(path),
+                    "metadata": {
+                        "source_payload_key": path_key,
+                        "allow_copy_in_bundle": False,
+                        "copy_reason": "external_reference_path",
+                    },
+                }
+            )
+
+    def add(path_key: str, artifact_type: str, role: str) -> None:
+        path = payload.get(path_key)
+        if path:
+            specs.append(
+                {
+                    "artifact_type": artifact_type,
+                    "role": role,
+                    "path": str(path),
+                    "metadata": {"source_payload_key": path_key},
+                }
+            )
+
+    if event_type in {"dataset.loaded", "viewer.created"}:
+        add("dataset_path", "dataset", "source_dataset")
+        add("image_path", "image_volume", "image")
+        add("label_path", "label_volume", "label")
+        add("mask_path", "mask_volume", "mask")
+        add("ground_truth_path", "label_volume", "ground_truth")
+        add("source_ground_truth_path", "label_volume", "ground_truth")
+        add_non_copy_path(
+            "withheld_ground_truth", "label_volume", "withheld_ground_truth"
+        )
+        add_non_copy_path("source_ground_truth", "label_volume", "ground_truth")
+        add_non_copy_path(
+            "withheld_ground_truth_path", "label_volume", "withheld_ground_truth"
+        )
+    if event_type in {"proofreading.masks_exported", "retraining.staged"}:
+        add("written_path", "correction_set", "corrected_mask")
+        add("output_path", "correction_set", "corrected_mask")
+        add("corrected_mask_path", "correction_set", "corrected_mask")
+        add("backup_path", "mask_volume", "backup_mask")
+    if event_type.startswith("training."):
+        add("outputPath", "training_output", "run_directory")
+        add("output_path", "training_output", "run_directory")
+        add("checkpointPath", "model_checkpoint", "candidate_checkpoint")
+        add("checkpoint_path", "model_checkpoint", "candidate_checkpoint")
+    if event_type.startswith("inference."):
+        add("outputPath", "inference_output", "prediction")
+        add("output_path", "inference_output", "prediction")
+        add("checkpointPath", "model_checkpoint", "input_checkpoint")
+        add("checkpoint_path", "model_checkpoint", "input_checkpoint")
+    return specs
+
+
+def materialize_event_artifacts(
+    db: Session,
+    *,
+    workflow: WorkflowSession,
+    event: WorkflowEvent,
+    payload: Dict[str, Any],
+) -> None:
+    for spec in _artifact_specs_for_event(event.event_type, payload):
+        create_workflow_artifact(
+            db,
+            workflow_id=workflow.id,
+            source_event_id=event.id,
+            commit=False,
+            **spec,
+        )
+
+    corrected_mask_path = (
+        payload.get("corrected_mask_path")
+        or payload.get("written_path")
+        or payload.get("output_path")
+    )
+    if (
+        event.event_type in {"proofreading.masks_exported", "retraining.staged"}
+        and corrected_mask_path
+    ):
+        create_or_update_correction_set(
+            db,
+            workflow=workflow,
+            corrected_mask_path=str(corrected_mask_path),
+            source_event_id=event.id,
+            metadata={"source_event_type": event.event_type},
+            commit=False,
+        )
+
+    create_or_update_model_run_from_event(
+        db, workflow=workflow, event=event, payload=payload
+    )
+
+
 def get_user_workflow_or_404(
     db: Session, *, workflow_id: int, user_id: int
 ) -> WorkflowSession:
@@ -128,7 +1034,36 @@ def get_current_or_create_workflow(db: Session, *, user_id: int) -> WorkflowSess
     if workflow:
         return workflow
 
-    workflow = WorkflowSession(user_id=user_id, title="Segmentation Workflow")
+    return create_workflow_session(db, user_id=user_id)
+
+
+def create_workflow_session(
+    db: Session,
+    *,
+    user_id: int,
+    title: str = "Segmentation Workflow",
+    metadata: Optional[Dict[str, Any]] = None,
+) -> WorkflowSession:
+    initial_defaults = _initial_project_defaults()
+    initial_metadata = {
+        **initial_defaults.get("metadata", {}),
+        **(metadata or {}),
+    }
+    workflow_title = title or "Segmentation Workflow"
+    if initial_defaults and workflow_title == "Segmentation Workflow":
+        workflow_title = initial_defaults.get("title") or workflow_title
+
+    workflow = WorkflowSession(
+        user_id=user_id,
+        title=workflow_title,
+        stage="setup",
+        dataset_path=initial_defaults.get("dataset_path"),
+        image_path=initial_defaults.get("image_path"),
+        label_path=initial_defaults.get("label_path"),
+        mask_path=initial_defaults.get("mask_path"),
+        config_path=initial_defaults.get("config_path"),
+        metadata_json=encode_json(initial_metadata),
+    )
     db.add(workflow)
     db.commit()
     db.refresh(workflow)
@@ -155,6 +1090,7 @@ def get_current_or_create_workflow(db: Session, *, user_id: int) -> WorkflowSess
     "neuroglancer_url",
     "inference_output_path",
     "checkpoint_path",
+    "config_path",
     "proofreading_session_id",
     "corrected_mask_path",
     "training_output_path",
@@ -170,7 +1106,10 @@ def update_workflow_fields(
 ) -> WorkflowSession:
     for key, value in updates.items():
         if key == "metadata":
-            workflow.metadata_json = encode_json(value if isinstance(value, dict) else {})
+            patch = value if isinstance(value, dict) else {}
+            workflow.metadata_json = encode_json(
+                _merge_dicts(decode_json(workflow.metadata_json), patch)
+            )
             continue
         if key == "metadata_json":
             workflow.metadata_json = value
@@ -189,6 +1128,138 @@ def update_workflow_fields(
     return workflow
 
 
+def create_workflow_command(
+    db: Session,
+    *,
+    workflow_id: int,
+    command_type: str,
+    idempotency_key: str,
+    actor: str = "agent",
+    source_event_id: Optional[int] = None,
+    approval_event_id: Optional[int] = None,
+    input_payload: Optional[Dict[str, Any]] = None,
+    status: str = "queued",
+    commit: bool = False,
+) -> WorkflowCommand:
+    actor = validate_actor(actor)
+    status = validate_command_status(status)
+    existing = (
+        db.query(WorkflowCommand)
+        .filter(
+            WorkflowCommand.workflow_id == workflow_id,
+            WorkflowCommand.idempotency_key == idempotency_key,
+        )
+        .first()
+    )
+    if existing:
+        return existing
+    command = WorkflowCommand(
+        workflow_id=workflow_id,
+        command_type=command_type,
+        status=status,
+        idempotency_key=idempotency_key,
+        actor=actor,
+        source_event_id=source_event_id,
+        approval_event_id=approval_event_id,
+        input_json=encode_json(input_payload or {}),
+    )
+    db.add(command)
+    db.flush()
+    if commit:
+        db.commit()
+        db.refresh(command)
+    return command
+
+
+def mark_workflow_command_running(
+    db: Session,
+    command: WorkflowCommand,
+    *,
+    lease_owner: str = "server_api",
+    input_payload: Optional[Dict[str, Any]] = None,
+    commit: bool = False,
+) -> WorkflowCommand:
+    if command.status not in {"queued", "claimed", "retry_pending", "failed"}:
+        raise HTTPException(
+            status_code=409,
+            detail=f"Command cannot be run from status: {command.status}",
+        )
+    now = _now()
+    command.status = "running"
+    command.attempt_count = int(command.attempt_count or 0) + 1
+    command.lease_owner = lease_owner
+    command.started_at = now
+    command.completed_at = None
+    command.error_json = None
+    if input_payload is not None:
+        command.input_json = encode_json(input_payload)
+    db.flush()
+    if commit:
+        db.commit()
+        db.refresh(command)
+    return command
+
+
+def complete_workflow_command(
+    db: Session,
+    command: WorkflowCommand,
+    *,
+    result_payload: Optional[Dict[str, Any]] = None,
+    commit: bool = False,
+) -> WorkflowCommand:
+    command.status = "completed"
+    command.result_json = encode_json(result_payload or {})
+    command.error_json = None
+    command.lease_owner = None
+    command.lease_expires_at = None
+    command.completed_at = _now()
+    db.flush()
+    if commit:
+        db.commit()
+        db.refresh(command)
+    return command
+
+
+def submit_workflow_command(
+    db: Session,
+    command: WorkflowCommand,
+    *,
+    result_payload: Optional[Dict[str, Any]] = None,
+    commit: bool = False,
+) -> WorkflowCommand:
+    command.status = "submitted"
+    command.result_json = encode_json(result_payload or {})
+    command.error_json = None
+    command.lease_owner = None
+    command.lease_expires_at = None
+    command.completed_at = None
+    db.flush()
+    if commit:
+        db.commit()
+        db.refresh(command)
+    return command
+
+
+def fail_workflow_command(
+    db: Session,
+    command: WorkflowCommand,
+    *,
+    error_payload: Optional[Dict[str, Any]] = None,
+    retryable: bool = False,
+    commit: bool = False,
+) -> WorkflowCommand:
+    command.status = "retry_pending" if retryable else "failed"
+    command.error_json = encode_json(error_payload or {})
+    command.lease_owner = None
+    command.lease_expires_at = None
+    command.completed_at = _now()
+    db.flush()
+    if commit:
+        db.commit()
+        db.refresh(command)
+    return command
+
+
 def append_workflow_event(
     db: Session,
     *,
@@ -198,6 +1269,8 @@ def append_workflow_event(
     summary: str,
     stage: Optional[str] = None,
     payload: Optional[Dict[str, Any]] = None,
+    schema_version: int = DEFAULT_EVENT_SCHEMA_VERSION,
+    idempotency_key: Optional[str] = None,
     approval_status: str = "not_required",
     commit: bool = True,
 ) -> Optional[WorkflowEvent]:
@@ -206,6 +1279,18 @@ def append_workflow_event(
     actor = validate_actor(actor)
     approval_status = validate_approval_status(approval_status)
     stage = validate_stage(stage) if stage else stage
+    if idempotency_key:
+        existing = (
+            db.query(WorkflowEvent)
+            .filter(
+                WorkflowEvent.workflow_id == workflow_id,
+                WorkflowEvent.idempotency_key == idempotency_key,
+            )
+            .order_by(WorkflowEvent.id.desc())
+            .first()
+        )
+        if existing:
+            return existing
     event = WorkflowEvent(
         workflow_id=workflow_id,
         actor=actor,
@@ -213,9 +1298,22 @@ def append_workflow_event(
         stage=stage,
         summary=summary,
         payload_json=encode_json(payload),
+        schema_version=schema_version or DEFAULT_EVENT_SCHEMA_VERSION,
+        idempotency_key=idempotency_key,
         approval_status=approval_status,
     )
     db.add(event)
+    db.flush()
+    workflow = (
+        db.query(WorkflowSession).filter(WorkflowSession.id == workflow_id).first()
+    )
+    if workflow:
+        materialize_event_artifacts(
+            db,
+            workflow=workflow,
+            event=event,
+            payload=payload or {},
+        )
     if commit:
         db.commit()
         db.refresh(event)
@@ -231,6 +1329,8 @@ def append_event_for_workflow_if_present(
     summary: str,
     stage: Optional[str] = None,
     payload: Optional[Dict[str, Any]] = None,
+    schema_version: int = DEFAULT_EVENT_SCHEMA_VERSION,
+    idempotency_key: Optional[str] = None,
 ) -> Optional[WorkflowEvent]:
     if not workflow_id:
         return None
@@ -242,5 +1342,7 @@ def append_event_for_workflow_if_present(
         summary=summary,
         stage=stage,
         payload=payload,
+        schema_version=schema_version,
+        idempotency_key=idempotency_key,
         commit=True,
     )
diff --git a/server_api/workflows/volume_io.py b/server_api/workflows/volume_io.py
new file mode 100644
index 00000000..c2e4b1ba
--- /dev/null
+++ b/server_api/workflows/volume_io.py
@@ -0,0 +1,483 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, List, Optional, Sequence, Tuple, Union
+
+import numpy as np
+
+CropSpec = Union[str, Sequence[slice], None]
+
+COMMON_DATASET_NAMES = (
+    "data",
+    "main",
+    "volume",
+    "vol",
+    "raw",
+    "image",
+    "images",
+    "label",
+    "labels",
+    "seg",
+    "segmentation",
+    "prediction",
+    "predictions",
+)
+
+SUPPORTED_VOLUME_FORMATS = (
+    "TIFF/OME-TIFF: .tif, .tiff, .ome.tif, .ome.tiff",
+    "HDF5: .h5, .hdf5, .hdf",
+    "NumPy: .npy, .npz",
+    "Zarr/N5: .zarr, .n5",
+    "Common 2D images: .png, .jpg, .jpeg, .bmp",
+    "Optional NIfTI if nibabel is installed: .nii, .nii.gz",
+    "Optional MRC if mrcfile is installed: .mrc, .map, .rec",
+)
+
+
+def split_dataset_ref(path: str) -> Tuple[str, Optional[str]]:
+    if "::" not in path:
+        return path, None
+    file_path, dataset_key = path.split("::", 1)
+    return file_path, dataset_key or None
+
+
+def parse_crop(crop: CropSpec) -> Optional[Tuple[slice, ...]]:
+    if crop is None:
+        return None
+    if isinstance(crop, (list, tuple)) and all(
+        isinstance(item, slice) for item in crop
+    ):
+        return tuple(crop)
+    if not isinstance(crop, str):
+        raise ValueError("crop must be a string like '0:16,0:256,0:256'")
+
+    normalized = crop.strip().lower()
+    if normalized in {"", "none", "full", ":"}:
+        return None
+
+    slices: List[slice] = []
+    for part in normalized.split(","):
+        token = part.strip()
+        if not token:
+            raise ValueError(f"Invalid empty crop token in {crop!r}")
+        if ":" not in token:
+            index = int(token)
+            slices.append(slice(index, index + 1))
+            continue
+        pieces = token.split(":")
+        if len(pieces) > 3:
+            raise ValueError(f"Invalid crop token {token!r}")
+        values = [int(piece) if piece else None for piece in pieces]
+        while len(values) < 3:
+            values.append(None)
+        slices.append(slice(values[0], values[1], values[2]))
+    return tuple(slices)
+
+
+def _normalize_crop_for_shape(
+    crop: Optional[Tuple[slice, ...]], shape: Sequence[int]
+) -> Union[slice, Tuple[slice, ...]]:
+    if crop is None:
+        return slice(None)
+    if len(crop) > len(shape):
+        raise ValueError(f"Crop has {len(crop)} dimensions but array has {len(shape)}")
+    return tuple(list(crop) + [slice(None)] * (len(shape) - len(crop)))
+
+
+def _infer_channel_axis(
+    shape: Sequence[int],
+    *,
+    channel: Optional[int],
+    reference_ndim: Optional[int],
+    label: str,
+) -> Optional[int]:
+    if channel is None:
+        return None
+    if channel < 0:
+        raise ValueError(f"{label} channel must be non-negative")
+
+    reference_ndim = reference_ndim or max(1, len(shape) - 1)
+    if len(shape) == reference_ndim:
+        raise ValueError(
+            f"{label} volume is already {reference_ndim}D; "
+            "do not pass a channel selector for this artifact."
+        )
+    if len(shape) != reference_ndim + 1:
+        raise ValueError(
+            f"{label} volume has shape {tuple(shape)}; expected "
+            f"{reference_ndim}D or {reference_ndim + 1}D for channel selection."
+        )
+
+    if shape[0] > channel and shape[0] <= 16:
+        return 0
+    if shape[-1] > channel and shape[-1] <= 16:
+        return len(shape) - 1
+    if shape[0] > channel:
+        return 0
+    if shape[-1] > channel:
+        return len(shape) - 1
+    raise ValueError(
+        f"{label} channel {channel} is out of bounds for volume shape {tuple(shape)}"
+    )
+
+
+def _normalize_crop_for_output(
+    crop: Optional[Tuple[slice, ...]], output_ndim: int
+) -> List[slice]:
+    if crop is None:
+        return [slice(None)] * output_ndim
+    if len(crop) > output_ndim:
+        raise ValueError(f"Crop has {len(crop)} dimensions but array has {output_ndim}")
+    return list(crop) + [slice(None)] * (output_ndim - len(crop))
+
+
+def _array_index(
+    data: Any,
+    crop: Optional[Tuple[slice, ...]] = None,
+    *,
+    channel: Optional[int] = None,
+    reference_ndim: Optional[int] = None,
+    label: str = "volume",
+) -> Union[int, slice, Tuple[Any, ...]]:
+    shape = getattr(data, "shape", ())
+    if channel is None:
+        return _normalize_crop_for_shape(crop, shape)
+
+    channel_axis = _infer_channel_axis(
+        shape,
+        channel=channel,
+        reference_ndim=reference_ndim,
+        label=label,
+    )
+    output_ndim = len(shape) - 1
+    crop_key = _normalize_crop_for_output(crop, output_ndim)
+    key: List[Any] = []
+    crop_index = 0
+    for axis_index in range(len(shape)):
+        if axis_index == channel_axis:
+            key.append(channel)
+            continue
+        key.append(crop_key[crop_index])
+        crop_index += 1
+    return tuple(key)
+
+
+def _as_array(
+    data: Any,
+    crop: Optional[Tuple[slice, ...]] = None,
+    *,
+    channel: Optional[int] = None,
+    reference_ndim: Optional[int] = None,
+    label: str = "volume",
+) -> np.ndarray:
+    if crop is None and channel is None:
+        return np.asarray(data)
+    key = _array_index(
+        data,
+        crop,
+        channel=channel,
+        reference_ndim=reference_ndim,
+        label=label,
+    )
+    return np.asarray(data[key])
+
+
+def _collect_h5_datasets(handle: Any) -> List[str]:
+    import h5py
+
+    datasets: List[str] = []
+
+    def visitor(name: str, obj: Any) -> None:
+        if isinstance(obj, h5py.Dataset):
+            datasets.append(name)
+
+    handle.visititems(visitor)
+    return datasets
+
+
+def _select_h5_dataset(handle: Any, dataset_key: Optional[str]) -> Any:
+    import h5py
+
+    if dataset_key:
+        if dataset_key not in handle:
+            raise ValueError(f"HDF5 dataset {dataset_key!r} not found")
+        target = handle[dataset_key]
+        if not isinstance(target, h5py.Dataset):
+            raise ValueError(f"HDF5 path {dataset_key!r} is not a dataset")
+        return target
+
+    for name in COMMON_DATASET_NAMES:
+        if name in handle and isinstance(handle[name], h5py.Dataset):
+            return handle[name]
+
+    datasets = _collect_h5_datasets(handle)
+    if not datasets:
+        raise ValueError("HDF5 file does not contain any datasets")
+    return handle[datasets[0]]
+
+
+def _read_hdf5(
+    path: Path,
+    dataset_key: Optional[str],
+    crop: Optional[Tuple[slice, ...]],
+    *,
+    channel: Optional[int] = None,
+    reference_ndim: Optional[int] = None,
+    label: str = "volume",
+) -> np.ndarray:
+    import h5py
+
+    with h5py.File(path, "r") as handle:
+        dataset = _select_h5_dataset(handle, dataset_key)
+        return _as_array(
+            dataset,
+            crop,
+            channel=channel,
+            reference_ndim=reference_ndim,
+            label=label,
+        )
+
+
+def _is_zarr_array(value: Any) -> bool:
+    return (
+        hasattr(value, "shape")
+        and hasattr(value, "dtype")
+        and hasattr(value, "__getitem__")
+    )
+
+
+def _collect_zarr_arrays(group: Any, prefix: str = "") -> List[str]:
+    arrays: List[str] = []
+    try:
+        keys = list(group.keys())
+    except Exception:
+        return arrays
+    for key in keys:
+        child = group[key]
+        child_path = f"{prefix}/{key}" if prefix else str(key)
+        if _is_zarr_array(child):
+            arrays.append(child_path)
+        else:
+            arrays.extend(_collect_zarr_arrays(child, child_path))
+    return arrays
+
+
+def _select_zarr_array(store: Any, dataset_key: Optional[str]) -> Any:
+    if _is_zarr_array(store):
+        if dataset_key:
+            raise ValueError(
+                "Dataset key was provided, but Zarr path is already an array"
+            )
+        return store
+
+    if dataset_key:
+        return store[dataset_key]
+
+    for name in COMMON_DATASET_NAMES:
+        try:
+            child = store[name]
+        except Exception:
+            continue
+        if _is_zarr_array(child):
+            return child
+
+    arrays = _collect_zarr_arrays(store)
+    if not arrays:
+        raise ValueError("Zarr/N5 store does not contain any arrays")
+    return store[arrays[0]]
+
+
+def _read_zarr(
+    path: Path,
+    dataset_key: Optional[str],
+    crop: Optional[Tuple[slice, ...]],
+    *,
+    channel: Optional[int] = None,
+    reference_ndim: Optional[int] = None,
+    label: str = "volume",
+) -> np.ndarray:
+    import zarr
+
+    store = zarr.open(str(path), mode="r")
+    array = _select_zarr_array(store, dataset_key)
+    return _as_array(
+        array,
+        crop,
+        channel=channel,
+        reference_ndim=reference_ndim,
+        label=label,
+    )
+
+
+def _read_npz(
+    path: Path,
+    dataset_key: Optional[str],
+    crop: Optional[Tuple[slice, ...]],
+    *,
+    channel: Optional[int] = None,
+    reference_ndim: Optional[int] = None,
+    label: str = "volume",
+) -> np.ndarray:
+    with np.load(path) as loaded:
+        key = dataset_key
+        if not key:
+            for candidate in COMMON_DATASET_NAMES:
+                if candidate in loaded:
+                    key = candidate
+                    break
+        if not key:
+            keys = list(loaded.keys())
+            if not keys:
+                raise ValueError("NPZ file does not contain any arrays")
+            key = keys[0]
+        return _as_array(
+            loaded[key],
+            crop,
+            channel=channel,
+            reference_ndim=reference_ndim,
+            label=label,
+        )
+
+
+def _read_nifti(
+    path: Path,
+    crop: Optional[Tuple[slice, ...]],
+    *,
+    channel: Optional[int] = None,
+    reference_ndim: Optional[int] = None,
+    label: str = "volume",
+) -> np.ndarray:
+    try:
+        import nibabel as nib
+    except Exception as exc:  # pragma: no cover - optional dependency
+        raise RuntimeError("nibabel is required to read NIfTI volumes") from exc
+
+    image = nib.load(str(path))
+    data = image.dataobj
+    return _as_array(
+        data,
+        crop,
+        channel=channel,
+        reference_ndim=reference_ndim,
+        label=label,
+    )
+
+
+def _read_mrc(
+    path: Path,
+    crop: Optional[Tuple[slice, ...]],
+    *,
+    channel: Optional[int] = None,
+    reference_ndim: Optional[int] = None,
+    label: str = "volume",
+) -> np.ndarray:
+    try:
+        import mrcfile
+    except Exception as exc:  # pragma: no cover - optional dependency
+        raise RuntimeError("mrcfile is required to read MRC/MAP volumes") from exc
+
+    with mrcfile.open(str(path), permissive=True) as handle:
+        return _as_array(
+            handle.data,
+            crop,
+            channel=channel,
+            reference_ndim=reference_ndim,
+            label=label,
+        )
+
+
+def load_volume(
+    path: str,
+    *,
+    dataset_key: Optional[str] = None,
+    crop: CropSpec = None,
+    channel: Optional[int] = None,
+    reference_ndim: Optional[int] = None,
+    label: str = "volume",
+) -> np.ndarray:
+    file_path, inline_dataset_key = split_dataset_ref(str(path))
+    dataset_key = dataset_key or inline_dataset_key
+    target = Path(file_path).expanduser()
+    if not target.exists():
+        raise FileNotFoundError(f"Volume artifact does not exist: {target}")
+
+    crop_slices = parse_crop(crop)
+    lower_name = target.name.lower()
+    lower_path = str(target).lower()
+
+    if lower_name.endswith((".h5", ".hdf5", ".hdf")):
+        return _read_hdf5(
+            target,
+            dataset_key,
+            crop_slices,
+            channel=channel,
+            reference_ndim=reference_ndim,
+            label=label,
+        )
+    if lower_name.endswith((".tif", ".tiff", ".ome.tif", ".ome.tiff")):
+        import tifffile
+
+        return _as_array(
+            tifffile.imread(str(target)),
+            crop_slices,
+            channel=channel,
+            reference_ndim=reference_ndim,
+            label=label,
+        )
+    if lower_name.endswith(".npy"):
+        return _as_array(
+            np.load(target, mmap_mode="r"),
+            crop_slices,
+            channel=channel,
+            reference_ndim=reference_ndim,
+            label=label,
+        )
+    if lower_name.endswith(".npz"):
+        return _read_npz(
+            target,
+            dataset_key,
+            crop_slices,
+            channel=channel,
+            reference_ndim=reference_ndim,
+            label=label,
+        )
+    if target.is_dir() or lower_name.endswith((".zarr", ".n5")):
+        return _read_zarr(
+            target,
+            dataset_key,
+            crop_slices,
+            channel=channel,
+            reference_ndim=reference_ndim,
+            label=label,
+        )
+    if lower_path.endswith((".nii", ".nii.gz")):
+        return _read_nifti(
+            target,
+            crop_slices,
+            channel=channel,
+            reference_ndim=reference_ndim,
+            label=label,
+        )
+    if lower_name.endswith((".mrc", ".map", ".rec")):
+        return _read_mrc(
+            target,
+            crop_slices,
+            channel=channel,
+            reference_ndim=reference_ndim,
+            label=label,
+        )
+    if lower_name.endswith((".png", ".jpg", ".jpeg", ".bmp")):
+        import imageio.v3 as iio
+
+        return _as_array(
+            iio.imread(target),
+            crop_slices,
+            channel=channel,
+            reference_ndim=reference_ndim,
+            label=label,
+        )
+
+    raise ValueError(
+        f"Unsupported volume format for {target}. Supported formats: "
+        + "; ".join(SUPPORTED_VOLUME_FORMATS)
+    )
diff --git a/server_api/workflows/volume_pairs.py b/server_api/workflows/volume_pairs.py
new file mode 100644
index 00000000..905c506b
--- /dev/null
+++ b/server_api/workflows/volume_pairs.py
@@ -0,0 +1,259 @@
+from __future__ import annotations
+
+import pathlib
+import re
+from typing import Any, Dict, List, Optional, Tuple
+
+NEUROGLANCER_VOLUME_FILE_SUFFIXES = (
+    ".h5",
+    ".hdf5",
+    ".hdf",
+    ".tif",
+    ".tiff",
+    ".ome.tif",
+    ".ome.tiff",
+    ".npy",
+    ".npz",
+    ".nii",
+    ".nii.gz",
+    ".mrc",
+    ".map",
+    ".rec",
+    ".png",
+    ".jpg",
+    ".jpeg",
+    ".bmp",
+)
+NEUROGLANCER_VOLUME_DIR_SUFFIXES = (".zarr", ".n5")
+
+
+def _path_has_suffix(path: pathlib.Path, suffixes: tuple[str, ...]) -> bool:
+    lower = path.name.lower()
+    return any(lower.endswith(suffix) for suffix in suffixes)
+
+
+def _is_neuroglancer_volume_file(path: pathlib.Path) -> bool:
+    return path.is_file() and _path_has_suffix(path, NEUROGLANCER_VOLUME_FILE_SUFFIXES)
+
+
+def _is_chunked_volume_directory(path: pathlib.Path) -> bool:
+    return path.is_dir() and _path_has_suffix(path, NEUROGLANCER_VOLUME_DIR_SUFFIXES)
+
+
+def _volume_pair_key(path: pathlib.Path) -> str:
+    name = path.name.lower()
+    for suffix in sorted(
+        NEUROGLANCER_VOLUME_FILE_SUFFIXES + NEUROGLANCER_VOLUME_DIR_SUFFIXES,
+        key=len,
+        reverse=True,
+    ):
+        if name.endswith(suffix):
+            name = name[: -len(suffix)]
+            break
+    replacements = (
+        ("image_", ""),
+        ("images_", ""),
+        ("img_", ""),
+        ("raw_", ""),
+        ("volume_", ""),
+        ("vol_", ""),
+        ("seg_", ""),
+        ("label_", ""),
+        ("labels_", ""),
+        ("mask_", ""),
+        ("masks_", ""),
+        ("gt_", ""),
+        ("ground_truth_", ""),
+        ("_image", ""),
+        ("_images", ""),
+        ("_img", ""),
+        ("_im", ""),
+        ("_raw", ""),
+        ("_volume", ""),
+        ("_vol", ""),
+        ("_seg", ""),
+        ("_label", ""),
+        ("_labels", ""),
+        ("_mask", ""),
+        ("_masks", ""),
+        ("_gt", ""),
+        ("_ground_truth", ""),
+        ("-image", ""),
+        ("-images", ""),
+        ("-img", ""),
+        ("-raw", ""),
+        ("-volume", ""),
+        ("-seg", ""),
+        ("-label", ""),
+        ("-labels", ""),
+        ("-mask", ""),
+    )
+    for old, new in replacements:
+        name = name.replace(old, new)
+    return re.sub(r"[^a-z0-9]+", "_", name).strip("_")
+
+
+def _volume_file_candidates(
+    directory: pathlib.Path, *, max_candidates: int = 2000
+) -> List[pathlib.Path]:
+    if not directory.exists() or not directory.is_dir():
+        return []
+    direct = [
+        child
+        for child in sorted(directory.iterdir(), key=lambda item: item.name.lower())
+        if _is_neuroglancer_volume_file(child) or _is_chunked_volume_directory(child)
+    ]
+    if direct:
+        return direct[:max_candidates]
+
+    candidates: List[pathlib.Path] = []
+    for child in sorted(directory.rglob("*"), key=lambda item: str(item).lower()):
+        if _is_neuroglancer_volume_file(child) or _is_chunked_volume_directory(child):
+            candidates.append(child)
+            if len(candidates) >= max_candidates:
+                break
+    return candidates
+
+
+def _as_volume_candidates(path: Optional[pathlib.Path]) -> List[pathlib.Path]:
+    if path is None:
+        return []
+    if _is_chunked_volume_directory(path) or _is_neuroglancer_volume_file(path):
+        return [path]
+    if path.is_dir():
+        return _volume_file_candidates(path)
+    return []
+
+
+def discover_neuroglancer_volume_pairs(
+    image_path: pathlib.Path,
+    label_path: Optional[pathlib.Path] = None,
+    *,
+    max_pairs: int = 50,
+) -> Dict[str, Any]:
+    image_candidates = _as_volume_candidates(image_path)
+    label_candidates = _as_volume_candidates(label_path)
+    label_by_key: Dict[str, List[pathlib.Path]] = {}
+    for candidate in label_candidates:
+        label_by_key.setdefault(_volume_pair_key(candidate), []).append(candidate)
+
+    pairs: List[Dict[str, Any]] = []
+    unpaired_images: List[str] = []
+    used_images: set[str] = set()
+    used_labels: set[str] = set()
+    for image_candidate in image_candidates:
+        key = _volume_pair_key(image_candidate)
+        label_candidate = None
+        if key in label_by_key and label_by_key[key]:
+            label_candidate = label_by_key[key].pop(0)
+            used_images.add(str(image_candidate))
+            used_labels.add(str(label_candidate))
+        if label_candidate:
+            pairs.append(
+                {
+                    "key": key,
+                    "image_path": str(image_candidate),
+                    "label_path": str(label_candidate),
+                    "image_name": image_candidate.name,
+                    "label_name": label_candidate.name,
+                }
+            )
+        else:
+            unpaired_images.append(str(image_candidate))
+        if len(pairs) >= max_pairs:
+            break
+
+    if not pairs and len(image_candidates) == 1 and len(label_candidates) == 1:
+        image_candidate = image_candidates[0]
+        label_candidate = label_candidates[0]
+        pairs.append(
+            {
+                "key": _volume_pair_key(image_candidate),
+                "image_path": str(image_candidate),
+                "label_path": str(label_candidate),
+                "image_name": image_candidate.name,
+                "label_name": label_candidate.name,
+                "match_basis": "single-image-single-label",
+            }
+        )
+        used_images.add(str(image_candidate))
+        used_labels.add(str(label_candidate))
+
+    unpaired_images = [image for image in unpaired_images if image not in used_images]
+    unpaired_labels = [
+        str(candidate)
+        for candidate in label_candidates
+        if str(candidate) not in used_labels
+    ]
+    return {
+        "requested_image_path": str(image_path),
+        "requested_label_path": str(label_path) if label_path else None,
+        "image_is_directory": image_path.is_dir()
+        and not _is_chunked_volume_directory(image_path),
+        "label_is_directory": bool(label_path)
+        and label_path.is_dir()
+        and not _is_chunked_volume_directory(label_path),
+        "image_candidate_count": len(image_candidates),
+        "label_candidate_count": len(label_candidates),
+        "pair_count": len(pairs),
+        "pairs": pairs,
+        "unpaired_images": unpaired_images[:10],
+        "unpaired_labels": unpaired_labels[:10],
+        "truncated": len(pairs) >= max_pairs,
+    }
+
+
+def _resolve_neuroglancer_image_path(
+    image_path: pathlib.Path,
+    label_path: Optional[pathlib.Path] = None,
+) -> Tuple[pathlib.Path, Optional[str]]:
+    if _is_chunked_volume_directory(image_path) or image_path.is_file():
+        return image_path, None
+    if not image_path.is_dir():
+        return image_path, None
+
+    discovery = discover_neuroglancer_volume_pairs(image_path, label_path)
+    if discovery["pairs"]:
+        selected = pathlib.Path(discovery["pairs"][0]["image_path"])
+        return (
+            selected,
+            f"Selected matching image volume {selected.name} from folder {image_path}.",
+        )
+
+    image_candidates = _volume_file_candidates(image_path)
+    if not image_candidates:
+        raise ValueError(f"No readable image volume files found in {image_path}")
+
+    return (
+        image_candidates[0],
+        f"Selected first readable image volume {image_candidates[0].name} from folder {image_path}.",
+    )
+
+
+def _resolve_neuroglancer_label_path(
+    label_path: Optional[pathlib.Path],
+    resolved_image_path: pathlib.Path,
+) -> Tuple[Optional[pathlib.Path], Optional[str]]:
+    if label_path is None:
+        return None, None
+    if _is_chunked_volume_directory(label_path) or label_path.is_file():
+        return label_path, None
+    if not label_path.is_dir():
+        return label_path, None
+
+    discovery = discover_neuroglancer_volume_pairs(resolved_image_path, label_path)
+    if discovery["pairs"]:
+        selected = pathlib.Path(discovery["pairs"][0]["label_path"])
+        return (
+            selected,
+            f"Selected matching label volume {selected.name} from folder {label_path}.",
+        )
+
+    label_candidates = _volume_file_candidates(label_path)
+    if not label_candidates:
+        raise ValueError(f"No readable label volume files found in {label_path}")
+
+    return (
+        label_candidates[0],
+        f"Selected first readable label volume {label_candidates[0].name} from folder {label_path}.",
+    )
diff --git a/server_pytc/main.py b/server_pytc/main.py
index dc5110a6..004432fa 100644
--- a/server_pytc/main.py
+++ b/server_pytc/main.py
@@ -1,11 +1,15 @@
+import logging
+import time
 import uvicorn
 from fastapi import FastAPI, HTTPException, Request
 from fastapi.middleware.cors import CORSMiddleware
+from app_event_logger import append_app_event, configure_process_logging
 from runtime_settings import get_allowed_origins
 from server_pytc.services.model import (
     get_inference_status,
     get_inference_logs,
     get_tensorboard,
+    get_tensorboard_status,
     initialize_tensorboard,
     get_training_logs as get_training_process_logs,
     get_training_status as get_training_process_status,
@@ -15,13 +19,8 @@
     stop_training,
 )
 
-print("\n" + "=" * 80)
-print("SERVER_PYTC STARTING UP")
-print(f"Python executable: {__import__('sys').executable}")
-print(f"Working directory: {__import__('os').getcwd()}")
-print("=" * 80 + "\n")
-
 app = FastAPI()
+logger = logging.getLogger(__name__)
 
 app.add_middleware(
     CORSMiddleware,
@@ -32,6 +31,58 @@
 )
 
 
+@app.on_event("startup")
+async def configure_app_event_logging():
+    log_path = configure_process_logging("server_pytc")
+    logger.info("App event logging enabled at %s", log_path)
+
+
+@app.middleware("http")
+async def log_http_requests(request: Request, call_next):
+    start_time = time.perf_counter()
+    path = request.url.path
+    method = request.method
+    client_host = request.client.host if request.client else None
+    append_app_event(
+        component="server_pytc",
+        event="http_request_started",
+        level="INFO",
+        message=f"{method} {path}",
+        method=method,
+        path=path,
+        client_host=client_host,
+    )
+    try:
+        response = await call_next(request)
+    except Exception as exc:
+        append_app_event(
+            component="server_pytc",
+            event="http_request_failed",
+            level="ERROR",
+            message=f"{method} {path} failed",
+            method=method,
+            path=path,
+            client_host=client_host,
+            latency_ms=round((time.perf_counter() - start_time) * 1000, 2),
+            error_type=exc.__class__.__name__,
+            error=str(exc),
+        )
+        raise
+
+    append_app_event(
+        component="server_pytc",
+        event="http_request_completed",
+        level="INFO",
+        message=f"{method} {path} -> {response.status_code}",
+        method=method,
+        path=path,
+        client_host=client_host,
+        status_code=response.status_code,
+        latency_ms=round((time.perf_counter() - start_time) * 1000, 2),
+    )
+    return response
+
+
 @app.get("/hello")
 def hello():
     return {"hello"}
@@ -41,6 +92,19 @@ def hello():
 async def start_model_training(req: Request):
     print("\n========== SERVER_PYTC: START_MODEL_TRAINING ENDPOINT CALLED ==========")
     req = await req.json()
+    append_app_event(
+        component="server_pytc",
+        event="training_request_received",
+        level="INFO",
+        message="Training request received by worker",
+        source="worker_endpoint",
+        payload_keys=sorted(req.keys()),
+        config_origin_path=req.get("configOriginPath"),
+        output_path=req.get("outputPath"),
+        log_path=req.get("logPath"),
+        training_config_length=len(req.get("trainingConfig") or ""),
+        workflow_id=req.get("workflow_id") or req.get("workflowId"),
+    )
     print(f"[SERVER_PYTC] Received request payload keys: {list(req.keys())}")
     print(f"[SERVER_PYTC] Arguments: {req.get('arguments', {})}")
     print(f"[SERVER_PYTC] Log path: {req.get('logPath', 'NOT PROVIDED')}")
@@ -83,13 +147,15 @@ async def training_logs():
 
 @app.get("/start_tensorboard")
 async def start_tensorboard(logPath: str | None = None):
-    if not logPath:
-        raise HTTPException(
-            status_code=400,
-            detail="Missing required query parameter: logPath",
-        )
-    initialize_tensorboard(logPath)
-    return {"status": "started", "url": get_tensorboard()}
+    try:
+        status = initialize_tensorboard(logPath)
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+    return {
+        "status": status["phase"],
+        "url": get_tensorboard(),
+        "tensorboard": status,
+    }
 
 
 @app.get("/get_tensorboard_url")
@@ -97,9 +163,28 @@ async def get_tensorboard_url():
     return get_tensorboard()
 
 
+@app.get("/get_tensorboard_status")
+async def tensorboard_status():
+    return get_tensorboard_status()
+
+
 @app.post("/start_model_inference")
 async def start_model_inference(req: Request):
     req = await req.json()
+    append_app_event(
+        component="server_pytc",
+        event="inference_request_received",
+        level="INFO",
+        message="Inference request received by worker",
+        source="worker_endpoint",
+        payload_keys=sorted(req.keys()),
+        config_origin_path=req.get("configOriginPath"),
+        output_path=req.get("outputPath"),
+        checkpoint_path=req.get("checkpointPath")
+        or (req.get("arguments") or {}).get("checkpoint"),
+        inference_config_length=len(req.get("inferenceConfig") or ""),
+        workflow_id=req.get("workflow_id") or req.get("workflowId"),
+    )
     print("start model inference")
     return start_inference(req)
 
@@ -121,6 +206,13 @@ async def inference_logs():
 
 
 def run():
+    log_path = configure_process_logging("server_pytc")
+    print("\n" + "=" * 80)
+    print("SERVER_PYTC STARTING UP")
+    print(f"Python executable: {__import__('sys').executable}")
+    print(f"Working directory: {__import__('os').getcwd()}")
+    print(f"App event log: {log_path}")
+    print("=" * 80 + "\n")
     print("\n" + "=" * 80)
     print("SERVER_PYTC: Starting Uvicorn server on port 4243...")
     print("=" * 80 + "\n")
diff --git a/server_pytc/services/model.py b/server_pytc/services/model.py
index 89180645..7edf2408 100644
--- a/server_pytc/services/model.py
+++ b/server_pytc/services/model.py
@@ -1,25 +1,38 @@
 import atexit
+import json
+import os
 import pathlib
+import socket
 import subprocess
 import sys
 import tempfile
 import threading
+import time
 from collections import deque
 from datetime import datetime, timezone
 from typing import Any
+from urllib import error as urllib_error, request as urllib_request
 
 import psutil
+from app_event_logger import append_app_event
 
 # Track spawned processes so we can stop/poll cleanly.
 _training_process = None
 _inference_process = None
+_tensorboard_process = None
 _temp_files = {
     "training": [],
     "inference": [],
 }
-tensorboard_url = None
 _RUNTIME_LOG_LIMIT = 2000
+_TENSORBOARD_LOG_LIMIT = 200
+_TENSORBOARD_HOST = "127.0.0.1"
+_TENSORBOARD_BIND_HOST = "0.0.0.0"
+_TENSORBOARD_PREFERRED_PORT = 6006
+_TENSORBOARD_START_TIMEOUT_SECONDS = 15.0
+_TENSORBOARD_POLL_INTERVAL_SECONDS = 0.25
 _runtime_lock = threading.Lock()
+_tensorboard_lock = threading.Lock()
 
 
 def _new_runtime_state():
@@ -47,6 +60,92 @@ def _new_runtime_state():
 }
 
 
+def _new_tensorboard_state():
+    return {
+        "phase": "idle",
+        "pid": None,
+        "port": None,
+        "url": None,
+        "command": None,
+        "logdirSpec": None,
+        "startedAt": None,
+        "endedAt": None,
+        "lastUpdatedAt": None,
+        "lastError": None,
+        "lineCount": 0,
+        "lines": deque(maxlen=_TENSORBOARD_LOG_LIMIT),
+    }
+
+
+_tensorboard_state = _new_tensorboard_state()
+_tensorboard_sources: dict[str, dict[str, str]] = {}
+_DIRECT_VOLUME_SUFFIXES = (
+    ".h5",
+    ".hdf5",
+    ".hdf",
+    ".tif",
+    ".tiff",
+    ".ome.tif",
+    ".ome.tiff",
+    ".zarr",
+    ".n5",
+    ".npy",
+    ".npz",
+    ".nii",
+    ".nii.gz",
+    ".mrc",
+    ".map",
+    ".rec",
+    ".png",
+    ".jpg",
+    ".jpeg",
+    ".bmp",
+)
+_PREDICTION_OUTPUT_SUFFIXES = (
+    ".h5",
+    ".hdf5",
+    ".hdf",
+    ".tif",
+    ".tiff",
+    ".ome.tif",
+    ".ome.tiff",
+    ".zarr",
+    ".n5",
+    ".npy",
+    ".npz",
+    ".nii",
+    ".nii.gz",
+    ".mrc",
+    ".map",
+    ".rec",
+)
+_DIRECT_VOLUME_CONFIG_PATHS = {
+    ("DATASET", "IMAGE_NAME"): "image",
+    ("DATASET", "LABEL_NAME"): "label",
+    ("DATASET", "VALID_MASK_NAME"): "label",
+    ("INFERENCE", "IMAGE_NAME"): "image",
+}
+_FRACTIONAL_FLOAT_CONFIG_PATHS = {
+    ("DATASET", "VALID_RATIO"),
+    ("DATASET", "REJECT_SAMPLING", "P"),
+    ("DATASET", "MEAN"),
+    ("DATASET", "STD"),
+    ("SOLVER", "BASE_LR"),
+    ("SOLVER", "WEIGHT_DECAY"),
+    ("SOLVER", "MOMENTUM"),
+    ("SOLVER", "WARMUP_FACTOR"),
+}
+_VALID_INFERENCE_AUG_NUMS = (4, 8, 16)
+_DEFAULT_MOUNTED_PROJECT_ROOTS = tuple(
+    pathlib.Path(path).expanduser()
+    for path in (
+        os.environ.get("PYTC_INITIAL_PROJECT_ROOT", ""),
+        "/home/weidf/demo_data/prepilot_lucchi_pp",
+    )
+    if path
+)
+
+
 def _project_root() -> pathlib.Path:
     return pathlib.Path(__file__).resolve().parent.parent.parent
 
@@ -55,6 +154,24 @@ def _utc_now() -> str:
     return datetime.now(timezone.utc).isoformat()
 
 
+def _level_for_log_text(text: str | None, *, default: str = "INFO") -> str:
+    normalized = (text or "").upper()
+    if any(
+        needle in normalized
+        for needle in (
+            "TRACEBACK",
+            "EXCEPTION",
+            "ERROR",
+            "FAILED",
+            "UNICODEDECODEERROR",
+        )
+    ):
+        return "ERROR"
+    if "WARN" in normalized:
+        return "WARNING"
+    return default
+
+
 def _get_runtime_process(kind: str):
     if kind == "training":
         return _training_process
@@ -73,7 +190,9 @@ def _clear_runtime_process(kind: str, process=None):
         _inference_process = None
 
 
-def _reset_runtime_state(kind: str, *, phase: str = "idle", metadata: dict | None = None):
+def _reset_runtime_state(
+    kind: str, *, phase: str = "idle", metadata: dict | None = None
+):
     state = _new_runtime_state()
     timestamp = _utc_now()
     state["phase"] = phase
@@ -95,24 +214,114 @@ def _update_runtime_state(kind: str, **updates):
         state["lastUpdatedAt"] = _utc_now()
 
 
-def _append_runtime_log(kind: str, line: str):
+def _merge_runtime_metadata(kind: str, **updates) -> dict[str, Any]:
+    clean_updates = {
+        key: value
+        for key, value in updates.items()
+        if value is not None and value != ""
+    }
+    with _runtime_lock:
+        state = _runtime_state[kind]
+        metadata = dict(state.get("metadata") or {})
+        metadata.update(clean_updates)
+        state["metadata"] = metadata
+        state["lastUpdatedAt"] = _utc_now()
+        return dict(metadata)
+
+
+def _runtime_event_fields(kind: str) -> dict[str, Any]:
+    with _runtime_lock:
+        state = _runtime_state[kind]
+        return {
+            "runtime_kind": kind,
+            "runtime_phase": state["phase"],
+            "runtime_pid": state["pid"],
+            "runtime_exit_code": state["exitCode"],
+            "runtime_config_path": state["configPath"],
+            "runtime_config_origin_path": state["configOriginPath"],
+        }
+
+
+def _emit_runtime_app_event(
+    kind: str,
+    event: str,
+    message: str,
+    *,
+    level: str | None = None,
+    **fields,
+):
+    append_app_event(
+        component="server_pytc",
+        event=event,
+        level=level or _level_for_log_text(message),
+        message=message,
+        **_runtime_event_fields(kind),
+        **fields,
+    )
+
+
+def _append_runtime_log(
+    kind: str,
+    line: str,
+    *,
+    event: str = "runtime_log_line",
+    level: str | None = None,
+    source: str = "runtime",
+    **fields,
+):
     timestamp = _utc_now()
     text = "" if line is None else str(line).rstrip("\n")
+    effective_level = level or _level_for_log_text(text)
     entry = f"[{timestamp}] {text}" if text else f"[{timestamp}]"
+    line_index = None
     with _runtime_lock:
         state = _runtime_state[kind]
         state["lines"].append(entry)
         state["lineCount"] += 1
         state["lastUpdatedAt"] = timestamp
+        if text and effective_level == "ERROR":
+            state["lastError"] = text
+        line_index = state["lineCount"]
+
+    if text:
+        _emit_runtime_app_event(
+            kind,
+            event,
+            text,
+            level=effective_level,
+            source=source,
+            runtime_line_index=line_index,
+            runtime_line_timestamp=timestamp,
+            **fields,
+        )
 
 
-def _append_runtime_event(kind: str, message: str):
-    _append_runtime_log(kind, f"[MODEL.PY] {message}")
+def _append_runtime_event(
+    kind: str,
+    message: str,
+    *,
+    event: str = "runtime_event",
+    level: str = "INFO",
+    **fields,
+):
+    _append_runtime_log(
+        kind,
+        f"[MODEL.PY] {message}",
+        event=event,
+        level=level,
+        source="model",
+        **fields,
+    )
 
 
 def _set_runtime_error(kind: str, message: str):
     _update_runtime_state(kind, lastError=message)
-    _append_runtime_event(kind, f"ERROR: {message}")
+    _append_runtime_event(
+        kind,
+        f"ERROR: {message}",
+        event="runtime_error",
+        level="ERROR",
+    )
 
 
 def _get_runtime_snapshot(kind: str) -> dict[str, Any]:
@@ -151,6 +360,1010 @@ def _get_runtime_snapshot(kind: str) -> dict[str, Any]:
             "lines": lines,
             "text": "\n".join(lines),
         }
+    if kind == "training" and not snapshot["isRunning"]:
+        metadata = snapshot.get("metadata") or {}
+        if not metadata.get("checkpointPath"):
+            latest_checkpoint = _find_latest_checkpoint(metadata.get("outputPath"))
+            if latest_checkpoint:
+                metadata = _merge_runtime_metadata(
+                    kind,
+                    checkpointPath=latest_checkpoint,
+                    latestCheckpointPath=latest_checkpoint,
+                    latestCheckpointName=pathlib.Path(latest_checkpoint).name,
+                )
+                snapshot["metadata"] = metadata
+    if kind == "inference" and not snapshot["isRunning"]:
+        metadata = snapshot.get("metadata") or {}
+        if not (metadata.get("predictionPath") or metadata.get("latestPredictionPath")):
+            latest_prediction = _find_latest_prediction_output(
+                metadata.get("outputPath")
+            )
+            if latest_prediction:
+                metadata = _merge_runtime_metadata(
+                    kind,
+                    predictionPath=latest_prediction,
+                    latestPredictionPath=latest_prediction,
+                    latestPredictionName=pathlib.Path(latest_prediction).name,
+                )
+                snapshot["metadata"] = metadata
+    return snapshot
+
+
+def _tensorboard_sources_payload() -> dict[str, dict[str, str | bool]]:
+    payload: dict[str, dict[str, str | bool]] = {}
+    for name, source in _tensorboard_sources.items():
+        path = pathlib.Path(source["path"])
+        payload[name] = {
+            "name": source["name"],
+            "path": str(path),
+            "exists": path.exists(),
+            "registeredAt": source["registeredAt"],
+        }
+    return payload
+
+
+def _update_tensorboard_state(**updates):
+    with _tensorboard_lock:
+        for key, value in updates.items():
+            if key == "lines":
+                _tensorboard_state["lines"] = deque(
+                    value,
+                    maxlen=_TENSORBOARD_LOG_LIMIT,
+                )
+            else:
+                _tensorboard_state[key] = value
+        _tensorboard_state["lastUpdatedAt"] = _utc_now()
+
+
+def _append_tensorboard_log(line: str):
+    timestamp = _utc_now()
+    text = "" if line is None else str(line).rstrip("\n")
+    entry = f"[{timestamp}] {text}" if text else f"[{timestamp}]"
+    line_index = None
+    phase = None
+    pid = None
+    port = None
+    url = None
+    with _tensorboard_lock:
+        _tensorboard_state["lines"].append(entry)
+        _tensorboard_state["lineCount"] += 1
+        _tensorboard_state["lastUpdatedAt"] = timestamp
+        line_index = _tensorboard_state["lineCount"]
+        phase = _tensorboard_state["phase"]
+        pid = _tensorboard_state["pid"]
+        port = _tensorboard_state["port"]
+        url = _tensorboard_state["url"]
+
+    if text:
+        append_app_event(
+            component="server_pytc",
+            event="tensorboard_log_line",
+            level=_level_for_log_text(text),
+            message=text,
+            source="tensorboard",
+            tensorboard_phase=phase,
+            tensorboard_pid=pid,
+            tensorboard_port=port,
+            tensorboard_url=url,
+            tensorboard_line_index=line_index,
+            tensorboard_line_timestamp=timestamp,
+        )
+
+
+def _set_tensorboard_error(message: str):
+    _update_tensorboard_state(lastError=message)
+    _append_tensorboard_log(f"[TENSORBOARD] ERROR: {message}")
+
+
+def _load_yaml_config(config_text: str) -> dict[str, Any]:
+    yaml = _load_yaml_module()
+    if yaml is None:
+        return {}
+
+    try:
+        config_obj = yaml.safe_load(config_text) or {}
+    except Exception:
+        return {}
+
+    return config_obj if isinstance(config_obj, dict) else {}
+
+
+def _load_yaml_module():
+    try:
+        import yaml  # type: ignore
+    except Exception:
+        return None
+    return yaml
+
+
+def _load_yaml_config_from_path(path_value: pathlib.Path | None) -> dict[str, Any]:
+    if path_value is None or not path_value.exists():
+        return {}
+    try:
+        return _load_yaml_config(path_value.read_text(encoding="utf-8"))
+    except Exception:
+        return {}
+
+
+def _get_nested_value(data: dict[str, Any], path: tuple[str, ...]) -> Any:
+    cursor: Any = data
+    for key in path:
+        if not isinstance(cursor, dict) or key not in cursor:
+            return None
+        cursor = cursor[key]
+    return cursor
+
+
+def _set_nested_value(data: dict[str, Any], path: tuple[str, ...], value: Any) -> bool:
+    if not path:
+        return False
+    cursor: Any = data
+    for key in path[:-1]:
+        if not isinstance(cursor, dict):
+            return False
+        if key not in cursor or not isinstance(cursor[key], dict):
+            cursor[key] = {}
+        cursor = cursor[key]
+    if not isinstance(cursor, dict):
+        return False
+    cursor[path[-1]] = value
+    return True
+
+
+def _path_label(path: tuple[str, ...]) -> str:
+    return ".".join(path)
+
+
+def _config_path_exists(path_value: Any) -> bool:
+    if not isinstance(path_value, str) or not path_value.strip():
+        return False
+    try:
+        return pathlib.Path(path_value).expanduser().exists()
+    except Exception:
+        return False
+
+
+def _resolve_runtime_data_path(path_value: Any) -> str:
+    if not isinstance(path_value, str) or not path_value.strip():
+        return ""
+
+    raw_value = path_value.strip()
+    candidate = pathlib.Path(raw_value).expanduser()
+    if candidate.is_absolute():
+        return str(candidate.resolve())
+
+    project_candidate = (_project_root() / candidate).resolve()
+    if project_candidate.exists():
+        return str(project_candidate)
+
+    parts = candidate.parts
+    for root in _DEFAULT_MOUNTED_PROJECT_ROOTS:
+        if not parts:
+            continue
+        root = root.resolve()
+        if parts[0] == root.name:
+            return str((root.joinpath(*parts[1:])).resolve())
+        direct = root.joinpath(*parts).resolve()
+        if direct.exists() or parts[0] in {"data", "outputs", "configs", "checkpoints"}:
+            return str(direct)
+
+    return raw_value
+
+
+def _resolve_runtime_data_value(raw_value: Any) -> Any:
+    if isinstance(raw_value, str):
+        return _resolve_runtime_data_path(raw_value)
+    if isinstance(raw_value, list):
+        return [
+            _resolve_runtime_data_path(item) if isinstance(item, str) else item
+            for item in raw_value
+        ]
+    return raw_value
+
+
+def _direct_volume_files_in_directory(directory: pathlib.Path) -> list[str]:
+    files: list[pathlib.Path] = []
+    for child in directory.iterdir():
+        if not (child.is_file() or child.is_symlink()):
+            continue
+        lower_name = child.name.lower()
+        if lower_name.endswith(_DIRECT_VOLUME_SUFFIXES):
+            files.append(child)
+    return [str(path.resolve()) for path in sorted(files, key=lambda item: item.name)]
+
+
+def _load_runtime_training_subset_pairs(
+    image_dir: pathlib.Path,
+    label_dir: pathlib.Path,
+) -> tuple[list[str], list[str]]:
+    seen_parents: list[pathlib.Path] = []
+    for parent in (image_dir.parent, label_dir.parent):
+        if parent not in seen_parents:
+            seen_parents.append(parent)
+
+    for parent in seen_parents:
+        manifest_path = parent / "volume_subset_manifest.json"
+        if not manifest_path.exists():
+            continue
+        try:
+            manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+        except Exception:
+            continue
+
+        image_paths: list[str] = []
+        label_paths: list[str] = []
+        for pair in manifest.get("train_pairs") or []:
+            if not isinstance(pair, dict):
+                continue
+            image_path = pair.get("subset_image_path") or pair.get("image_path")
+            label_path = (
+                pair.get("subset_segmentation_path")
+                or pair.get("subset_label_path")
+                or pair.get("segmentation_path")
+                or pair.get("label_path")
+            )
+            if not image_path or not label_path:
+                continue
+            resolved_image = pathlib.Path(str(image_path)).expanduser().resolve()
+            resolved_label = pathlib.Path(str(label_path)).expanduser().resolve()
+            if not resolved_image.exists() or not resolved_label.exists():
+                continue
+            image_paths.append(str(resolved_image))
+            label_paths.append(str(resolved_label))
+
+        if image_paths and len(image_paths) == len(label_paths):
+            return image_paths, label_paths
+
+    return [], []
+
+
+def _resolve_runtime_training_inputs(
+    input_image_path: Any,
+    input_label_path: Any,
+) -> tuple[Any, Any, str]:
+    if not isinstance(input_image_path, str) or not isinstance(input_label_path, str):
+        return input_image_path, input_label_path, "runtime_request_training_paths"
+
+    image_path = pathlib.Path(_resolve_runtime_data_path(input_image_path)).expanduser()
+    label_path = pathlib.Path(_resolve_runtime_data_path(input_label_path)).expanduser()
+    image_is_dir = image_path.is_dir()
+    label_is_dir = label_path.is_dir()
+    if not image_is_dir and not label_is_dir:
+        return input_image_path, input_label_path, "runtime_request_training_paths"
+    if image_is_dir != label_is_dir:
+        raise ValueError(
+            "Training image and label inputs must both be files or both be paired "
+            f"directories; got image={image_path} label={label_path}."
+        )
+
+    manifest_images, manifest_labels = _load_runtime_training_subset_pairs(
+        image_path,
+        label_path,
+    )
+    if manifest_images:
+        return (
+            manifest_images,
+            manifest_labels,
+            "runtime_request_training_subset_manifest",
+        )
+
+    image_files = _direct_volume_files_in_directory(image_path)
+    label_files = _direct_volume_files_in_directory(label_path)
+    if not image_files or not label_files:
+        raise FileNotFoundError(
+            "Training subset directories must contain direct volume files; "
+            f"got image={image_path} label={label_path}."
+        )
+    if len(image_files) != len(label_files):
+        raise ValueError(
+            "Training subset directories must contain the same number of image and "
+            f"label volumes; got {len(image_files)} image(s) and {len(label_files)} label(s)."
+        )
+    return image_files, label_files, "runtime_request_training_subset_directory"
+
+
+def _apply_runtime_path_overrides(
+    config_text: str,
+    payload: dict[str, Any],
+    *,
+    kind: str,
+) -> tuple[str, list[dict[str, Any]]]:
+    yaml = _load_yaml_module()
+    if yaml is None:
+        return config_text, []
+
+    config_obj = _load_yaml_config(config_text)
+    if not config_obj:
+        return config_text, []
+
+    changes: list[dict[str, Any]] = []
+
+    def apply(
+        path: tuple[str, ...],
+        raw_value: Any,
+        reason: str,
+        *,
+        allow_empty: bool = False,
+    ):
+        if not isinstance(raw_value, (str, list)):
+            return
+        if isinstance(raw_value, str) and not raw_value.strip() and not allow_empty:
+            return
+        if isinstance(raw_value, list) and not raw_value and not allow_empty:
+            return
+        value = (
+            ""
+            if isinstance(raw_value, str) and allow_empty and not raw_value.strip()
+            else _resolve_runtime_data_value(raw_value)
+        )
+        old_value = _get_nested_value(config_obj, path)
+        if old_value == value:
+            return
+        _set_nested_value(config_obj, path, value)
+        changes.append(
+            {
+                "path": _path_label(path),
+                "old_value": old_value,
+                "new_value": value,
+                "reason": reason,
+            }
+        )
+
+    input_image_path = payload.get("inputImagePath") or payload.get("input_image_path")
+    output_path = payload.get("outputPath") or payload.get("output_path")
+
+    if kind == "training":
+        input_label_path = payload.get("inputLabelPath") or payload.get(
+            "input_label_path"
+        )
+        input_image_path, input_label_path, training_path_reason = (
+            _resolve_runtime_training_inputs(input_image_path, input_label_path)
+        )
+        apply(
+            ("DATASET", "INPUT_PATH"), "", "clear_runtime_input_base", allow_empty=True
+        )
+        apply(("DATASET", "IMAGE_NAME"), input_image_path, training_path_reason)
+        apply(("DATASET", "LABEL_NAME"), input_label_path, training_path_reason)
+        apply(("DATASET", "OUTPUT_PATH"), output_path, "runtime_request_output_path")
+    else:
+        apply(
+            ("DATASET", "INPUT_PATH"), "", "clear_runtime_input_base", allow_empty=True
+        )
+        apply(("DATASET", "IMAGE_NAME"), input_image_path, "runtime_request_image_path")
+        apply(
+            ("INFERENCE", "INPUT_PATH"),
+            "",
+            "clear_runtime_input_base",
+            allow_empty=True,
+        )
+        apply(
+            ("INFERENCE", "IMAGE_NAME"), input_image_path, "runtime_request_image_path"
+        )
+        apply(("INFERENCE", "OUTPUT_PATH"), output_path, "runtime_request_output_path")
+
+    if not changes:
+        return config_text, []
+
+    return (
+        yaml.safe_dump(config_obj, sort_keys=False, allow_unicode=False),
+        changes,
+    )
+
+
+def _runtime_path_exists(path_value: Any) -> bool:
+    if not isinstance(path_value, str) or not path_value.strip():
+        return False
+    try:
+        return (
+            pathlib.Path(_resolve_runtime_data_path(path_value)).expanduser().exists()
+        )
+    except Exception:
+        return False
+
+
+def _runtime_volume_input_exists(path_value: Any) -> bool:
+    if isinstance(path_value, list):
+        return bool(path_value) and all(
+            _runtime_volume_input_exists(item) for item in path_value
+        )
+    if not isinstance(path_value, str) or not path_value.strip():
+        return False
+    try:
+        resolved = pathlib.Path(_resolve_runtime_data_path(path_value)).expanduser()
+    except Exception:
+        return False
+    if not resolved.exists():
+        return False
+    lower_name = resolved.name.lower()
+    if resolved.is_dir():
+        return lower_name.endswith((".zarr", ".n5"))
+    return True
+
+
+def _runtime_path_display(path_value: Any) -> str:
+    if isinstance(path_value, list):
+        preview = ", ".join(str(item) for item in path_value[:3])
+        if len(path_value) > 3:
+            preview += f", ... ({len(path_value)} total)"
+        return preview or "<empty list>"
+    return str(path_value or "<empty>")
+
+
+def _validate_runtime_launch_inputs(
+    config_text: str,
+    *,
+    kind: str,
+    arguments: dict[str, Any] | None = None,
+) -> None:
+    config_obj = _load_yaml_config(config_text)
+    if kind == "training":
+        required = [
+            (
+                "training image",
+                _get_nested_value(config_obj, ("DATASET", "IMAGE_NAME")),
+            ),
+            (
+                "training label",
+                _get_nested_value(config_obj, ("DATASET", "LABEL_NAME")),
+            ),
+        ]
+    else:
+        required = [
+            (
+                "inference image",
+                _get_nested_value(config_obj, ("INFERENCE", "IMAGE_NAME")),
+            ),
+            ("checkpoint", (arguments or {}).get("checkpoint")),
+        ]
+
+    missing = [
+        f"{label}: {_runtime_path_display(path_value)}"
+        for label, path_value in required
+        if not (
+            _runtime_volume_input_exists(path_value)
+            if label in {"training image", "training label", "inference image"}
+            else _runtime_path_exists(path_value)
+        )
+    ]
+    if missing:
+        raise FileNotFoundError(
+            "Cannot start "
+            f"{kind}; required path(s) do not exist: " + "; ".join(missing)
+        )
+
+
+def _resolve_missing_direct_volume_path(path_value: Any, role: str) -> str | None:
+    if not isinstance(path_value, str) or not path_value.strip():
+        return None
+
+    candidate = pathlib.Path(path_value).expanduser()
+    if candidate.exists():
+        return str(candidate.resolve())
+
+    suffix = candidate.suffix.lower()
+    if suffix not in _DIRECT_VOLUME_SUFFIXES:
+        return None
+
+    parent = candidate.parent
+    stem = candidate.stem
+    if not parent.exists():
+        return None
+
+    role_suffixes = (
+        ("_im", "_img", "_image")
+        if role == "image"
+        else ("_seg", "_mask", "_label", "_gt", "_consensus")
+    )
+
+    for extra in role_suffixes:
+        maybe = parent / f"{stem}{extra}{suffix}"
+        if maybe.exists():
+            return str(maybe.resolve())
+
+    matches = sorted(parent.glob(f"{stem}_*{suffix}"))
+    if not matches:
+        return None
+
+    preferred = []
+    for extra in role_suffixes:
+        preferred.extend([match for match in matches if match.stem.endswith(extra)])
+    unique_preferred = list(dict.fromkeys(preferred))
+    if len(unique_preferred) == 1:
+        return str(unique_preferred[0].resolve())
+    if len(matches) == 1:
+        return str(matches[0].resolve())
+    return None
+
+
+def _sanitize_fractional_float_paths(
+    config_obj: dict[str, Any],
+    origin_obj: dict[str, Any],
+) -> list[dict[str, Any]]:
+    changes: list[dict[str, Any]] = []
+    if not origin_obj:
+        return changes
+
+    for path in _FRACTIONAL_FLOAT_CONFIG_PATHS:
+        current_value = _get_nested_value(config_obj, path)
+        origin_value = _get_nested_value(origin_obj, path)
+        if not isinstance(origin_value, float) or isinstance(current_value, bool):
+            continue
+        if not isinstance(current_value, int):
+            continue
+        if float(origin_value).is_integer():
+            continue
+        if float(current_value) == float(origin_value):
+            continue
+        _set_nested_value(config_obj, path, float(origin_value))
+        changes.append(
+            {
+                "path": _path_label(path),
+                "old_value": current_value,
+                "new_value": float(origin_value),
+                "reason": "restored_fractional_origin_value",
+            }
+        )
+
+    return changes
+
+
+def _sanitize_direct_volume_paths(
+    config_obj: dict[str, Any],
+    origin_obj: dict[str, Any],
+) -> list[dict[str, Any]]:
+    changes: list[dict[str, Any]] = []
+
+    for path, role in _DIRECT_VOLUME_CONFIG_PATHS.items():
+        current_value = _get_nested_value(config_obj, path)
+        if not isinstance(current_value, str) or not current_value.strip():
+            continue
+        if _config_path_exists(current_value):
+            continue
+
+        origin_value = _get_nested_value(origin_obj, path)
+        replacement = None
+        reason = None
+        if (
+            isinstance(origin_value, str)
+            and origin_value.strip()
+            and _config_path_exists(origin_value)
+        ):
+            replacement = origin_value
+            reason = "restored_existing_origin_path"
+        else:
+            resolved = _resolve_missing_direct_volume_path(current_value, role)
+            if resolved:
+                replacement = resolved
+                reason = "resolved_missing_direct_volume_path"
+
+        if replacement and replacement != current_value:
+            _set_nested_value(config_obj, path, replacement)
+            changes.append(
+                {
+                    "path": _path_label(path),
+                    "old_value": current_value,
+                    "new_value": replacement,
+                    "reason": reason,
+                }
+            )
+
+    return changes
+
+
+def _sanitize_inference_aug_num(
+    config_obj: dict[str, Any],
+    origin_obj: dict[str, Any],
+) -> list[dict[str, Any]]:
+    path = ("INFERENCE", "AUG_NUM")
+    current_value = _get_nested_value(config_obj, path)
+    if not isinstance(current_value, int) or current_value in _VALID_INFERENCE_AUG_NUMS:
+        return []
+
+    origin_value = _get_nested_value(origin_obj, path)
+    if isinstance(origin_value, int) and origin_value in _VALID_INFERENCE_AUG_NUMS:
+        replacement = origin_value
+        reason = "restored_valid_origin_aug_num"
+    else:
+        replacement = min(
+            _VALID_INFERENCE_AUG_NUMS,
+            key=lambda option: abs(option - current_value),
+        )
+        reason = "coerced_to_supported_aug_num"
+
+    _set_nested_value(config_obj, path, replacement)
+    return [
+        {
+            "path": _path_label(path),
+            "old_value": current_value,
+            "new_value": replacement,
+            "reason": reason,
+        }
+    ]
+
+
+def _sanitize_runtime_config_text(
+    config_text: str,
+    config_origin_path: str | None,
+    auto_parameters: bool = False,
+) -> tuple[str, list[dict[str, Any]]]:
+    yaml = _load_yaml_module()
+    if yaml is None:
+        return config_text, []
+
+    config_obj = _load_yaml_config(config_text)
+    if not config_obj:
+        return config_text, []
+
+    origin_obj = _load_yaml_config_from_path(
+        _resolve_config_origin_path(config_origin_path)
+    )
+    changes: list[dict[str, Any]] = []
+    changes.extend(_sanitize_fractional_float_paths(config_obj, origin_obj))
+    changes.extend(_sanitize_direct_volume_paths(config_obj, origin_obj))
+    changes.extend(_sanitize_inference_aug_num(config_obj, origin_obj))
+    if auto_parameters:
+        changes.extend(_apply_training_safe_defaults(config_obj))
+
+    if not changes:
+        return config_text, []
+
+    sanitized_text = yaml.safe_dump(
+        config_obj,
+        sort_keys=False,
+        allow_unicode=False,
+    )
+    return sanitized_text, changes
+
+
+def _set_training_default(
+    config_obj: dict[str, Any],
+    path: tuple[str, ...],
+    value: Any,
+) -> dict[str, Any] | None:
+    current_value = _get_nested_value(config_obj, path)
+    if current_value == value:
+        return None
+    _set_nested_value(config_obj, path, value)
+    return {
+        "path": _path_label(path),
+        "old_value": current_value,
+        "new_value": value,
+        "reason": "agent_safe_training_default",
+    }
+
+
+def _apply_training_safe_defaults(config_obj: dict[str, Any]) -> list[dict[str, Any]]:
+    defaults: list[tuple[tuple[str, ...], Any]] = [
+        (("SOLVER", "SAMPLES_PER_BATCH"), 1),
+        (("SOLVER", "ITERATION_SAVE"), 80),
+        (("SOLVER", "ITERATION_TOTAL"), 80),
+        (("SOLVER", "ITERATION_VAL"), 80),
+        (("SOLVER", "WARMUP_ITERS"), 10),
+        (("SYSTEM", "NUM_CPUS"), 2),
+        (("SYSTEM", "NUM_GPUS"), 1),
+        (("MODEL", "INPUT_SIZE"), [65, 65, 65]),
+        (("MODEL", "OUTPUT_SIZE"), [65, 65, 65]),
+        (("MODEL", "FILTERS"), [8, 12, 16, 24, 32]),
+        (("DATASET", "PAD_SIZE"), [4, 16, 16]),
+        (("INFERENCE", "INPUT_SIZE"), [65, 65, 65]),
+        (("INFERENCE", "OUTPUT_SIZE"), [65, 65, 65]),
+        (("INFERENCE", "STRIDE"), [32, 32, 32]),
+        (("INFERENCE", "SAMPLES_PER_BATCH"), 1),
+        (("INFERENCE", "PAD_SIZE"), [4, 16, 16]),
+    ]
+    changes: list[dict[str, Any]] = []
+    for path, value in defaults:
+        change = _set_training_default(config_obj, path, value)
+        if change:
+            changes.append(change)
+    return changes
+
+
+def _training_uses_gpu(config_text: str) -> bool:
+    config_obj = _load_yaml_config(config_text)
+    gpu_count = _get_nested_value(config_obj, ("SYSTEM", "NUM_GPUS"))
+    try:
+        return int(gpu_count) > 0
+    except (TypeError, ValueError):
+        return False
+
+
+def _env_flag_enabled(name: str, default: bool = True) -> bool:
+    raw_value = os.environ.get(name)
+    if raw_value is None:
+        return default
+    return str(raw_value).strip().lower() not in {"0", "false", "no", "off"}
+
+
+def _ollama_models_to_unload() -> list[str]:
+    seen: set[str] = set()
+    models: list[str] = []
+    for env_name in ("PYTC_HELPER_OLLAMA_MODEL", "OLLAMA_HELPER_MODEL", "OLLAMA_MODEL"):
+        value = os.environ.get(env_name, "")
+        for item in str(value).replace(",", " ").split():
+            model = item.strip()
+            if model and model not in seen:
+                seen.add(model)
+                models.append(model)
+    return models
+
+
+def _unload_ollama_before_gpu_training(kind: str = "training") -> list[str]:
+    if not _env_flag_enabled("PYTC_UNLOAD_OLLAMA_BEFORE_TRAINING", False):
+        _append_runtime_event(
+            kind,
+            "Keeping Ollama models loaded during GPU training.",
+            event="runtime_gpu_memory_preflight",
+            level="INFO",
+            policy="keep_loaded",
+        )
+        return []
+
+    unloaded: list[str] = []
+    for model_name in _ollama_models_to_unload():
+        try:
+            result = subprocess.run(
+                ["ollama", "stop", model_name],
+                stdout=subprocess.PIPE,
+                stderr=subprocess.STDOUT,
+                text=True,
+                timeout=15,
+                check=False,
+            )
+            unloaded.append(model_name)
+            _append_runtime_event(
+                kind,
+                f"Requested Ollama model unload before GPU training: {model_name}",
+                event="runtime_gpu_memory_preflight",
+                level="INFO",
+                exit_code=result.returncode,
+                output=(result.stdout or "").strip()[-1000:],
+            )
+        except Exception as exc:
+            _append_runtime_event(
+                kind,
+                f"Could not unload Ollama model before GPU training: {model_name}: {exc}",
+                event="runtime_gpu_memory_preflight",
+                level="WARNING",
+            )
+    return unloaded
+
+
+def _looks_like_direct_volume(path_value: Any) -> bool:
+    text = str(path_value or "").strip().lower()
+    return bool(text) and text.endswith(_DIRECT_VOLUME_SUFFIXES)
+
+
+def _detect_chunk_tile_mismatch(config_text: str) -> dict[str, Any] | None:
+    config_obj = _load_yaml_config(config_text)
+    dataset = config_obj.get("DATASET") or {}
+    if not isinstance(dataset, dict):
+        return None
+
+    do_chunk_title = dataset.get("DO_CHUNK_TITLE")
+    if do_chunk_title in (None, False, 0, "0", "false", "False"):
+        return None
+
+    image_name = dataset.get("IMAGE_NAME")
+    label_name = dataset.get("LABEL_NAME")
+    if not any(_looks_like_direct_volume(value) for value in (image_name, label_name)):
+        return None
+
+    return {
+        "code": "tile_dataset_direct_volume_mismatch",
+        "message": (
+            "DATASET.DO_CHUNK_TITLE is enabled, so PyTC will use TileDataset and expect "
+            "JSON tile manifests, but IMAGE_NAME/LABEL_NAME point to direct volume files. "
+            "That leads to json.load(...) on the H5/TIFF path and crashes with a decode error."
+        ),
+        "do_chunk_title": do_chunk_title,
+        "image_name": image_name,
+        "label_name": label_name,
+    }
+
+
+def _resolve_tensorboard_log_dir(path_value: str | None) -> pathlib.Path | None:
+    if not path_value or not str(path_value).strip():
+        return None
+
+    candidate = pathlib.Path(str(path_value).strip()).expanduser()
+    if not candidate.is_absolute():
+        candidate = (_project_root() / candidate).resolve()
+    else:
+        candidate = candidate.resolve()
+
+    candidate.mkdir(parents=True, exist_ok=True)
+    return candidate
+
+
+def _register_tensorboard_source(source_key: str, log_dir: str) -> str:
+    resolved = _resolve_tensorboard_log_dir(log_dir)
+    if resolved is None:
+        raise ValueError("TensorBoard log directory is required")
+
+    _tensorboard_sources[source_key] = {
+        "name": source_key,
+        "path": str(resolved),
+        "registeredAt": _utc_now(),
+    }
+    _append_tensorboard_log(f"[TENSORBOARD] Watching {source_key} logs at {resolved}")
+    append_app_event(
+        component="server_pytc",
+        event="tensorboard_source_registered",
+        level="INFO",
+        message=f"Registered TensorBoard source {source_key}",
+        source="tensorboard",
+        tensorboard_source_key=source_key,
+        tensorboard_source_path=str(resolved),
+    )
+    return str(resolved)
+
+
+def _build_tensorboard_logdir_spec() -> str | None:
+    parts: list[str] = []
+    for source_key in sorted(_tensorboard_sources):
+        source = _tensorboard_sources[source_key]
+        parts.append(f"{source['name']}:{source['path']}")
+    return ",".join(parts) if parts else None
+
+
+def _is_port_available(port: int) -> bool:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+        sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        try:
+            sock.bind((_TENSORBOARD_HOST, port))
+        except OSError:
+            return False
+    return True
+
+
+def _pick_tensorboard_port(preferred: int | None = None) -> int:
+    candidate_ports = []
+    if preferred:
+        candidate_ports.append(int(preferred))
+    if _TENSORBOARD_PREFERRED_PORT not in candidate_ports:
+        candidate_ports.append(_TENSORBOARD_PREFERRED_PORT)
+
+    for port in candidate_ports:
+        if _is_port_available(port):
+            return port
+
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+        sock.bind((_TENSORBOARD_HOST, 0))
+        return int(sock.getsockname()[1])
+
+
+def _tensorboard_url_for_port(port: int | None) -> str | None:
+    if not port:
+        return None
+    return f"http://{_TENSORBOARD_HOST}:{int(port)}/"
+
+
+def _wait_for_tensorboard_ready(port: int, process: subprocess.Popen) -> bool:
+    url = _tensorboard_url_for_port(port)
+    deadline = time.monotonic() + _TENSORBOARD_START_TIMEOUT_SECONDS
+
+    while time.monotonic() < deadline:
+        if process.poll() is not None:
+            return False
+
+        try:
+            with urllib_request.urlopen(url, timeout=1) as response:
+                if response.status < 500:
+                    return True
+        except urllib_error.URLError:
+            pass
+        except Exception:
+            pass
+
+        time.sleep(_TENSORBOARD_POLL_INTERVAL_SECONDS)
+
+    return False
+
+
+def _terminate_managed_tensorboard():
+    global _tensorboard_process
+
+    process = _tensorboard_process
+    if process is None:
+        return
+
+    try:
+        if process.poll() is None:
+            process.terminate()
+            process.wait(timeout=10)
+    except subprocess.TimeoutExpired:
+        process.kill()
+        process.wait()
+    except Exception as exc:
+        _append_tensorboard_log(
+            f"[TENSORBOARD] Error terminating existing process: {exc}"
+        )
+    finally:
+        if _tensorboard_process is process:
+            _tensorboard_process = None
+
+
+def _watch_tensorboard_process(process: subprocess.Popen):
+    global _tensorboard_process
+
+    try:
+        if process.stdout is not None:
+            for line in process.stdout:
+                _append_tensorboard_log(line.rstrip())
+        process.wait()
+    except Exception as exc:
+        _append_tensorboard_log(
+            f"[TENSORBOARD] Error reading TensorBoard output: {exc}"
+        )
+        return
+
+    exit_code = process.returncode
+    with _tensorboard_lock:
+        current_pid = _tensorboard_state["pid"]
+        is_current = _tensorboard_process is process
+        if is_current:
+            _tensorboard_process = None
+
+    if current_pid != process.pid and not is_current:
+        return
+
+    updates = {
+        "phase": "finished" if exit_code == 0 else "failed",
+        "pid": None,
+        "endedAt": _utc_now(),
+    }
+    if exit_code not in (None, 0):
+        updates["lastError"] = f"TensorBoard exited with code {exit_code}"
+    _update_tensorboard_state(**updates)
+    append_app_event(
+        component="server_pytc",
+        event="tensorboard_process_finished",
+        level="INFO" if exit_code == 0 else "ERROR",
+        message="TensorBoard process exited",
+        source="tensorboard",
+        tensorboard_exit_code=exit_code,
+        tensorboard_pid=process.pid,
+    )
+
+
+def _get_tensorboard_snapshot() -> dict[str, Any]:
+    process = _tensorboard_process
+    is_running = bool(process and process.poll() is None)
+    with _tensorboard_lock:
+        phase = _tensorboard_state["phase"]
+        pid = _tensorboard_state["pid"]
+        ended_at = _tensorboard_state["endedAt"]
+        last_error = _tensorboard_state["lastError"]
+        lines = list(_tensorboard_state["lines"])
+        line_count = _tensorboard_state["lineCount"]
+        port = _tensorboard_state["port"]
+
+        if not is_running and phase in {"starting", "running"} and process is not None:
+            exit_code = process.returncode
+            phase = "finished" if exit_code == 0 else "failed"
+            pid = None
+            ended_at = ended_at or _utc_now()
+            if exit_code not in (None, 0) and not last_error:
+                last_error = f"TensorBoard exited with code {exit_code}"
+
+        snapshot = {
+            "isRunning": is_running,
+            "phase": phase,
+            "pid": process.pid if is_running else pid,
+            "port": port,
+            "url": _tensorboard_state["url"] or _tensorboard_url_for_port(port),
+            "command": _tensorboard_state["command"],
+            "logdirSpec": _tensorboard_state["logdirSpec"],
+            "startedAt": _tensorboard_state["startedAt"],
+            "endedAt": ended_at,
+            "lastUpdatedAt": _tensorboard_state["lastUpdatedAt"],
+            "lastError": last_error,
+            "lineCount": line_count,
+            "lines": lines,
+            "text": "\n".join(lines),
+            "sources": _tensorboard_sources_payload(),
+        }
     return snapshot
 
 
@@ -238,7 +1451,13 @@ def _build_cli_arguments(
     return cli_args
 
 
-def _start_logged_process(command: list[str], cwd: pathlib.Path, label: str, kind: str):
+def _start_logged_process(
+    command: list[str],
+    cwd: pathlib.Path,
+    label: str,
+    kind: str,
+    env: dict[str, str] | None = None,
+):
     process = subprocess.Popen(
         command,
         stdout=subprocess.PIPE,
@@ -246,6 +1465,7 @@ def _start_logged_process(command: list[str], cwd: pathlib.Path, label: str, kin
         text=True,
         bufsize=1,
         cwd=str(cwd),
+        env=env,
     )
     _update_runtime_state(
         kind,
@@ -258,16 +1478,71 @@ def _start_logged_process(command: list[str], cwd: pathlib.Path, label: str, kin
         lastError=None,
     )
     _append_runtime_event(kind, f"Spawned {label.lower()} process PID {process.pid}")
+    _emit_runtime_app_event(
+        kind,
+        "runtime_process_spawned",
+        f"{label} subprocess spawned",
+        level="INFO",
+        source="subprocess",
+        command=command,
+        cwd=str(cwd),
+        subprocess_pid=process.pid,
+        subprocess_label=label,
+    )
 
     def _log_subprocess_output():
         print(f"[MODEL.PY] === {label} subprocess output (PID {process.pid}) ===")
         try:
             if process.stdout is not None:
                 for line in process.stdout:
-                    _append_runtime_log(kind, line.rstrip())
+                    _append_runtime_log(
+                        kind,
+                        line.rstrip(),
+                        event="runtime_output_line",
+                        source="subprocess",
+                        stream="stdout",
+                        subprocess_label=label,
+                        subprocess_pid=process.pid,
+                    )
                     print(f"[{label}:{process.pid}] {line.rstrip()}")
             process.wait()
             exit_code = process.returncode
+            if exit_code == 0:
+                discovered_artifacts = _discover_runtime_artifacts(kind)
+                if discovered_artifacts:
+                    merged_metadata = _merge_runtime_metadata(
+                        kind,
+                        **discovered_artifacts,
+                    )
+                    artifact_path = discovered_artifacts.get(
+                        "latestCheckpointPath"
+                    ) or discovered_artifacts.get("latestPredictionPath")
+                    artifact_label = (
+                        "checkpoint" if kind == "training" else "prediction output"
+                    )
+                    _append_runtime_event(
+                        kind,
+                        f"Latest {artifact_label} discovered: {artifact_path}",
+                        event="runtime_artifact_discovered",
+                        checkpoint_path=discovered_artifacts.get(
+                            "latestCheckpointPath"
+                        ),
+                        prediction_path=discovered_artifacts.get(
+                            "latestPredictionPath"
+                        ),
+                        output_path=merged_metadata.get("outputPath"),
+                    )
+                elif kind == "training":
+                    output_path = (
+                        _get_runtime_snapshot(kind).get("metadata") or {}
+                    ).get("outputPath")
+                    _append_runtime_event(
+                        kind,
+                        f"No checkpoint artifact was found in {output_path or 'the training output directory'}.",
+                        event="runtime_artifact_missing",
+                        level="WARNING",
+                        output_path=output_path,
+                    )
             _update_runtime_state(
                 kind,
                 phase="finished" if exit_code == 0 else "failed",
@@ -277,6 +1552,17 @@ def _log_subprocess_output():
             _append_runtime_event(
                 kind,
                 f"{label} subprocess finished with exit code: {exit_code}",
+                event="runtime_process_finished",
+            )
+            _emit_runtime_app_event(
+                kind,
+                "runtime_process_finished",
+                f"{label} subprocess exited",
+                level="INFO" if exit_code == 0 else "ERROR",
+                source="subprocess",
+                subprocess_label=label,
+                subprocess_pid=process.pid,
+                exit_code=exit_code,
             )
             _clear_runtime_process(kind, process)
             print(
@@ -291,17 +1577,8 @@ def _log_subprocess_output():
 
 
 def _extract_output_path_from_yaml(config_text: str, mode: str) -> str | None:
-    try:
-        import yaml
-    except Exception:
-        return None
-
-    try:
-        config_obj = yaml.safe_load(config_text) or {}
-    except Exception:
-        return None
-
-    if not isinstance(config_obj, dict):
+    config_obj = _load_yaml_config(config_text)
+    if not config_obj:
         return None
 
     if mode == "train":
@@ -329,10 +1606,169 @@ def _extract_output_path_from_yaml(config_text: str, mode: str) -> str | None:
     return None
 
 
+def _resolve_runtime_output_dir(path_value: str | None) -> pathlib.Path | None:
+    if not path_value or not str(path_value).strip():
+        return None
+
+    candidate = pathlib.Path(str(path_value).strip()).expanduser()
+    if not candidate.is_absolute():
+        candidate = (_project_root() / candidate).resolve()
+    else:
+        candidate = candidate.resolve()
+
+    if candidate.is_file():
+        return candidate.parent
+    if candidate.exists():
+        return candidate
+    return None
+
+
+def _find_latest_checkpoint(output_path: str | None) -> str | None:
+    output_dir = _resolve_runtime_output_dir(output_path)
+    if output_dir is None or not output_dir.exists():
+        return None
+
+    candidates: list[pathlib.Path] = []
+    for pattern in ("checkpoint_*.pth.tar", "checkpoint_*.pth", "*.ckpt"):
+        candidates.extend(path for path in output_dir.glob(pattern) if path.is_file())
+
+    if not candidates:
+        return None
+
+    latest = max(candidates, key=lambda path: (path.stat().st_mtime, path.name))
+    return str(latest.resolve())
+
+
+def _path_has_prediction_suffix(path: pathlib.Path) -> bool:
+    lower_name = path.name.lower()
+    lower_path = str(path).lower()
+    return lower_name.endswith(_PREDICTION_OUTPUT_SUFFIXES) or lower_path.endswith(
+        (".ome.tif", ".ome.tiff", ".nii.gz")
+    )
+
+
+def _is_prediction_output_candidate(path: pathlib.Path) -> bool:
+    if path.name.startswith("."):
+        return False
+    if not _path_has_prediction_suffix(path):
+        return False
+    if path.is_dir():
+        return path.name.lower().endswith((".zarr", ".n5"))
+    return path.is_file()
+
+
+def _prediction_output_priority(path: pathlib.Path) -> tuple[float, int, str]:
+    name = path.name.lower()
+    preferred = 0
+    if name.startswith("result_xy"):
+        preferred = 3
+    elif name.startswith("result"):
+        preferred = 2
+    elif "prediction" in name or "pred" in name:
+        preferred = 1
+    try:
+        mtime = path.stat().st_mtime
+    except OSError:
+        mtime = 0.0
+    return (mtime, preferred, path.name)
+
+
+def _resolve_prediction_search_dir(path_value: str | None) -> pathlib.Path | None:
+    if not path_value or not str(path_value).strip():
+        return None
+
+    candidate = pathlib.Path(str(path_value).strip()).expanduser()
+    if not candidate.is_absolute():
+        candidate = (_project_root() / candidate).resolve()
+    else:
+        candidate = candidate.resolve()
+
+    if _is_prediction_output_candidate(candidate):
+        return candidate.parent
+    if candidate.is_dir():
+        return candidate
+    if candidate.parent.exists():
+        return candidate.parent
+    return None
+
+
+def _find_latest_prediction_output(output_path: str | None) -> str | None:
+    if not output_path or not str(output_path).strip():
+        return None
+
+    requested = pathlib.Path(str(output_path).strip()).expanduser()
+    if not requested.is_absolute():
+        requested = (_project_root() / requested).resolve()
+    else:
+        requested = requested.resolve()
+    if _is_prediction_output_candidate(requested):
+        return str(requested)
+
+    output_dir = _resolve_prediction_search_dir(output_path)
+    if output_dir is None or not output_dir.exists():
+        return None
+
+    candidates: list[pathlib.Path] = []
+    for child in output_dir.rglob("*"):
+        if _is_prediction_output_candidate(child):
+            candidates.append(child)
+
+    if not candidates:
+        return None
+
+    latest = max(candidates, key=_prediction_output_priority)
+    return str(latest.resolve())
+
+
+def _discover_runtime_artifacts(kind: str) -> dict[str, Any]:
+    snapshot = _get_runtime_snapshot(kind)
+    metadata = snapshot.get("metadata") or {}
+    output_path = metadata.get("outputPath")
+
+    if kind == "inference":
+        latest_prediction = _find_latest_prediction_output(output_path)
+        if not latest_prediction:
+            return {}
+        return {
+            "predictionPath": latest_prediction,
+            "latestPredictionPath": latest_prediction,
+            "latestPredictionName": pathlib.Path(latest_prediction).name,
+        }
+
+    if kind != "training":
+        return {}
+
+    latest_checkpoint = _find_latest_checkpoint(output_path)
+    if not latest_checkpoint:
+        return {}
+
+    return {
+        "checkpointPath": latest_checkpoint,
+        "latestCheckpointPath": latest_checkpoint,
+        "latestCheckpointName": pathlib.Path(latest_checkpoint).name,
+    }
+
+
 def _launch_tensorboard(log_dir: str | None, config_text: str, mode: str):
     resolved = log_dir or _extract_output_path_from_yaml(config_text, mode)
     if resolved:
-        initialize_tensorboard(resolved)
+        source_key = "training" if mode == "train" else "inference"
+        try:
+            status = initialize_tensorboard(resolved, source_key=source_key)
+            _append_runtime_event(
+                source_key,
+                f"TensorBoard available at {status['url']}",
+                event="tensorboard_ready",
+                tensorboard_url=status["url"],
+                tensorboard_port=status["port"],
+            )
+        except Exception as exc:
+            _append_runtime_event(
+                source_key,
+                f"TensorBoard could not be started automatically: {exc}",
+                event="tensorboard_error",
+                level="ERROR",
+            )
     return resolved
 
 
@@ -350,6 +1786,10 @@ def start_training(payload: dict):
     config_text = payload.get("trainingConfig", "")
     temp_filepath = None
     config_origin_path = payload.get("configOriginPath")
+    auto_parameters = bool(
+        payload.get("autoParameters") or payload.get("auto_parameters")
+    )
+    config_corrections: list[dict[str, Any]] = []
     _reset_runtime_state(
         "training",
         phase="starting",
@@ -357,12 +1797,31 @@ def start_training(payload: dict):
             "label": "training",
             "outputPath": payload.get("outputPath"),
             "logPath": payload.get("logPath"),
+            "inputImagePath": payload.get("inputImagePath"),
+            "inputLabelPath": payload.get("inputLabelPath"),
+            "configOriginPath": config_origin_path,
+            "workflowId": payload.get("workflowId") or payload.get("workflow_id"),
+            "runId": payload.get("runId") or payload.get("run_id"),
+            "commandId": payload.get("command_id") or payload.get("commandId"),
+            "autoParameters": auto_parameters,
         },
     )
 
     try:
         current_dir = _project_root()
         script_path = _pytc_script_path()
+        config_text, path_corrections = _apply_runtime_path_overrides(
+            config_text,
+            payload,
+            kind="training",
+        )
+        config_text, config_corrections = _sanitize_runtime_config_text(
+            config_text,
+            config_origin_path,
+            auto_parameters=auto_parameters,
+        )
+        config_corrections = path_corrections + config_corrections
+        _validate_runtime_launch_inputs(config_text, kind="training")
         temp_filepath = _write_temp_config(
             config_text,
             "training",
@@ -373,8 +1832,18 @@ def start_training(payload: dict):
             configPath=temp_filepath,
             configOriginPath=config_origin_path,
         )
-        _append_runtime_event("training", f"Config origin: {config_origin_path or 'none'}")
+        _append_runtime_event(
+            "training", f"Config origin: {config_origin_path or 'none'}"
+        )
         _append_runtime_event("training", f"Staged config path: {temp_filepath}")
+        if config_corrections:
+            _append_runtime_event(
+                "training",
+                f"Sanitized staged training config with {len(config_corrections)} correction(s)",
+                event="runtime_config_sanitized",
+                level="WARNING",
+                corrections=config_corrections,
+            )
 
         command = [
             sys.executable,
@@ -390,12 +1859,53 @@ def start_training(payload: dict):
         )
 
         print(f"[MODEL.PY] Final training command: {' '.join(command)}")
-        _append_runtime_event("training", f"Final training command: {' '.join(command)}")
+        _append_runtime_event(
+            "training", f"Final training command: {' '.join(command)}"
+        )
+        process_env = os.environ.copy()
+        process_env.setdefault("PYTORCH_ALLOC_CONF", "expandable_segments:True")
+        if _training_uses_gpu(config_text):
+            unloaded_models = _unload_ollama_before_gpu_training("training")
+        else:
+            unloaded_models = []
+        _emit_runtime_app_event(
+            "training",
+            "runtime_config_snapshot",
+            "Training config staged",
+            level="INFO",
+            source="model",
+            config_origin_path=config_origin_path,
+            staged_config_path=temp_filepath,
+            command=command,
+            arguments=payload.get("arguments", {}) or {},
+            output_path=payload.get("outputPath"),
+            log_path=payload.get("logPath"),
+            input_image_path=payload.get("inputImagePath"),
+            input_label_path=payload.get("inputLabelPath"),
+            auto_parameters=auto_parameters,
+            ollama_unloaded_models=unloaded_models,
+            config_text=config_text,
+            config_text_length=len(config_text or ""),
+            config_line_count=(config_text or "").count("\n")
+            + (1 if config_text else 0),
+            config_sanitized=bool(config_corrections),
+            config_corrections=config_corrections,
+        )
+        config_diagnostic = _detect_chunk_tile_mismatch(config_text)
+        if config_diagnostic:
+            _append_runtime_event(
+                "training",
+                config_diagnostic["message"],
+                event="runtime_config_warning",
+                level="WARNING",
+                diagnostic=config_diagnostic,
+            )
         _training_process = _start_logged_process(
             command,
             current_dir,
             "TRAINING",
             "training",
+            env=process_env,
         )
 
         log_dir = _launch_tensorboard(payload.get("outputPath"), config_text, "train")
@@ -423,9 +1933,7 @@ def _stop_processes(matcher, description: str):
                 cmdline = proc.info["cmdline"] or []
                 if not matcher(cmdline):
                     continue
-                print(
-                    f"Terminating process {proc.info['pid']}: {' '.join(cmdline)}"
-                )
+                print(f"Terminating process {proc.info['pid']}: {' '.join(cmdline)}")
                 proc.terminate()
                 proc.wait(timeout=10)
             except (psutil.NoSuchProcess, psutil.AccessDenied, psutil.TimeoutExpired):
@@ -507,39 +2015,134 @@ def stop_training():
             _training_process = None
 
     stop_pytc_processes("train")
-    stop_tensorboard()
     cleanup_temp_files("training")
     _update_runtime_state("training", phase="stopped", endedAt=_utc_now())
     _append_runtime_event("training", "Training stop requested")
     return {"status": "stopped"}
 
 
-def initialize_tensorboard(logPath):
-    global tensorboard_url
+def initialize_tensorboard(logPath: str | None = None, source_key: str = "manual"):
+    global _tensorboard_process
 
-    print(f"[MODEL.PY] initialize_tensorboard called with logPath: {logPath}")
-    from tensorboard import program
+    if logPath:
+        resolved = _register_tensorboard_source(source_key, logPath)
+    else:
+        resolved = None
 
-    tb = program.TensorBoard()
-    try:
-        tb.configure(argv=[None, "--logdir", logPath, "--host", "0.0.0.0"])
-        tensorboard_url = tb.launch()
-        print(f"[MODEL.PY] ✓ TensorBoard is running at {tensorboard_url}")
-    except Exception as exc:
-        tensorboard_url = "http://localhost:6006/"
-        print(
-            f"[MODEL.PY] ⚠ TensorBoard fallback to {tensorboard_url} due to error: {exc}"
+    logdir_spec = _build_tensorboard_logdir_spec()
+    if not logdir_spec:
+        raise ValueError(
+            "No TensorBoard log directory is registered yet. Start a training or inference job first."
+        )
+
+    snapshot = _get_tensorboard_snapshot()
+    if snapshot["isRunning"] and snapshot["logdirSpec"] == logdir_spec:
+        return snapshot
+
+    if snapshot["isRunning"] or snapshot["phase"] in {"starting", "failed", "finished"}:
+        _terminate_managed_tensorboard()
+
+    port = _pick_tensorboard_port(snapshot.get("port"))
+    command = [
+        sys.executable,
+        "-m",
+        "tensorboard.main",
+        "--logdir_spec",
+        logdir_spec,
+        "--host",
+        _TENSORBOARD_BIND_HOST,
+        "--port",
+        str(port),
+    ]
+    process = subprocess.Popen(
+        command,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        text=True,
+        bufsize=1,
+        cwd=str(_project_root()),
+    )
+    _tensorboard_process = process
+    _update_tensorboard_state(
+        phase="starting",
+        pid=process.pid,
+        port=port,
+        url=_tensorboard_url_for_port(port),
+        command=" ".join(command),
+        logdirSpec=logdir_spec,
+        startedAt=_utc_now(),
+        endedAt=None,
+        lastError=None,
+    )
+    _append_tensorboard_log(f"[TENSORBOARD] Launching with logdir spec: {logdir_spec}")
+    append_app_event(
+        component="server_pytc",
+        event="tensorboard_launch",
+        level="INFO",
+        message="Launching TensorBoard",
+        source="tensorboard",
+        command=command,
+        tensorboard_port=port,
+        tensorboard_url=_tensorboard_url_for_port(port),
+        tensorboard_logdir_spec=logdir_spec,
+    )
+    threading.Thread(
+        target=_watch_tensorboard_process,
+        args=(process,),
+        daemon=True,
+    ).start()
+
+    if not _wait_for_tensorboard_ready(port, process):
+        _terminate_managed_tensorboard()
+        error_message = "TensorBoard did not become ready before the startup timeout."
+        _update_tensorboard_state(
+            phase="failed",
+            pid=None,
+            port=None,
+            endedAt=_utc_now(),
         )
+        _set_tensorboard_error(error_message)
+        raise RuntimeError(error_message)
+
+    _update_tensorboard_state(phase="running")
+    if resolved:
+        _append_tensorboard_log(
+            f"[TENSORBOARD] Ready and watching {source_key} at {resolved}"
+        )
+    append_app_event(
+        component="server_pytc",
+        event="tensorboard_ready",
+        level="INFO",
+        message="TensorBoard is ready",
+        source="tensorboard",
+        tensorboard_port=port,
+        tensorboard_url=_tensorboard_url_for_port(port),
+        tensorboard_logdir_spec=logdir_spec,
+    )
+    return _get_tensorboard_snapshot()
 
 
 def get_tensorboard():
-    return tensorboard_url
+    snapshot = _get_tensorboard_snapshot()
+    return snapshot["url"] if snapshot["isRunning"] else None
 
 
-def stop_tensorboard():
-    global tensorboard_url
-    tensorboard_url = None
-    stop_process_by_name("tensorboard")
+def get_tensorboard_status():
+    return _get_tensorboard_snapshot()
+
+
+def stop_tensorboard(clear_sources: bool = False):
+    _terminate_managed_tensorboard()
+    if clear_sources:
+        _tensorboard_sources.clear()
+    _update_tensorboard_state(
+        phase="stopped",
+        pid=None,
+        port=None,
+        url=None,
+        endedAt=_utc_now(),
+        lastError=None,
+    )
 
 
 def start_inference(payload: dict):
@@ -553,6 +2156,7 @@ def start_inference(payload: dict):
     config_text = payload.get("inferenceConfig", "")
     temp_filepath = None
     config_origin_path = payload.get("configOriginPath")
+    config_corrections: list[dict[str, Any]] = []
     _reset_runtime_state(
         "inference",
         phase="starting",
@@ -561,12 +2165,24 @@ def start_inference(payload: dict):
             "outputPath": payload.get("outputPath"),
             "checkpointPath": payload.get("checkpointPath")
             or (payload.get("arguments") or {}).get("checkpoint"),
+            "configOriginPath": config_origin_path,
+            "workflowId": payload.get("workflow_id") or payload.get("workflowId"),
         },
     )
 
     try:
         current_dir = _project_root()
         script_path = _pytc_script_path()
+        config_text, path_corrections = _apply_runtime_path_overrides(
+            config_text,
+            payload,
+            kind="inference",
+        )
+        config_text, config_corrections = _sanitize_runtime_config_text(
+            config_text,
+            config_origin_path,
+        )
+        config_corrections = path_corrections + config_corrections
         temp_filepath = _write_temp_config(
             config_text,
             "inference",
@@ -581,10 +2197,27 @@ def start_inference(payload: dict):
             "inference", f"Config origin: {config_origin_path or 'none'}"
         )
         _append_runtime_event("inference", f"Staged config path: {temp_filepath}")
+        if config_corrections:
+            _append_runtime_event(
+                "inference",
+                f"Sanitized staged inference config with {len(config_corrections)} correction(s)",
+                event="runtime_config_sanitized",
+                level="WARNING",
+                corrections=config_corrections,
+            )
 
         arguments = dict(payload.get("arguments") or {})
         if payload.get("checkpointPath") and not arguments.get("checkpoint"):
             arguments["checkpoint"] = payload["checkpointPath"]
+        if arguments.get("checkpoint"):
+            arguments["checkpoint"] = _resolve_runtime_data_path(
+                arguments["checkpoint"]
+            )
+        _validate_runtime_launch_inputs(
+            config_text,
+            kind="inference",
+            arguments=arguments,
+        )
 
         command = [
             sys.executable,
@@ -601,13 +2234,48 @@ def start_inference(payload: dict):
         )
 
         print(f"[MODEL.PY] Final inference command: {' '.join(command)}")
-        _append_runtime_event("inference", f"Final inference command: {' '.join(command)}")
+        _append_runtime_event(
+            "inference", f"Final inference command: {' '.join(command)}"
+        )
+        _emit_runtime_app_event(
+            "inference",
+            "runtime_config_snapshot",
+            "Inference config staged",
+            level="INFO",
+            source="model",
+            config_origin_path=config_origin_path,
+            staged_config_path=temp_filepath,
+            command=command,
+            arguments=arguments,
+            output_path=payload.get("outputPath"),
+            input_image_path=payload.get("inputImagePath"),
+            checkpoint_path=payload.get("checkpointPath"),
+            config_text=config_text,
+            config_text_length=len(config_text or ""),
+            config_line_count=(config_text or "").count("\n")
+            + (1 if config_text else 0),
+            config_sanitized=bool(config_corrections),
+            config_corrections=config_corrections,
+        )
+        config_diagnostic = _detect_chunk_tile_mismatch(config_text)
+        if config_diagnostic:
+            _append_runtime_event(
+                "inference",
+                config_diagnostic["message"],
+                event="runtime_config_warning",
+                level="WARNING",
+                diagnostic=config_diagnostic,
+            )
         _inference_process = _start_logged_process(
             command,
             current_dir,
             "INFERENCE",
             "inference",
         )
+        log_dir = _launch_tensorboard(payload.get("outputPath"), config_text, "test")
+        if log_dir:
+            _append_runtime_event("inference", f"TensorBoard log dir: {log_dir}")
+            print(f"[MODEL.PY] TensorBoard monitoring directory: {log_dir}")
         result = {"status": "started", "pid": _inference_process.pid}
         print(f"[MODEL.PY] Returning: {result}")
         print("========== MODEL.PY: END OF START_INFERENCE ==========\n")
@@ -657,7 +2325,8 @@ def stop_inference():
     if _inference_process and _inference_process.poll() is None:
         try:
             _append_runtime_event(
-                "inference", f"Terminating inference process PID: {_inference_process.pid}"
+                "inference",
+                f"Terminating inference process PID: {_inference_process.pid}",
             )
             print(f"Terminating inference process PID: {_inference_process.pid}")
             _inference_process.terminate()
@@ -680,4 +2349,5 @@ def stop_inference():
     return {"status": "stopped"}
 
 
+atexit.register(stop_tensorboard)
 atexit.register(cleanup_temp_files)
diff --git a/testing_projects/mito25_paper_loop_smoke/checkpoints/checkpoint_00001.pth.tar b/testing_projects/mito25_paper_loop_smoke/checkpoints/checkpoint_00001.pth.tar
new file mode 120000
index 00000000..0660ed24
--- /dev/null
+++ b/testing_projects/mito25_paper_loop_smoke/checkpoints/checkpoint_00001.pth.tar
@@ -0,0 +1 @@
+/Users/adamg/seg.bio/outputs/mito25_local_smoke_bc/checkpoint_00001.pth.tar
\ No newline at end of file
diff --git a/testing_projects/mito25_paper_loop_smoke/configs/Mito25-Local-BC.yaml b/testing_projects/mito25_paper_loop_smoke/configs/Mito25-Local-BC.yaml
new file mode 120000
index 00000000..5245bae8
--- /dev/null
+++ b/testing_projects/mito25_paper_loop_smoke/configs/Mito25-Local-BC.yaml
@@ -0,0 +1 @@
+/Users/adamg/seg.bio/pytc-client/pytorch_connectomics/configs/MitoEM/Mito25-Local-BC.yaml
\ No newline at end of file
diff --git a/testing_projects/mito25_paper_loop_smoke/configs/Mito25-Local-Smoke-BC.yaml b/testing_projects/mito25_paper_loop_smoke/configs/Mito25-Local-Smoke-BC.yaml
new file mode 120000
index 00000000..2296fbba
--- /dev/null
+++ b/testing_projects/mito25_paper_loop_smoke/configs/Mito25-Local-Smoke-BC.yaml
@@ -0,0 +1 @@
+/Users/adamg/seg.bio/pytc-client/pytorch_connectomics/configs/MitoEM/Mito25-Local-Smoke-BC.yaml
\ No newline at end of file
diff --git a/testing_projects/mito25_paper_loop_smoke/data/image/mito25_smoke_13312-15360_im.h5 b/testing_projects/mito25_paper_loop_smoke/data/image/mito25_smoke_13312-15360_im.h5
new file mode 120000
index 00000000..34e8671f
--- /dev/null
+++ b/testing_projects/mito25_paper_loop_smoke/data/image/mito25_smoke_13312-15360_im.h5
@@ -0,0 +1 @@
+/Users/adamg/seg.bio/testing_data/mito25_smoke/image/512-768_8192-10240_13312-15360_im.h5
\ No newline at end of file
diff --git a/testing_projects/mito25_paper_loop_smoke/data/seg/.pytc_instance_labels.tif b/testing_projects/mito25_paper_loop_smoke/data/seg/.pytc_instance_labels.tif
new file mode 100644
index 00000000..5e7d5f4d
Binary files /dev/null and b/testing_projects/mito25_paper_loop_smoke/data/seg/.pytc_instance_labels.tif differ
diff --git a/testing_projects/mito25_paper_loop_smoke/data/seg/.pytc_proofreading.json b/testing_projects/mito25_paper_loop_smoke/data/seg/.pytc_proofreading.json
new file mode 100644
index 00000000..e61edec3
--- /dev/null
+++ b/testing_projects/mito25_paper_loop_smoke/data/seg/.pytc_proofreading.json
@@ -0,0 +1,222 @@
+{
+  "schema_version": 3,
+  "updated_at": "2026-04-25T17:25:17.877002+00:00",
+  "project": {
+    "name": "mito25-paper-loop-smoke",
+    "dataset_path": "/Users/adamg/seg.bio/pytc-client/testing_projects/mito25_paper_loop_smoke/data/image/mito25_smoke_13312-15360_im.h5",
+    "mask_path": "/Users/adamg/seg.bio/pytc-client/testing_projects/mito25_paper_loop_smoke/data/seg/mito25_smoke_13312-15360_seg.h5",
+    "instance_mode": "instance"
+  },
+  "review": {
+    "total_instances": 14,
+    "reviewed_instances": 0,
+    "progress": 0.0,
+    "counts": {
+      "correct": 0,
+      "incorrect": 0,
+      "unsure": 0,
+      "error": 14
+    }
+  },
+  "instances": {
+    "373": {
+      "classification": "error",
+      "reviewed_at": null,
+      "notes": "",
+      "metadata": {
+        "voxel_count": 46238,
+        "com_z": 30,
+        "com_y": 364,
+        "com_x": 32
+      },
+      "edits": {
+        "last_edit_at": "2026-04-25T17:25:17.876418+00:00",
+        "count": 1,
+        "pixels_added": 1388,
+        "pixels_removed": 0,
+        "pixels_changed": 1388,
+        "pixels_blocked": 0,
+        "by_axis": {
+          "xy": 1388
+        }
+      },
+      "history": [
+        {
+          "at": "2026-04-25T17:25:17.876418+00:00",
+          "by": "local",
+          "type": "mask_edit",
+          "axis": "xy",
+          "z_index": 39,
+          "pixels_added": 1388,
+          "pixels_removed": 0,
+          "pixels_changed": 1388,
+          "pixels_blocked": 0
+        }
+      ]
+    },
+    "374": {
+      "classification": "error",
+      "reviewed_at": null,
+      "notes": "",
+      "metadata": {
+        "voxel_count": 19208,
+        "com_z": 39,
+        "com_y": 319,
+        "com_x": 253
+      }
+    },
+    "388": {
+      "classification": "error",
+      "reviewed_at": null,
+      "notes": "",
+      "metadata": {
+        "voxel_count": 19085,
+        "com_z": 27,
+        "com_y": 95,
+        "com_x": 77
+      }
+    },
+    "401": {
+      "classification": "error",
+      "reviewed_at": null,
+      "notes": "",
+      "metadata": {
+        "voxel_count": 14194,
+        "com_z": 30,
+        "com_y": 292,
+        "com_x": 202
+      }
+    },
+    "414": {
+      "classification": "error",
+      "reviewed_at": null,
+      "notes": "",
+      "metadata": {
+        "voxel_count": 14052,
+        "com_z": 24,
+        "com_y": 85,
+        "com_x": 457
+      }
+    },
+    "385": {
+      "classification": "error",
+      "reviewed_at": null,
+      "notes": "",
+      "metadata": {
+        "voxel_count": 11567,
+        "com_z": 47,
+        "com_y": 488,
+        "com_x": 12
+      }
+    },
+    "398": {
+      "classification": "error",
+      "reviewed_at": null,
+      "notes": "",
+      "metadata": {
+        "voxel_count": 8935,
+        "com_z": 29,
+        "com_y": 369,
+        "com_x": 157
+      }
+    },
+    "399": {
+      "classification": "error",
+      "reviewed_at": null,
+      "notes": "",
+      "metadata": {
+        "voxel_count": 7979,
+        "com_z": 23,
+        "com_y": 364,
+        "com_x": 191
+      }
+    },
+    "375": {
+      "classification": "error",
+      "reviewed_at": null,
+      "notes": "",
+      "metadata": {
+        "voxel_count": 4300,
+        "com_z": 53,
+        "com_y": 358,
+        "com_x": 172
+      }
+    },
+    "400": {
+      "classification": "error",
+      "reviewed_at": null,
+      "notes": "",
+      "metadata": {
+        "voxel_count": 1835,
+        "com_z": 4,
+        "com_y": 299,
+        "com_x": 163
+      }
+    },
+    "413": {
+      "classification": "error",
+      "reviewed_at": null,
+      "notes": "",
+      "metadata": {
+        "voxel_count": 1304,
+        "com_z": 1,
+        "com_y": 43,
+        "com_x": 427
+      }
+    },
+    "432": {
+      "classification": "error",
+      "reviewed_at": null,
+      "notes": "",
+      "metadata": {
+        "voxel_count": 629,
+        "com_z": 16,
+        "com_y": 251,
+        "com_x": 204
+      }
+    },
+    "451": {
+      "classification": "error",
+      "reviewed_at": null,
+      "notes": "",
+      "metadata": {
+        "voxel_count": 523,
+        "com_z": 4,
+        "com_y": 129,
+        "com_x": 161
+      }
+    },
+    "443": {
+      "classification": "error",
+      "reviewed_at": null,
+      "notes": "",
+      "metadata": {
+        "voxel_count": 486,
+        "com_z": 1,
+        "com_y": 22,
+        "com_x": 508
+      }
+    }
+  },
+  "extensions": {},
+  "artifact": {
+    "enabled": true,
+    "artifact_path": "/Users/adamg/seg.bio/pytc-client/testing_projects/mito25_paper_loop_smoke/data/seg/.pytc_instance_labels.tif",
+    "artifact_exists": true,
+    "dirty": false,
+    "writable": true,
+    "last_saved_at": "2026-04-25T17:25:17.876254+00:00",
+    "last_error": null,
+    "last_export_at": null,
+    "last_export_mode": null,
+    "last_export_path": null,
+    "last_backup_path": null
+  },
+  "ui_state": {
+    "axis": "xy",
+    "overlay_all_alpha": 0.08,
+    "overlay_active_alpha": 0.8,
+    "last_instance_id": 373,
+    "last_slice_index": 39
+  }
+}
diff --git a/testing_projects/mito25_paper_loop_smoke/data/seg/mito25_smoke_13312-15360_seg.h5 b/testing_projects/mito25_paper_loop_smoke/data/seg/mito25_smoke_13312-15360_seg.h5
new file mode 120000
index 00000000..c7cd0d7e
--- /dev/null
+++ b/testing_projects/mito25_paper_loop_smoke/data/seg/mito25_smoke_13312-15360_seg.h5
@@ -0,0 +1 @@
+/Users/adamg/seg.bio/testing_data/mito25_smoke/seg/512-768_8192-10240_13312-15360_seg.h5
\ No newline at end of file
diff --git a/testing_projects/mito25_paper_loop_smoke/notes/README.md b/testing_projects/mito25_paper_loop_smoke/notes/README.md
new file mode 100644
index 00000000..1756202e
--- /dev/null
+++ b/testing_projects/mito25_paper_loop_smoke/notes/README.md
@@ -0,0 +1,19 @@
+# Mito25 Paper Loop Smoke Project
+
+Use this mounted project to test the current prototype checkpoint without
+digging through unrelated folders.
+
+## What To Test
+
+- Open File Management and confirm `mito25-paper-loop-smoke` is mounted.
+- In `data/image`, use `mito25_smoke_13312-15360_im.h5` with dataset key `main`.
+- In `data/seg`, use `mito25_smoke_13312-15360_seg.h5` with dataset key `data`.
+- In `configs`, use `Mito25-Local-Smoke-BC.yaml` for smoke inference/training checks.
+- In `checkpoints`, use `checkpoint_00001.pth.tar`.
+- In `predictions`, use `baseline_result_xy.h5` and `candidate_result_xy.h5`, dataset `vol0`, channel `0`, for before/after smoke evaluation.
+
+## Known Boundary
+
+This mount contains existing smoke artifacts. It is for validating file picking,
+workflow capture, helper stability, and prediction-ingestion paths. A fresh
+app-launched inference/retraining loop is still the next prototype checkpoint.
diff --git a/testing_projects/mito25_paper_loop_smoke/predictions/baseline_result_xy.h5 b/testing_projects/mito25_paper_loop_smoke/predictions/baseline_result_xy.h5
new file mode 120000
index 00000000..8bcd34d9
--- /dev/null
+++ b/testing_projects/mito25_paper_loop_smoke/predictions/baseline_result_xy.h5
@@ -0,0 +1 @@
+/Users/adamg/seg.bio/outputs/mito25_local_smoke_bc/test/result_xy.h5
\ No newline at end of file
diff --git a/testing_projects/mito25_paper_loop_smoke/predictions/candidate_result_xy.h5 b/testing_projects/mito25_paper_loop_smoke/predictions/candidate_result_xy.h5
new file mode 120000
index 00000000..04e4c3c1
--- /dev/null
+++ b/testing_projects/mito25_paper_loop_smoke/predictions/candidate_result_xy.h5
@@ -0,0 +1 @@
+/Users/adamg/seg.bio/outputs/app_smoke_everywhere_infer/result_xy.h5
\ No newline at end of file
diff --git a/tests/test_api_compatibility_routes.py b/tests/test_api_compatibility_routes.py
new file mode 100644
index 00000000..f0119fe2
--- /dev/null
+++ b/tests/test_api_compatibility_routes.py
@@ -0,0 +1,145 @@
+import tempfile
+import unittest
+
+from fastapi.testclient import TestClient
+from sqlalchemy import create_engine
+from sqlalchemy.orm import sessionmaker
+
+from server_api.auth import database as auth_database
+from server_api.auth import models
+from server_api.main import app as server_api_app
+from server_api.main import _normalize_api_compat_path
+
+
+class ApiCompatibilityRouteTests(unittest.TestCase):
+    def setUp(self):
+        self.temp_dir = tempfile.TemporaryDirectory()
+        self.db_path = f"{self.temp_dir.name}/api-compatibility-test.db"
+        self.engine = create_engine(
+            f"sqlite:///{self.db_path}", connect_args={"check_same_thread": False}
+        )
+        self.SessionLocal = sessionmaker(
+            autocommit=False, autoflush=False, bind=self.engine
+        )
+        models.Base.metadata.create_all(bind=self.engine)
+
+        def override_get_db():
+            db = self.SessionLocal()
+            try:
+                yield db
+            finally:
+                db.close()
+
+        server_api_app.dependency_overrides[auth_database.get_db] = override_get_db
+        self.client = TestClient(server_api_app)
+
+    def tearDown(self):
+        server_api_app.dependency_overrides.clear()
+        self.engine.dispose()
+        self.temp_dir.cleanup()
+
+    def test_compat_workflow_current_matches_canonical_route(self):
+        canonical = self.client.get("/api/workflows/current")
+        legacy = self.client.get("/api/api/workflows/current")
+
+        self.assertEqual(canonical.status_code, 200)
+        self.assertEqual(legacy.status_code, 200)
+        self.assertEqual(
+            canonical.json()["workflow"]["id"],
+            legacy.json()["workflow"]["id"],
+        )
+        self.assertEqual(canonical.json()["events"], legacy.json()["events"])
+
+    def test_compat_files_root_and_project_suggestions_match_canonical(self):
+        canonical_root = self.client.get("/files", params={"parent": "root"})
+        legacy_root = self.client.get("/api/files", params={"parent": "root"})
+
+        self.assertEqual(canonical_root.status_code, 200)
+        self.assertEqual(legacy_root.status_code, 200)
+        self.assertEqual(canonical_root.json(), legacy_root.json())
+
+        canonical_suggestions = self.client.get("/files/project-suggestions")
+        legacy_suggestions = self.client.get("/api/files/project-suggestions")
+
+        self.assertEqual(canonical_suggestions.status_code, 200)
+        self.assertEqual(legacy_suggestions.status_code, 200)
+        canonical_payload = canonical_suggestions.json()
+        legacy_payload = legacy_suggestions.json()
+        self.assertEqual(len(canonical_payload), len(legacy_payload))
+
+        canonical_lookup = {item["id"]: item for item in canonical_payload}
+        for item in legacy_payload:
+            canonical_item = canonical_lookup[item["id"]]
+            self.assertEqual(canonical_item["name"], item["name"])
+            self.assertEqual(canonical_item["directory_path"], item["directory_path"])
+            self.assertEqual(canonical_item["description"], item["description"])
+            self.assertEqual(canonical_item["recommended"], item["recommended"])
+            self.assertEqual(canonical_item["already_mounted"], item["already_mounted"])
+            self.assertEqual(canonical_item["mounted_root_id"], item["mounted_root_id"])
+
+    def test_compat_log_event_matches_canonical(self):
+        payload = {
+            "event": "frontend-compat-test",
+            "level": "INFO",
+            "message": "api compatibility check",
+            "source": "compat-test",
+            "sessionId": "api-compat-session",
+            "url": "http://localhost/tests",
+            "data": {"status": "ok"},
+        }
+        canonical = self.client.post("/app/log-event", json=payload)
+        legacy = self.client.post("/api/app/log-event", json=payload)
+
+        self.assertEqual(canonical.status_code, 200)
+        self.assertEqual(legacy.status_code, 200)
+        self.assertEqual(canonical.json(), {"status": "ok"})
+        self.assertEqual(legacy.json(), {"status": "ok"})
+
+    def test_compat_neuroglancer_routes_match_canonical_validation(self):
+        canonical = self.client.post("/neuroglancer", json={})
+        legacy = self.client.post("/api/neuroglancer", json={})
+
+        self.assertEqual(canonical.status_code, legacy.status_code)
+        self.assertGreaterEqual(canonical.status_code, 400)
+        self.assertLess(canonical.status_code, 500)
+
+        canonical_proofread = self.client.post("/neuroglancer/proofread", json={})
+        legacy_proofread = self.client.post("/api/neuroglancer/proofread", json={})
+
+        self.assertEqual(canonical_proofread.status_code, legacy_proofread.status_code)
+        self.assertGreaterEqual(canonical_proofread.status_code, 400)
+        self.assertLess(canonical_proofread.status_code, 500)
+
+    def test_unrelated_paths_are_not_remapped(self):
+        response = self.client.get("/api/filesystem")
+        self.assertEqual(response.status_code, 404)
+        response = self.client.get("/api/apply")
+        self.assertEqual(response.status_code, 404)
+
+
+class ApiCompatibilityPathNormalizationTests(unittest.TestCase):
+    def test_runtime_paths_under_api_prefix_map_to_canonical_routes(self):
+        self.assertEqual(
+            _normalize_api_compat_path("/api/start_model_training"),
+            "/start_model_training",
+        )
+        self.assertEqual(
+            _normalize_api_compat_path("/api/start_model_inference"),
+            "/start_model_inference",
+        )
+        self.assertEqual(
+            _normalize_api_compat_path("/api/stop_model_training"),
+            "/stop_model_training",
+        )
+        self.assertEqual(
+            _normalize_api_compat_path("/api/training_status"),
+            "/training_status",
+        )
+        self.assertEqual(
+            _normalize_api_compat_path("/api/get_tensorboard_status"),
+            "/get_tensorboard_status",
+        )
+
+    def test_unrelated_api_prefixes_are_not_rewritten(self):
+        self.assertIsNone(_normalize_api_compat_path("/api/filesystem"))
+        self.assertIsNone(_normalize_api_compat_path("/api/apply"))
diff --git a/tests/test_app_event_logger.py b/tests/test_app_event_logger.py
new file mode 100644
index 00000000..9127e0d1
--- /dev/null
+++ b/tests/test_app_event_logger.py
@@ -0,0 +1,48 @@
+import json
+import io
+
+from app_event_logger import _AppEventStream, append_app_event, get_app_event_log_path
+
+
+def test_append_app_event_writes_jsonl(tmp_path, monkeypatch):
+    log_path = tmp_path / "app-events.jsonl"
+    monkeypatch.setenv("PYTC_APP_EVENT_LOG_PATH", str(log_path))
+
+    record = append_app_event(
+        component="test",
+        event="unit_test",
+        level="warning",
+        message="hello world",
+        data={"answer": 42},
+    )
+
+    assert get_app_event_log_path() == log_path
+    assert log_path.is_file()
+    assert record["component"] == "test"
+    assert record["event"] == "unit_test"
+    assert record["level"] == "WARNING"
+
+    written = json.loads(log_path.read_text(encoding="utf-8").strip())
+    assert written["component"] == "test"
+    assert written["event"] == "unit_test"
+    assert written["message"] == "hello world"
+    assert written["data"] == {"answer": 42}
+
+
+def test_app_event_stream_detects_info_lines_on_stderr(tmp_path, monkeypatch):
+    log_path = tmp_path / "app-events.jsonl"
+    monkeypatch.setenv("PYTC_APP_EVENT_LOG_PATH", str(log_path))
+
+    stream = _AppEventStream(
+        component="test",
+        stream_name="stderr",
+        level="ERROR",
+        original_stream=io.StringIO(),
+    )
+    stream.write("INFO:     Shutting down\n")
+    stream.flush()
+
+    written = json.loads(log_path.read_text(encoding="utf-8").strip())
+    assert written["event"] == "stderr_line"
+    assert written["level"] == "INFO"
+    assert written["message"] == "INFO:     Shutting down"
diff --git a/tests/test_browser_yixiao_case_study_smoke.py b/tests/test_browser_yixiao_case_study_smoke.py
new file mode 100644
index 00000000..453c21bb
--- /dev/null
+++ b/tests/test_browser_yixiao_case_study_smoke.py
@@ -0,0 +1,181 @@
+from __future__ import annotations
+
+import json
+import argparse
+import pytest
+
+from scripts import browser_yixiao_case_study_smoke as smoke
+
+
+def test_parse_viewport_defaults_when_empty() -> None:
+    assert smoke._parse_viewport("") == smoke.VIEWPORT_DEFAULT
+
+
+def test_parse_viewport_rejects_small_values() -> None:
+    for value in ["319x800", "800x319", "100x100"]:
+        try:
+            smoke._parse_viewport(value)
+            raise AssertionError(f"expected ValueError for {value}")
+        except argparse.ArgumentTypeError:
+            pass
+
+
+def test_parse_viewport_parses_valid_dimensions() -> None:
+    assert smoke._parse_viewport("1920x1080") == (1920, 1080)
+
+
+def test_extract_progress_from_text_parses_metrics_and_rates() -> None:
+    raw = """
+        Tracked volumes
+        10
+        Fully good
+        6
+        Needs proofreading
+        2
+        No segmentation
+        2
+        Completion
+        60%
+        Segmentation coverage: 80%
+    """
+
+    values, completion_pct, segmentation_pct = smoke._extract_progress_from_text(raw)
+
+    assert values == {
+        "Tracked volumes": 10,
+        "Fully good": 6,
+        "Needs proofreading": 2,
+        "No segmentation": 2,
+    }
+    assert completion_pct == 60
+    assert segmentation_pct == 80
+
+
+def test_arg_parser_defaults_are_browser_ready() -> None:
+    args = smoke._build_arg_parser().parse_args([])
+
+    assert args.base_url == smoke.DEFAULT_BASE_URL
+    assert args.report == smoke.DEFAULT_REPORT
+    assert args.viewport == f"{smoke.VIEWPORT_DEFAULT[0]}x{smoke.VIEWPORT_DEFAULT[1]}"
+    assert args.timeout_ms == 30_000
+    assert not args.no_headless
+    assert not args.skip_assistant
+    assert not args.skip_reload
+
+
+def test_run_smoke_raises_install_guidance_when_playwright_missing(monkeypatch) -> None:
+    monkeypatch.setattr(
+        smoke,
+        "_playwright_import_error",
+        lambda: ModuleNotFoundError("no module named playwright"),
+    )
+
+    with pytest.raises(RuntimeError) as exc:
+        smoke.run_smoke(
+            base_url=smoke.DEFAULT_BASE_URL,
+            timeout_ms=10_000,
+            viewport=smoke.VIEWPORT_DEFAULT,
+            headless=True,
+            skip_assistant=False,
+            skip_reload=False,
+        )
+
+    message = str(exc.value)
+    assert "Observed issue:" in message
+    assert "no module named playwright" in message
+    assert smoke._playwright_install_hint() in message
+
+
+def test_main_applies_timeout_minimum_and_writes_success_report(
+    monkeypatch,
+    tmp_path,
+) -> None:
+    captured = {}
+
+    def fake_run_smoke(
+        base_url,
+        timeout_ms,
+        viewport,
+        headless,
+        skip_assistant,
+        skip_reload,
+    ):
+        captured.update(
+            {
+                "base_url": base_url,
+                "timeout_ms": timeout_ms,
+                "viewport": viewport,
+                "headless": headless,
+                "skip_assistant": skip_assistant,
+                "skip_reload": skip_reload,
+            },
+        )
+        return {
+            "checks": ["page loaded"],
+            "base_url": base_url,
+            "progress_snapshot": {
+                "metrics": {
+                    "tracked": 10,
+                    "good": 6,
+                    "proofread": 2,
+                    "missing": 2,
+                },
+                "completion_percent": 60,
+                "segmentation_coverage_percent": 80,
+            },
+        }
+
+    monkeypatch.setattr(smoke, "run_smoke", fake_run_smoke)
+    report_path = tmp_path / "browser-report.json"
+
+    result = smoke.main(
+        [
+            "--base-url",
+            "https://demo.seg.bio",
+            "--timeout-ms",
+            "1000",
+            "--viewport",
+            "1280x900",
+            "--skip-assistant",
+            "--skip-reload",
+            "--report",
+            str(report_path),
+        ],
+    )
+
+    assert result == 0
+    assert report_path.exists()
+    assert captured["timeout_ms"] == 5000
+    assert captured["headless"] is True
+    assert captured["skip_assistant"] is True
+    assert captured["skip_reload"] is True
+    assert captured["viewport"] == smoke.VIEWPORT_DEFAULT
+
+    report = json.loads(report_path.read_text(encoding="utf-8"))
+    assert report["passed"] is True
+    assert report["base_url"] == "https://demo.seg.bio"
+    assert report["checks"] == ["page loaded"]
+    assert report["progress_snapshot"]["completion_percent"] == 60
+    assert report["progress_snapshot"]["segmentation_coverage_percent"] == 80
+
+
+def test_main_writes_error_shape_on_failure(monkeypatch, tmp_path) -> None:
+    def fake_run_smoke(*_args, **_kwargs):
+        raise RuntimeError("playwright is not ready")
+
+    monkeypatch.setattr(smoke, "run_smoke", fake_run_smoke)
+    report_path = tmp_path / "browser-failed.json"
+
+    result = smoke.main(
+        [
+            "--report",
+            str(report_path),
+        ]
+    )
+
+    assert result == 1
+    assert report_path.exists()
+    report = json.loads(report_path.read_text(encoding="utf-8"))
+    assert report["passed"] is False
+    assert report["error"] == "playwright is not ready"
+    assert report["error_type"] == "RuntimeError"
diff --git a/tests/test_chatbot_faiss_generation.py b/tests/test_chatbot_faiss_generation.py
index e24b10f8..4a5245f2 100644
--- a/tests/test_chatbot_faiss_generation.py
+++ b/tests/test_chatbot_faiss_generation.py
@@ -1,4 +1,8 @@
 from server_api.chatbot import update_faiss
+from server_api.chatbot.chatbot import (
+    AGENT_RESPONSE_STYLE,
+    _compact_agent_response,
+)
 
 
 def test_faiss_index_exists_requires_both_files(tmp_path):
@@ -43,12 +47,19 @@ def fake_build(summaries_directory, target_directory, *, model=None, base_url=No
 
 
 def test_ensure_faiss_index_skips_when_present(tmp_path, monkeypatch):
+    monkeypatch.delenv("OLLAMA_EMBED_MODEL", raising=False)
+    monkeypatch.delenv("OLLAMA_BASE_URL", raising=False)
     summaries_dir = tmp_path / "summaries"
     faiss_dir = tmp_path / "faiss_index"
     summaries_dir.mkdir()
     faiss_dir.mkdir()
     (faiss_dir / "index.faiss").write_text("stub")
     (faiss_dir / "index.pkl").write_text("stub")
+    update_faiss.write_index_settings(
+        faiss_dir,
+        model=update_faiss.DEFAULT_OLLAMA_EMBED_MODEL,
+        base_url=update_faiss.DEFAULT_OLLAMA_BASE_URL,
+    )
 
     def fail_build(*args, **kwargs):
         raise AssertionError("build_faiss_index should not be called")
@@ -63,6 +74,41 @@ def fail_build(*args, **kwargs):
     assert generated is False
 
 
+def test_ensure_faiss_index_rebuilds_when_settings_missing(tmp_path, monkeypatch):
+    monkeypatch.delenv("OLLAMA_EMBED_MODEL", raising=False)
+    monkeypatch.delenv("OLLAMA_BASE_URL", raising=False)
+    summaries_dir = tmp_path / "summaries"
+    faiss_dir = tmp_path / "faiss_index"
+    summaries_dir.mkdir()
+    faiss_dir.mkdir()
+    (faiss_dir / "index.faiss").write_text("stub")
+    (faiss_dir / "index.pkl").write_text("stub")
+    calls = []
+
+    def fake_build(summaries_directory, target_directory, *, model=None, base_url=None):
+        calls.append((summaries_directory, target_directory, model, base_url))
+        update_faiss.write_index_settings(
+            target_directory, model=model, base_url=base_url
+        )
+
+    monkeypatch.setattr(update_faiss, "build_faiss_index", fake_build)
+
+    generated = update_faiss.ensure_faiss_index(
+        summaries_directory=summaries_dir,
+        faiss_directory=faiss_dir,
+    )
+
+    assert generated is True
+    assert calls == [
+        (
+            summaries_dir,
+            faiss_dir,
+            update_faiss.DEFAULT_OLLAMA_EMBED_MODEL,
+            update_faiss.DEFAULT_OLLAMA_BASE_URL,
+        )
+    ]
+
+
 def test_resolve_ollama_settings_uses_env_defaults(monkeypatch):
     monkeypatch.delenv("OLLAMA_EMBED_MODEL", raising=False)
     monkeypatch.delenv("OLLAMA_BASE_URL", raising=False)
@@ -84,3 +130,57 @@ def test_resolve_ollama_settings_prefers_explicit_values(monkeypatch):
 
     assert model == "cli-model"
     assert base_url == "http://cli.test:8888"
+
+
+def test_agent_response_style_requires_skimmable_answers():
+    assert "Maximum 90 words" in AGENT_RESPONSE_STYLE
+    assert "recommended next action first" in AGENT_RESPONSE_STYLE
+
+
+def test_helper_ollama_settings_use_small_helper_model(monkeypatch):
+    from server_api.chatbot import chatbot
+
+    monkeypatch.delenv("PYTC_HELPER_OLLAMA_MODEL", raising=False)
+    monkeypatch.delenv("OLLAMA_HELPER_MODEL", raising=False)
+    monkeypatch.setenv("OLLAMA_MODEL", "large-main-model")
+    monkeypatch.setenv("OLLAMA_EMBED_MODEL", "shared-embed-model")
+
+    base_url, model, embed_model = chatbot._resolve_ollama_settings(helper=True)
+
+    assert model == chatbot.DEFAULT_HELPER_OLLAMA_MODEL
+    assert embed_model == "shared-embed-model"
+    assert base_url == chatbot.DEFAULT_OLLAMA_BASE_URL
+
+
+def test_helper_ollama_settings_prefer_helper_env(monkeypatch):
+    from server_api.chatbot import chatbot
+
+    monkeypatch.setenv("PYTC_HELPER_OLLAMA_BASE_URL", "http://helper.test:11434")
+    monkeypatch.setenv("PYTC_HELPER_OLLAMA_MODEL", "helper-model")
+    monkeypatch.setenv("PYTC_HELPER_OLLAMA_EMBED_MODEL", "helper-embed")
+
+    base_url, model, embed_model = chatbot._resolve_ollama_settings(helper=True)
+
+    assert base_url == "http://helper.test:11434"
+    assert model == "helper-model"
+    assert embed_model == "helper-embed"
+
+
+def test_compact_agent_response_shortens_long_non_code_answers():
+    response = "\n".join(
+        [
+            f"- detail {index} about a long biological workflow explanation"
+            for index in range(30)
+        ]
+    )
+
+    compacted = _compact_agent_response(response, max_words=40)
+
+    assert len(compacted.split()) <= 50
+    assert "Ask for details" in compacted
+
+
+def test_compact_agent_response_preserves_code_blocks():
+    response = "Run this:\n```bash\npython scripts/main.py --help\n```"
+
+    assert _compact_agent_response(response, max_words=5) == response
diff --git a/tests/test_check_files_route.py b/tests/test_check_files_route.py
index 2cb134d0..f1397a51 100644
--- a/tests/test_check_files_route.py
+++ b/tests/test_check_files_route.py
@@ -6,7 +6,6 @@
 
 from server_api.main import app as server_api_app
 
-
 REPO_ROOT = pathlib.Path(__file__).resolve().parents[1]
 SNEMI_ROOT = pathlib.Path(
     os.getenv(
diff --git a/tests/test_closed_loop_smoke_script.py b/tests/test_closed_loop_smoke_script.py
new file mode 100644
index 00000000..bbf0e069
--- /dev/null
+++ b/tests/test_closed_loop_smoke_script.py
@@ -0,0 +1,203 @@
+import pathlib
+
+import pytest
+
+pytest.importorskip("fastapi")
+pytest.importorskip("sqlalchemy")
+pytest.importorskip("tifffile")
+h5py = pytest.importorskip("h5py")
+
+import numpy as np
+
+from scripts.run_closed_loop_smoke import run_closed_loop_smoke
+
+
+def test_closed_loop_smoke_script_writes_researcher_evidence_bundle(tmp_path):
+    report = run_closed_loop_smoke(pathlib.Path(tmp_path))
+
+    assert report["ready_for_case_study"] is True
+    assert report["metric_summary"]["candidate_improved_dice"] is True
+    assert report["bundle_counts"]["model_runs"] >= 3
+    assert report["bundle_counts"]["model_versions"] == 1
+    assert report["bundle_counts"]["correction_sets"] >= 1
+    assert report["bundle_counts"]["evaluation_results"] == 1
+    assert report["bundle_counts"]["agent_plans"] == 1
+    assert "actual PyTC training subprocess" in report["simulated_or_not_exercised"]
+    assert (
+        "browser-level proofreading editor interaction"
+        in report["simulated_or_not_exercised"]
+    )
+
+    assert (tmp_path / "smoke-report.json").exists()
+    assert (tmp_path / "workflow-bundle.json").exists()
+    assert (tmp_path / "readiness.json").exists()
+    assert (tmp_path / "evaluation-report.json").exists()
+
+
+def test_closed_loop_smoke_script_accepts_real_hdf5_pair(tmp_path):
+    image_path = tmp_path / "image.h5"
+    mask_path = tmp_path / "mask.h5"
+    image = np.arange(8 * 16 * 16, dtype=np.uint8).reshape(8, 16, 16)
+    mask = np.zeros((8, 16, 16), dtype=np.uint16)
+    mask[:, 4:12, 5:13] = 7
+    with h5py.File(image_path, "w") as handle:
+        handle.create_dataset("main", data=image)
+    with h5py.File(mask_path, "w") as handle:
+        handle.create_dataset("data", data=mask)
+
+    report = run_closed_loop_smoke(
+        pathlib.Path(tmp_path / "smoke"),
+        image_path=str(image_path),
+        mask_path=str(mask_path),
+        image_dataset="main",
+        mask_dataset="data",
+        crop="0:4,0:12,0:12",
+    )
+
+    assert report["artifact_mode"] == "real_pair_derived_predictions"
+    assert report["ready_for_case_study"] is True
+    assert report["source_data"]["image_dataset"] == "main"
+    assert report["source_data"]["mask_dataset"] == "data"
+    assert (
+        "real biomedical/connectomics sample data"
+        not in report["simulated_or_not_exercised"]
+    )
+    assert any(
+        item.startswith("baseline/candidate predictions derived")
+        for item in report["simulated_or_not_exercised"]
+    )
+
+
+def test_closed_loop_smoke_reports_runtime_sync_and_iteration_overrides(tmp_path):
+    report = run_closed_loop_smoke(
+        pathlib.Path(tmp_path / "smoke"),
+        training_iterations=9,
+        inference_iterations=3,
+    )
+
+    assert report["runtime_overrides"]["training_iterations"] == 9
+    assert report["runtime_overrides"]["inference_iterations"] == 3
+    assert isinstance(report["runtime_sync"]["training_runs"], list)
+    assert isinstance(report["runtime_sync"]["inference_runs"], list)
+    assert isinstance(report["runtime_sync"]["model_versions"], list)
+    assert "checkpoint" in report["runtime_checkpoints"]
+    assert report["runtime_checkpoints"]["checkpoint"]
+    assert report["runtime_checkpoints"]["training_run_checkpoint"]
+    assert report["runtime_checkpoints"]["inference_run_checkpoint"]
+    assert "id" in report["runtime_sync"]["model_versions"][0]
+
+
+def test_closed_loop_smoke_script_accepts_real_hdf5_predictions(tmp_path):
+    image_path = tmp_path / "image.h5"
+    mask_path = tmp_path / "mask.h5"
+    baseline_path = tmp_path / "baseline-prediction.h5"
+    candidate_path = tmp_path / "candidate-prediction.h5"
+    image = np.arange(8 * 16 * 16, dtype=np.uint8).reshape(8, 16, 16)
+    mask = np.zeros((8, 16, 16), dtype=np.uint16)
+    mask[:, 4:12, 5:13] = 7
+    baseline = mask.copy()
+    baseline[:, :, :7] = 0
+    candidate = mask.copy()
+    for path, dataset, array in [
+        (image_path, "main", image),
+        (mask_path, "data", mask),
+        (baseline_path, "prediction", baseline),
+        (candidate_path, "prediction", candidate),
+    ]:
+        with h5py.File(path, "w") as handle:
+            handle.create_dataset(dataset, data=array)
+
+    report = run_closed_loop_smoke(
+        pathlib.Path(tmp_path / "smoke"),
+        image_path=str(image_path),
+        mask_path=str(mask_path),
+        image_dataset="main",
+        mask_dataset="data",
+        baseline_prediction_path=str(baseline_path),
+        candidate_prediction_path=str(candidate_path),
+        baseline_dataset="prediction",
+        candidate_dataset="prediction",
+        crop="0:4,0:12,0:12",
+    )
+
+    assert report["artifact_mode"] == "real_pair_real_predictions"
+    assert report["ready_for_case_study"] is True
+    assert report["metric_summary"]["candidate_improved_dice"] is True
+    assert report["metric_summary"]["dice_delta"] > 0
+    assert report["source_data"]["baseline_dataset"] == "prediction"
+    assert report["source_data"]["candidate_dataset"] == "prediction"
+    assert (
+        "real prediction artifacts supplied by caller"
+        in report["real_checks_exercised"]
+    )
+    assert not any(
+        item.startswith("baseline/candidate predictions derived")
+        for item in report["simulated_or_not_exercised"]
+    )
+
+
+def test_closed_loop_smoke_requires_explicit_ground_truth_in_real_pair_mode(tmp_path):
+    image_path = tmp_path / "image.tif"
+    mask_path = tmp_path / "mask.tif"
+    image_path.write_text("image", encoding="utf-8")
+    mask_path.write_text("mask", encoding="utf-8")
+
+    with pytest.raises(ValueError, match="explicit --ground-truth-path"):
+        run_closed_loop_smoke(
+            pathlib.Path(tmp_path / "smoke"),
+            image_path=str(image_path),
+            mask_path=str(mask_path),
+            require_explicit_ground_truth=True,
+        )
+
+
+def test_closed_loop_smoke_accepts_channel_first_pytc_predictions(tmp_path):
+    image_path = tmp_path / "image.h5"
+    mask_path = tmp_path / "mask.h5"
+    baseline_path = tmp_path / "baseline-result_xy.h5"
+    candidate_path = tmp_path / "candidate-result_xy.h5"
+    image = np.arange(8 * 16 * 16, dtype=np.uint8).reshape(8, 16, 16)
+    mask = np.zeros((8, 16, 16), dtype=np.uint16)
+    mask[:, 4:12, 5:13] = 1
+    baseline = np.stack([np.zeros_like(mask), mask.copy()])
+    baseline[1, :, :, :7] = 0
+    candidate = np.stack([np.zeros_like(mask), mask.copy()])
+    for path, dataset, array in [
+        (image_path, "main", image),
+        (mask_path, "data", mask),
+        (baseline_path, "vol0", baseline),
+        (candidate_path, "vol0", candidate),
+    ]:
+        with h5py.File(path, "w") as handle:
+            handle.create_dataset(dataset, data=array)
+
+    report = run_closed_loop_smoke(
+        pathlib.Path(tmp_path / "smoke"),
+        image_path=str(image_path),
+        mask_path=str(mask_path),
+        image_dataset="main",
+        mask_dataset="data",
+        baseline_prediction_path=str(baseline_path),
+        candidate_prediction_path=str(candidate_path),
+        baseline_dataset="vol0",
+        candidate_dataset="vol0",
+        baseline_channel=1,
+        candidate_channel=1,
+        crop="0:4,0:12,0:12",
+    )
+
+    assert report["artifact_mode"] == "real_pair_real_predictions"
+    assert report["ready_for_case_study"] is True
+    assert report["metric_summary"]["candidate_improved_dice"] is True
+    assert report["source_data"]["baseline_channel"] == 1
+    assert report["source_data"]["candidate_channel"] == 1
+
+
+def test_closed_loop_smoke_rejects_partial_real_prediction_inputs(tmp_path):
+    with pytest.raises(ValueError, match="requires both baseline_prediction_path"):
+        run_closed_loop_smoke(
+            pathlib.Path(tmp_path / "smoke"),
+            image_path=str(tmp_path / "missing-image.h5"),
+            mask_path=str(tmp_path / "missing-mask.h5"),
+            baseline_prediction_path=str(tmp_path / "baseline.h5"),
+        )
diff --git a/tests/test_ehtool_data_manager.py b/tests/test_ehtool_data_manager.py
new file mode 100644
index 00000000..b289e30f
--- /dev/null
+++ b/tests/test_ehtool_data_manager.py
@@ -0,0 +1,119 @@
+import numpy as np
+import pytest
+import tifffile
+
+from server_api.ehtool.data_manager import DataManager
+from server_api.ehtool.utils import array_to_base64, glasbey_color, labels_to_rgba
+
+h5py = pytest.importorskip("h5py")
+
+
+def test_semantic_mask_edits_persist_instance_artifact_and_binary_mask(tmp_path):
+    image_path = tmp_path / "image.tif"
+    mask_path = tmp_path / "mask.tif"
+
+    image = np.zeros((2, 8, 8), dtype=np.uint8)
+    mask = np.zeros((2, 8, 8), dtype=np.uint8)
+    mask[0, 1:3, 1:3] = 255
+    mask[0, 5:7, 5:7] = 255
+    tifffile.imwrite(str(image_path), image)
+    tifffile.imwrite(str(mask_path), mask)
+
+    manager = DataManager()
+    manager.load_dataset(str(image_path), str(mask_path))
+    manager.ensure_instances()
+
+    assert manager.instance_mode == "semantic"
+    instance_id = manager.instances[0]["id"]
+
+    edited_active_mask = np.zeros((8, 8), dtype=np.uint8)
+    edited_active_mask[0:4, 0:4] = 255
+    result = manager.save_instance_mask_slice(
+        instance_id=instance_id,
+        axis="xy",
+        index=0,
+        mask_base64=array_to_base64(edited_active_mask, format="PNG"),
+    )
+
+    assert result["pixels_changed"] > 0
+    assert manager.mask_volume[0, 0, 0] == 255
+    assert manager.mask_volume[0, 4, 4] == 0
+    assert manager.instance_artifact_path
+    assert (tmp_path / ".pytc_instance_labels.tif").exists()
+    assert (tmp_path / ".pytc_proofreading.json").exists()
+
+    reloaded = DataManager()
+    reloaded.load_dataset(str(image_path), str(mask_path))
+    reloaded.ensure_instances()
+
+    assert reloaded.instance_mode == "semantic"
+    assert reloaded.mask_volume[0, 0, 0] == 255
+    assert reloaded.instance_volume[0, 0, 0] == instance_id
+
+
+def test_side_axis_active_mask_uses_original_instance_labels(tmp_path):
+    image_path = tmp_path / "image.tif"
+    mask_path = tmp_path / "mask.tif"
+
+    image = np.zeros((3, 5, 5), dtype=np.uint8)
+    mask = np.zeros((3, 5, 5), dtype=np.uint16)
+    mask[:, 2, 1:4] = 300
+    mask[0, 0, 0] = 301
+    mask[2, 4, 4] = 302
+    tifffile.imwrite(str(image_path), image)
+    tifffile.imwrite(str(mask_path), mask)
+
+    manager = DataManager()
+    manager.load_dataset(str(image_path), str(mask_path))
+    manager.ensure_instances()
+
+    image_slice, label_slice, active_mask, index, total = (
+        manager.get_instance_slice_axis(
+            instance_id=300,
+            axis="zx",
+            index=2,
+        )
+    )
+
+    assert index == 2
+    assert total == 5
+    assert image_slice.shape == label_slice.shape == active_mask.shape
+    assert np.count_nonzero(active_mask) == 9
+
+
+def test_labels_to_rgba_vectorized_overlay_preserves_large_label_colors():
+    labels = np.zeros((4, 5), dtype=np.uint16)
+    labels[0, 0] = 1
+    labels[1, 2] = 300
+    labels[3, 4] = 1025
+
+    rgba = labels_to_rgba(labels)
+
+    assert rgba.shape == (4, 5, 4)
+    assert tuple(rgba[0, 0, :3]) == glasbey_color(1)
+    assert tuple(rgba[1, 2, :3]) == glasbey_color(300)
+    assert tuple(rgba[3, 4, :3]) == glasbey_color(1025)
+    assert rgba[0, 1, 3] == 0
+    assert rgba[1, 2, 3] == 255
+
+
+def test_hdf5_project_load_accepts_main_and_data_dataset_names(tmp_path):
+    image_path = tmp_path / "image-main.h5"
+    mask_path = tmp_path / "mask-data.h5"
+
+    image = np.zeros((3, 8, 8), dtype=np.uint8)
+    mask = np.zeros((3, 8, 8), dtype=np.uint16)
+    mask[:, 2:4, 2:4] = 7
+    with h5py.File(image_path, "w") as handle:
+        handle.create_dataset("main", data=image)
+    with h5py.File(mask_path, "w") as handle:
+        handle.create_dataset("data", data=mask)
+
+    manager = DataManager()
+    result = manager.load_dataset(str(image_path), str(mask_path))
+
+    assert result["total_layers"] == 3
+    assert result["is_3d"] is True
+    assert manager.image_volume.shape == (3, 8, 8)
+    assert manager.mask_volume.shape == (3, 8, 8)
+    assert manager.mask_volume.dtype == np.uint16
diff --git a/tests/test_ehtool_mesh_preview.py b/tests/test_ehtool_mesh_preview.py
new file mode 100644
index 00000000..700027ee
--- /dev/null
+++ b/tests/test_ehtool_mesh_preview.py
@@ -0,0 +1,32 @@
+import numpy as np
+
+from server_api.ehtool.router import _extract_marching_cubes_surface
+
+
+class FakeMeasure:
+    def __init__(self):
+        self.steps = []
+
+    def marching_cubes(self, _volume, level, step_size, allow_degenerate):
+        self.steps.append(step_size)
+        face_count = 120 if step_size == 1 else 40
+        vertices = np.zeros((face_count * 3, 3), dtype=np.float32)
+        faces = np.arange(face_count * 3, dtype=np.int64).reshape(face_count, 3)
+        normals = np.zeros_like(vertices)
+        values = np.zeros((vertices.shape[0],), dtype=np.float32)
+        return vertices, faces, normals, values
+
+
+def test_mesh_extraction_raises_stride_instead_of_dropping_faces():
+    measure = FakeMeasure()
+
+    _vertices, faces, _normals, _values, mesh_step = _extract_marching_cubes_surface(
+        measure,
+        np.zeros((4, 4, 4), dtype=np.float32),
+        initial_step=1,
+        face_limit=60,
+    )
+
+    assert measure.steps == [1, 2]
+    assert mesh_step == 2
+    assert faces.shape[0] == 40
diff --git a/tests/test_file_workspace_routes.py b/tests/test_file_workspace_routes.py
index 7d64c74a..26c7510b 100644
--- a/tests/test_file_workspace_routes.py
+++ b/tests/test_file_workspace_routes.py
@@ -2,6 +2,7 @@
 import shutil
 import tempfile
 import unittest
+import json
 
 from fastapi.testclient import TestClient
 from sqlalchemy import create_engine
@@ -9,6 +10,7 @@
 
 from server_api.auth import database as auth_database
 from server_api.auth import models
+from server_api.auth.router import _scan_project_profile
 from server_api.main import app as server_api_app
 
 
@@ -86,6 +88,10 @@ def test_mount_directory_skips_os_metadata_files(self):
         mount_root = pathlib.Path(self.temp_dir.name) / "project"
         mount_root.mkdir()
         (mount_root / ".DS_Store").write_text("junk", encoding="utf-8")
+        (mount_root / ".pytc_project_context.json").write_text(
+            '{"schema_version":"pytc-project-context/v1"}',
+            encoding="utf-8",
+        )
         (mount_root / "volume.tif").write_text("data", encoding="utf-8")
 
         response = self.client.post(
@@ -106,6 +112,7 @@ def test_mount_directory_skips_os_metadata_files(self):
         self.assertIn("project", names)
         self.assertIn("volume.tif", names)
         self.assertNotIn(".DS_Store", names)
+        self.assertNotIn(".pytc_project_context.json", names)
 
         root_response = self.client.get("/files", params={"parent": "root"})
         self.assertEqual(root_response.status_code, 200)
@@ -120,11 +127,115 @@ def test_mount_directory_skips_os_metadata_files(self):
         child_names = [item["name"] for item in child_response.json()]
         self.assertEqual(child_names, ["volume.tif"])
 
+    def test_missing_parent_file_listing_returns_404(self):
+        response = self.client.get("/files", params={"parent": "999999"})
+
+        self.assertEqual(response.status_code, 404)
+        self.assertIn("no longer mounted", response.json()["detail"])
+
+    def test_project_context_profile_is_saved_in_hidden_project_file(self):
+        project_root = pathlib.Path(self.temp_dir.name) / "profile-project"
+        project_root.mkdir()
+        mount_response = self.client.post(
+            "/files/mount",
+            json={
+                "directory_path": str(project_root),
+                "destination_path": "root",
+            },
+        )
+        self.assertEqual(mount_response.status_code, 200)
+
+        write_response = self.client.put(
+            "/files/project-context",
+            json={
+                "directory_path": str(project_root),
+                "profile": {
+                    "project_name": "profile-project",
+                    "semantic_context": {
+                        "imaging_modality": "EM",
+                        "target_structure": "mitochondria",
+                    },
+                    "mechanistic_mapping": {"image": "data/image"},
+                },
+            },
+        )
+        self.assertEqual(write_response.status_code, 200)
+        context_path = project_root / ".pytc_project_context.json"
+        self.assertTrue(context_path.exists())
+
+        read_response = self.client.get(
+            "/files/project-context",
+            params={"directory_path": str(project_root)},
+        )
+        self.assertEqual(read_response.status_code, 200)
+        payload = read_response.json()
+        self.assertTrue(payload["exists"])
+        self.assertEqual(
+            payload["profile"]["schema_version"],
+            "pytc-project-context/v1",
+        )
+        self.assertEqual(
+            payload["profile"]["semantic_context"]["target_structure"],
+            "mitochondria",
+        )
+
+    def test_project_context_profile_can_be_deleted(self):
+        project_root = pathlib.Path(self.temp_dir.name) / "profile-project-delete"
+        project_root.mkdir()
+        mount_response = self.client.post(
+            "/files/mount",
+            json={
+                "directory_path": str(project_root),
+                "destination_path": "root",
+            },
+        )
+        self.assertEqual(mount_response.status_code, 200)
+        context_path = project_root / ".pytc_project_context.json"
+        context_path.write_text(
+            '{"schema_version":"pytc-project-context/v1"}',
+            encoding="utf-8",
+        )
+
+        response = self.client.delete(
+            "/files/project-context",
+            params={"directory_path": str(project_root)},
+        )
+
+        self.assertEqual(response.status_code, 200)
+        self.assertTrue(response.json()["deleted"])
+        self.assertFalse(context_path.exists())
+
+    def test_project_profile_infers_voxel_size_from_notes(self):
+        project_root = pathlib.Path(self.temp_dir.name) / "resolution-project"
+        project_root.mkdir()
+        (project_root / "README.md").write_text(
+            "EM mitochondria segmentation. Voxel size: 40 x 4 x 4 nm.",
+            encoding="utf-8",
+        )
+        (project_root / "image.h5").write_text("placeholder", encoding="utf-8")
+        (project_root / "label.h5").write_text("placeholder", encoding="utf-8")
+
+        profile = _scan_project_profile(str(project_root))
+
+        self.assertEqual(
+            profile["context_hints"]["voxel_size_nm"],
+            [40.0, 4.0, 4.0],
+        )
+        self.assertEqual(
+            profile["schema"]["context_hints"]["voxel_size_nm"],
+            [40.0, 4.0, 4.0],
+        )
+
     def test_reset_workspace_preserves_mounted_sources_and_clears_uploads(self):
         mount_root = pathlib.Path(self.temp_dir.name) / "mounted-project"
         mount_root.mkdir()
         mounted_file = mount_root / "volume.tif"
         mounted_file.write_text("data", encoding="utf-8")
+        context_file = mount_root / ".pytc_project_context.json"
+        context_file.write_text(
+            '{"schema_version":"pytc-project-context/v1"}',
+            encoding="utf-8",
+        )
 
         mount_response = self.client.post(
             "/files/mount",
@@ -150,6 +261,7 @@ def test_reset_workspace_preserves_mounted_sources_and_clears_uploads(self):
         self.assertEqual(response.json()["mounted_root_count"], 1)
         self.assertTrue(mount_root.exists())
         self.assertTrue(mounted_file.exists())
+        self.assertTrue(context_file.exists())
         self.assertFalse(upload_file.exists())
         self.assertTrue(self.uploads_root.exists())
 
@@ -157,6 +269,461 @@ def test_reset_workspace_preserves_mounted_sources_and_clears_uploads(self):
         self.assertEqual(files_response.status_code, 200)
         self.assertEqual(files_response.json(), [])
 
+    def test_get_files_repairs_renamed_mounted_file_entries(self):
+        mount_root = pathlib.Path(self.temp_dir.name) / "project"
+        mount_root.mkdir()
+        original_file = mount_root / "volume.h5"
+        original_file.write_bytes(b"data")
+
+        mount_response = self.client.post(
+            "/files/mount",
+            json={
+                "directory_path": str(mount_root),
+                "destination_path": "root",
+            },
+        )
+        self.assertEqual(mount_response.status_code, 200)
+        mounted_root_id = mount_response.json()["mounted_root_id"]
+
+        renamed_file = mount_root / "volume_im.h5"
+        original_file.rename(renamed_file)
+
+        child_response = self.client.get(
+            "/files",
+            params={"parent": str(mounted_root_id)},
+        )
+        self.assertEqual(child_response.status_code, 200)
+
+        child_entries = child_response.json()
+        self.assertEqual([item["name"] for item in child_entries], ["volume_im.h5"])
+        self.assertEqual(child_entries[0]["physical_path"], str(renamed_file))
+
+    def test_get_files_prunes_missing_managed_upload_entries(self):
+        missing_upload = self.uploads_root / "ghost.h5"
+        self._create_file(
+            name="ghost.h5",
+            physical_path=str(missing_upload),
+            size="10B",
+            file_type="application/x-hdf5",
+        )
+
+        response = self.client.get("/files")
+        self.assertEqual(response.status_code, 200)
+        returned_names = [item["name"] for item in response.json()]
+        self.assertNotIn("ghost.h5", returned_names)
+
+        with self.SessionLocal() as db:
+            ghost = db.query(models.File).filter(models.File.name == "ghost.h5").first()
+            self.assertIsNone(ghost)
+
+    def test_project_suggestions_marks_existing_smoke_project_mount(self):
+        repo_root = pathlib.Path(__file__).resolve().parents[1]
+        workspace_root = repo_root.parent
+        smoke_project = repo_root / "testing_projects" / "mito25_paper_loop_smoke"
+        smoke_project.mkdir(parents=True, exist_ok=True)
+        snemi_project = workspace_root / "testing_data" / "snemi"
+        snemi_project.mkdir(parents=True, exist_ok=True)
+
+        response = self.client.get("/files/project-suggestions")
+        self.assertEqual(response.status_code, 200)
+        suggestions = response.json()
+        smoke_suggestion = next(
+            item for item in suggestions if item["id"] == "mito25-paper-loop-smoke"
+        )
+        self.assertTrue(
+            any(item["id"] == "snemi-proofreading-data" for item in suggestions)
+        )
+        self.assertFalse(smoke_suggestion["already_mounted"])
+
+        mount_response = self.client.post(
+            "/files/mount",
+            json={
+                "directory_path": str(smoke_project),
+                "destination_path": "root",
+                "mount_name": "mito25-paper-loop-smoke",
+            },
+        )
+        self.assertEqual(mount_response.status_code, 200)
+
+        mounted_response = self.client.get("/files/project-suggestions")
+        self.assertEqual(mounted_response.status_code, 200)
+        mounted_smoke = next(
+            item
+            for item in mounted_response.json()
+            if item["id"] == "mito25-paper-loop-smoke"
+        )
+        self.assertTrue(mounted_smoke["already_mounted"])
+        self.assertEqual(
+            mounted_smoke["mounted_root_id"],
+            mount_response.json()["mounted_root_id"],
+        )
+        self.assertIn("profile", mounted_smoke)
+
+    def test_users_me_projects_lists_owned_mounted_projects(self):
+        project_root = pathlib.Path(self.temp_dir.name) / "owned-project"
+        image_dir = project_root / "data" / "image"
+        label_dir = project_root / "data" / "seg"
+        image_dir.mkdir(parents=True)
+        label_dir.mkdir(parents=True)
+        (image_dir / "sample_im.h5").write_bytes(b"image")
+        (label_dir / "sample_seg.h5").write_bytes(b"label")
+
+        mount_response = self.client.post(
+            "/files/mount",
+            json={
+                "directory_path": str(project_root),
+                "destination_path": "root",
+                "mount_name": "Owned Demo",
+            },
+        )
+        self.assertEqual(mount_response.status_code, 200)
+
+        response = self.client.get("/users/me/projects")
+
+        self.assertEqual(response.status_code, 200)
+        payload = response.json()
+        self.assertEqual(payload["user"]["username"], "guest")
+        self.assertEqual(len(payload["mounted_projects"]), 1)
+        project = payload["mounted_projects"][0]
+        self.assertEqual(project["name"], "Owned Demo")
+        self.assertEqual(project["directory_path"], str(project_root))
+        self.assertEqual(
+            project["mounted_root_id"],
+            mount_response.json()["mounted_root_id"],
+        )
+        self.assertGreaterEqual(project["mounted_folders"], 2)
+        self.assertEqual(project["mounted_files"], 2)
+        self.assertEqual(project["profile"]["counts"]["image"], 1)
+        self.assertEqual(project["profile"]["counts"]["label"], 1)
+
+    def test_project_profile_detects_smoke_project_roles(self):
+        project_root = pathlib.Path(self.temp_dir.name) / "project-profile"
+        (project_root / "data" / "image").mkdir(parents=True)
+        (project_root / "data" / "seg").mkdir(parents=True)
+        (project_root / "configs").mkdir()
+        (project_root / "checkpoints").mkdir()
+        (project_root / "predictions").mkdir()
+        (project_root / "data" / "image" / "mito25_smoke_im.h5").write_bytes(b"im")
+        (project_root / "data" / "seg" / "mito25_smoke_seg.h5").write_bytes(b"seg")
+        (project_root / "configs" / "Mito25-Local-Smoke.yaml").write_text(
+            "SYSTEM: {}\n", encoding="utf-8"
+        )
+        (project_root / "checkpoints" / "checkpoint_00001.pth.tar").write_bytes(b"ckpt")
+        (project_root / "predictions" / "baseline_result_xy.h5").write_bytes(
+            b"baseline"
+        )
+        (project_root / "predictions" / "candidate_result_xy.h5").write_bytes(
+            b"candidate"
+        )
+
+        profile = _scan_project_profile(str(project_root))
+
+        self.assertTrue(profile["ready_for_smoke"])
+        self.assertEqual(profile["counts"]["image"], 1)
+        self.assertEqual(profile["counts"]["label"], 1)
+        self.assertEqual(profile["counts"]["prediction"], 2)
+        self.assertEqual(profile["counts"]["config"], 1)
+        self.assertEqual(profile["counts"]["checkpoint"], 1)
+        self.assertEqual(profile["schema"]["schema_version"], "pytc-project-profile/v1")
+        self.assertTrue(profile["schema"]["workable"])
+        self.assertEqual(profile["schema"]["mode"], "closed_loop_ready")
+        self.assertEqual(profile["schema"]["stages"]["inference"]["status"], "ready")
+        self.assertEqual(
+            profile["paired_examples"],
+            [
+                {
+                    "image": "data/image/mito25_smoke_im.h5",
+                    "label": "data/seg/mito25_smoke_seg.h5",
+                }
+            ],
+        )
+
+    def test_project_profile_treats_image_only_volume_as_workable_start(self):
+        project_root = pathlib.Path(self.temp_dir.name) / "image-only-project"
+        (project_root / "raw").mkdir(parents=True)
+        (project_root / "raw" / "sample_volume.ome.tif").write_bytes(b"image")
+
+        profile = _scan_project_profile(str(project_root))
+
+        self.assertFalse(profile["ready_for_smoke"])
+        self.assertEqual(profile["counts"]["image"], 1)
+        self.assertTrue(profile["schema"]["workable"])
+        self.assertEqual(profile["schema"]["mode"], "image_only")
+        self.assertEqual(
+            profile["schema"]["primary_paths"]["image"],
+            "raw/sample_volume.ome.tif",
+        )
+        self.assertEqual(
+            profile["schema"]["stages"]["visualization"]["status"], "ready"
+        )
+        self.assertEqual(
+            profile["schema"]["stages"]["inference"]["status"],
+            "needs_input",
+        )
+        self.assertEqual(
+            profile["schema"]["stages"]["inference"]["missing"],
+            ["checkpoint"],
+        )
+
+    def test_project_profile_groups_multi_volume_batches_by_directory(self):
+        project_root = pathlib.Path(self.temp_dir.name) / "batch-profile"
+        image_dir = project_root / "data" / "source" / "Image" / "train"
+        label_dir = project_root / "data" / "source" / "Label" / "train"
+        image_dir.mkdir(parents=True)
+        label_dir.mkdir(parents=True)
+        (project_root / "configs").mkdir()
+        (project_root / "checkpoints").mkdir()
+        for index in range(4):
+            (image_dir / f"crop_{index:03d}_im.h5").write_bytes(b"im")
+            (label_dir / f"crop_{index:03d}_seg.h5").write_bytes(b"seg")
+        (project_root / "configs" / "batch.yaml").write_text(
+            "SYSTEM: {}\n", encoding="utf-8"
+        )
+        (project_root / "checkpoints" / "model.pth.tar").write_bytes(b"ckpt")
+
+        profile = _scan_project_profile(str(project_root))
+
+        self.assertEqual(profile["counts"]["image"], 4)
+        self.assertEqual(profile["counts"]["label"], 4)
+        self.assertEqual(
+            profile["role_directories"]["image"][0],
+            {
+                "path": "data/source/Image/train",
+                "count": 4,
+                "examples": [
+                    "data/source/Image/train/crop_000_im.h5",
+                    "data/source/Image/train/crop_001_im.h5",
+                    "data/source/Image/train/crop_002_im.h5",
+                ],
+            },
+        )
+        self.assertEqual(
+            profile["schema"]["primary_paths"]["image_root"],
+            "data/source/Image/train",
+        )
+        self.assertEqual(
+            profile["schema"]["primary_paths"]["label_root"],
+            "data/source/Label/train",
+        )
+        self.assertEqual(profile["volume_sets"][0]["image_count"], 4)
+        self.assertEqual(profile["volume_sets"][0]["label_count"], 4)
+        self.assertEqual(profile["volume_sets"][0]["pair_count"], 4)
+
+    def test_project_profile_prefers_manifest_volume_map(self):
+        project_root = pathlib.Path(self.temp_dir.name) / "manifest-profile"
+        raw_dir = project_root / "data" / "raw"
+        seg_dir = project_root / "data" / "seg"
+        train_dir = project_root / "data" / "pytc_train" / "1"
+        config_dir = project_root / "configs"
+        raw_dir.mkdir(parents=True)
+        seg_dir.mkdir(parents=True)
+        train_dir.mkdir(parents=True)
+        config_dir.mkdir()
+        for volume_id in ["1", "2", "3"]:
+            (raw_dir / volume_id).mkdir()
+            (raw_dir / volume_id / f"{volume_id}-xri_raw.tif").write_bytes(b"raw")
+        for volume_id in ["1", "2"]:
+            (seg_dir / volume_id).mkdir()
+            (seg_dir / volume_id / f"{volume_id}-mask.tif").write_bytes(b"mask")
+        (train_dir / "1-xri_raw-tiled_clahe.tif").write_bytes(b"train raw")
+        (train_dir / "1-annotated_mask.tif").write_bytes(b"train mask")
+        (config_dir / "TapeReader-Fiber-BCS-AppCompat-Sanity.yaml").write_text(
+            "SYSTEM: {}\n", encoding="utf-8"
+        )
+        (project_root / "project_manifest.json").write_text(
+            json.dumps(
+                {
+                    "title": "Yixiao TapeReader XRI Case Study",
+                    "task": "CytoTape fibre instance segmentation",
+                    "imaging_modality": "X-ray / XRI volumetric microscopy",
+                    "target_structure": "CytoTape fibres",
+                    "task_family": "XRI fibre instance segmentation",
+                    "active_paths": {
+                        "image_root": "data/raw",
+                        "label_root": "data/seg",
+                        "config": "configs/TapeReader-Fiber-BCS-AppCompat-Sanity.yaml",
+                    },
+                    "initial_progress_summary": {
+                        "ground_truth": 2,
+                        "needs_proofreading": 0,
+                        "missing_segmentation": 1,
+                    },
+                    "workflow_split": {
+                        "ground_truth_training_volumes": ["1", "2"],
+                        "image_only_inference_targets": ["3"],
+                    },
+                    "voxel_size": {"zyx_nm": [40, 16.3, 16.3]},
+                    "volumes": [
+                        {
+                            "id": "1",
+                            "status": "ground_truth",
+                            "image": "data/raw/1/1-xri_raw.tif",
+                            "segmentation": "data/seg/1/1-mask.tif",
+                        },
+                        {
+                            "id": "2",
+                            "status": "ground_truth",
+                            "image": "data/raw/2/2-xri_raw.tif",
+                            "segmentation": "data/seg/2/2-mask.tif",
+                        },
+                        {
+                            "id": "3",
+                            "status": "missing_segmentation",
+                            "image": "data/raw/3/3-xri_raw.tif",
+                            "segmentation": None,
+                        },
+                    ],
+                }
+            ),
+            encoding="utf-8",
+        )
+
+        profile = _scan_project_profile(str(project_root))
+
+        self.assertEqual(profile["role_directories"]["image"][0]["path"], "data/raw")
+        self.assertEqual(profile["role_directories"]["label"][0]["path"], "data/seg")
+        self.assertEqual(
+            profile["schema"]["primary_paths"]["image"], "data/raw/1/1-xri_raw.tif"
+        )
+        self.assertEqual(
+            profile["schema"]["primary_paths"]["label"], "data/seg/1/1-mask.tif"
+        )
+        self.assertEqual(
+            profile["schema"]["primary_paths"]["config"],
+            "configs/TapeReader-Fiber-BCS-AppCompat-Sanity.yaml",
+        )
+        self.assertEqual(profile["schema"]["primary_paths"]["image_root"], "data/raw")
+        self.assertEqual(profile["schema"]["primary_paths"]["label_root"], "data/seg")
+        self.assertEqual(profile["volume_sets"][0]["source"], "project_manifest")
+        self.assertEqual(profile["volume_sets"][0]["image_count"], 3)
+        self.assertEqual(profile["volume_sets"][0]["label_count"], 2)
+        self.assertEqual(profile["volume_sets"][0]["pair_count"], 2)
+        self.assertEqual(
+            profile["context_hints"]["task_family"],
+            "XRI fibre instance segmentation",
+        )
+        self.assertEqual(profile["context_hints"]["voxel_size_nm"], [40, 16.3, 16.3])
+
+    def test_project_profile_uses_content_for_context_hints(self):
+        project_root = pathlib.Path(self.temp_dir.name) / "content-profile"
+        (project_root / "volumes").mkdir(parents=True)
+        (project_root / "volumes" / "raw_image.h5").write_bytes(b"not-real-hdf5")
+        (project_root / "project_manifest.json").write_text(
+            json.dumps(
+                {
+                    "task": "Mitochondria semantic segmentation benchmark",
+                    "notes": [
+                        "Electron microscopy volume with expert masks.",
+                        "Prioritize segmentation accuracy.",
+                    ],
+                }
+            ),
+            encoding="utf-8",
+        )
+
+        profile = _scan_project_profile(str(project_root))
+
+        self.assertEqual(profile["content_signals"]["extension_counts"][".h5"], 1)
+        self.assertEqual(profile["content_signals"]["extension_counts"][".json"], 1)
+        self.assertEqual(
+            profile["content_signals"]["text_sources"][0]["path"],
+            "project_manifest.json",
+        )
+        self.assertEqual(profile["context_hints"]["imaging_modality"], "EM")
+        self.assertEqual(profile["context_hints"]["target_structure"], "mitochondria")
+        self.assertEqual(profile["context_hints"]["task_goal"], "segmentation")
+        self.assertEqual(profile["context_hints"]["optimization_priority"], "accuracy")
+
+    def test_project_profile_spot_checks_hdf5_dataset_keys(self):
+        try:
+            import h5py
+        except Exception:
+            self.skipTest("h5py not installed")
+
+        project_root = pathlib.Path(self.temp_dir.name) / "hdf5-profile"
+        project_root.mkdir()
+        h5_path = project_root / "sample_volume.h5"
+        with h5py.File(h5_path, "w") as handle:
+            handle.create_dataset("volumes/raw", data=[[[1, 2], [3, 4]]])
+            handle.create_dataset("volumes/labels/neuron_ids", data=[[[1, 1], [2, 2]]])
+
+        profile = _scan_project_profile(str(project_root))
+        metadata = profile["content_signals"]["volume_metadata"][0]
+
+        self.assertTrue(metadata["readable"])
+        self.assertEqual(metadata["format"], "hdf5")
+        self.assertEqual(
+            [dataset["path"] for dataset in metadata["datasets"]],
+            ["volumes/labels/neuron_ids", "volumes/raw"],
+        )
+        self.assertEqual(profile["context_hints"]["target_structure"], "neurites")
+
+    def test_project_profile_audits_hdf5_pairs_and_metadata_facts(self):
+        try:
+            import h5py
+        except Exception:
+            self.skipTest("h5py not installed")
+
+        project_root = pathlib.Path(self.temp_dir.name) / "hdf5-audit-profile"
+        image_dir = project_root / "data" / "image"
+        label_dir = project_root / "data" / "seg"
+        image_dir.mkdir(parents=True)
+        label_dir.mkdir(parents=True)
+        with h5py.File(image_dir / "sample_im.h5", "w") as handle:
+            handle.attrs["voxel_size_nm_zyx"] = [30, 8, 8]
+            handle.create_dataset(
+                "volumes/raw",
+                data=[
+                    [[1, 2, 3], [4, 5, 6]],
+                    [[7, 8, 9], [10, 11, 12]],
+                ],
+            )
+        with h5py.File(label_dir / "sample_seg.h5", "w") as handle:
+            handle.create_dataset(
+                "volumes/labels/mitochondria",
+                data=[
+                    [[0, 1, 1], [0, 0, 2]],
+                    [[0, 2, 2], [0, 0, 0]],
+                ],
+            )
+
+        profile = _scan_project_profile(str(project_root))
+        audit = profile["audit"]
+
+        self.assertEqual(audit["schema_version"], "pytc-project-audit/v1")
+        self.assertEqual(audit["summary"]["audited_volumes"], 2)
+        self.assertEqual(audit["summary"]["readable_volumes"], 2)
+        self.assertEqual(audit["summary"]["shape_match_count"], 1)
+        self.assertEqual(profile["context_hints"]["voxel_size_nm"], [30, 8, 8])
+        self.assertEqual(
+            profile["context_hints"]["voxel_size_source"],
+            "volume_metadata:data/image/sample_im.h5",
+        )
+        self.assertEqual(
+            audit["pair_checks"][0],
+            {
+                "image": "data/image/sample_im.h5",
+                "label": "data/seg/sample_seg.h5",
+                "image_shape": [2, 2, 3],
+                "label_shape": [2, 2, 3],
+                "shape_match": True,
+                "source": "volume_metadata",
+            },
+        )
+        self.assertEqual(
+            audit["context_facts"][0],
+            {
+                "key": "voxel_size_nm",
+                "label": "Voxel size",
+                "value": [30, 8, 8],
+                "unit": "nm",
+                "axis_order": "z,y,x",
+                "source": "volume_metadata:data/image/sample_im.h5",
+                "confidence": "high",
+            },
+        )
+        self.assertGreater(audit["volumes"][0]["stats"]["nonzero_fraction"], 0)
+
 
 if __name__ == "__main__":
     unittest.main()
diff --git a/tests/test_inline_helper_safe_mode.py b/tests/test_inline_helper_safe_mode.py
new file mode 100644
index 00000000..7e961e68
--- /dev/null
+++ b/tests/test_inline_helper_safe_mode.py
@@ -0,0 +1,154 @@
+from unittest.mock import patch
+
+import pytest
+
+pytest.importorskip("fastapi")
+from fastapi.testclient import TestClient
+
+from server_api.main import app as server_api_app
+
+
+def test_inline_helper_defaults_to_docs_mode_without_building_agent(monkeypatch):
+    monkeypatch.delenv("PYTC_INLINE_HELP_MODE", raising=False)
+    client = TestClient(server_api_app)
+
+    with patch("server_api.main.build_helper_chain") as build_helper_chain:
+        response = client.post(
+            "/chat/helper/query",
+            json={
+                "taskKey": "inference:advanced-config:Augmentations",
+                "query": "Explain this setting and recommend a concrete value.",
+                "fieldContext": 'Field: "Augmentations". YAML key: INFERENCE.AUG_NUM.',
+            },
+        )
+
+    assert response.status_code == 200
+    payload = response.json()
+    assert payload["mode"] == "docs"
+    assert "test-time transformed predictions" in payload["response"]
+    assert "AUG_NUM" in payload["response"]
+    build_helper_chain.assert_not_called()
+
+
+def test_inline_helper_gives_concise_file_picker_guidance(monkeypatch):
+    monkeypatch.delenv("PYTC_INLINE_HELP_MODE", raising=False)
+    client = TestClient(server_api_app)
+
+    response = client.post(
+        "/chat/helper/query",
+        json={
+            "taskKey": "training:Input Image",
+            "query": "What do I put here?",
+            "fieldContext": 'Field: "Input Image". YAML key: DATASET.INPUT_PATH.',
+        },
+    )
+
+    assert response.status_code == 200
+    payload = response.json()
+    assert payload["mode"] == "docs"
+    assert "folder icon" in payload["response"]
+    assert "Relevant local docs" not in payload["response"]
+    assert "Model Training Page" not in payload["response"]
+
+
+def test_inline_helper_followup_uses_same_field_history(monkeypatch):
+    monkeypatch.delenv("PYTC_INLINE_HELP_MODE", raising=False)
+    client = TestClient(server_api_app)
+
+    response = client.post(
+        "/chat/helper/query",
+        json={
+            "taskKey": "training:Input Image",
+            "query": "oooo cool....what does that mean?",
+            "fieldContext": 'Field: "Input Image". YAML key: DATASET.INPUT_PATH.',
+            "history": [
+                {
+                    "role": "assistant",
+                    "content": (
+                        "Select a volume file for H5/TIFF/NIfTI/Zarr-style data, "
+                        "or select a folder when the dataset is stored as a directory/stack."
+                    ),
+                }
+            ],
+        },
+    )
+
+    assert response.status_code == 200
+    payload = response.json()
+    assert payload["mode"] == "docs"
+    assert "common ways microscopy image volumes are stored" in payload["response"]
+    assert "Use the folder icon" not in payload["response"]
+
+
+def test_inline_helper_casual_message_does_not_dump_docs(monkeypatch):
+    monkeypatch.delenv("PYTC_INLINE_HELP_MODE", raising=False)
+    client = TestClient(server_api_app)
+
+    response = client.post(
+        "/chat/helper/query",
+        json={
+            "taskKey": "training:Input Image",
+            "query": "hi!",
+            "fieldContext": 'Field: "Input Image". YAML key: DATASET.INPUT_PATH.',
+        },
+    )
+
+    assert response.status_code == 200
+    payload = response.json()
+    assert payload["mode"] == "docs"
+    assert "Ask me about this specific field" in payload["response"]
+    assert "Relevant guidance" not in payload["response"]
+    assert "PyTC Training Guide" not in payload["response"]
+
+
+def test_inline_helper_agent_mode_reuses_shared_chain(monkeypatch):
+    monkeypatch.setenv("PYTC_INLINE_HELP_MODE", "agent")
+
+    import server_api.main as main
+
+    main._helper_chains.clear()
+    main._helper_histories.clear()
+    calls = []
+
+    class FakeAgent:
+        def invoke(self, payload):
+            return {
+                "messages": [
+                    type(
+                        "Message",
+                        (),
+                        {"content": f"reply {len(payload['messages'])}"},
+                    )()
+                ]
+            }
+
+    def fake_build_helper_chain():
+        calls.append("build")
+        return FakeAgent(), lambda: None
+
+    monkeypatch.setattr(main, "build_helper_chain", fake_build_helper_chain)
+    client = TestClient(server_api_app)
+
+    first = client.post(
+        "/chat/helper/query",
+        json={
+            "taskKey": "training:Input Image",
+            "query": "What do I put here?",
+            "fieldContext": 'Field: "Input Image".',
+        },
+    )
+    second = client.post(
+        "/chat/helper/query",
+        json={
+            "taskKey": "training:Input Label",
+            "query": "What do I put here?",
+            "fieldContext": 'Field: "Input Label".',
+        },
+    )
+
+    assert first.status_code == 200
+    assert second.status_code == 200
+    assert calls == ["build"]
+    assert main._SHARED_HELPER_CHAIN_KEY in main._helper_chains
+    assert "training:Input Image" in main._helper_histories
+    assert "training:Input Label" in main._helper_histories
diff --git a/tests/test_inspect_demo_instance.py b/tests/test_inspect_demo_instance.py
new file mode 100644
index 00000000..db6003fd
--- /dev/null
+++ b/tests/test_inspect_demo_instance.py
@@ -0,0 +1,407 @@
+from __future__ import annotations
+
+import json
+from argparse import Namespace
+from pathlib import Path
+from typing import Any
+from requests import exceptions as request_exceptions
+
+from scripts import inspect_demo_instance as diag
+
+
+def _write_json_lines(path: Path, rows: list[dict[str, Any]]) -> None:
+    path.write_text("\n".join(json.dumps(row) for row in rows), encoding="utf-8")
+
+
+def test_check_api_health_warns_for_bad_payload(monkeypatch):
+    def fake_request_json(*, base_url, path, **kwargs):
+        assert path == "/health"
+        assert base_url == "https://demo.seg.bio"
+        return 500, {"status": "down"}, None
+
+    monkeypatch.setattr(diag, "_http_request_json", fake_request_json)
+    result = diag.check_api_health(api_base="https://demo.seg.bio", timeout=1)
+    assert result.name == "api.health"
+    assert result.status == "warn"
+    assert result.details == {"status_code": 500, "payload": {"status": "down"}}
+
+
+def test_check_workflow_auth_warning(monkeypatch):
+    def fake_request_json(*, base_url, path, **kwargs):
+        return 401, {"detail": "Unauthorized"}, None
+
+    monkeypatch.setattr(diag, "_http_request_json", fake_request_json)
+    result = diag.check_workflow(api_base="http://127.0.0.1:4342", timeout=1)
+    assert result.name == "workflow.current"
+    assert result.status == "warn"
+    assert result.message == "Current workflow endpoint requires authentication"
+    assert result.details == {"status_code": 401}
+
+
+def test_check_runtime_events_reports_worker_mismatch(monkeypatch, tmp_path):
+    log_path = tmp_path / "app-events.jsonl"
+    _write_json_lines(
+        log_path,
+        [
+            {"event": "worker_proxy_request_started", "component": "server_api"},
+            {
+                "event": "api_runtime_configured",
+                "component": "server_api",
+                "worker_url": "http://expected-worker:4243",
+                "neuroglancer_port": 4244,
+                "neuroglancer_public_base": "https://demo.seg.bio/neuroglancer",
+            },
+        ],
+    )
+
+    results = diag.check_runtime_events(
+        app_log_path=log_path,
+        timeout_lines=100,
+        expected_worker_url="http://wrong-worker:4243",
+        neuroglancer_port=4244,
+        neuroglancer_public_base="https://demo.seg.bio/neuroglancer",
+    )
+    assert any(
+        item.name == "api.runtime_config" and item.status == "warn" for item in results
+    )
+    assert any(
+        item.name == "api.runtime_config_worker_url" and item.status == "warn"
+        for item in results
+    )
+    snapshot = next(item for item in results if item.name == "api.runtime_config")
+    assert snapshot.details == {
+        "expected": {
+            "worker_url": "http://wrong-worker:4243",
+            "neuroglancer_port": 4244,
+            "neuroglancer_public_base": "https://demo.seg.bio/neuroglancer",
+        },
+        "observed": {
+            "worker_url": "http://expected-worker:4243",
+            "neuroglancer_port": 4244,
+            "neuroglancer_public_base": "https://demo.seg.bio/neuroglancer",
+        },
+        "mismatches": ["worker_url"],
+    }
+    for row in results:
+        if row.name == "api.runtime_config_worker_url":
+            assert row.details["expected_worker_url"] == "http://wrong-worker:4243"
+            assert row.details["configured_worker_url"] == "http://expected-worker:4243"
+
+
+def test_check_runtime_events_reports_neuroglancer_port_mismatch(monkeypatch, tmp_path):
+    log_path = tmp_path / "app-events.jsonl"
+    _write_json_lines(
+        log_path,
+        [
+            {
+                "event": "api_runtime_configured",
+                "component": "server_api",
+                "worker_url": "http://worker:4243",
+                "neuroglancer_port": 4245,
+                "neuroglancer_public_base": "https://demo.seg.bio/neuroglancer",
+            },
+        ],
+    )
+
+    results = diag.check_runtime_events(
+        app_log_path=log_path,
+        timeout_lines=100,
+        expected_worker_url="http://worker:4243",
+        neuroglancer_port=4244,
+        neuroglancer_public_base="https://demo.seg.bio/neuroglancer",
+    )
+    snapshot = next(item for item in results if item.name == "api.runtime_config")
+    assert snapshot.status == "warn"
+    assert snapshot.details["mismatches"] == ["neuroglancer_port"]
+    assert snapshot.details["observed"]["neuroglancer_port"] == 4245
+
+
+def test_check_worker_path_detects_mismatched_proxy_target(monkeypatch, tmp_path):
+    log_path = tmp_path / "app-events.jsonl"
+    _write_json_lines(
+        log_path,
+        [
+            {
+                "component": "server_api",
+                "event": "worker_proxy_request_completed",
+                "path": "/training_status",
+                "worker_url": "http://proxy-target:4243",
+            }
+        ],
+    )
+
+    def fake_request_json(*, base_url, path, **kwargs):
+        if path == "/hello":
+            return 200, ["hello"], None
+        if path == "/training_status":
+            return 200, {"worker_url": "http://proxy-target:4243"}, None
+        raise AssertionError(f"unexpected path: {path}")
+
+    monkeypatch.setattr(diag, "_http_request_json", fake_request_json)
+    results = diag.check_worker_path(
+        api_base="https://demo.seg.bio",
+        expected_worker_url="http://expected:4243",
+        app_log_path=log_path,
+        timeout=1,
+    )
+    assert len(results) == 4
+    assert results[0].name == "worker.hello"
+    assert results[0].status == "pass"
+    mismatch = next(item for item in results if item.name == "worker.url_mismatch")
+    assert mismatch.status == "fail"
+    assert mismatch.details["expected_worker_url"] == "http://expected:4243"
+    assert mismatch.details["observed_worker_url"] == "http://proxy-target:4243"
+
+
+def test_check_worker_path_training_status_timeout_is_warning(monkeypatch, tmp_path):
+    log_path = tmp_path / "app-events.jsonl"
+    _write_json_lines(log_path, [])
+
+    def fake_request_json(*, base_url, path, **kwargs):
+        if path == "/hello":
+            return 200, ["hello"], None
+        if path == "/training_status":
+            raise request_exceptions.Timeout("temporary overload")
+        raise AssertionError(f"unexpected path: {path}")
+
+    monkeypatch.setattr(diag, "_http_request_json", fake_request_json)
+    results = diag.check_worker_path(
+        api_base="https://demo.seg.bio",
+        expected_worker_url="http://expected:4243",
+        app_log_path=log_path,
+        timeout=1,
+    )
+
+    training_result = next(
+        item for item in results if item.name == "api.training_status"
+    )
+    assert training_result.status == "warn"
+    assert "temporary overload" in training_result.details["error"]
+
+    mismatch = next(item for item in results if item.name == "worker.url_mismatch")
+    assert mismatch.status == "warn"
+    assert mismatch.details["expected_worker_url"] == "http://expected:4243"
+
+
+def test_check_disk_and_errors_uses_tail_for_error_count(tmp_path):
+    log_path = tmp_path / "app-events.jsonl"
+    rows = [
+        {"level": "ERROR", "event": "too_many"},
+        {"level": "INFO", "event": "ok"},
+        {"level": "ERROR", "event": "still_bad"},
+    ]
+    _write_json_lines(log_path, rows)
+    results = diag.check_disk_and_errors(
+        app_log_path=log_path,
+        workflow_bundle_dir=tmp_path / "workflow-bundles",
+        error_tail_lines=2,
+    )
+
+    error_result = next(row for row in results if row.name == "app_error_events")
+    assert error_result.status == "warn"
+    assert error_result.details["error_count"] == 1
+
+
+def test_neuroglancer_checks_port_reachability_warning_on_connection_refused(
+    monkeypatch,
+):
+    def fake_create_connection(addr, timeout=1):
+        raise ConnectionRefusedError("refused")
+
+    monkeypatch.setattr(diag.socket, "create_connection", fake_create_connection)
+    results = diag.check_neuroglancer(
+        api_base="https://demo.seg.bio",
+        workflow={
+            "id": 7,
+            "neuroglancer_url": "https://demo.seg.bio/neuroglancer/v/abc",
+        },
+        neuroglancer_port=4244,
+        neuroglancer_public_base="https://demo.seg.bio/neuroglancer",
+    )
+
+    status_lookup = {row.name: row.status for row in results}
+    assert status_lookup["neuroglancer.port"] == "warn"
+    assert status_lookup["neuroglancer.public_base"] == "pass"
+    assert status_lookup["neuroglancer.url_match"] == "pass"
+
+
+def test_run_diagnostics_emits_consistent_reports(monkeypatch, tmp_path):
+    def fake_request_json(*, base_url, path, **kwargs):
+        if path == "/health":
+            return 200, {"status": "ok"}, None
+        if path == "/app/log-path":
+            return 200, {"path": str(tmp_path / "app-events.jsonl")}, None
+        if path == "/api/workflows/current":
+            return 200, {"workflow": {"id": 3}, "events": []}, None
+        if path == "/training_status":
+            return 200, {"worker_url": "http://worker:4243"}, None
+        if path == "/chat/status":
+            return 200, {"configured": True}, None
+        if path == "/hello":
+            return 200, ["hello"], None
+        raise AssertionError(f"unexpected path: {path}")
+
+    monkeypatch.setattr(diag, "_http_request_json", fake_request_json)
+    monkeypatch.setattr(
+        diag,
+        "_tail_json_lines",
+        lambda *args, **kwargs: [],
+    )
+
+    class _NoopConnection:
+        def __enter__(self):
+            return self
+
+        def __exit__(self, exc_type, exc, tb):
+            return False
+
+    monkeypatch.setattr(
+        diag.socket,
+        "create_connection",
+        lambda *_args, **_kwargs: _NoopConnection(),
+    )
+
+    args = Namespace(
+        api_base="https://demo.seg.bio",
+        worker_protocol="http",
+        worker_url="worker:4243",
+        neuroglancer_port=4244,
+        neuroglancer_public_base="https://demo.seg.bio/neuroglancer",
+        workflow_bundle_dir=str(tmp_path / "workflow-bundles"),
+        timeout=1,
+        log_tail_lines=50,
+    )
+    results = diag.run_diagnostics(args)
+
+    names = [check.name for check in results]
+    assert "api.health" in names
+    assert "api.log_path" in names
+    assert "workflow.current" in names
+    assert any(name == "worker.url_mismatch" for name in names)
+    assert any(
+        check.name == "worker.url_mismatch" and check.status == "pass"
+        for check in results
+    )
+
+
+def test_run_diagnostics_tolerates_training_status_timeout_as_warning(
+    monkeypatch, tmp_path
+):
+    def fake_request_json(*, base_url, path, **kwargs):
+        if path == "/health":
+            return 200, {"status": "ok"}, None
+        if path == "/app/log-path":
+            return 200, {"path": str(tmp_path / "app-events.jsonl")}, None
+        if path == "/api/workflows/current":
+            return 200, {"workflow": {"id": 3}, "events": []}, None
+        if path == "/chat/status":
+            return 200, {"configured": True}, None
+        if path == "/hello":
+            return 200, ["hello"], None
+        if path == "/training_status":
+            raise request_exceptions.Timeout("temporary overload")
+        raise AssertionError(f"unexpected path: {path}")
+
+    monkeypatch.setattr(diag, "_http_request_json", fake_request_json)
+    monkeypatch.setattr(
+        diag,
+        "_tail_json_lines",
+        lambda *args, **kwargs: [],
+    )
+
+    class _NoopConnection:
+        def __enter__(self):
+            return self
+
+        def __exit__(self, exc_type, exc, tb):
+            return False
+
+    monkeypatch.setattr(
+        diag.socket,
+        "create_connection",
+        lambda *_args, **_kwargs: _NoopConnection(),
+    )
+
+    args = Namespace(
+        api_base="https://demo.seg.bio",
+        worker_protocol="http",
+        worker_url="worker:4243",
+        neuroglancer_port=4244,
+        neuroglancer_public_base="https://demo.seg.bio/neuroglancer",
+        workflow_bundle_dir=str(tmp_path / "workflow-bundles"),
+        timeout=1,
+        log_tail_lines=50,
+    )
+    results = diag.run_diagnostics(args)
+
+    assert all(check.status != "fail" for check in results)
+    timeout_result = next(
+        item
+        for item in results
+        if item.name == "api.training_status"
+        and item.message == "API /training_status request failed"
+    )
+    assert timeout_result.status == "warn"
+
+
+def test_demo2_defaults_are_applied_for_demo_host(monkeypatch, tmp_path):
+    def fake_request_json(*, base_url, path, **kwargs):
+        if path == "/health":
+            return 200, {"status": "ok"}, None
+        if path == "/app/log-path":
+            return 200, {"path": str(tmp_path / "app-events.jsonl")}, None
+        if path == "/api/workflows/current":
+            return (
+                200,
+                {
+                    "workflow": {
+                        "id": 3,
+                        "neuroglancer_url": "https://demo.seg.bio/neuroglancer/v/abc",
+                    },
+                    "events": [],
+                },
+                None,
+            )
+        if path == "/training_status":
+            return 200, {"worker_url": "http://localhost:4243"}, None
+        if path == "/chat/status":
+            return 200, {"configured": True}, None
+        if path == "/hello":
+            return 200, ["hello"], None
+        raise AssertionError(f"unexpected path: {path}")
+
+    monkeypatch.setattr(diag, "_http_request_json", fake_request_json)
+    monkeypatch.setattr(
+        diag,
+        "_tail_json_lines",
+        lambda *args, **kwargs: [],
+    )
+
+    class _NoopConnection:
+        def __enter__(self):
+            return self
+
+        def __exit__(self, exc_type, exc, tb):
+            return False
+
+    monkeypatch.setattr(
+        diag.socket,
+        "create_connection",
+        lambda *_args, **_kwargs: _NoopConnection(),
+    )
+
+    args = Namespace(
+        api_base="https://demo.seg.bio",
+        worker_protocol="http",
+        worker_url="localhost:4243",
+        neuroglancer_port=0,
+        neuroglancer_public_base="",
+        workflow_bundle_dir=str(tmp_path / "workflow-bundles"),
+        timeout=1,
+        log_tail_lines=120,
+    )
+    results = diag.run_diagnostics(args)
+
+    names = {check.name: check for check in results}
+    assert names["neuroglancer.port"].status == "pass"
+    assert names["neuroglancer.public_base"].status == "pass"
diff --git a/tests/test_manage_demo_instance.py b/tests/test_manage_demo_instance.py
new file mode 100644
index 00000000..05bca6ac
--- /dev/null
+++ b/tests/test_manage_demo_instance.py
@@ -0,0 +1,126 @@
+from __future__ import annotations
+
+from pathlib import Path
+import signal
+
+from scripts import manage_demo_instance as mgr
+
+
+def test_discover_demo_api_processes_filters_by_root_and_port(monkeypatch):
+    root = Path("/home/weidf/deploy/pytc-client-demo2")
+    other_root = Path("/home/weidf/other-project")
+
+    def fake_ps(*_args, **_kwargs):
+        return "\n".join(
+            [
+                "1234 python /tmp/whatever.py",
+                "2345 PYTC_API_PORT=4342 python -m server_api.main",
+                "3456 PYTC_API_PORT=4343 python -m server_api.main",
+                "4567 PYTC_API_PORT=4342 python -m server_api.main",
+            ]
+        )
+
+    monkeypatch.setattr(mgr.subprocess, "check_output", fake_ps)
+    monkeypatch.setattr(
+        mgr,
+        "_read_process_cwd",
+        lambda pid: str(
+            {
+                2345: str(root),
+                3456: str(root),
+                4567: str(other_root),
+            }[pid]
+        ),
+    )
+    monkeypatch.setattr(
+        mgr,
+        "_read_process_env",
+        lambda pid: (
+            {"PYTC_API_PORT": "4342"} if pid == 2345 else {"PYTC_API_PORT": "4343"}
+        ),
+    )
+
+    found = mgr.discover_demo_api_processes(api_port=4342, root=root)
+    assert [item.pid for item in found] == [2345]
+
+
+def test_build_api_command_includes_nohup_and_setsid_and_defaults():
+    command, env = mgr._build_api_command(
+        python_bin=Path("/home/example/.venv/bin/python"),
+        api_port=4342,
+    )
+
+    assert command[:2] == ["nohup", "setsid"]
+    assert command[-2:] == ["-m", "server_api.main"]
+    assert env["PYTC_API_PORT"] == str(mgr.DEMO2_API_PORT)
+    assert env["PYTC_WORKER_URL"] == mgr.DEMO2_WORKER_URL
+    assert env["PYTC_NEUROGLANCER_PUBLIC_BASE"] == mgr.DEMO2_NEUROGLANCER_PUBLIC_BASE
+
+
+def test_build_api_command_uses_requested_api_port():
+    command, env = mgr._build_api_command(
+        python_bin=Path("/home/example/.venv/bin/python"),
+        api_port=4567,
+    )
+
+    assert command[:2] == ["nohup", "setsid"]
+    assert env["PYTC_API_PORT"] == "4567"
+    assert env["PYTC_API_HOST"] == "127.0.0.1"
+
+
+def test_runtime_snapshot_message_includes_runtime_config():
+    message = mgr._runtime_snapshot_message(
+        {
+            "PYTC_WORKER_URL": "localhost:4243",
+            "PYTC_NEUROGLANCER_PORT": "4244",
+            "PYTC_NEUROGLANCER_PUBLIC_BASE": "https://demo.seg.bio/neuroglancer",
+        },
+        api_port=4342,
+    )
+    assert message == (
+        "Runtime config -> api_port=4342, "
+        "worker_url=localhost:4243, "
+        "neuroglancer_port=4244, "
+        "neuroglancer_public_base=https://demo.seg.bio/neuroglancer"
+    )
+
+
+def test_parse_extra_env(monkeypatch):
+    assert mgr.parse_extra_env(["A=1", " B=2 "]) == {"A": "1", "B": "2"}
+
+
+def test_stop_demo_api_uses_sigterm_and_returns_success(monkeypatch):
+    root = Path("/home/weidf/deploy/pytc-client-demo2")
+    processes = [
+        mgr.DemoApiProcess(
+            pid=2345, command="python -m server_api.main", cwd=str(root), env={}
+        ),
+    ]
+
+    killed = []
+
+    def fake_find(*, api_port, root):
+        return processes
+
+    def fake_kill(pid, signal_num):
+        killed.append((pid, signal_num))
+
+    def fake_is_alive(pid):
+        return False
+
+    monkeypatch.setattr(mgr, "discover_demo_api_processes", fake_find)
+    monkeypatch.setattr(mgr.os, "kill", fake_kill)
+    monkeypatch.setattr(mgr, "_is_process_alive", fake_is_alive)
+
+    result = mgr.stop_demo_api(api_port=4342, root=root)
+
+    assert result == 0
+    assert killed == [(2345, signal.SIGTERM)]
+
+
+def test_main_status_stops_without_disruptive_cleanup_when_not_running(monkeypatch):
+    parser_args = ["status", "--api-port", "4342", "--repo-root", "/tmp/demo"]
+    monkeypatch.setattr(mgr, "discover_demo_api_processes", lambda *_, **__: [])
+
+    result = mgr.main(parser_args)
+    assert result == 1
diff --git a/tests/test_neuroglancer_url_contract.py b/tests/test_neuroglancer_url_contract.py
index 1b3244bb..e051e31b 100644
--- a/tests/test_neuroglancer_url_contract.py
+++ b/tests/test_neuroglancer_url_contract.py
@@ -4,6 +4,12 @@
 from starlette.requests import Request
 
 from server_api.main import _build_neuroglancer_public_url
+from server_api import main as server_main
+
+
+class DummyViewer:
+    def __init__(self, token):
+        self.token = token
 
 
 def make_request(*, host="localhost:4242", scheme="http", extra_headers=None):
@@ -27,6 +33,15 @@ def make_request(*, host="localhost:4242", scheme="http", extra_headers=None):
 
 
 class NeuroglancerUrlContractTests(unittest.TestCase):
+    def setUp(self):
+        self._log_patch = patch.object(server_main, "append_app_event")
+        self._log_patch.start()
+
+    def tearDown(self):
+        self._log_patch.stop()
+        with server_main._retained_neuroglancer_viewers_lock:
+            server_main._retained_neuroglancer_viewers.clear()
+
     def test_default_public_url_uses_request_host_with_neuroglancer_port(self):
         request = make_request(host="localhost:4242", scheme="http")
 
@@ -69,6 +84,47 @@ def test_forwarded_headers_override_request_scheme_and_host(self):
 
         self.assertEqual(public_url, "https://viewer.internal:4244/v/proxy")
 
+    def test_retain_neuroglancer_viewer_keeps_strong_reference(self):
+        viewer = DummyViewer("viewer-token")
+
+        token = server_main._retain_neuroglancer_viewer(
+            viewer,
+            public_url="https://viewer.example.com/ng/v/viewer-token/",
+            internal_viewer_url="http://127.0.0.1:4244/v/viewer-token/",
+            mode="visualization",
+            workflow_id=7,
+            image_path="/data/image.h5",
+            label_path="/data/label.h5",
+        )
+
+        self.assertEqual(token, "viewer-token")
+        self.assertIs(
+            server_main._retained_neuroglancer_viewers["viewer-token"]["viewer"],
+            viewer,
+        )
+
+    def test_retain_neuroglancer_viewer_evicts_oldest_over_capacity(self):
+        previous_limit = server_main.PYTC_NEUROGLANCER_MAX_VIEWERS
+        server_main.PYTC_NEUROGLANCER_MAX_VIEWERS = 1
+        try:
+            server_main._retain_neuroglancer_viewer(
+                DummyViewer("old"),
+                public_url="https://viewer.example.com/ng/v/old/",
+                internal_viewer_url="http://127.0.0.1:4244/v/old/",
+                mode="visualization",
+            )
+            server_main._retain_neuroglancer_viewer(
+                DummyViewer("new"),
+                public_url="https://viewer.example.com/ng/v/new/",
+                internal_viewer_url="http://127.0.0.1:4244/v/new/",
+                mode="visualization",
+            )
+
+            self.assertNotIn("old", server_main._retained_neuroglancer_viewers)
+            self.assertIn("new", server_main._retained_neuroglancer_viewers)
+        finally:
+            server_main.PYTC_NEUROGLANCER_MAX_VIEWERS = previous_limit
+
 
 if __name__ == "__main__":
     unittest.main()
diff --git a/tests/test_neuroglancer_volume_normalization.py b/tests/test_neuroglancer_volume_normalization.py
new file mode 100644
index 00000000..b24c06ec
--- /dev/null
+++ b/tests/test_neuroglancer_volume_normalization.py
@@ -0,0 +1,161 @@
+import numpy as np
+
+from server_api.main import (
+    discover_neuroglancer_volume_pairs,
+    _normalize_segmentation_volume_for_neuroglancer,
+    _resolve_neuroglancer_image_path,
+    _resolve_neuroglancer_label_path,
+)
+
+
+def test_normalize_segmentation_converts_non_negative_int64_to_unsigned():
+    volume = np.array([[0, 1], [2, 255]], dtype=np.int64)
+
+    normalized = _normalize_segmentation_volume_for_neuroglancer(volume)
+
+    assert normalized.dtype == np.uint8
+    assert np.array_equal(normalized, volume)
+
+
+def test_normalize_segmentation_uses_uint64_for_large_labels():
+    volume = np.array([[0, 2**40]], dtype=np.int64)
+
+    normalized = _normalize_segmentation_volume_for_neuroglancer(volume)
+
+    assert normalized.dtype == np.uint64
+    assert np.array_equal(normalized, volume.astype(np.uint64))
+
+
+def test_normalize_segmentation_rejects_negative_labels():
+    volume = np.array([[0, -1]], dtype=np.int64)
+
+    try:
+        _normalize_segmentation_volume_for_neuroglancer(volume)
+    except ValueError as exc:
+        assert "non-negative" in str(exc)
+    else:
+        raise AssertionError("expected negative labels to be rejected")
+
+
+def test_normalize_segmentation_accepts_integral_float_labels():
+    volume = np.array([[0.0, 1.0], [2.0, 3.0]], dtype=np.float32)
+
+    normalized = _normalize_segmentation_volume_for_neuroglancer(volume)
+
+    assert normalized.dtype == np.uint8
+    assert np.array_equal(normalized, volume.astype(np.uint8))
+
+
+def test_normalize_segmentation_rejects_fractional_float_labels():
+    volume = np.array([[0.5, 1.0]], dtype=np.float32)
+
+    try:
+        _normalize_segmentation_volume_for_neuroglancer(volume)
+    except ValueError as exc:
+        assert "integer-valued" in str(exc)
+    else:
+        raise AssertionError("expected fractional labels to be rejected")
+
+
+def test_normalize_segmentation_squeezes_singleton_channel_volumes():
+    volume = np.array([[[[0, 1], [2, 3]]]], dtype=np.uint8)
+
+    normalized = _normalize_segmentation_volume_for_neuroglancer(volume)
+
+    assert normalized.shape == (1, 2, 2)
+    assert normalized.dtype == np.uint8
+    assert np.array_equal(normalized, volume[0])
+
+
+def test_normalize_segmentation_builds_preview_from_two_channel_prediction():
+    semantic = np.zeros((8, 8, 8), dtype=np.uint8)
+    boundary = np.zeros_like(semantic)
+    semantic[1:7, 1:7, 1:7] = 255
+    volume = np.stack([semantic, boundary], axis=0)
+
+    normalized = _normalize_segmentation_volume_for_neuroglancer(volume)
+
+    assert normalized.ndim == 3
+    assert normalized.shape == semantic.shape
+    assert normalized.dtype == np.uint8
+    assert int(normalized.max()) > 0
+
+
+def test_normalize_segmentation_uses_argmax_for_multiclass_prediction():
+    volume = np.zeros((3, 2, 2, 2), dtype=np.uint8)
+    volume[2, 1, 1, 1] = 255
+
+    normalized = _normalize_segmentation_volume_for_neuroglancer(volume)
+
+    assert normalized.shape == (2, 2, 2)
+    assert normalized.dtype == np.uint8
+    assert int(normalized[1, 1, 1]) == 2
+
+
+def test_resolve_neuroglancer_directory_inputs_to_matching_pair(tmp_path):
+    image_dir = tmp_path / "Image" / "train"
+    label_dir = tmp_path / "Label" / "train"
+    image_dir.mkdir(parents=True)
+    label_dir.mkdir(parents=True)
+    (image_dir / "img_000_604_576.h5").write_bytes(b"")
+    (image_dir / "img_508_604_200.h5").write_bytes(b"")
+    (label_dir / "seg_508_604_200.h5").write_bytes(b"")
+    (label_dir / "seg_000_604_576.h5").write_bytes(b"")
+
+    image_path, image_note = _resolve_neuroglancer_image_path(image_dir, label_dir)
+    label_path, label_note = _resolve_neuroglancer_label_path(label_dir, image_path)
+
+    assert image_path == image_dir / "img_000_604_576.h5"
+    assert label_path == label_dir / "seg_000_604_576.h5"
+    assert "Selected matching image volume" in image_note
+    assert "Selected matching label volume" in label_note
+
+
+def test_discover_neuroglancer_directory_pairs_lists_all_clear_matches(tmp_path):
+    image_dir = tmp_path / "Image" / "train"
+    label_dir = tmp_path / "Label" / "train"
+    image_dir.mkdir(parents=True)
+    label_dir.mkdir(parents=True)
+    (image_dir / "img_000_604_576.h5").write_bytes(b"")
+    (image_dir / "img_508_604_200.h5").write_bytes(b"")
+    (image_dir / "img_unpaired.h5").write_bytes(b"")
+    (label_dir / "seg_508_604_200.h5").write_bytes(b"")
+    (label_dir / "seg_000_604_576.h5").write_bytes(b"")
+
+    discovery = discover_neuroglancer_volume_pairs(image_dir, label_dir)
+
+    assert discovery["image_is_directory"] is True
+    assert discovery["label_is_directory"] is True
+    assert discovery["image_candidate_count"] == 3
+    assert discovery["label_candidate_count"] == 2
+    assert discovery["pair_count"] == 2
+    assert [pair["image_name"] for pair in discovery["pairs"]] == [
+        "img_000_604_576.h5",
+        "img_508_604_200.h5",
+    ]
+    assert discovery["pairs"][0]["label_name"] == "seg_000_604_576.h5"
+    assert str(image_dir / "img_unpaired.h5") in discovery["unpaired_images"]
+
+
+def test_discover_neuroglancer_single_file_fallback_does_not_report_unpaired(tmp_path):
+    image_path = tmp_path / "1-xri_raw.tif"
+    label_path = tmp_path / "1-mask.tif"
+    image_path.write_bytes(b"")
+    label_path.write_bytes(b"")
+
+    discovery = discover_neuroglancer_volume_pairs(image_path, label_path)
+
+    assert discovery["pair_count"] == 1
+    assert discovery["pairs"][0]["match_basis"] == "single-image-single-label"
+    assert discovery["unpaired_images"] == []
+    assert discovery["unpaired_labels"] == []
+
+
+def test_resolve_neuroglancer_keeps_chunked_volume_directories(tmp_path):
+    zarr_path = tmp_path / "volume.zarr"
+    zarr_path.mkdir()
+
+    resolved_path, note = _resolve_neuroglancer_image_path(zarr_path)
+
+    assert resolved_path == zarr_path
+    assert note is None
diff --git a/tests/test_project_manager_routes.py b/tests/test_project_manager_routes.py
index 77574269..0bdf5010 100644
--- a/tests/test_project_manager_routes.py
+++ b/tests/test_project_manager_routes.py
@@ -53,7 +53,9 @@ def test_config_endpoint_updates_metadata_and_data_root(self):
 
         self.assertEqual(response.status_code, 200)
         payload = response.json()
-        self.assertEqual(pathlib.Path(payload["metadata_path"]), metadata_path.resolve())
+        self.assertEqual(
+            pathlib.Path(payload["metadata_path"]), metadata_path.resolve()
+        )
         self.assertEqual(pathlib.Path(payload["data_root"]), data_root.resolve())
         self.assertTrue(payload["using_metadata_override"])
         self.assertTrue(payload["using_data_root_override"])
diff --git a/tests/test_pytc_architectures_route.py b/tests/test_pytc_architectures_route.py
new file mode 100644
index 00000000..6c4d3404
--- /dev/null
+++ b/tests/test_pytc_architectures_route.py
@@ -0,0 +1,24 @@
+import unittest
+
+from fastapi.testclient import TestClient
+
+from server_api.main import app as server_api_app
+
+
+class PytcArchitectureRouteTests(unittest.TestCase):
+    def setUp(self):
+        self.client = TestClient(server_api_app)
+
+    def test_pytc_architectures_returns_known_models(self):
+        response = self.client.get("/pytc/architectures")
+
+        self.assertEqual(response.status_code, 200)
+        payload = response.json()
+        self.assertIn("architectures", payload)
+        self.assertIn("unet_3d", payload["architectures"])
+        self.assertIn("unet_plus_3d", payload["architectures"])
+        self.assertIn("swinunetr", payload["architectures"])
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/tests/test_pytc_runtime_routes.py b/tests/test_pytc_runtime_routes.py
index 17692de5..aee1fc9f 100644
--- a/tests/test_pytc_runtime_routes.py
+++ b/tests/test_pytc_runtime_routes.py
@@ -1,12 +1,28 @@
 import json
+import os
 import pathlib
+import tempfile
 import unittest
 from unittest.mock import patch
 
 import requests
+from fastapi import HTTPException
 from fastapi.testclient import TestClient
+from sqlalchemy import create_engine
+from sqlalchemy.orm import sessionmaker
 
+from server_api.auth import database as auth_database
+from server_api.auth import models
 from server_api.main import app as server_api_app
+from server_api.main import (
+    UM_NEUROGLANCER_MASK_RED_SHADER,
+    UM_NEUROGLANCER_RAW_IMAGE_SHADER,
+    _build_neuroglancer_layer,
+    _has_single_neuroglancer_main,
+    _resolve_mask_image_shader,
+    _resolve_raw_image_shader,
+)
+from server_api.main import _coerce_neuroglancer_scales
 from server_pytc.main import app as server_pytc_app
 from server_pytc.services import model as model_service
 
@@ -23,10 +39,103 @@ def json(self):
         return self._payload
 
 
+class DummyLocalVolume:
+    def __init__(self, data, dimensions, volume_type, voxel_offset, **_kwargs):
+        self.data = data
+        self.dimensions = dimensions
+        self.volume_type = volume_type
+        self.voxel_offset = tuple(voxel_offset)
+        self.shader = None
+
+
+class DummyImageLayer:
+    def __init__(self, source, shader=None, **_kwargs):
+        self.source = source
+        self.shader = shader
+
+
+class DummySegmentationLayer:
+    def __init__(self, source, **kwargs):
+        self.source = source
+        self.kwargs = kwargs
+
+
+class DummyNeuroglancerModule:
+    def __init__(self, include_image_layer=True):
+        self.LocalVolume = DummyLocalVolume
+        self.SegmentationLayer = DummySegmentationLayer
+        if include_image_layer:
+            self.ImageLayer = DummyImageLayer
+
+
+class NeuroglancerShaderBehaviorTests(unittest.TestCase):
+    def test_raw_image_shader_resolver_matches_constant(self):
+        self.assertEqual(_resolve_raw_image_shader(), UM_NEUROGLANCER_RAW_IMAGE_SHADER)
+
+    def test_mask_shader_resolver_matches_constant(self):
+        self.assertEqual(_resolve_mask_image_shader(), UM_NEUROGLANCER_MASK_RED_SHADER)
+
+    def test_raw_um_shader_shape_and_controls(self):
+        self.assertIn("#uicontrol invlerp normalized", UM_NEUROGLANCER_RAW_IMAGE_SHADER)
+        self.assertIn(
+            "#uicontrol float contrast slider(min=-3, max=3, step=0.01)",
+            UM_NEUROGLANCER_RAW_IMAGE_SHADER,
+        )
+        self.assertIn(
+            "emitGrayscale((normalized() + brightness) * exp(contrast));",
+            UM_NEUROGLANCER_RAW_IMAGE_SHADER,
+        )
+        self.assertTrue(_has_single_neuroglancer_main(UM_NEUROGLANCER_RAW_IMAGE_SHADER))
+
+    def test_mask_red_shader_shape_and_controls(self):
+        self.assertIn("emitRGB(vec3(1.0, 0.0, 0.0));", UM_NEUROGLANCER_MASK_RED_SHADER)
+        self.assertTrue(_has_single_neuroglancer_main(UM_NEUROGLANCER_MASK_RED_SHADER))
+
+    def test_shader_builder_keeps_segmentation_layers_without_image_shader(self):
+        module = DummyNeuroglancerModule()
+        source = _build_neuroglancer_layer(
+            module,
+            data="mask",
+            dimensions=(40, 16, 16),
+            volume_type="segmentation",
+            segmentation_kwargs={"object_alpha": 0.4},
+        )
+        self.assertIsInstance(source, DummySegmentationLayer)
+        self.assertEqual(source.source.volume_type, "segmentation")
+        self.assertEqual(source.source.shader, None)
+
+    def test_shader_builder_uses_red_mask_shader_for_image_like_mask_layer(self):
+        module = DummyNeuroglancerModule(include_image_layer=True)
+        source = _build_neuroglancer_layer(
+            module,
+            data="mask",
+            dimensions=(40, 16, 16),
+            volume_type="image",
+            image_shader=UM_NEUROGLANCER_MASK_RED_SHADER,
+        )
+        self.assertIsInstance(source, DummyImageLayer)
+        self.assertEqual(source.shader, UM_NEUROGLANCER_MASK_RED_SHADER)
+
+    def test_shader_builder_fallback_to_source_shader_when_imagelayer_missing(self):
+        module = DummyNeuroglancerModule(include_image_layer=False)
+        source = _build_neuroglancer_layer(
+            module,
+            data="mask",
+            dimensions=(40, 16, 16),
+            volume_type="image",
+            image_shader=UM_NEUROGLANCER_MASK_RED_SHADER,
+        )
+        self.assertIsInstance(source, DummyLocalVolume)
+        self.assertEqual(source.shader, UM_NEUROGLANCER_MASK_RED_SHADER)
+
+
 class ServerPytcRouteTests(unittest.TestCase):
     def setUp(self):
         self.client = TestClient(server_pytc_app)
 
+    def tearDown(self):
+        model_service.stop_tensorboard(clear_sources=True)
+
     def test_inference_status_route_returns_worker_payload(self):
         payload = {"isRunning": True, "pid": 1234, "exitCode": None}
         with patch("server_pytc.main.get_inference_status", return_value=payload):
@@ -35,19 +144,46 @@ def test_inference_status_route_returns_worker_payload(self):
         self.assertEqual(response.status_code, 200)
         self.assertEqual(response.json(), payload)
 
-    def test_start_tensorboard_without_log_path_returns_400(self):
-        response = self.client.get("/start_tensorboard")
+    def test_start_tensorboard_without_registered_sources_returns_400(self):
+        with patch(
+            "server_pytc.main.initialize_tensorboard",
+            side_effect=ValueError("No TensorBoard log directory is registered yet."),
+        ):
+            response = self.client.get("/start_tensorboard")
 
         self.assertEqual(response.status_code, 400)
         self.assertEqual(
-            response.json()["detail"], "Missing required query parameter: logPath"
+            response.json()["detail"], "No TensorBoard log directory is registered yet."
+        )
+
+    def test_tensorboard_status_route_returns_worker_payload(self):
+        payload = {
+            "isRunning": True,
+            "phase": "running",
+            "pid": 4321,
+            "url": "http://127.0.0.1:6006/",
+            "sources": {"training": {"name": "training", "path": "/tmp/out"}},
+        }
+        with patch("server_pytc.main.get_tensorboard_status", return_value=payload):
+            response = self.client.get("/get_tensorboard_status")
+
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(response.json(), payload)
+
+    def test_neuroglancer_scale_validation_requires_finite_positive_zyx(self):
+        self.assertEqual(
+            _coerce_neuroglancer_scales(["40", 4, 4.0]),
+            [40.0, 4.0, 4.0],
         )
 
+        for invalid_scales in (None, [1, 1], [1, 1, 0], [1, -1, 1], [1, 1, "nan"]):
+            with self.subTest(scales=invalid_scales):
+                with self.assertRaises(HTTPException):
+                    _coerce_neuroglancer_scales(invalid_scales)
+
     def test_training_logs_route_returns_worker_payload(self):
         payload = {"phase": "running", "text": "hello", "lines": ["hello"]}
-        with patch(
-            "server_pytc.main.get_training_process_logs", return_value=payload
-        ):
+        with patch("server_pytc.main.get_training_process_logs", return_value=payload):
             response = self.client.get("/training_logs")
 
         self.assertEqual(response.status_code, 200)
@@ -84,7 +220,7 @@ def test_inference_status_proxy_returns_worker_payload(self):
         request_mock.assert_called_once()
 
     def test_start_tensorboard_proxy_propagates_worker_client_error(self):
-        worker_payload = {"detail": "Missing required query parameter: logPath"}
+        worker_payload = {"detail": "No TensorBoard log directory is registered yet."}
         with patch(
             "server_api.main.requests.request",
             return_value=FakeResponse(400, payload=worker_payload),
@@ -96,6 +232,49 @@ def test_start_tensorboard_proxy_propagates_worker_client_error(self):
         self.assertEqual(detail["upstream_status"], 400)
         self.assertEqual(detail["upstream_body"], worker_payload)
 
+    def test_tensorboard_status_proxy_returns_worker_payload(self):
+        payload = {
+            "isRunning": False,
+            "phase": "stopped",
+            "pid": None,
+            "url": None,
+            "sources": {
+                "training": {
+                    "name": "training",
+                    "path": "/tmp/train",
+                    "exists": True,
+                }
+            },
+        }
+        with patch(
+            "server_api.main.requests.request",
+            return_value=FakeResponse(200, payload=payload),
+        ):
+            response = self.client.get("/get_tensorboard_status")
+
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(response.json(), payload)
+
+    def test_pytc_config_route_allows_project_config_under_allowed_root(self):
+        with tempfile.TemporaryDirectory() as tmp_dir:
+            config_root = pathlib.Path(tmp_dir) / "demo-project"
+            config_path = config_root / "configs" / "Project.yaml"
+            config_path.parent.mkdir(parents=True)
+            config_path.write_text("DATASET: {}\n", encoding="utf-8")
+
+            with patch.dict(
+                os.environ,
+                {"PYTC_ADDITIONAL_CONFIG_ROOTS": str(config_root)},
+            ):
+                response = self.client.get(
+                    "/pytc/config",
+                    params={"path": str(config_path)},
+                )
+
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(response.json()["path"], str(config_path.resolve()))
+        self.assertEqual(response.json()["content"], "DATASET: {}\n")
+
     def test_start_model_training_proxy_returns_504_on_timeout(self):
         with patch(
             "server_api.main.requests.request",
@@ -109,6 +288,27 @@ def test_start_model_training_proxy_returns_504_on_timeout(self):
         self.assertEqual(response.status_code, 504)
         self.assertEqual(response.json()["detail"]["error"], "Timeout")
 
+    def test_worker_proxy_logs_connection_failures(self):
+        with (
+            patch(
+                "server_api.main.requests.request",
+                side_effect=requests.exceptions.ConnectionError("connection refused"),
+            ),
+            patch("server_api.main.append_app_event") as log_event,
+        ):
+            response = self.client.get("/training_status")
+
+        self.assertEqual(response.status_code, 503)
+        self.assertEqual(response.json()["detail"]["error"], "ConnectionError")
+        failure_events = [
+            call.kwargs
+            for call in log_event.call_args_list
+            if call.kwargs.get("event") == "worker_proxy_request_failed"
+        ]
+        self.assertTrue(failure_events)
+        self.assertEqual(failure_events[-1]["error"], "ConnectionError")
+        self.assertIn("/training_status", failure_events[-1]["path"])
+
     def test_training_logs_proxy_returns_worker_payload(self):
         payload = {"phase": "running", "text": "runtime", "lines": ["runtime"]}
         with patch(
@@ -121,9 +321,262 @@ def test_training_logs_proxy_returns_worker_payload(self):
         self.assertEqual(response.json(), payload)
 
 
+class WorkflowInferenceRuntimeSyncTests(unittest.TestCase):
+    def setUp(self):
+        self.temp_dir = tempfile.TemporaryDirectory()
+        self.db_path = pathlib.Path(self.temp_dir.name) / "workflow-runtime-sync.db"
+        self.engine = create_engine(
+            f"sqlite:///{self.db_path}", connect_args={"check_same_thread": False}
+        )
+        self.SessionLocal = sessionmaker(
+            autocommit=False, autoflush=False, bind=self.engine
+        )
+        models.Base.metadata.create_all(bind=self.engine)
+
+        def override_get_db():
+            db = self.SessionLocal()
+            try:
+                yield db
+            finally:
+                db.close()
+
+        server_api_app.dependency_overrides[auth_database.get_db] = override_get_db
+        self.client = TestClient(server_api_app)
+
+    def tearDown(self):
+        server_api_app.dependency_overrides.clear()
+        self.engine.dispose()
+        self.temp_dir.cleanup()
+
+    def _workflow_id(self):
+        response = self.client.get("/api/workflows/current")
+        self.assertEqual(response.status_code, 200)
+        return response.json()["workflow"]["id"]
+
+    def test_sync_completed_inference_runtime_materializes_prediction_run(self):
+        workflow_id = self._workflow_id()
+        output_dir = pathlib.Path(self.temp_dir.name) / "inference-output"
+        output_dir.mkdir()
+        prediction = output_dir / "result_xy.h5"
+        checkpoint = output_dir / "checkpoint_00001.pth.tar"
+        prediction.write_text("prediction", encoding="utf-8")
+        checkpoint.write_text("checkpoint", encoding="utf-8")
+
+        runtime_payload = {
+            "phase": "finished",
+            "pid": None,
+            "exitCode": 0,
+            "configPath": "/tmp/staged-inference.yaml",
+            "configOriginPath": "configs/MitoEM/Mito25-Local-Smoke-BC.yaml",
+            "startedAt": "2026-04-25T10:00:00+00:00",
+            "endedAt": "2026-04-25T10:01:00+00:00",
+            "lineCount": 12,
+            "metadata": {
+                "outputPath": str(output_dir),
+                "checkpointPath": str(checkpoint),
+            },
+        }
+
+        with patch("server_api.main._proxy_to_worker", return_value=runtime_payload):
+            response = self.client.post(
+                f"/api/workflows/{workflow_id}/sync-inference-runtime",
+                json={},
+            )
+            duplicate_response = self.client.post(
+                f"/api/workflows/{workflow_id}/sync-inference-runtime",
+                json={},
+            )
+
+        self.assertEqual(response.status_code, 200)
+        payload = response.json()
+        self.assertTrue(payload["synced"])
+        self.assertEqual(payload["outputPath"], str(prediction.resolve()))
+        self.assertFalse(payload["deduplicated"])
+        self.assertEqual(duplicate_response.status_code, 200)
+        self.assertTrue(duplicate_response.json()["deduplicated"])
+
+        runs_response = self.client.get(
+            f"/api/workflows/{workflow_id}/model-runs?run_type=inference"
+        )
+        self.assertEqual(runs_response.status_code, 200)
+        runs = runs_response.json()
+        self.assertEqual(len(runs), 1)
+        self.assertEqual(runs[0]["status"], "completed")
+        self.assertEqual(runs[0]["output_path"], str(prediction.resolve()))
+
+        artifacts_response = self.client.get(
+            f"/api/workflows/{workflow_id}/artifacts?artifact_type=inference_output"
+        )
+        self.assertEqual(artifacts_response.status_code, 200)
+        artifacts = artifacts_response.json()
+        self.assertEqual(len(artifacts), 1)
+        self.assertEqual(artifacts[0]["path"], str(prediction.resolve()))
+
+    def test_start_training_uses_workflow_paths_when_explicit_paths_are_stale(self):
+        workflow_id = self._workflow_id()
+        project_root = pathlib.Path(self.temp_dir.name) / "project"
+        image_path = project_root / "data" / "image" / "test_im.h5"
+        label_path = project_root / "data" / "seg" / "test_mito.h5"
+        output_path = project_root / "outputs" / "training"
+        image_path.parent.mkdir(parents=True)
+        label_path.parent.mkdir(parents=True)
+        output_path.mkdir(parents=True)
+        image_path.write_text("image", encoding="utf-8")
+        label_path.write_text("label", encoding="utf-8")
+
+        update_response = self.client.patch(
+            f"/api/workflows/{workflow_id}",
+            json={
+                "image_path": str(image_path),
+                "label_path": str(label_path),
+            },
+        )
+        self.assertEqual(update_response.status_code, 200)
+
+        captured = {}
+
+        def fake_worker(method, endpoint, json_body=None, **_kwargs):
+            captured["method"] = method
+            captured["endpoint"] = endpoint
+            captured["json_body"] = json_body
+            return {"phase": "starting"}
+
+        with patch("server_api.main._proxy_to_worker", side_effect=fake_worker):
+            response = self.client.post(
+                "/start_model_training",
+                json={
+                    "workflowId": workflow_id,
+                    "trainingConfig": "DATASET: {}\n",
+                    "inputImagePath": str(project_root / "data" / "image" / "old.h5"),
+                    "inputLabelPath": str(
+                        project_root / "data" / "seg" / ".pytc_instance_labels.tif"
+                    ),
+                    "outputPath": str(output_path),
+                },
+            )
+
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(captured["method"], "post")
+        self.assertEqual(captured["endpoint"], "/start_model_training")
+        self.assertEqual(
+            captured["json_body"]["inputImagePath"], str(image_path.resolve())
+        )
+        self.assertEqual(
+            captured["json_body"]["inputLabelPath"], str(label_path.resolve())
+        )
+
+    def test_durable_training_command_runner_launches_worker_and_records_state(self):
+        workflow_id = self._workflow_id()
+        project_root = pathlib.Path(self.temp_dir.name) / "project"
+        image_path = project_root / "data" / "image" / "train_im.h5"
+        label_path = project_root / "data" / "seg" / "corrected.tif"
+        output_path = project_root / "outputs" / "training"
+        image_path.parent.mkdir(parents=True)
+        label_path.parent.mkdir(parents=True)
+        output_path.mkdir(parents=True)
+        image_path.write_text("image", encoding="utf-8")
+        label_path.write_text("label", encoding="utf-8")
+
+        patch_response = self.client.patch(
+            f"/api/workflows/{workflow_id}",
+            json={
+                "stage": "retraining_staged",
+                "image_path": str(image_path),
+                "corrected_mask_path": str(label_path),
+            },
+        )
+        self.assertEqual(patch_response.status_code, 200)
+        client_effects = {
+            "runtime_action": {
+                "kind": "start_training",
+                "autopick_parameters": True,
+                "parameter_mode": "agent_default",
+            },
+            "set_training_config_preset": "configs/MitoEM/Mito25-Local-BC.yaml",
+            "set_training_image_path": str(image_path),
+            "set_training_label_path": str(label_path),
+            "set_training_output_path": str(output_path),
+            "set_training_log_path": str(output_path),
+        }
+        proposal = self.client.post(
+            f"/api/workflows/{workflow_id}/agent-actions",
+            json={
+                "action": "start_training_run",
+                "payload": {
+                    "client_effects": client_effects,
+                    "config_preset": client_effects["set_training_config_preset"],
+                    "image_path": str(image_path),
+                    "label_path": str(label_path),
+                    "output_path": str(output_path),
+                },
+            },
+        )
+        self.assertEqual(proposal.status_code, 200)
+        approval = self.client.post(
+            f"/api/workflows/{workflow_id}/agent-actions/"
+            f"{proposal.json()['id']}/approve"
+        )
+        self.assertEqual(approval.status_code, 200)
+        command = approval.json()["commands"][0]
+        captured = {}
+
+        def fake_worker(method, endpoint, json_body=None, **_kwargs):
+            captured["method"] = method
+            captured["endpoint"] = endpoint
+            captured["json_body"] = json_body
+            return {"status": "started", "pid": 4242}
+
+        with patch("server_api.main._proxy_to_worker", side_effect=fake_worker):
+            run_response = self.client.post(
+                f"/api/workflows/{workflow_id}/commands/{command['id']}/run"
+            )
+
+        self.assertEqual(run_response.status_code, 200)
+        payload = run_response.json()
+        self.assertEqual(payload["command"]["status"], "submitted")
+        self.assertEqual(payload["command"]["attempt_count"], 1)
+        self.assertEqual(payload["worker"]["pid"], 4242)
+        self.assertEqual(captured["method"], "post")
+        self.assertEqual(captured["endpoint"], "/start_model_training")
+        self.assertEqual(captured["json_body"]["workflowId"], workflow_id)
+        self.assertEqual(captured["json_body"]["command_id"], command["id"])
+        self.assertEqual(
+            captured["json_body"]["run_id"],
+            f"workflow-command-{command['id']}",
+        )
+        self.assertIn("DATASET", captured["json_body"]["trainingConfig"])
+        self.assertEqual(
+            captured["json_body"]["inputImagePath"], str(image_path.resolve())
+        )
+        self.assertEqual(
+            captured["json_body"]["inputLabelPath"], str(label_path.resolve())
+        )
+
+        commands_response = self.client.get(f"/api/workflows/{workflow_id}/commands")
+        self.assertEqual(commands_response.status_code, 200)
+        self.assertEqual(commands_response.json()[0]["status"], "submitted")
+
+        events_response = self.client.get(f"/api/workflows/{workflow_id}/events")
+        self.assertEqual(events_response.status_code, 200)
+        started_events = [
+            event
+            for event in events_response.json()
+            if event["event_type"] == "training.started"
+        ]
+        self.assertEqual(len(started_events), 1)
+        self.assertEqual(started_events[0]["payload"]["command_id"], command["id"])
+        self.assertEqual(
+            started_events[0]["payload"]["run_id"],
+            f"workflow-command-{command['id']}",
+        )
+
+
 class ModelServiceTests(unittest.TestCase):
     def tearDown(self):
+        model_service.stop_tensorboard(clear_sources=True)
         model_service.cleanup_temp_files()
+        model_service._reset_runtime_state("training")
+        model_service._reset_runtime_state("inference")
 
     def test_write_temp_config_uses_origin_parent_for_relative_bases(self):
         config_path = model_service._write_temp_config(
@@ -139,6 +592,481 @@ def test_write_temp_config_uses_origin_parent_for_relative_bases(self):
         self.assertTrue(written_path.exists())
         self.assertEqual(written_path.parent, expected_parent)
 
+    def test_register_tensorboard_source_builds_named_logdir_spec(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            training_dir = pathlib.Path(tmpdir) / "train"
+            inference_dir = pathlib.Path(tmpdir) / "infer"
+
+            first = model_service._register_tensorboard_source(
+                "training",
+                str(training_dir),
+            )
+            second = model_service._register_tensorboard_source(
+                "inference",
+                str(inference_dir),
+            )
+
+            self.assertTrue(pathlib.Path(first).exists())
+            self.assertTrue(pathlib.Path(second).exists())
+            self.assertEqual(
+                model_service._build_tensorboard_logdir_spec(),
+                f"inference:{pathlib.Path(second).resolve()},training:{pathlib.Path(first).resolve()}",
+            )
+
+    def test_runtime_log_lines_are_exported_to_app_event_log(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            log_path = pathlib.Path(tmpdir) / "app-events.jsonl"
+            previous = os.environ.get("PYTC_APP_EVENT_LOG_PATH")
+            os.environ["PYTC_APP_EVENT_LOG_PATH"] = str(log_path)
+            try:
+                model_service._reset_runtime_state("training", phase="starting")
+                model_service._update_runtime_state("training", pid=12345)
+                model_service._append_runtime_event(
+                    "training", "Config origin: foo.yaml"
+                )
+                model_service._append_runtime_log(
+                    "training",
+                    "UnicodeDecodeError: invalid start byte",
+                    event="runtime_output_line",
+                    source="subprocess",
+                    stream="stdout",
+                )
+            finally:
+                if previous is None:
+                    os.environ.pop("PYTC_APP_EVENT_LOG_PATH", None)
+                else:
+                    os.environ["PYTC_APP_EVENT_LOG_PATH"] = previous
+
+            records = [
+                json.loads(line)
+                for line in log_path.read_text(encoding="utf-8").splitlines()
+                if line.strip()
+            ]
+            self.assertEqual(records[0]["event"], "runtime_event")
+            self.assertEqual(records[0]["runtime_kind"], "training")
+            self.assertEqual(records[0]["runtime_phase"], "starting")
+            self.assertEqual(records[0]["runtime_pid"], 12345)
+            self.assertEqual(records[1]["event"], "runtime_output_line")
+            self.assertEqual(records[1]["level"], "ERROR")
+            self.assertEqual(records[1]["source"], "subprocess")
+            self.assertEqual(records[1]["stream"], "stdout")
+
+    def test_detect_chunk_tile_mismatch_for_direct_h5_volume(self):
+        diagnostic = model_service._detect_chunk_tile_mismatch("""
+DATASET:
+  DO_CHUNK_TITLE: 1
+  IMAGE_NAME: /tmp/train-volume.h5
+  LABEL_NAME: /tmp/train-label.h5
+""")
+
+        self.assertIsNotNone(diagnostic)
+        self.assertEqual(diagnostic["code"], "tile_dataset_direct_volume_mismatch")
+        self.assertIn("TileDataset", diagnostic["message"])
+        self.assertEqual(diagnostic["image_name"], "/tmp/train-volume.h5")
+
+    def test_sanitize_runtime_config_restores_fractional_values_and_paths(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            tmp_root = pathlib.Path(tmpdir)
+            image_path = tmp_root / "pair_im.h5"
+            label_path = tmp_root / "pair_seg.h5"
+            infer_path = tmp_root / "pair2_im.h5"
+            for path in (image_path, label_path, infer_path):
+                path.write_text("placeholder", encoding="utf-8")
+
+            origin_config = tmp_root / "origin.yaml"
+            origin_config.write_text(
+                "\n".join(
+                    [
+                        "DATASET:",
+                        f"  IMAGE_NAME: {image_path}",
+                        f"  LABEL_NAME: {label_path}",
+                        "  VALID_RATIO: 0.5",
+                        "  REJECT_SAMPLING:",
+                        "    P: 0.95",
+                        "INFERENCE:",
+                        f"  IMAGE_NAME: {infer_path}",
+                        "  AUG_NUM: 4",
+                        "",
+                    ]
+                ),
+                encoding="utf-8",
+            )
+
+            corrupted_config = "\n".join(
+                [
+                    "DATASET:",
+                    f"  IMAGE_NAME: {image_path.with_name('pair.h5')}",
+                    f"  LABEL_NAME: {label_path.with_name('pair.h5')}",
+                    "  VALID_RATIO: 0",
+                    "  REJECT_SAMPLING:",
+                    "    P: 0",
+                    "INFERENCE:",
+                    f"  IMAGE_NAME: {infer_path.with_name('pair2.h5')}",
+                    "  AUG_NUM: 1",
+                    "",
+                ]
+            )
+
+            sanitized_text, changes = model_service._sanitize_runtime_config_text(
+                corrupted_config,
+                str(origin_config),
+            )
+            sanitized = model_service._load_yaml_config(sanitized_text)
+
+            self.assertEqual(sanitized["DATASET"]["IMAGE_NAME"], str(image_path))
+            self.assertEqual(sanitized["DATASET"]["LABEL_NAME"], str(label_path))
+            self.assertEqual(sanitized["INFERENCE"]["IMAGE_NAME"], str(infer_path))
+            self.assertEqual(sanitized["DATASET"]["VALID_RATIO"], 0.5)
+            self.assertEqual(sanitized["DATASET"]["REJECT_SAMPLING"]["P"], 0.95)
+            self.assertEqual(sanitized["INFERENCE"]["AUG_NUM"], 4)
+            self.assertGreaterEqual(len(changes), 4)
+
+    def test_runtime_path_overrides_update_inference_image_section(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            tmp_root = pathlib.Path(tmpdir)
+            image_path = tmp_root / "test_im.h5"
+            image_path.write_text("placeholder", encoding="utf-8")
+            output_path = tmp_root / "outputs"
+
+            config_text = "\n".join(
+                [
+                    "DATASET:",
+                    "  INPUT_PATH: ''",
+                    "  IMAGE_NAME: img/test_im.tif",
+                    "INFERENCE:",
+                    "  INPUT_PATH: null",
+                    "  IMAGE_NAME: img/test_im.tif",
+                    "  OUTPUT_PATH: outputs/Lucchi_UNet/test",
+                    "",
+                ]
+            )
+
+            rewritten_text, changes = model_service._apply_runtime_path_overrides(
+                config_text,
+                {
+                    "inputImagePath": str(image_path),
+                    "outputPath": str(output_path),
+                },
+                kind="inference",
+            )
+            rewritten = model_service._load_yaml_config(rewritten_text)
+
+            self.assertEqual(
+                rewritten["DATASET"]["IMAGE_NAME"], str(image_path.resolve())
+            )
+            self.assertEqual(
+                rewritten["INFERENCE"]["IMAGE_NAME"], str(image_path.resolve())
+            )
+            self.assertEqual(
+                rewritten["INFERENCE"]["OUTPUT_PATH"], str(output_path.resolve())
+            )
+            self.assertEqual(rewritten["DATASET"]["INPUT_PATH"], "")
+            self.assertEqual(rewritten["INFERENCE"]["INPUT_PATH"], "")
+            self.assertGreaterEqual(len(changes), 4)
+
+    def test_runtime_path_overrides_resolve_mounted_project_alias(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            tmp_root = pathlib.Path(tmpdir) / "prepilot_lucchi_pp"
+            image_path = tmp_root / "data" / "image" / "test_im.h5"
+            image_path.parent.mkdir(parents=True)
+            image_path.write_text("placeholder", encoding="utf-8")
+            previous_roots = model_service._DEFAULT_MOUNTED_PROJECT_ROOTS
+            model_service._DEFAULT_MOUNTED_PROJECT_ROOTS = (tmp_root,)
+            try:
+                rewritten_text, _changes = model_service._apply_runtime_path_overrides(
+                    "INFERENCE:\n  IMAGE_NAME: img/test_im.tif\n",
+                    {
+                        "inputImagePath": "prepilot_lucchi_pp/data/image/test_im.h5",
+                    },
+                    kind="inference",
+                )
+            finally:
+                model_service._DEFAULT_MOUNTED_PROJECT_ROOTS = previous_roots
+
+            rewritten = model_service._load_yaml_config(rewritten_text)
+            self.assertEqual(
+                rewritten["INFERENCE"]["IMAGE_NAME"],
+                str(image_path.resolve()),
+            )
+
+    def test_runtime_path_overrides_expand_training_subset_directories(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            tmp_root = pathlib.Path(tmpdir)
+            image_dir = tmp_root / "subset" / "image"
+            label_dir = tmp_root / "subset" / "seg"
+            image_dir.mkdir(parents=True)
+            label_dir.mkdir(parents=True)
+            image_a = image_dir / "a_im.h5"
+            image_b = image_dir / "b_im.h5"
+            label_a = label_dir / "a_seg.h5"
+            label_b = label_dir / "b_seg.h5"
+            for path in (image_a, image_b, label_a, label_b):
+                path.write_text("placeholder", encoding="utf-8")
+            manifest_path = tmp_root / "subset" / "volume_subset_manifest.json"
+            manifest_path.write_text(
+                json.dumps(
+                    {
+                        "train_pairs": [
+                            {
+                                "subset_image_path": str(image_b),
+                                "subset_segmentation_path": str(label_b),
+                            },
+                            {
+                                "subset_image_path": str(image_a),
+                                "subset_segmentation_path": str(label_a),
+                            },
+                        ],
+                    }
+                ),
+                encoding="utf-8",
+            )
+
+            rewritten_text, changes = model_service._apply_runtime_path_overrides(
+                "DATASET:\n  INPUT_PATH: .\n  IMAGE_NAME: old/image\n  LABEL_NAME: old/seg\n",
+                {
+                    "inputImagePath": str(image_dir),
+                    "inputLabelPath": str(label_dir),
+                },
+                kind="training",
+            )
+            rewritten = model_service._load_yaml_config(rewritten_text)
+
+            self.assertEqual(
+                rewritten["DATASET"]["IMAGE_NAME"],
+                [str(image_b.resolve()), str(image_a.resolve())],
+            )
+            self.assertEqual(
+                rewritten["DATASET"]["LABEL_NAME"],
+                [str(label_b.resolve()), str(label_a.resolve())],
+            )
+            self.assertEqual(rewritten["DATASET"]["INPUT_PATH"], "")
+            self.assertTrue(
+                any(
+                    change["reason"] == "runtime_request_training_subset_manifest"
+                    for change in changes
+                )
+            )
+
+    def test_runtime_launch_validation_rejects_missing_training_label(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            image_path = pathlib.Path(tmpdir) / "train_im.h5"
+            image_path.write_text("placeholder", encoding="utf-8")
+            config_text = "\n".join(
+                [
+                    "DATASET:",
+                    f"  IMAGE_NAME: {image_path}",
+                    f"  LABEL_NAME: {pathlib.Path(tmpdir) / 'missing_label.tif'}",
+                    "",
+                ]
+            )
+
+            with self.assertRaises(FileNotFoundError):
+                model_service._validate_runtime_launch_inputs(
+                    config_text,
+                    kind="training",
+                )
+
+    def test_runtime_launch_validation_accepts_existing_training_inputs(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            image_path = pathlib.Path(tmpdir) / "train_im.h5"
+            label_path = pathlib.Path(tmpdir) / "train_mito.h5"
+            image_path.write_text("placeholder", encoding="utf-8")
+            label_path.write_text("placeholder", encoding="utf-8")
+            config_text = "\n".join(
+                [
+                    "DATASET:",
+                    f"  IMAGE_NAME: {image_path}",
+                    f"  LABEL_NAME: {label_path}",
+                    "",
+                ]
+            )
+
+            model_service._validate_runtime_launch_inputs(
+                config_text,
+                kind="training",
+            )
+
+    def test_runtime_launch_validation_accepts_training_input_lists(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            tmp_root = pathlib.Path(tmpdir)
+            image_paths = [tmp_root / "train_a_im.h5", tmp_root / "train_b_im.h5"]
+            label_paths = [tmp_root / "train_a_seg.h5", tmp_root / "train_b_seg.h5"]
+            for path in [*image_paths, *label_paths]:
+                path.write_text("placeholder", encoding="utf-8")
+            config_text = "\n".join(
+                [
+                    "DATASET:",
+                    "  IMAGE_NAME:",
+                    *[f"    - {path}" for path in image_paths],
+                    "  LABEL_NAME:",
+                    *[f"    - {path}" for path in label_paths],
+                    "",
+                ]
+            )
+
+            model_service._validate_runtime_launch_inputs(
+                config_text,
+                kind="training",
+            )
+
+    def test_runtime_launch_validation_rejects_unexpanded_training_directory(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            image_dir = pathlib.Path(tmpdir) / "image"
+            label_dir = pathlib.Path(tmpdir) / "seg"
+            image_dir.mkdir()
+            label_dir.mkdir()
+            config_text = "\n".join(
+                [
+                    "DATASET:",
+                    f"  IMAGE_NAME: {image_dir}",
+                    f"  LABEL_NAME: {label_dir}",
+                    "",
+                ]
+            )
+
+            with self.assertRaises(FileNotFoundError):
+                model_service._validate_runtime_launch_inputs(
+                    config_text,
+                    kind="training",
+                )
+
+    def test_sanitize_runtime_config_applies_safe_training_defaults(self):
+        config_text = "\n".join(
+            [
+                "MODEL:",
+                "  INPUT_SIZE: [112, 112, 112]",
+                "  OUTPUT_SIZE: [112, 112, 112]",
+                "  FILTERS: [28, 36, 48, 64, 80]",
+                "DATASET:",
+                "  PAD_SIZE: [8, 28, 28]",
+                "INFERENCE:",
+                "  INPUT_SIZE: [112, 112, 112]",
+                "  OUTPUT_SIZE: [112, 112, 112]",
+                "  STRIDE: [56, 56, 56]",
+                "  SAMPLES_PER_BATCH: 4",
+                "  PAD_SIZE: [8, 28, 28]",
+                "SOLVER:",
+                "  SAMPLES_PER_BATCH: 2",
+                "  ITERATION_SAVE: 5000",
+                "  ITERATION_TOTAL: 100000",
+                "SYSTEM:",
+                "  NUM_CPUS: 1",
+                "  NUM_GPUS: 1",
+                "",
+            ]
+        )
+
+        sanitized_text, changes = model_service._sanitize_runtime_config_text(
+            config_text,
+            None,
+            auto_parameters=True,
+        )
+        sanitized = model_service._load_yaml_config(sanitized_text)
+
+        self.assertEqual(sanitized["SOLVER"]["SAMPLES_PER_BATCH"], 1)
+        self.assertEqual(sanitized["SOLVER"]["ITERATION_SAVE"], 80)
+        self.assertEqual(sanitized["SOLVER"]["ITERATION_TOTAL"], 80)
+        self.assertEqual(sanitized["SOLVER"]["ITERATION_VAL"], 80)
+        self.assertEqual(sanitized["SYSTEM"]["NUM_CPUS"], 2)
+        self.assertEqual(sanitized["SYSTEM"]["NUM_GPUS"], 1)
+        self.assertEqual(sanitized["MODEL"]["INPUT_SIZE"], [65, 65, 65])
+        self.assertEqual(sanitized["MODEL"]["OUTPUT_SIZE"], [65, 65, 65])
+        self.assertEqual(sanitized["MODEL"]["FILTERS"], [8, 12, 16, 24, 32])
+        self.assertEqual(sanitized["DATASET"]["PAD_SIZE"], [4, 16, 16])
+        self.assertEqual(sanitized["INFERENCE"]["STRIDE"], [32, 32, 32])
+        self.assertTrue(
+            any(change["reason"] == "agent_safe_training_default" for change in changes)
+        )
+
+    def test_runtime_error_lines_update_last_error(self):
+        model_service._reset_runtime_state("training", phase="running")
+        model_service._append_runtime_log(
+            "training",
+            "ValueError: boom",
+            event="runtime_output_line",
+            source="subprocess",
+            stream="stdout",
+        )
+
+        snapshot = model_service.get_training_status()
+        self.assertEqual(snapshot["lastError"], "ValueError: boom")
+
+    def test_find_latest_checkpoint_returns_newest_training_artifact(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            output_dir = pathlib.Path(tmpdir)
+            older = output_dir / "checkpoint_00050.pth.tar"
+            newer = output_dir / "checkpoint_00200.pth.tar"
+            older.write_text("older", encoding="utf-8")
+            newer.write_text("newer", encoding="utf-8")
+
+            os.utime(older, (1, 1))
+            os.utime(newer, (2, 2))
+
+            latest = model_service._find_latest_checkpoint(str(output_dir))
+
+            self.assertEqual(latest, str(newer.resolve()))
+
+    def test_training_snapshot_backfills_checkpoint_metadata_after_exit(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            output_dir = pathlib.Path(tmpdir)
+            checkpoint_path = output_dir / "checkpoint_00010.pth.tar"
+            checkpoint_path.write_text("checkpoint", encoding="utf-8")
+
+            model_service._reset_runtime_state(
+                "training",
+                phase="finished",
+                metadata={"outputPath": str(output_dir)},
+            )
+
+            snapshot = model_service.get_training_logs()
+
+            self.assertEqual(
+                snapshot["metadata"]["checkpointPath"],
+                str(checkpoint_path.resolve()),
+            )
+            self.assertEqual(
+                snapshot["metadata"]["latestCheckpointName"],
+                checkpoint_path.name,
+            )
+
+    def test_find_latest_prediction_output_returns_newest_inference_artifact(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            output_dir = pathlib.Path(tmpdir)
+            older = output_dir / "prediction.h5"
+            newer = output_dir / "result_xy.h5"
+            older.write_text("older", encoding="utf-8")
+            newer.write_text("newer", encoding="utf-8")
+
+            os.utime(older, (1, 1))
+            os.utime(newer, (2, 2))
+
+            latest = model_service._find_latest_prediction_output(str(output_dir))
+
+            self.assertEqual(latest, str(newer.resolve()))
+
+    def test_inference_snapshot_backfills_prediction_metadata_after_exit(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            output_dir = pathlib.Path(tmpdir)
+            prediction_path = output_dir / "result_xy.h5"
+            prediction_path.write_text("prediction", encoding="utf-8")
+
+            model_service._reset_runtime_state(
+                "inference",
+                phase="finished",
+                metadata={"outputPath": str(output_dir)},
+            )
+
+            snapshot = model_service.get_inference_logs()
+
+            self.assertEqual(
+                snapshot["metadata"]["predictionPath"],
+                str(prediction_path.resolve()),
+            )
+            self.assertEqual(
+                snapshot["metadata"]["latestPredictionName"],
+                prediction_path.name,
+            )
+
 
 if __name__ == "__main__":
     unittest.main()
diff --git a/tests/test_volume_io.py b/tests/test_volume_io.py
new file mode 100644
index 00000000..9e6e36d4
--- /dev/null
+++ b/tests/test_volume_io.py
@@ -0,0 +1,72 @@
+import numpy as np
+import pytest
+
+h5py = pytest.importorskip("h5py")
+pytest.importorskip("tifffile")
+
+from server_api.workflows.volume_io import load_volume, parse_crop
+
+
+def test_parse_crop_accepts_voxel_slice_strings():
+    assert parse_crop("0:4,10:20,30:40") == (
+        slice(0, 4, None),
+        slice(10, 20, None),
+        slice(30, 40, None),
+    )
+    assert parse_crop("full") is None
+
+
+def test_load_volume_reads_hdf5_dataset_with_crop(tmp_path):
+    path = tmp_path / "volume.h5"
+    volume = np.arange(4 * 5 * 6, dtype=np.uint16).reshape(4, 5, 6)
+    with h5py.File(path, "w") as handle:
+        handle.create_dataset("data", data=volume)
+
+    loaded = load_volume(str(path), dataset_key="data", crop="1:3,2:5,1:4")
+
+    np.testing.assert_array_equal(loaded, volume[1:3, 2:5, 1:4])
+
+
+def test_load_volume_reads_inline_hdf5_dataset_reference(tmp_path):
+    path = tmp_path / "volume.h5"
+    volume = np.arange(2 * 3 * 4, dtype=np.uint8).reshape(2, 3, 4)
+    with h5py.File(path, "w") as handle:
+        handle.create_dataset("main", data=volume)
+
+    loaded = load_volume(f"{path}::main")
+
+    np.testing.assert_array_equal(loaded, volume)
+
+
+def test_load_volume_selects_channel_before_crop_for_hdf5(tmp_path):
+    path = tmp_path / "prediction.h5"
+    volume = np.arange(2 * 4 * 5 * 6, dtype=np.float32).reshape(2, 4, 5, 6)
+    with h5py.File(path, "w") as handle:
+        handle.create_dataset("vol0", data=volume)
+
+    loaded = load_volume(
+        str(path),
+        dataset_key="vol0",
+        crop="1:3,2:5,1:4",
+        channel=1,
+        reference_ndim=3,
+        label="prediction",
+    )
+
+    np.testing.assert_array_equal(loaded, volume[1, 1:3, 2:5, 1:4])
+
+
+def test_load_volume_rejects_channel_for_already_3d_volume(tmp_path):
+    path = tmp_path / "mask.h5"
+    volume = np.arange(4 * 5 * 6, dtype=np.uint16).reshape(4, 5, 6)
+    with h5py.File(path, "w") as handle:
+        handle.create_dataset("data", data=volume)
+
+    with pytest.raises(ValueError, match="already 3D"):
+        load_volume(
+            str(path),
+            dataset_key="data",
+            channel=0,
+            reference_ndim=3,
+            label="mask",
+        )
diff --git a/tests/test_worker_model_service.py b/tests/test_worker_model_service.py
index a38e9dc2..930f7727 100644
--- a/tests/test_worker_model_service.py
+++ b/tests/test_worker_model_service.py
@@ -1,6 +1,8 @@
+import os
 import pathlib
 import tempfile
 import unittest
+from unittest.mock import MagicMock, patch
 
 from server_pytc.services import model as model_service
 
@@ -39,8 +41,12 @@ def test_matches_pytc_mode_process_supports_current_cli(self):
             "--inference",
         ]
 
-        self.assertTrue(model_service._matches_pytc_mode_process(train_cmdline, "train"))
-        self.assertFalse(model_service._matches_pytc_mode_process(train_cmdline, "test"))
+        self.assertTrue(
+            model_service._matches_pytc_mode_process(train_cmdline, "train")
+        )
+        self.assertFalse(
+            model_service._matches_pytc_mode_process(train_cmdline, "test")
+        )
         self.assertTrue(
             model_service._matches_pytc_mode_process(inference_cmdline, "test")
         )
@@ -66,6 +72,44 @@ def test_cleanup_temp_files_is_scoped_by_kind(self):
 
         self.assertFalse(pathlib.Path(inference_file.name).exists())
 
+    def test_ollama_unload_is_disabled_by_default(self):
+        with patch.dict(
+            os.environ,
+            {
+                "OLLAMA_MODEL": "qwen3.6:27b",
+                "PYTC_HELPER_OLLAMA_MODEL": "",
+                "OLLAMA_HELPER_MODEL": "",
+            },
+            clear=False,
+        ):
+            os.environ.pop("PYTC_UNLOAD_OLLAMA_BEFORE_TRAINING", None)
+            with patch("server_pytc.services.model.subprocess.run") as run_mock:
+                unloaded = model_service._unload_ollama_before_gpu_training()
+
+        self.assertEqual(unloaded, [])
+        run_mock.assert_not_called()
+
+    def test_ollama_unload_can_be_enabled_explicitly(self):
+        run_result = MagicMock(returncode=0, stdout="")
+        with patch.dict(
+            os.environ,
+            {
+                "PYTC_UNLOAD_OLLAMA_BEFORE_TRAINING": "1",
+                "OLLAMA_MODEL": "qwen3.6:27b",
+                "PYTC_HELPER_OLLAMA_MODEL": "",
+                "OLLAMA_HELPER_MODEL": "",
+            },
+            clear=False,
+        ):
+            with patch(
+                "server_pytc.services.model.subprocess.run",
+                return_value=run_result,
+            ) as run_mock:
+                unloaded = model_service._unload_ollama_before_gpu_training()
+
+        self.assertEqual(unloaded, ["qwen3.6:27b"])
+        run_mock.assert_called_once()
+
 
 if __name__ == "__main__":
     unittest.main()
diff --git a/tests/test_workflow_artifact_records.py b/tests/test_workflow_artifact_records.py
new file mode 100644
index 00000000..eb3b6801
--- /dev/null
+++ b/tests/test_workflow_artifact_records.py
@@ -0,0 +1,436 @@
+import pathlib
+import tempfile
+import unittest
+
+import pytest
+import numpy as np
+
+pytest.importorskip("sqlalchemy")
+from sqlalchemy import create_engine
+from sqlalchemy.orm import sessionmaker
+
+pytest.importorskip("fastapi")
+tifffile = pytest.importorskip("tifffile")
+h5py = pytest.importorskip("h5py")
+from fastapi.testclient import TestClient
+
+from server_api.auth import database as auth_database
+from server_api.auth import models
+from server_api.main import app as server_api_app
+
+
+class WorkflowArtifactRecordTests(unittest.TestCase):
+    def setUp(self):
+        self.temp_dir = tempfile.TemporaryDirectory()
+        self.root = pathlib.Path(self.temp_dir.name)
+        self.db_path = self.root / "workflow-artifacts-test.db"
+        self.engine = create_engine(
+            f"sqlite:///{self.db_path}", connect_args={"check_same_thread": False}
+        )
+        self.SessionLocal = sessionmaker(
+            autocommit=False, autoflush=False, bind=self.engine
+        )
+        models.Base.metadata.create_all(bind=self.engine)
+
+        def override_get_db():
+            db = self.SessionLocal()
+            try:
+                yield db
+            finally:
+                db.close()
+
+        server_api_app.dependency_overrides[auth_database.get_db] = override_get_db
+        self.client = TestClient(server_api_app)
+
+    def tearDown(self):
+        server_api_app.dependency_overrides.clear()
+        self.engine.dispose()
+        self.temp_dir.cleanup()
+
+    def _workflow_id(self):
+        response = self.client.get("/api/workflows/current")
+        self.assertEqual(response.status_code, 200)
+        return response.json()["workflow"]["id"]
+
+    def _write_file(self, name: str) -> str:
+        path = self.root / name
+        path.write_text(name, encoding="utf-8")
+        return str(path)
+
+    def test_events_materialize_artifacts_runs_versions_and_corrections(self):
+        workflow_id = self._workflow_id()
+        image_path = self._write_file("image.tif")
+        mask_path = self._write_file("mask.tif")
+        ground_truth_path = self._write_file("ground-truth.tif")
+        corrected_path = self._write_file("corrected.tif")
+        training_output = self._write_file("training-output")
+        checkpoint_path = self._write_file("checkpoint.pth")
+
+        self.client.post(
+            f"/api/workflows/{workflow_id}/events",
+            json={
+                "actor": "user",
+                "event_type": "dataset.loaded",
+                "stage": "proofreading",
+                "summary": "Loaded dataset.",
+                "payload": {
+                    "dataset_path": image_path,
+                    "image_path": image_path,
+                    "mask_path": mask_path,
+                    "source_ground_truth_path": ground_truth_path,
+                },
+            },
+        )
+        self.client.post(
+            f"/api/workflows/{workflow_id}/events",
+            json={
+                "actor": "user",
+                "event_type": "proofreading.mask_saved",
+                "stage": "proofreading",
+                "summary": "Saved first correction.",
+                "payload": {"instance_id": 12, "z_index": 1},
+            },
+        )
+        self.client.post(
+            f"/api/workflows/{workflow_id}/events",
+            json={
+                "actor": "user",
+                "event_type": "proofreading.mask_saved",
+                "stage": "proofreading",
+                "summary": "Saved second correction.",
+                "payload": {"instance_id": 13, "z_index": 2},
+            },
+        )
+        self.client.post(
+            f"/api/workflows/{workflow_id}/events",
+            json={
+                "actor": "user",
+                "event_type": "proofreading.masks_exported",
+                "stage": "proofreading",
+                "summary": "Exported corrections.",
+                "payload": {"written_path": corrected_path},
+            },
+        )
+        self.client.post(
+            f"/api/workflows/{workflow_id}/events",
+            json={
+                "actor": "user",
+                "event_type": "training.started",
+                "stage": "retraining_staged",
+                "summary": "Started training.",
+                "payload": {"outputPath": training_output},
+            },
+        )
+        self.client.post(
+            f"/api/workflows/{workflow_id}/events",
+            json={
+                "actor": "system",
+                "event_type": "training.completed",
+                "stage": "evaluation",
+                "summary": "Training completed.",
+                "payload": {
+                    "outputPath": training_output,
+                    "checkpointPath": checkpoint_path,
+                    "checkpointName": "checkpoint.pth",
+                },
+            },
+        )
+
+        artifacts = self.client.get(f"/api/workflows/{workflow_id}/artifacts").json()
+        artifact_types = {artifact["artifact_type"] for artifact in artifacts}
+        self.assertIn("image_volume", artifact_types)
+        self.assertIn("mask_volume", artifact_types)
+        self.assertIn("correction_set", artifact_types)
+        self.assertIn("model_checkpoint", artifact_types)
+        ground_truth_artifacts = [
+            artifact for artifact in artifacts if artifact["role"] == "ground_truth"
+        ]
+        self.assertEqual(ground_truth_artifacts[0]["path"], ground_truth_path)
+
+        correction_sets = self.client.get(
+            f"/api/workflows/{workflow_id}/correction-sets"
+        ).json()
+        self.assertEqual(len(correction_sets), 1)
+        self.assertEqual(correction_sets[0]["corrected_mask_path"], corrected_path)
+        self.assertEqual(correction_sets[0]["edit_count"], 2)
+        self.assertEqual(correction_sets[0]["region_count"], 2)
+
+        model_runs = self.client.get(f"/api/workflows/{workflow_id}/model-runs").json()
+        self.assertEqual(len(model_runs), 1)
+        self.assertEqual(model_runs[0]["run_type"], "training")
+        self.assertEqual(model_runs[0]["status"], "completed")
+        self.assertEqual(model_runs[0]["checkpoint_path"], checkpoint_path)
+        self.assertTrue(model_runs[0]["run_id"].startswith("training-"))
+
+        model_versions = self.client.get(
+            f"/api/workflows/{workflow_id}/model-versions"
+        ).json()
+        self.assertEqual(len(model_versions), 1)
+        self.assertEqual(model_versions[0]["version_label"], "checkpoint.pth")
+
+        bundle = self.client.post(f"/api/workflows/{workflow_id}/export-bundle").json()
+        self.assertGreaterEqual(len(bundle["artifacts"]), 4)
+        self.assertEqual(len(bundle["model_runs"]), 1)
+        self.assertEqual(len(bundle["model_versions"]), 1)
+        self.assertEqual(len(bundle["correction_sets"]), 1)
+
+        events = self.client.get(f"/api/workflows/{workflow_id}/events").json()
+        self.assertIn(
+            "workflow.bundle_exported",
+            {event["event_type"] for event in events},
+        )
+
+    def test_dataset_loaded_with_withheld_ground_truth_creates_reference_artifact(self):
+        workflow_id = self._workflow_id()
+        image_path = self._write_file("withheld-image.tif")
+        holdout_mask_path = self._write_file("withheld-mask.tif")
+        self.client.post(
+            f"/api/workflows/{workflow_id}/events",
+            json={
+                "actor": "user",
+                "event_type": "dataset.loaded",
+                "stage": "visualization",
+                "summary": "Loaded image with external held-out target mask.",
+                "payload": {
+                    "image_path": image_path,
+                    "withheld_ground_truth": holdout_mask_path,
+                },
+            },
+        )
+        artifacts = self.client.get(f"/api/workflows/{workflow_id}/artifacts").json()
+        holdout_artifacts = [
+            artifact
+            for artifact in artifacts
+            if artifact["role"] == "withheld_ground_truth"
+            and artifact["path"] == holdout_mask_path
+        ]
+        self.assertEqual(len(holdout_artifacts), 1)
+        self.assertFalse(
+            holdout_artifacts[0]["metadata"].get("allow_copy_in_bundle", True)
+        )
+
+    def test_model_run_events_pair_by_explicit_run_id(self):
+        workflow_id = self._workflow_id()
+        first_output = self._write_file("training-output-a")
+        second_output = self._write_file("training-output-b")
+        first_checkpoint = self._write_file("checkpoint-a.pth")
+        second_checkpoint = self._write_file("checkpoint-b.pth")
+
+        for run_id, output in (
+            ("train-run-a", first_output),
+            ("train-run-b", second_output),
+        ):
+            response = self.client.post(
+                f"/api/workflows/{workflow_id}/events",
+                json={
+                    "actor": "system",
+                    "event_type": "training.started",
+                    "stage": "retraining_staged",
+                    "summary": f"Started {run_id}.",
+                    "payload": {"run_id": run_id, "outputPath": output},
+                },
+            )
+            self.assertEqual(response.status_code, 200)
+
+        complete_second = self.client.post(
+            f"/api/workflows/{workflow_id}/events",
+            json={
+                "actor": "system",
+                "event_type": "training.completed",
+                "stage": "evaluation",
+                "summary": "Second training completed first.",
+                "payload": {
+                    "run_id": "train-run-b",
+                    "outputPath": second_output,
+                    "checkpointPath": second_checkpoint,
+                },
+            },
+        )
+        self.assertEqual(complete_second.status_code, 200)
+        complete_first = self.client.post(
+            f"/api/workflows/{workflow_id}/events",
+            json={
+                "actor": "system",
+                "event_type": "training.completed",
+                "stage": "evaluation",
+                "summary": "First training completed second.",
+                "payload": {
+                    "run_id": "train-run-a",
+                    "outputPath": first_output,
+                    "checkpointPath": first_checkpoint,
+                },
+            },
+        )
+        self.assertEqual(complete_first.status_code, 200)
+
+        model_runs = self.client.get(f"/api/workflows/{workflow_id}/model-runs").json()
+        runs_by_id = {run["run_id"]: run for run in model_runs}
+        self.assertEqual(runs_by_id["train-run-a"]["checkpoint_path"], first_checkpoint)
+        self.assertEqual(
+            runs_by_id["train-run-b"]["checkpoint_path"], second_checkpoint
+        )
+
+    def test_manual_evaluation_records_and_readiness_endpoint(self):
+        workflow_id = self._workflow_id()
+        report_path = self._write_file("eval-report.json")
+
+        artifact_response = self.client.post(
+            f"/api/workflows/{workflow_id}/artifacts",
+            json={
+                "artifact_type": "evaluation_report",
+                "role": "case_study_evidence",
+                "path": report_path,
+            },
+        )
+        self.assertEqual(artifact_response.status_code, 200)
+        self.assertTrue(artifact_response.json()["exists"])
+
+        run_response = self.client.post(
+            f"/api/workflows/{workflow_id}/model-runs",
+            json={
+                "run_type": "inference",
+                "status": "completed",
+                "output_path": self._write_file("prediction.tif"),
+            },
+        )
+        self.assertEqual(run_response.status_code, 200)
+
+        evaluation_response = self.client.post(
+            f"/api/workflows/{workflow_id}/evaluation-results",
+            json={
+                "name": "before-after-smoke",
+                "candidate_run_id": run_response.json()["id"],
+                "report_path": report_path,
+                "summary": "Smoke comparison completed.",
+                "metrics": {"dice": 0.75},
+            },
+        )
+        self.assertEqual(evaluation_response.status_code, 200)
+        self.assertEqual(evaluation_response.json()["metrics"]["dice"], 0.75)
+
+        readiness_response = self.client.get(
+            f"/api/workflows/{workflow_id}/case-study-readiness"
+        )
+        self.assertEqual(readiness_response.status_code, 200)
+        readiness = readiness_response.json()
+        self.assertEqual(readiness["workflow_id"], workflow_id)
+        self.assertEqual(readiness["total_count"], len(readiness["gates"]))
+        self.assertIn("next_required_items", readiness)
+
+    def test_compute_evaluation_result_records_before_after_metrics(self):
+        workflow_id = self._workflow_id()
+        ground_truth_path = self.root / "ground-truth.tif"
+        baseline_path = self.root / "baseline-prediction.tif"
+        candidate_path = self.root / "candidate-prediction.tif"
+        report_path = self.root / "computed-eval.json"
+
+        ground_truth = np.zeros((1, 4, 4), dtype=np.uint8)
+        ground_truth[:, 1:3, 1:3] = 1
+        baseline = np.zeros_like(ground_truth)
+        baseline[:, 1:2, 1:2] = 1
+        candidate = ground_truth.copy()
+        tifffile.imwrite(str(ground_truth_path), ground_truth)
+        tifffile.imwrite(str(baseline_path), baseline)
+        tifffile.imwrite(str(candidate_path), candidate)
+
+        response = self.client.post(
+            f"/api/workflows/{workflow_id}/evaluation-results/compute",
+            json={
+                "name": "computed-before-after",
+                "ground_truth_path": str(ground_truth_path),
+                "baseline_prediction_path": str(baseline_path),
+                "candidate_prediction_path": str(candidate_path),
+                "report_path": str(report_path),
+            },
+        )
+        self.assertEqual(response.status_code, 200)
+        payload = response.json()
+        self.assertEqual(payload["name"], "computed-before-after")
+        self.assertTrue(payload["metrics"]["summary"]["candidate_improved_dice"])
+        self.assertGreater(payload["metrics"]["delta"]["dice"], 0)
+        self.assertTrue(report_path.exists())
+
+    def test_compute_evaluation_result_supports_hdf5_dataset_keys_and_crop(self):
+        workflow_id = self._workflow_id()
+        ground_truth_path = self.root / "ground-truth.h5"
+        baseline_path = self.root / "baseline-prediction.h5"
+        candidate_path = self.root / "candidate-prediction.h5"
+
+        ground_truth = np.zeros((4, 8, 8), dtype=np.uint16)
+        ground_truth[:, 2:6, 2:6] = 1
+        baseline = ground_truth.copy()
+        baseline[:, :, :3] = 0
+        candidate = ground_truth.copy()
+        for path, dataset, array in [
+            (ground_truth_path, "data", ground_truth),
+            (baseline_path, "prediction", baseline),
+            (candidate_path, "prediction", candidate),
+        ]:
+            with h5py.File(path, "w") as handle:
+                handle.create_dataset(dataset, data=array)
+
+        response = self.client.post(
+            f"/api/workflows/{workflow_id}/evaluation-results/compute",
+            json={
+                "name": "computed-hdf5-before-after",
+                "ground_truth_path": str(ground_truth_path),
+                "ground_truth_dataset": "data",
+                "baseline_prediction_path": str(baseline_path),
+                "baseline_dataset": "prediction",
+                "candidate_prediction_path": str(candidate_path),
+                "candidate_dataset": "prediction",
+                "crop": "0:2,0:8,0:8",
+            },
+        )
+        self.assertEqual(response.status_code, 200)
+        payload = response.json()
+        self.assertTrue(payload["metrics"]["summary"]["candidate_improved_dice"])
+        self.assertEqual(payload["metadata"]["ground_truth_dataset"], "data")
+        self.assertEqual(payload["metadata"]["crop"], "0:2,0:8,0:8")
+
+    def test_compute_evaluation_result_supports_prediction_channel_selection(self):
+        workflow_id = self._workflow_id()
+        ground_truth_path = self.root / "ground-truth.h5"
+        baseline_path = self.root / "baseline-result_xy.h5"
+        candidate_path = self.root / "candidate-result_xy.h5"
+
+        ground_truth = np.zeros((4, 8, 8), dtype=np.uint16)
+        ground_truth[:, 2:6, 2:6] = 1
+        baseline_mask = ground_truth.copy()
+        baseline_mask[:, :, :4] = 0
+        candidate_mask = ground_truth.copy()
+        baseline = np.stack([np.zeros_like(ground_truth), baseline_mask])
+        candidate = np.stack([np.zeros_like(ground_truth), candidate_mask])
+        for path, dataset, array in [
+            (ground_truth_path, "data", ground_truth),
+            (baseline_path, "vol0", baseline),
+            (candidate_path, "vol0", candidate),
+        ]:
+            with h5py.File(path, "w") as handle:
+                handle.create_dataset(dataset, data=array)
+
+        response = self.client.post(
+            f"/api/workflows/{workflow_id}/evaluation-results/compute",
+            json={
+                "name": "computed-channel-before-after",
+                "ground_truth_path": str(ground_truth_path),
+                "ground_truth_dataset": "data",
+                "baseline_prediction_path": str(baseline_path),
+                "baseline_dataset": "vol0",
+                "baseline_channel": 1,
+                "candidate_prediction_path": str(candidate_path),
+                "candidate_dataset": "vol0",
+                "candidate_channel": 1,
+                "crop": "0:2,0:8,0:8",
+            },
+        )
+        self.assertEqual(response.status_code, 200)
+        payload = response.json()
+        self.assertTrue(payload["metrics"]["summary"]["candidate_improved_dice"])
+        self.assertGreater(payload["metrics"]["delta"]["dice"], 0)
+        self.assertEqual(payload["metadata"]["baseline_channel"], 1)
+        self.assertEqual(payload["metadata"]["candidate_channel"], 1)
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/tests/test_workflow_case_study_acceptance.py b/tests/test_workflow_case_study_acceptance.py
new file mode 100644
index 00000000..df9d1777
--- /dev/null
+++ b/tests/test_workflow_case_study_acceptance.py
@@ -0,0 +1,260 @@
+import pathlib
+import tempfile
+import unittest
+
+import numpy as np
+import pytest
+
+pytest.importorskip("sqlalchemy")
+from sqlalchemy import create_engine
+from sqlalchemy.orm import sessionmaker
+
+pytest.importorskip("fastapi")
+tifffile = pytest.importorskip("tifffile")
+from fastapi.testclient import TestClient
+
+from server_api.auth import database as auth_database
+from server_api.auth import models
+from server_api.main import app as server_api_app
+
+
+class WorkflowCaseStudyAcceptanceTests(unittest.TestCase):
+    def setUp(self):
+        self.temp_dir = tempfile.TemporaryDirectory()
+        self.root = pathlib.Path(self.temp_dir.name)
+        self.db_path = self.root / "workflow-case-study.db"
+        self.engine = create_engine(
+            f"sqlite:///{self.db_path}", connect_args={"check_same_thread": False}
+        )
+        self.SessionLocal = sessionmaker(
+            autocommit=False, autoflush=False, bind=self.engine
+        )
+        models.Base.metadata.create_all(bind=self.engine)
+
+        def override_get_db():
+            db = self.SessionLocal()
+            try:
+                yield db
+            finally:
+                db.close()
+
+        server_api_app.dependency_overrides[auth_database.get_db] = override_get_db
+        self.client = TestClient(server_api_app)
+
+    def tearDown(self):
+        server_api_app.dependency_overrides.clear()
+        self.engine.dispose()
+        self.temp_dir.cleanup()
+
+    def _workflow_id(self):
+        response = self.client.get("/api/workflows/current")
+        self.assertEqual(response.status_code, 200)
+        return response.json()["workflow"]["id"]
+
+    def _write_file(self, name: str, content: str = "artifact") -> str:
+        path = self.root / name
+        path.write_text(content, encoding="utf-8")
+        return str(path)
+
+    def test_synthetic_closed_loop_reaches_case_study_readiness(self):
+        workflow_id = self._workflow_id()
+        image_path = self._write_file("image.tif")
+        mask_path = self._write_file("mask.tif")
+        corrected_path = self._write_file("corrected-mask.tif")
+        training_output = self._write_file("training-output")
+        checkpoint_path = self._write_file("checkpoint.pth")
+        report_path = self.root / "before-after-report.json"
+
+        ground_truth_path = self.root / "ground-truth.tif"
+        baseline_path = self.root / "baseline-prediction.tif"
+        candidate_path = self.root / "candidate-prediction.tif"
+        ground_truth = np.zeros((1, 4, 4), dtype=np.uint8)
+        ground_truth[:, 1:3, 1:3] = 1
+        baseline = np.zeros_like(ground_truth)
+        baseline[:, 1:2, 1:2] = 1
+        candidate = ground_truth.copy()
+        tifffile.imwrite(str(ground_truth_path), ground_truth)
+        tifffile.imwrite(str(baseline_path), baseline)
+        tifffile.imwrite(str(candidate_path), candidate)
+
+        self.client.post(
+            f"/api/workflows/{workflow_id}/events",
+            json={
+                "actor": "user",
+                "event_type": "dataset.loaded",
+                "stage": "visualization",
+                "summary": "Loaded sample image and mask.",
+                "payload": {"image_path": image_path, "mask_path": mask_path},
+            },
+        )
+        self.client.post(
+            f"/api/workflows/{workflow_id}/events",
+            json={
+                "actor": "system",
+                "event_type": "inference.completed",
+                "stage": "inference",
+                "summary": "Baseline inference completed.",
+                "payload": {"outputPath": str(baseline_path)},
+            },
+        )
+        self.client.post(
+            f"/api/workflows/{workflow_id}/events",
+            json={
+                "actor": "user",
+                "event_type": "proofreading.instance_classified",
+                "stage": "proofreading",
+                "summary": "Marked a top hotspot as incorrect.",
+                "payload": {"region_id": "z:1", "classification": "incorrect"},
+            },
+        )
+        self.client.post(
+            f"/api/workflows/{workflow_id}/events",
+            json={
+                "actor": "user",
+                "event_type": "proofreading.mask_saved",
+                "stage": "proofreading",
+                "summary": "Saved corrected hotspot mask.",
+                "payload": {"region_id": "z:1", "instance_id": 42},
+            },
+        )
+        self.client.post(
+            f"/api/workflows/{workflow_id}/events",
+            json={
+                "actor": "system",
+                "event_type": "proofreading.masks_exported",
+                "stage": "proofreading",
+                "summary": "Exported corrected masks.",
+                "payload": {"written_path": corrected_path, "region_id": "z:1"},
+            },
+        )
+        self.client.get(f"/api/workflows/{workflow_id}/hotspots")
+
+        proposal = self.client.post(
+            f"/api/workflows/{workflow_id}/agent-actions",
+            json={
+                "action": "stage_retraining_from_corrections",
+                "summary": "Stage corrections for retraining.",
+                "payload": {"corrected_mask_path": corrected_path},
+            },
+        ).json()
+        approve_proposal = self.client.post(
+            f"/api/workflows/{workflow_id}/agent-actions/{proposal['id']}/approve"
+        )
+        self.assertEqual(approve_proposal.status_code, 200)
+
+        self.client.post(
+            f"/api/workflows/{workflow_id}/events",
+            json={
+                "actor": "system",
+                "event_type": "training.completed",
+                "stage": "evaluation",
+                "summary": "Retraining completed.",
+                "payload": {
+                    "outputPath": training_output,
+                    "checkpointPath": checkpoint_path,
+                    "checkpointName": "checkpoint.pth",
+                },
+            },
+        )
+        self.client.post(
+            f"/api/workflows/{workflow_id}/events",
+            json={
+                "actor": "system",
+                "event_type": "inference.completed",
+                "stage": "evaluation",
+                "summary": "Candidate inference completed.",
+                "payload": {
+                    "outputPath": str(candidate_path),
+                    "checkpointPath": checkpoint_path,
+                },
+            },
+        )
+
+        plan = self.client.post(
+            f"/api/workflows/{workflow_id}/agent-plans",
+            json={"title": "Synthetic case-study loop"},
+        ).json()
+        approve_plan = self.client.post(
+            f"/api/workflows/{workflow_id}/agent-plans/{plan['id']}/approve"
+        )
+        self.assertEqual(approve_plan.status_code, 200)
+
+        evaluation = self.client.post(
+            f"/api/workflows/{workflow_id}/evaluation-results/compute",
+            json={
+                "name": "case-study-before-after",
+                "ground_truth_path": str(ground_truth_path),
+                "baseline_prediction_path": str(baseline_path),
+                "candidate_prediction_path": str(candidate_path),
+                "report_path": str(report_path),
+            },
+        )
+        self.assertEqual(evaluation.status_code, 200)
+        self.assertTrue(
+            evaluation.json()["metrics"]["summary"]["candidate_improved_dice"]
+        )
+
+        readiness = self.client.get(
+            f"/api/workflows/{workflow_id}/case-study-readiness"
+        )
+        self.assertEqual(readiness.status_code, 200)
+        readiness_payload = readiness.json()
+        self.assertTrue(readiness_payload["ready_for_case_study"])
+        self.assertEqual(readiness_payload["next_required_items"], [])
+
+        bundle = self.client.post(f"/api/workflows/{workflow_id}/export-bundle").json()
+        self.assertGreaterEqual(len(bundle["events"]), 10)
+        self.assertEqual(len(bundle["agent_plans"]), 1)
+        self.assertGreaterEqual(len(bundle["model_runs"]), 3)
+        self.assertEqual(len(bundle["model_versions"]), 1)
+        self.assertEqual(len(bundle["evaluation_results"]), 1)
+
+    def test_case_study_readiness_gate_taxonomy_surface(self):
+        workflow_id = self._workflow_id()
+
+        response = self.client.get(f"/api/workflows/{workflow_id}/case-study-readiness")
+        self.assertEqual(response.status_code, 200)
+        readiness = response.json()
+
+        required_top_level = {
+            "workflow_id",
+            "ready_for_case_study",
+            "completed_count",
+            "total_count",
+            "gates",
+            "next_required_items",
+        }
+        self.assertTrue(required_top_level.issubset(readiness))
+        self.assertEqual(readiness["workflow_id"], workflow_id)
+        self.assertIsInstance(readiness["gates"], list)
+        self.assertIsInstance(readiness["next_required_items"], list)
+        self.assertEqual(len(readiness["gates"]), readiness["total_count"])
+
+        gate_ids = {item["id"] for item in readiness["gates"]}
+        for required_gate in [
+            "workflow_context",
+            "data_loaded",
+            "baseline_inference",
+            "proofreading_corrections",
+            "retraining_handoff",
+            "training_completion",
+            "model_version",
+            "post_retraining_inference",
+            "evaluation_result",
+            "agent_plan_preview",
+            "agent_audit",
+        ]:
+            self.assertIn(required_gate, gate_ids)
+
+        self.assertLessEqual(
+            len(readiness["next_required_items"]), readiness["total_count"]
+        )
+        if readiness["ready_for_case_study"]:
+            self.assertEqual(readiness["completed_count"], readiness["total_count"])
+            self.assertEqual(readiness["next_required_items"], [])
+        else:
+            self.assertGreaterEqual(readiness["completed_count"], 0)
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/tests/test_workflow_evidence_export.py b/tests/test_workflow_evidence_export.py
index 9792ff16..a808728f 100644
--- a/tests/test_workflow_evidence_export.py
+++ b/tests/test_workflow_evidence_export.py
@@ -3,6 +3,7 @@
 import unittest
 
 import pytest
+
 pytest.importorskip("sqlalchemy")
 from sqlalchemy import create_engine
 from sqlalchemy.orm import sessionmaker
@@ -52,29 +53,91 @@ def test_evidence_export_contains_required_sections(self):
         self.assertEqual(response.status_code, 200)
         workflow_id = response.json()["workflow"]["id"]
 
+        proposal = self.client.post(
+            f"/api/workflows/{workflow_id}/agent-actions",
+            json={
+                "action": "start_training_run",
+                "summary": "Start training from proposal",
+                "payload": {
+                    "label_path": "/tmp/project/label.tif",
+                    "run_reference": "evidence-run-1",
+                },
+            },
+        )
+        self.assertEqual(proposal.status_code, 200)
+        proposal_id = proposal.json()["id"]
+
+        approval = self.client.post(
+            f"/api/workflows/{workflow_id}/agent-actions/{proposal_id}/approve"
+        )
+        self.assertEqual(approval.status_code, 200)
+        run_response = self.client.post(
+            f"/api/workflows/{workflow_id}/model-runs",
+            json={
+                "run_id": "evidence-run-1",
+                "run_type": "training",
+                "status": "completed",
+                "name": "evidence-run-1",
+                "config_path": "/tmp/project/config.yaml",
+                "output_path": "/tmp/project/train-output",
+                "checkpoint_path": "/tmp/project/checkpoint.pt",
+                "input_artifact_id": None,
+                "output_artifact_id": None,
+                "metrics": {},
+                "metadata": {},
+            },
+        )
+        self.assertEqual(run_response.status_code, 200)
+
+        self.client.post(
+            f"/api/workflows/{workflow_id}/events",
+            json={
+                "actor": "system",
+                "event_type": "training.started",
+                "stage": "retraining_staged",
+                "summary": "Training started",
+                "payload": {
+                    "run_id": "evidence-run-1",
+                    "outputPath": "/tmp/project/train-output",
+                    "checkpointPath": "/tmp/project/checkpoint.pt",
+                },
+            },
+        )
         self.client.post(
             f"/api/workflows/{workflow_id}/events",
             json={
-                "actor": "agent",
-                "event_type": "agent.proposal_created",
-                "stage": "proofreading",
-                "summary": "Proposal created",
-                "approval_status": "pending",
+                "actor": "system",
+                "event_type": "training.completed",
+                "stage": "retraining_staged",
+                "summary": "Training completed",
+                "payload": {
+                    "run_id": "evidence-run-1",
+                    "outputPath": "/tmp/project/train-output",
+                    "checkpointPath": "/tmp/project/checkpoint.pt",
+                    "checkpointName": "checkpoint.pt",
+                },
             },
         )
         self.client.post(
             f"/api/workflows/{workflow_id}/events",
             json={
-                "actor": "user",
-                "event_type": "agent.proposal_approved",
+                "actor": "system",
+                "event_type": "inference.failed",
                 "stage": "retraining_staged",
-                "summary": "Proposal approved",
+                "summary": "Inference failed",
+                "payload": {
+                    "run_id": "evidence-run-1",
+                    "outputPath": "/tmp/project/infer-output",
+                    "checkpointPath": "/tmp/project/checkpoint.pt",
+                },
             },
         )
 
         with self.SessionLocal() as db:
             workflow = (
-                db.query(WorkflowSession).filter(WorkflowSession.id == workflow_id).first()
+                db.query(WorkflowSession)
+                .filter(WorkflowSession.id == workflow_id)
+                .first()
             )
             events = (
                 db.query(WorkflowEvent)
@@ -82,16 +145,67 @@ def test_evidence_export_contains_required_sections(self):
                 .order_by(WorkflowEvent.created_at.asc(), WorkflowEvent.id.asc())
                 .all()
             )
+            export_payload = build_workflow_evidence_export(workflow, events)
 
-        export_payload = build_workflow_evidence_export(workflow, events)
         self.assertEqual(export_payload["version"], EVIDENCE_EXPORT_VERSION)
         self.assertEqual(export_payload["workflow_id"], workflow_id)
         self.assertIn("stage_progression_summary", export_payload)
         self.assertIn("agent_proposal_approval_summary", export_payload)
+        self.assertIn("agent_proposal_approval_links", export_payload)
+        self.assertIn("agent_proposal_approval_graph", export_payload)
+        self.assertIn("user_status_changes", export_payload)
         self.assertIn("key_event_timeline_snippet", export_payload)
+        self.assertIn("project_memory_summary", export_payload)
         self.assertGreaterEqual(
             export_payload["agent_proposal_approval_summary"]["approved_count"], 1
         )
+        self.assertEqual(
+            export_payload["project_memory_summary"]["schema_version"],
+            "pytc-project-memory-summary/v1",
+        )
+        self.assertGreaterEqual(len(export_payload["user_status_changes"]), 1)
+        self.assertTrue(
+            any(
+                change.get("event_type") == "agent.proposal_approved"
+                for change in export_payload["user_status_changes"]
+            )
+        )
+        self.assertEqual(
+            export_payload["agent_proposal_approval_links"][0]["approval_status"],
+            "approved",
+        )
+        self.assertIn("action", export_payload["agent_proposal_approval_links"][0])
+        self.assertIn("model_context", export_payload)
+
+        graph = export_payload["agent_proposal_approval_graph"]
+        self.assertEqual(len(graph), 1)
+        node = graph[0]
+        self.assertEqual(node["proposal"]["action"], "start_training_run")
+        self.assertIsNotNone(node["approval"])
+        self.assertEqual(node["approval"]["status"], "approved")
+        self.assertTrue(
+            any(
+                item["event_type"] == "training.run_approved"
+                for item in node["action_events"]
+            )
+        )
+        self.assertTrue(
+            any(
+                item.get("command_type") == "start_training"
+                for item in node["commands"]
+            )
+        )
+        self.assertEqual(len(node["runs"]), 1)
+        run_node = node["runs"][0]
+        self.assertEqual(run_node["run_type"], "training")
+        self.assertEqual(run_node["run_id"], "evidence-run-1")
+        self.assertGreaterEqual(len(run_node["progress_events"]), 2)
+        self.assertEqual(
+            run_node["progress_events"][0]["event_type"], "training.started"
+        )
+        self.assertEqual(
+            run_node["progress_events"][1]["event_type"], "training.completed"
+        )
 
 
 if __name__ == "__main__":
diff --git a/tests/test_workflow_export_bundle.py b/tests/test_workflow_export_bundle.py
index d166e53f..d154152a 100644
--- a/tests/test_workflow_export_bundle.py
+++ b/tests/test_workflow_export_bundle.py
@@ -1,8 +1,11 @@
+import json
 import pathlib
 import tempfile
 import unittest
+from unittest.mock import patch
 
 import pytest
+
 pytest.importorskip("sqlalchemy")
 from sqlalchemy import create_engine
 from sqlalchemy.orm import sessionmaker
@@ -72,21 +75,254 @@ def test_export_bundle_sorts_events_and_reports_artifact_existence(self):
                 "payload": {"output_path": str(existing_path)},
             },
         )
+        agent_response = self.client.post(
+            f"/api/workflows/{workflow_id}/agent/query",
+            json={"query": "what should I do next?"},
+        )
+        self.assertEqual(agent_response.status_code, 200)
 
-        response = self.client.post(f"/api/workflows/{workflow_id}/export-bundle")
+        bundle_root = pathlib.Path(self.temp_dir.name) / "bundles"
+        with patch.dict(
+            "os.environ",
+            {"PYTC_WORKFLOW_BUNDLE_DIR": str(bundle_root)},
+        ):
+            response = self.client.post(f"/api/workflows/{workflow_id}/export-bundle")
         self.assertEqual(response.status_code, 200)
         payload = response.json()
 
         self.assertEqual(payload["schema_version"], "workflow-export-bundle/v1")
         self.assertEqual(payload["workflow_id"], workflow_id)
         self.assertIsInstance(payload["events"], list)
+        self.assertEqual(
+            payload["project_memory"]["schema_version"],
+            "pytc-project-memory/v1",
+        )
+        self.assertEqual(
+            payload["project_memory_summary"]["schema_version"],
+            "pytc-project-memory-summary/v1",
+        )
+        self.assertEqual(
+            payload["project_memory_summary"]["workflow_id"],
+            workflow_id,
+        )
+        self.assertEqual(payload["project_memory"]["workflow_id"], workflow_id)
+        self.assertTrue(payload["agent_messages"])
+        self.assertTrue(payload["trace_index"])
+        self.assertTrue(all(entry.get("category") for entry in payload["trace_index"]))
+        self.assertIn("action_card_index", payload)
         self.assertGreaterEqual(len(payload["events"]), 2)  # includes workflow.created
 
-        artifacts = {entry["path"]: entry["exists"] for entry in payload["artifact_paths"]}
+        artifacts = {
+            entry["path"]: entry["exists"] for entry in payload["artifact_paths"]
+        }
         self.assertIn(str(existing_path), artifacts)
         self.assertIn(str(missing_path), artifacts)
         self.assertTrue(artifacts[str(existing_path)])
         self.assertFalse(artifacts[str(missing_path)])
+        missing_skipped = {
+            entry["path"]: entry
+            for entry in payload["skipped_artifacts"]
+            if entry.get("path")
+        }
+        self.assertEqual(
+            missing_skipped[str(missing_path)]["copy_mode"],
+            "missing",
+        )
+        self.assertEqual(
+            missing_skipped[str(missing_path)]["copy_policy"]["allow_copy"],
+            False,
+        )
+        manifest_path = pathlib.Path(payload["bundle_manifest_path"])
+        self.assertTrue(manifest_path.exists())
+        self.assertEqual(manifest_path.name, "workflow-bundle.json")
+        self.assertTrue((manifest_path.parent / "README.md").exists())
+        self.assertTrue((manifest_path.parent / "artifact-paths.json").exists())
+        persisted_manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+        self.assertEqual(
+            persisted_manifest["project_memory"]["schema_version"],
+            "pytc-project-memory/v1",
+        )
+        self.assertEqual(
+            persisted_manifest["project_memory_summary"]["schema_version"],
+            "pytc-project-memory-summary/v1",
+        )
+        copied_paths = {
+            pathlib.Path(entry["bundle_path"]).name
+            for entry in payload["copied_artifacts"]
+        }
+        self.assertTrue(any("existing-mask.tif" in name for name in copied_paths))
+
+        events = self.client.get(f"/api/workflows/{workflow_id}/events").json()
+        export_event = [
+            event
+            for event in events
+            if event["event_type"] == "workflow.bundle_exported"
+        ][-1]
+        self.assertEqual(
+            export_event["payload"]["bundle_manifest_path"],
+            payload["bundle_manifest_path"],
+        )
+
+    def test_export_bundle_raw_copy_limits_and_manifest_only_mode(self):
+        workflow_id = self._current_workflow_id()
+        raw_image_path = (
+            pathlib.Path(self.temp_dir.name) / "data" / "raw" / "image-raw.tif"
+        )
+        raw_image_path.parent.mkdir(parents=True, exist_ok=True)
+        raw_image_path.write_bytes(b"x" * 64)
+
+        config_path = pathlib.Path(self.temp_dir.name) / "configs" / "small-config.yaml"
+        config_path.parent.mkdir(parents=True, exist_ok=True)
+        config_path.write_text("a: 1", encoding="utf-8")
+
+        self.client.patch(
+            f"/api/workflows/{workflow_id}",
+            json={
+                "image_path": str(raw_image_path),
+                "config_path": str(config_path),
+                "stage": "proofreading",
+            },
+        )
+
+        bundle_root = pathlib.Path(self.temp_dir.name) / "bundles"
+        with patch.dict(
+            "os.environ",
+            {
+                "PYTC_WORKFLOW_BUNDLE_DIR": str(bundle_root),
+                "PYTC_WORKFLOW_BUNDLE_RAW_COPY_MAX_BYTES": "0",
+            },
+        ):
+            default_response = self.client.post(
+                f"/api/workflows/{workflow_id}/export-bundle",
+                params={"copy_max_bytes": 5},
+            )
+            manifest_response = self.client.post(
+                f"/api/workflows/{workflow_id}/export-bundle",
+                params={"copy_manifest_only": "true"},
+            )
+
+        self.assertEqual(default_response.status_code, 200)
+        self.assertEqual(manifest_response.status_code, 200)
+
+        default_payload = default_response.json()
+        skipped_default = {
+            entry["path"]: entry for entry in default_payload["skipped_artifacts"]
+        }
+        copied_default = {
+            entry["path"]: entry for entry in default_payload["copied_artifacts"]
+        }
+        self.assertIn(str(raw_image_path), skipped_default)
+        self.assertIn(str(config_path), copied_default)
+        self.assertIn(
+            skipped_default[str(raw_image_path)]["reason"],
+            {"raw_larger_than_copy_limit", "larger_than_copy_limit"},
+        )
+        self.assertEqual(
+            skipped_default[str(raw_image_path)]["copy_mode"],
+            "size_limit",
+        )
+        self.assertIsNotNone(skipped_default[str(raw_image_path)]["copy_policy"])
+        self.assertFalse(default_payload["copy_settings"]["copy_manifest_only"])
+
+        manifest_payload = manifest_response.json()
+        skipped_manifest = {
+            entry["path"]: entry for entry in manifest_payload["skipped_artifacts"]
+        }
+        self.assertTrue(manifest_payload["copy_settings"]["copy_manifest_only"])
+        self.assertEqual(manifest_payload["copied_artifacts"], [])
+        self.assertIn(str(raw_image_path), skipped_manifest)
+        self.assertIn(str(config_path), skipped_manifest)
+        self.assertEqual(
+            skipped_manifest[str(raw_image_path)]["reason"], "manifest_only"
+        )
+        self.assertEqual(skipped_manifest[str(config_path)]["reason"], "manifest_only")
+        self.assertEqual(
+            skipped_manifest[str(raw_image_path)]["copy_mode"], "manifest_only"
+        )
+        self.assertEqual(
+            skipped_manifest[str(config_path)]["copy_mode"], "manifest_only"
+        )
+
+    def test_export_bundle_tracks_holdout_reference_only_artifacts(self):
+        workflow_id = self._current_workflow_id()
+        dataset_root = pathlib.Path(self.temp_dir.name) / "project"
+        holdout_root = pathlib.Path(self.temp_dir.name) / "holdout"
+        dataset_root.mkdir()
+        holdout_root.mkdir()
+        image_path = dataset_root / "image.tif"
+        image_path.write_text("image", encoding="utf-8")
+        holdout_gt = holdout_root / "6_1-mask.tif"
+        holdout_gt.write_text("ground-truth", encoding="utf-8")
+
+        self.client.patch(
+            f"/api/workflows/{workflow_id}",
+            json={
+                "dataset_path": str(dataset_root),
+                "image_path": str(image_path),
+                "stage": "visualization",
+            },
+        )
+        self.client.post(
+            f"/api/workflows/{workflow_id}/events",
+            json={
+                "actor": "user",
+                "event_type": "dataset.loaded",
+                "stage": "visualization",
+                "summary": "Loaded image with external holdout mask.",
+                "payload": {
+                    "image_path": str(image_path),
+                    "withheld_ground_truth": str(holdout_gt),
+                },
+            },
+        )
+
+        bundle_root = pathlib.Path(self.temp_dir.name) / "bundles"
+        with patch.dict(
+            "os.environ",
+            {"PYTC_WORKFLOW_BUNDLE_DIR": str(bundle_root)},
+        ):
+            response = self.client.post(f"/api/workflows/{workflow_id}/export-bundle")
+        self.assertEqual(response.status_code, 200)
+        payload = response.json()
+
+        artifact_paths = {
+            entry["path"]: entry
+            for entry in payload["artifact_paths"]
+            if entry.get("path")
+        }
+        self.assertIn(str(holdout_gt), artifact_paths)
+        holdout_entry = artifact_paths[str(holdout_gt)]
+        self.assertFalse(holdout_entry["copy_policy"]["allow_copy"])
+        self.assertEqual(holdout_entry["copy_policy"]["reason"], "withheld_reference")
+        self.assertTrue(
+            any(
+                source.get("source_key") == "withheld_ground_truth"
+                for source in holdout_entry.get("sources", [])
+            )
+        )
+        self.assertIn(
+            str(holdout_gt), [entry["path"] for entry in payload["skipped_artifacts"]]
+        )
+        skipped = {
+            entry["path"]: entry
+            for entry in payload["skipped_artifacts"]
+            if entry.get("path")
+        }
+        self.assertEqual(
+            skipped[str(holdout_gt)]["reason"],
+            "reference_only_policy",
+        )
+        self.assertEqual(
+            skipped[str(holdout_gt)]["copy_mode"],
+            "policy",
+        )
+        self.assertFalse(skipped[str(holdout_gt)]["copy_policy"]["allow_copy"])
+        self.assertEqual(
+            skipped[str(holdout_gt)]["copy_policy"]["reason"],
+            "withheld_reference",
+        )
+        copied_paths = {entry["path"] for entry in payload["copied_artifacts"]}
+        self.assertNotIn(str(holdout_gt), copied_paths)
 
 
 if __name__ == "__main__":
diff --git a/tests/test_workflow_metrics.py b/tests/test_workflow_metrics.py
index 5f72479d..00a23e68 100644
--- a/tests/test_workflow_metrics.py
+++ b/tests/test_workflow_metrics.py
@@ -3,6 +3,7 @@
 import unittest
 
 import pytest
+
 pytest.importorskip("sqlalchemy")
 from sqlalchemy import create_engine
 from sqlalchemy.orm import sessionmaker
@@ -99,7 +100,9 @@ def test_metrics_aggregates_events_and_decisions(self):
             },
         ]
         for event in events:
-            response = self.client.post(f"/api/workflows/{workflow_id}/events", json=event)
+            response = self.client.post(
+                f"/api/workflows/{workflow_id}/events", json=event
+            )
             self.assertEqual(response.status_code, 200)
 
         response = self.client.get(f"/api/workflows/{workflow_id}/metrics")
diff --git a/tests/test_workflow_routes.py b/tests/test_workflow_routes.py
index da48d11f..a2161633 100644
--- a/tests/test_workflow_routes.py
+++ b/tests/test_workflow_routes.py
@@ -1,9 +1,12 @@
 import pathlib
+import json
 import tempfile
 import unittest
+from unittest.mock import patch
 
 import numpy as np
 import pytest
+
 pytest.importorskip("sqlalchemy")
 from sqlalchemy import create_engine
 from sqlalchemy.orm import sessionmaker
@@ -17,6 +20,7 @@
 import server_api.ehtool.router as ehtool_router_module
 from server_api.ehtool.utils import array_to_base64
 from server_api.main import app as server_api_app
+import server_api.workflows.router as workflows_router_module
 
 
 class WorkflowRouteTests(unittest.TestCase):
@@ -53,6 +57,32 @@ def _current_workflow(self):
         payload = response.json()
         return payload["workflow"], payload["events"]
 
+    def test_semantic_workflow_intents_have_one_source_of_truth(self):
+        prompt_intents = set(workflows_router_module.SEMANTIC_WORKFLOW_INTENT_ORDER)
+        self.assertEqual(
+            prompt_intents, workflows_router_module.SEMANTIC_WORKFLOW_INTENTS
+        )
+        self.assertIn("style_feedback", prompt_intents)
+        self.assertIn("project_files", prompt_intents)
+        self.assertIn("project_progress", prompt_intents)
+
+    def test_project_progress_matches_nested_xri_mask_by_volume_folder(self):
+        root = "/demo/yixiao"
+        image_path = f"{root}/data/raw/5_1/5_1-xri-raw.tif"
+        segmentation_paths = [
+            f"{root}/data/seg/4_3/4_3-mask.tif",
+            f"{root}/data/seg/5_1/5_1-mask.tif",
+        ]
+
+        matched = workflows_router_module._project_progress_match_segmentation(
+            image_path,
+            segmentation_paths,
+            project_root=root,
+            single_image=False,
+        )
+
+        self.assertEqual(matched, f"{root}/data/seg/5_1/5_1-mask.tif")
+
     def test_current_workflow_create_update_and_events(self):
         workflow, events = self._current_workflow()
 
@@ -88,6 +118,326 @@ def test_current_workflow_create_update_and_events(self):
         event_types = [event["event_type"] for event in events_response.json()]
         self.assertEqual(event_types, ["workflow.created", "dataset.loaded"])
 
+    def test_metadata_patches_merge_and_event_idempotency_is_stable(self):
+        workflow, _ = self._current_workflow()
+        workflow_id = workflow["id"]
+
+        first_patch = self.client.patch(
+            f"/api/workflows/{workflow_id}",
+            json={
+                "metadata": {
+                    "project_context": {
+                        "imaging_modality": "EM",
+                        "target_structure": "mitochondria",
+                    },
+                    "session_onboarding": {"goals": "draft"},
+                },
+            },
+        )
+        self.assertEqual(first_patch.status_code, 200)
+        second_patch = self.client.patch(
+            f"/api/workflows/{workflow_id}",
+            json={
+                "metadata": {"project_context": {"optimization_priority": "accuracy"}},
+            },
+        )
+        self.assertEqual(second_patch.status_code, 200)
+        metadata = second_patch.json()["metadata"]
+        self.assertEqual(metadata["project_context"]["imaging_modality"], "EM")
+        self.assertEqual(
+            metadata["project_context"]["target_structure"], "mitochondria"
+        )
+        self.assertEqual(
+            metadata["project_context"]["optimization_priority"],
+            "accuracy",
+        )
+        self.assertEqual(metadata["session_onboarding"]["goals"], "draft")
+
+        event_body = {
+            "actor": "system",
+            "event_type": "training.started",
+            "stage": "retraining_staged",
+            "summary": "Started once.",
+            "payload": {"outputPath": "/tmp/training-run"},
+            "idempotency_key": "runtime:start-training:abc",
+        }
+        first_event = self.client.post(
+            f"/api/workflows/{workflow_id}/events",
+            json=event_body,
+        )
+        self.assertEqual(first_event.status_code, 200)
+        second_event = self.client.post(
+            f"/api/workflows/{workflow_id}/events",
+            json={**event_body, "summary": "Retried request."},
+        )
+        self.assertEqual(second_event.status_code, 200)
+        self.assertEqual(first_event.json()["id"], second_event.json()["id"])
+        self.assertEqual(first_event.json()["schema_version"], 1)
+        self.assertEqual(
+            first_event.json()["idempotency_key"],
+            "runtime:start-training:abc",
+        )
+
+    def test_project_memory_endpoint_returns_canonical_context(self):
+        workflow, _ = self._current_workflow()
+        workflow_id = workflow["id"]
+        patch_response = self.client.patch(
+            f"/api/workflows/{workflow_id}",
+            json={
+                "title": "Yixiao TapeReader XRI Case Study",
+                "stage": "setup",
+                "dataset_path": "/projects/yixiao",
+                "image_path": "/projects/yixiao/data/raw",
+                "label_path": "/projects/yixiao/data/seg",
+                "metadata": {
+                    "project_context": {
+                        "imaging_modality": "X-ray / XRI volumetric microscopy",
+                        "target_structure": "CytoTape fibres",
+                        "task_family": "XRI fibre instance segmentation",
+                        "voxel_size_nm": [40, 16.3, 16.3],
+                        "mask_status": "mixed: some masks, some image-only volumes",
+                        "training_policy": "train only on confirmed ground-truth masks",
+                    }
+                },
+            },
+        )
+        self.assertEqual(patch_response.status_code, 200)
+        event_response = self.client.post(
+            f"/api/workflows/{workflow_id}/events",
+            json={
+                "actor": "user",
+                "event_type": "dataset.loaded",
+                "stage": "setup",
+                "summary": "Loaded Yixiao case study.",
+                "payload": {"source": "test"},
+            },
+        )
+        self.assertEqual(event_response.status_code, 200)
+
+        response = self.client.get(f"/api/workflows/{workflow_id}/memory")
+        self.assertEqual(response.status_code, 200)
+        memory = response.json()
+        self.assertEqual(memory["schema_version"], "pytc-project-memory/v1")
+        self.assertEqual(
+            memory["project_facts"]["task_family_preset"]["id"],
+            "tapereader_xri_fiber",
+        )
+        self.assertEqual(
+            memory["project_facts"]["project_context"]["target_structure"],
+            "CytoTape fibres",
+        )
+        self.assertEqual(
+            memory["artifact_index"]["canonical_paths"]["image"],
+            "/projects/yixiao/data/raw",
+        )
+        self.assertEqual(
+            memory["volume_states"]["summary"]["total"],
+            1,
+        )
+        canonical_status = memory["volume_states"]["items"][0]["canonical_status"]
+        self.assertEqual(
+            memory["volume_states"]["summary"]["canonical"]["counts"][canonical_status],
+            1,
+        )
+        self.assertEqual(
+            memory["volume_states"]["items"][0]["state_schema_version"],
+            "workflow-volume-state/v2",
+        )
+        self.assertIn(
+            memory["volume_states"]["items"][0]["annotation_state"],
+            {"draft_needs_proofreading", "image_only", "proofread_ground_truth"},
+        )
+        self.assertIn(
+            canonical_status,
+            {"draft_needs_proofreading", "image_only", "proofread_ground_truth"},
+        )
+        self.assertEqual(
+            memory["volume_states"]["items"][0]["image_path"],
+            "/projects/yixiao/data/raw",
+        )
+        self.assertEqual(
+            memory["freshness"]["volume_states"]["row_count"],
+            1,
+        )
+        self.assertEqual(
+            memory["evidence_events"][-1]["event_type"],
+            "dataset.loaded",
+        )
+
+    def test_current_workflow_reset_starts_clean_session(self):
+        workflow, _ = self._current_workflow()
+        patch_response = self.client.patch(
+            f"/api/workflows/{workflow['id']}",
+            json={
+                "stage": "proofreading",
+                "image_path": "/tmp/old-image.h5",
+                "mask_path": "/tmp/old-mask.h5",
+                "metadata": {"session_onboarding": {"goals": "old goal"}},
+            },
+        )
+        self.assertEqual(patch_response.status_code, 200)
+
+        reset_response = self.client.post(
+            "/api/workflows/current/reset",
+            json={"metadata": {"created_from": "test_reset"}},
+        )
+        self.assertEqual(reset_response.status_code, 200)
+        reset_payload = reset_response.json()
+        reset_workflow = reset_payload["workflow"]
+        self.assertNotEqual(reset_workflow["id"], workflow["id"])
+        self.assertEqual(reset_workflow["stage"], "setup")
+        self.assertIsNone(reset_workflow["image_path"])
+        self.assertEqual(reset_workflow["metadata"]["created_from"], "test_reset")
+        self.assertEqual(reset_payload["events"][0]["event_type"], "workflow.created")
+
+        current_workflow, _ = self._current_workflow()
+        self.assertEqual(current_workflow["id"], reset_workflow["id"])
+
+    def test_workflow_preflight_accepts_image_only_project_start(self):
+        workflow, _ = self._current_workflow()
+        workflow_id = workflow["id"]
+
+        patch_response = self.client.patch(
+            f"/api/workflows/{workflow_id}",
+            json={
+                "dataset_path": "/tmp/new-project",
+                "image_path": "/tmp/new-project/image/sample.ome.tif",
+            },
+        )
+        self.assertEqual(patch_response.status_code, 200)
+
+        response = self.client.get(f"/api/workflows/{workflow_id}/preflight")
+        self.assertEqual(response.status_code, 200)
+        payload = response.json()
+        self.assertEqual(payload["overall_status"], "image_only")
+        self.assertIn("checkpoint or mask/label", payload["summary"])
+
+        items = {item["id"]: item for item in payload["items"]}
+        self.assertTrue(items["project_setup"]["can_run"])
+        self.assertTrue(items["visualization"]["can_run"])
+        self.assertFalse(items["inference"]["can_run"])
+        self.assertEqual(items["inference"]["missing"], ["checkpoint"])
+        self.assertFalse(items["proofreading"]["can_run"])
+        self.assertIn("mask, label, or prediction", items["proofreading"]["missing"])
+
+        recommendation_response = self.client.get(
+            f"/api/workflows/{workflow_id}/agent/recommendation"
+        )
+        self.assertEqual(recommendation_response.status_code, 200)
+        self.assertEqual(
+            recommendation_response.json()["decision"],
+            "Add a checkpoint or mask/label.",
+        )
+
+        quick_next_response = self.client.post(
+            f"/api/workflows/{workflow_id}/agent/query",
+            json={"query": "What should I do next?"},
+        )
+        self.assertEqual(quick_next_response.status_code, 200)
+        quick_next_payload = quick_next_response.json()
+        self.assertEqual(quick_next_payload["intent"], "status")
+        self.assertIn("Add a checkpoint", quick_next_payload["response"])
+        self.assertTrue(quick_next_payload["actions"])
+
+    def test_workflow_preflight_treats_config_as_agent_inferred_detail(self):
+        workflow, _ = self._current_workflow()
+        workflow_id = workflow["id"]
+
+        patch_response = self.client.patch(
+            f"/api/workflows/{workflow_id}",
+            json={
+                "image_path": "/tmp/project/raw-volume.h5",
+                "label_path": "/tmp/project/labels-volume.h5",
+                "mask_path": "/tmp/project/labels-volume.h5",
+                "config_path": "/tmp/project/configs/custom.yaml",
+            },
+        )
+        self.assertEqual(patch_response.status_code, 200)
+        self.assertEqual(
+            patch_response.json()["config_path"], "/tmp/project/configs/custom.yaml"
+        )
+
+        response = self.client.get(f"/api/workflows/{workflow_id}/preflight")
+        self.assertEqual(response.status_code, 200)
+        items = {item["id"]: item for item in response.json()["items"]}
+
+        self.assertEqual(response.json()["overall_status"], "ready_to_proofread")
+        self.assertTrue(items["proofreading"]["can_run"])
+        self.assertTrue(items["training"]["can_run"])
+        self.assertEqual(items["training"]["missing"], [])
+        self.assertIn("inferred defaults", items["training"]["action"])
+        self.assertEqual(items["inference"]["missing"], ["checkpoint"])
+
+    def test_agent_training_prefers_confirmed_project_config_path(self):
+        workflow, _ = self._current_workflow()
+        workflow_id = workflow["id"]
+        self.client.patch(
+            f"/api/workflows/{workflow_id}",
+            json={
+                "title": "custom-connectomics-project",
+                "stage": "retraining_staged",
+                "image_path": "/projects/custom/data/raw.h5",
+                "corrected_mask_path": "/projects/custom/data/corrected.tif",
+                "config_path": "/projects/custom/configs/custom-training.yaml",
+                "metadata": {
+                    "project_context": {
+                        "imaging_modality": "EM",
+                        "target_structure": "membranes",
+                        "optimization_priority": "accuracy",
+                    }
+                },
+            },
+        )
+
+        response = self.client.post(
+            f"/api/workflows/{workflow_id}/agent/query",
+            json={"query": "train the model"},
+        )
+        self.assertEqual(response.status_code, 200)
+        effects = response.json()["actions"][0]["client_effects"]
+        self.assertEqual(
+            effects["set_training_config_preset"],
+            "/projects/custom/configs/custom-training.yaml",
+        )
+
+    def test_workflow_preflight_reports_compare_ready_from_two_outputs(self):
+        workflow, _ = self._current_workflow()
+        workflow_id = workflow["id"]
+
+        patch_response = self.client.patch(
+            f"/api/workflows/{workflow_id}",
+            json={
+                "image_path": "/tmp/project/raw-volume.h5",
+                "label_path": "/tmp/project/reference.h5",
+                "checkpoint_path": "/tmp/project/checkpoint.pth.tar",
+                "inference_output_path": "/tmp/project/candidate.h5",
+            },
+        )
+        self.assertEqual(patch_response.status_code, 200)
+        for name, output_path in [
+            ("baseline", "/tmp/project/baseline.h5"),
+            ("candidate", "/tmp/project/candidate.h5"),
+        ]:
+            run_response = self.client.post(
+                f"/api/workflows/{workflow_id}/model-runs",
+                json={
+                    "run_type": "inference",
+                    "status": "completed",
+                    "name": name,
+                    "output_path": output_path,
+                },
+            )
+            self.assertEqual(run_response.status_code, 200)
+
+        response = self.client.get(f"/api/workflows/{workflow_id}/preflight")
+        self.assertEqual(response.status_code, 200)
+        payload = response.json()
+        items = {item["id"]: item for item in payload["items"]}
+        self.assertEqual(payload["overall_status"], "ready_to_compare")
+        self.assertTrue(items["inference"]["can_run"])
+        self.assertTrue(items["evaluation"]["can_run"])
+        self.assertEqual(items["evaluation"]["missing"], [])
+
     def test_agent_action_approve_and_reject_flow(self):
         workflow, _ = self._current_workflow()
         workflow_id = workflow["id"]
@@ -108,7 +458,9 @@ def test_agent_action_approve_and_reject_flow(self):
             f"{reject_proposal.json()['id']}/reject"
         )
         self.assertEqual(reject_response.status_code, 200)
-        self.assertEqual(reject_response.json()["event_type"], "agent.proposal_rejected")
+        self.assertEqual(
+            reject_response.json()["event_type"], "agent.proposal_rejected"
+        )
 
         approve_proposal = self.client.post(
             f"/api/workflows/{workflow_id}/agent-actions",
@@ -135,12 +487,118 @@ def test_agent_action_approve_and_reject_flow(self):
             "/tmp/corrected.tif",
         )
 
+        effects_proposal = self.client.post(
+            f"/api/workflows/{workflow_id}/agent-actions",
+            json={
+                "action": "run_client_effects",
+                "summary": "Approve in-app inference run.",
+                "payload": {
+                    "item_id": "run-inference",
+                    "item_label": "Run inference",
+                    "risk_level": "runs_job",
+                    "client_effects": {
+                        "navigate_to": "inference",
+                        "set_inference_output_path": "/tmp/inference-out",
+                        "runtime_action": {"kind": "start_inference"},
+                    },
+                },
+            },
+        )
+        self.assertEqual(effects_proposal.status_code, 200)
+
+        effects_approval = self.client.post(
+            f"/api/workflows/{workflow_id}/agent-actions/"
+            f"{effects_proposal.json()['id']}/approve"
+        )
+        self.assertEqual(effects_approval.status_code, 200)
+        effects_payload = effects_approval.json()
+        self.assertEqual(effects_payload["commands"], [])
+        self.assertEqual(
+            effects_payload["client_effects"]["set_inference_output_path"],
+            "/tmp/inference-out",
+        )
+        self.assertEqual(
+            effects_payload["client_effects"]["runtime_action"]["kind"],
+            "start_inference",
+        )
+
         events_response = self.client.get(f"/api/workflows/{workflow_id}/events")
         event_types = [event["event_type"] for event in events_response.json()]
         self.assertIn("agent.proposal_approved", event_types)
         self.assertIn("agent.proposal_rejected", event_types)
+        self.assertIn("agent.client_effects_approved", event_types)
         self.assertIn("retraining.staged", event_types)
 
+    def test_agent_plan_preview_control_and_bundle_export(self):
+        workflow, _ = self._current_workflow()
+        workflow_id = workflow["id"]
+
+        plan_response = self.client.post(
+            f"/api/workflows/{workflow_id}/agent-plans",
+            json={
+                "title": "Case-study acceptance loop",
+                "goal": "Drive a bounded closed-loop segmentation study.",
+            },
+        )
+        self.assertEqual(plan_response.status_code, 200)
+        plan = plan_response.json()
+        self.assertEqual(plan["title"], "Case-study acceptance loop")
+        self.assertEqual(plan["approval_status"], "pending")
+        self.assertGreaterEqual(len(plan["steps"]), 8)
+        self.assertEqual(
+            plan["graph"]["execution_model"]["mode"],
+            "bounded_human_approved_plan_preview",
+        )
+        self.assertIn(
+            plan["graph"]["execution_model"]["langgraph"]["status"],
+            {"available_not_executing", "available_compile_failed", "unavailable"},
+        )
+
+        approval_step = next(
+            step for step in plan["steps"] if step["requires_approval"]
+        )
+        step_approval = self.client.post(
+            f"/api/workflows/{workflow_id}/agent-plans/{plan['id']}/steps/"
+            f"{approval_step['id']}/approve"
+        )
+        self.assertEqual(step_approval.status_code, 200)
+        self.assertEqual(step_approval.json()["status"], "approved")
+
+        approve_response = self.client.post(
+            f"/api/workflows/{workflow_id}/agent-plans/{plan['id']}/approve"
+        )
+        self.assertEqual(approve_response.status_code, 200)
+        self.assertEqual(approve_response.json()["status"], "approved")
+        self.assertEqual(approve_response.json()["approval_status"], "approved")
+
+        interrupt_response = self.client.post(
+            f"/api/workflows/{workflow_id}/agent-plans/{plan['id']}/interrupt"
+        )
+        self.assertEqual(interrupt_response.status_code, 200)
+        self.assertEqual(interrupt_response.json()["status"], "interrupted")
+
+        resume_response = self.client.post(
+            f"/api/workflows/{workflow_id}/agent-plans/{plan['id']}/resume"
+        )
+        self.assertEqual(resume_response.status_code, 200)
+        self.assertEqual(resume_response.json()["status"], "approved")
+
+        readiness_response = self.client.get(
+            f"/api/workflows/{workflow_id}/case-study-readiness"
+        )
+        self.assertEqual(readiness_response.status_code, 200)
+        readiness_gates = {
+            gate["id"]: gate for gate in readiness_response.json()["gates"]
+        }
+        self.assertTrue(readiness_gates["agent_plan_preview"]["complete"])
+        self.assertTrue(readiness_gates["agent_audit"]["complete"])
+
+        bundle_response = self.client.post(
+            f"/api/workflows/{workflow_id}/export-bundle"
+        )
+        self.assertEqual(bundle_response.status_code, 200)
+        self.assertEqual(len(bundle_response.json()["agent_plans"]), 1)
+
     def test_hotspots_and_impact_preview(self):
         workflow, _ = self._current_workflow()
         workflow_id = workflow["id"]
@@ -218,6 +676,2163 @@ def test_hotspots_and_impact_preview(self):
         self.assertIn(impact_payload["confidence"], {"low", "medium", "high"})
         self.assertIn("proofreading_mask_saved", impact_payload["signals"])
 
+        recommendation_response = self.client.get(
+            f"/api/workflows/{workflow_id}/agent/recommendation"
+        )
+        self.assertEqual(recommendation_response.status_code, 200)
+        recommendation = recommendation_response.json()
+        self.assertEqual(recommendation["stage"], "proofreading")
+        self.assertIn("training", recommendation["decision"].lower())
+        self.assertEqual(
+            recommendation["impact_preview"]["corrected_mask_path"],
+            "/tmp/corrected-z12.tif",
+        )
+        action_ids = {action["id"] for action in recommendation["actions"]}
+        self.assertIn("propose-retraining-handoff", action_ids)
+        readiness = {item["id"]: item for item in recommendation["readiness"]}
+        self.assertTrue(readiness["corrections"]["complete"])
+        self.assertGreaterEqual(len(recommendation["commands"]), 1)
+
+    def test_agent_can_start_proofreading_from_current_image_mask_pair(self):
+        workflow, _ = self._current_workflow()
+        workflow_id = workflow["id"]
+        image_path = "/tmp/mito-image.h5"
+        mask_path = "/tmp/mito-seg.h5"
+        patch_response = self.client.patch(
+            f"/api/workflows/{workflow_id}",
+            json={
+                "title": "Mito proofread",
+                "stage": "visualization",
+                "image_path": image_path,
+                "mask_path": mask_path,
+                "metadata": {
+                    "project_context": {
+                        "imaging_modality": "EM",
+                        "target_structure": "mitochondria",
+                        "optimization_priority": "accuracy",
+                    }
+                },
+            },
+        )
+        self.assertEqual(patch_response.status_code, 200)
+
+        recommendation_response = self.client.get(
+            f"/api/workflows/{workflow_id}/agent/recommendation"
+        )
+        self.assertEqual(recommendation_response.status_code, 200)
+        recommendation = recommendation_response.json()
+        primary = next(
+            action
+            for action in recommendation["actions"]
+            if action["variant"] == "primary"
+        )
+        self.assertEqual(primary["id"], "start-proofreading")
+        effects = primary["client_effects"]
+        self.assertEqual(effects["navigate_to"], "mask-proofreading")
+        self.assertEqual(effects["runtime_action"]["kind"], "start_proofreading")
+        self.assertEqual(effects["set_proofreading_dataset_path"], image_path)
+        self.assertEqual(effects["set_proofreading_mask_path"], mask_path)
+        self.assertEqual(effects["set_proofreading_project_name"], "Mito proofread")
+
+        query_response = self.client.post(
+            f"/api/workflows/{workflow_id}/agent/query",
+            json={"query": "proofread this data"},
+        )
+        self.assertEqual(query_response.status_code, 200)
+        query_payload = query_response.json()
+        self.assertIn("proofread this data", query_payload["response"].lower())
+        self.assertEqual(query_payload["actions"][0]["id"], "start-proofreading")
+        self.assertEqual(query_payload["commands"], [])
+
+    def test_agent_proofreading_launch_prefers_corrected_or_prediction_masks(self):
+        workflow, _ = self._current_workflow()
+        workflow_id = workflow["id"]
+        patch_response = self.client.patch(
+            f"/api/workflows/{workflow_id}",
+            json={
+                "title": "Corrected proofread",
+                "stage": "visualization",
+                "image_path": "/tmp/source-image.h5",
+                "mask_path": "/tmp/original-mask.h5",
+                "inference_output_path": "/tmp/prediction-mask.h5",
+                "corrected_mask_path": "/tmp/corrected-mask.tif",
+            },
+        )
+        self.assertEqual(patch_response.status_code, 200)
+
+        recommendation_response = self.client.get(
+            f"/api/workflows/{workflow_id}/agent/recommendation"
+        )
+        self.assertEqual(recommendation_response.status_code, 200)
+        recommendation = recommendation_response.json()
+        primary = next(
+            action
+            for action in recommendation["actions"]
+            if action["id"] == "start-proofreading"
+        )
+        self.assertEqual(
+            primary["client_effects"]["set_proofreading_dataset_path"],
+            "/tmp/source-image.h5",
+        )
+        self.assertEqual(
+            primary["client_effects"]["set_proofreading_mask_path"],
+            "/tmp/corrected-mask.tif",
+        )
+
+        patch_response = self.client.patch(
+            f"/api/workflows/{workflow_id}",
+            json={"corrected_mask_path": None},
+        )
+        self.assertEqual(patch_response.status_code, 200)
+        recommendation_response = self.client.get(
+            f"/api/workflows/{workflow_id}/agent/recommendation"
+        )
+        self.assertEqual(recommendation_response.status_code, 200)
+        recommendation = recommendation_response.json()
+        primary = next(
+            action
+            for action in recommendation["actions"]
+            if action["id"] == "start-proofreading"
+        )
+        self.assertEqual(
+            primary["client_effects"]["set_proofreading_mask_path"],
+            "/tmp/prediction-mask.h5",
+        )
+
+    def test_agent_visualize_request_populates_viewer_paths_not_status(self):
+        workflow, _ = self._current_workflow()
+        workflow_id = workflow["id"]
+        self.client.patch(
+            f"/api/workflows/{workflow_id}",
+            json={
+                "stage": "setup",
+                "image_path": "/projects/sample/data/image/train",
+                "label_path": "/projects/sample/data/labels/train",
+            },
+        )
+
+        response = self.client.post(
+            f"/api/workflows/{workflow_id}/agent/query",
+            json={
+                "query": "can you visualize some combination of volumes in my data? "
+                "i have images and segmentations where the names should already align"
+            },
+        )
+        self.assertEqual(response.status_code, 200)
+        payload = response.json()
+        self.assertEqual(payload["intent"], "view_data")
+        self.assertIn("view train", payload["response"].lower())
+        self.assertEqual(payload["actions"][0]["id"], "open-visualization")
+        self.assertEqual(payload["commands"], [])
+        effects = payload["actions"][0]["client_effects"]
+        self.assertEqual(effects["navigate_to"], "visualization")
+        self.assertEqual(effects["runtime_action"]["kind"], "load_visualization")
+        self.assertEqual(
+            effects["set_visualization_image_path"],
+            "/projects/sample/data/image/train",
+        )
+        self.assertEqual(
+            effects["set_visualization_label_path"],
+            "/projects/sample/data/labels/train",
+        )
+
+        casual_response = self.client.post(
+            f"/api/workflows/{workflow_id}/agent/query",
+            json={"query": "can i look at my labels real quick?"},
+        )
+        self.assertEqual(casual_response.status_code, 200)
+        casual_payload = casual_response.json()
+        self.assertEqual(casual_payload["intent"], "view_data")
+        self.assertNotIn("did not understand", casual_payload["response"].lower())
+        self.assertEqual(casual_payload["actions"][0]["id"], "open-visualization")
+
+        abbreviated_response = self.client.post(
+            f"/api/workflows/{workflow_id}/agent/query",
+            json={"query": "can we vis some data"},
+        )
+        self.assertEqual(abbreviated_response.status_code, 200)
+        abbreviated_payload = abbreviated_response.json()
+        self.assertEqual(abbreviated_payload["intent"], "view_data")
+        self.assertEqual(abbreviated_payload["actions"][0]["id"], "open-visualization")
+
+    def test_agent_visualize_request_discovers_directory_pairs_and_asks_for_more(self):
+        workflow, _ = self._current_workflow()
+        workflow_id = workflow["id"]
+        project_root = pathlib.Path(self.temp_dir.name) / "batch-project"
+        image_dir = project_root / "Image" / "train"
+        label_dir = project_root / "Label" / "train"
+        image_dir.mkdir(parents=True)
+        label_dir.mkdir(parents=True)
+        (image_dir / "img_000_604_576.h5").write_bytes(b"")
+        (image_dir / "img_508_604_200.h5").write_bytes(b"")
+        (label_dir / "seg_508_604_200.h5").write_bytes(b"")
+        (label_dir / "seg_000_604_576.h5").write_bytes(b"")
+        self.client.patch(
+            f"/api/workflows/{workflow_id}",
+            json={
+                "stage": "setup",
+                "image_path": str(image_dir),
+                "label_path": str(label_dir),
+            },
+        )
+
+        response = self.client.post(
+            f"/api/workflows/{workflow_id}/agent/query",
+            json={"query": "can we visualize my existing segs?"},
+        )
+
+        self.assertEqual(response.status_code, 200)
+        payload = response.json()
+        self.assertEqual(payload["intent"], "view_data")
+        self.assertIn("I found 2 clear image/seg pairs", payload["response"])
+        self.assertIn("Tell me if there are more folders", payload["response"])
+        effects = payload["actions"][0]["client_effects"]
+        self.assertEqual(
+            effects["set_visualization_image_path"],
+            str(image_dir / "img_000_604_576.h5"),
+        )
+        self.assertEqual(
+            effects["set_visualization_label_path"],
+            str(label_dir / "seg_000_604_576.h5"),
+        )
+        self.assertEqual(payload["commands"], [])
+
+    def test_agent_visualize_request_uses_explicit_selected_pair(self):
+        workflow, _ = self._current_workflow()
+        workflow_id = workflow["id"]
+        project_root = pathlib.Path(self.temp_dir.name) / "explicit-pair-project"
+        image_dir = project_root / "images"
+        label_dir = project_root / "labels"
+        image_dir.mkdir(parents=True)
+        label_dir.mkdir(parents=True)
+        selected_image = image_dir / "img_b.h5"
+        selected_label = label_dir / "label_b.h5"
+        other_image = image_dir / "img_a.h5"
+        other_label = label_dir / "label_a.h5"
+        other_image.write_bytes(b"")
+        other_label.write_bytes(b"")
+        selected_image.write_bytes(b"")
+        selected_label.write_bytes(b"")
+
+        self.client.patch(
+            f"/api/workflows/{workflow_id}",
+            json={
+                "stage": "setup",
+                "dataset_path": str(project_root),
+                "image_path": str(selected_image),
+                "label_path": str(selected_label),
+            },
+        )
+
+        response = self.client.post(
+            f"/api/workflows/{workflow_id}/agent/query",
+            json={"query": "can we visualize the selected pair?"},
+        )
+        self.assertEqual(response.status_code, 200)
+        payload = response.json()
+        self.assertEqual(payload["intent"], "view_data")
+        effects = payload["actions"][0]["client_effects"]
+        self.assertEqual(
+            effects["set_visualization_image_path"],
+            str(selected_image),
+        )
+        self.assertEqual(
+            effects["set_visualization_label_path"],
+            str(selected_label),
+        )
+
+    def test_agent_inspects_project_tree_for_alternate_volume_set(self):
+        workflow, _ = self._current_workflow()
+        workflow_id = workflow["id"]
+        project_root = pathlib.Path(self.temp_dir.name) / "lucchi-project"
+        image_dir = project_root / "data" / "image"
+        source_dir = project_root / "data" / "source" / "Lucchi++"
+        label_dir = project_root / "data" / "seg"
+        image_dir.mkdir(parents=True)
+        source_dir.mkdir(parents=True)
+        label_dir.mkdir(parents=True)
+        for stem in ["test", "train"]:
+            (image_dir / f"{stem}_im.h5").write_bytes(b"")
+            (source_dir / f"{stem}_im.h5").write_bytes(b"")
+            (label_dir / f"{stem}_mito.h5").write_bytes(b"")
+
+        self.client.patch(
+            f"/api/workflows/{workflow_id}",
+            json={
+                "stage": "visualization",
+                "dataset_path": str(project_root),
+                "image_path": str(image_dir / "test_im.h5"),
+                "label_path": str(label_dir / "test_mito.h5"),
+            },
+        )
+
+        response = self.client.post(
+            f"/api/workflows/{workflow_id}/agent/query",
+            json={
+                "query": (
+                    "can't you look for another aptly named pair of image and seg? "
+                    "there IS another pair in the project"
+                )
+            },
+        )
+
+        self.assertEqual(response.status_code, 200)
+        payload = response.json()
+        self.assertEqual(payload["intent"], "view_data")
+        self.assertIn("I inspected the project tree", payload["response"])
+        self.assertIn("another image/seg set", payload["response"])
+        self.assertNotIn("Before I choose", payload["response"])
+        effects = payload["actions"][0]["client_effects"]
+        self.assertEqual(effects["navigate_to"], "visualization")
+        self.assertEqual(effects["runtime_action"]["kind"], "load_visualization")
+        self.assertEqual(
+            effects["set_visualization_image_path"],
+            str(source_dir / "test_im.h5"),
+        )
+        self.assertEqual(
+            effects["set_visualization_label_path"],
+            str(label_dir / "test_mito.h5"),
+        )
+
+        current_response = self.client.get("/api/workflows/current")
+        self.assertEqual(current_response.status_code, 200)
+        observation = current_response.json()["workflow"]["metadata"][
+            "project_observation"
+        ]
+        self.assertGreaterEqual(len(observation["volume_sets"]), 2)
+
+    def test_agent_answers_project_file_overview_from_observation(self):
+        workflow, _ = self._current_workflow()
+        workflow_id = workflow["id"]
+        project_root = pathlib.Path(self.temp_dir.name) / "overview-project"
+        image_dir = project_root / "data" / "image"
+        label_dir = project_root / "data" / "seg"
+        config_dir = project_root / "configs"
+        output_dir = project_root / "outputs"
+        image_dir.mkdir(parents=True)
+        label_dir.mkdir(parents=True)
+        config_dir.mkdir(parents=True)
+        output_dir.mkdir(parents=True)
+        (image_dir / "test_im.h5").write_bytes(b"")
+        (label_dir / "test_mito.h5").write_bytes(b"")
+        (config_dir / "mito.yaml").write_text("MODEL: mito\n")
+
+        self.client.patch(
+            f"/api/workflows/{workflow_id}",
+            json={
+                "stage": "visualization",
+                "dataset_path": str(project_root),
+                "image_path": str(image_dir / "test_im.h5"),
+                "label_path": str(label_dir / "test_mito.h5"),
+            },
+        )
+
+        response = self.client.post(
+            f"/api/workflows/{workflow_id}/agent/query",
+            json={"query": "what exactly are the files in my lovely directory here?"},
+        )
+
+        self.assertEqual(response.status_code, 200)
+        payload = response.json()
+        self.assertEqual(payload["intent"], "project_files")
+        self.assertIn("I checked", payload["response"])
+        self.assertIn("At the top level", payload["response"])
+        self.assertIn("data/", payload["response"])
+        self.assertNotIn("Current read:", payload["response"])
+        self.assertNotIn("Do this:", payload["response"])
+        self.assertEqual(payload["actions"], [])
+        self.assertTrue(
+            any(item["label"] == "Checked project files" for item in payload["trace"])
+        )
+
+    def test_workflow_agent_conversation_hydrates_latest_workflow_chat(self):
+        workflow, _ = self._current_workflow()
+        workflow_id = workflow["id"]
+
+        query_response = self.client.post(
+            f"/api/workflows/{workflow_id}/agent/query",
+            json={"query": "what should I do next?"},
+        )
+        self.assertEqual(query_response.status_code, 200)
+        conversation_id = query_response.json()["conversation_id"]
+
+        response = self.client.get(f"/api/workflows/{workflow_id}/agent/conversation")
+
+        self.assertEqual(response.status_code, 200)
+        payload = response.json()
+        self.assertEqual(payload["conversation_id"], conversation_id)
+        self.assertEqual(len(payload["messages"]), 2)
+        self.assertEqual(payload["messages"][0]["role"], "user")
+        self.assertEqual(payload["messages"][1]["role"], "assistant")
+        self.assertEqual(
+            payload["messages"][1]["source"],
+            "workflow_orchestrator",
+        )
+        self.assertIn("trace", payload["messages"][1])
+        self.assertTrue(
+            all(
+                "category" in item and "data" in item
+                for item in payload["messages"][1]["trace"]
+            )
+        )
+
+    def test_project_progress_counts_ground_truth_unproofread_and_missing_volumes(self):
+        workflow, _ = self._current_workflow()
+        workflow_id = workflow["id"]
+        project_root = pathlib.Path(self.temp_dir.name) / "progress-project"
+        image_dir = project_root / "data" / "image"
+        label_dir = project_root / "data" / "seg"
+        image_dir.mkdir(parents=True)
+        label_dir.mkdir(parents=True)
+        for stem in ["vol_a", "vol_b", "vol_c"]:
+            (image_dir / f"{stem}_im.h5").write_bytes(b"")
+        (label_dir / "vol_a_ground_truth.h5").write_bytes(b"")
+        (label_dir / "vol_b_seg.h5").write_bytes(b"")
+
+        self.client.patch(
+            f"/api/workflows/{workflow_id}",
+            json={
+                "title": "Progress smoke",
+                "stage": "visualization",
+                "dataset_path": str(project_root),
+                "image_path": str(image_dir / "vol_a_im.h5"),
+                "label_path": str(label_dir / "vol_a_ground_truth.h5"),
+            },
+        )
+
+        response = self.client.get(f"/api/workflows/{workflow_id}/project-progress")
+
+        self.assertEqual(response.status_code, 200)
+        payload = response.json()
+        self.assertEqual(payload["summary"]["total"], 3)
+        self.assertEqual(payload["summary"]["ground_truth"], 1)
+        self.assertEqual(payload["summary"]["needs_proofreading"], 1)
+        self.assertEqual(payload["summary"]["missing_segmentation"], 1)
+        self.assertEqual(payload["summary"]["remaining"], 2)
+        self.assertIn("annotation_state", payload["composite_state_definitions"])
+        rows = {row["name"]: row for row in payload["volumes"]}
+        self.assertEqual(rows["vol_a_im.h5"]["status"], "ground_truth")
+        self.assertEqual(
+            rows["vol_a_im.h5"]["annotation_state"],
+            "proofread_ground_truth",
+        )
+        self.assertEqual(rows["vol_a_im.h5"]["role_state"], "training_source")
+        self.assertEqual(rows["vol_b_im.h5"]["status"], "needs_proofreading")
+        self.assertEqual(
+            rows["vol_b_im.h5"]["annotation_state"],
+            "draft_needs_proofreading",
+        )
+        self.assertEqual(rows["vol_c_im.h5"]["status"], "missing_segmentation")
+        self.assertEqual(rows["vol_c_im.h5"]["annotation_state"], "image_only")
+        self.assertIsInstance(rows["vol_a_im.h5"].get("volume_state_id"), int)
+        self.assertTrue(rows["vol_a_im.h5"]["eligible_for_training"])
+        self.assertTrue(rows["vol_c_im.h5"]["eligible_for_inference"])
+
+        update_response = self.client.post(
+            f"/api/workflows/{workflow_id}/project-progress/volume-status",
+            json={
+                "volume_id": rows["vol_b_im.h5"]["id"],
+                "status": "ground_truth",
+                "note": "Reviewed by expert.",
+            },
+        )
+        self.assertEqual(update_response.status_code, 200)
+        updated = update_response.json()
+        self.assertEqual(updated["summary"]["ground_truth"], 2)
+        updated_rows = {row["name"]: row for row in updated["volumes"]}
+        self.assertEqual(
+            updated_rows["vol_b_im.h5"]["status_source"], "manual_override"
+        )
+        self.assertEqual(
+            updated_rows["vol_b_im.h5"]["annotation_state"],
+            "proofread_ground_truth",
+        )
+        self.assertEqual(updated_rows["vol_b_im.h5"]["role_state"], "training_source")
+        self.assertEqual(updated_rows["vol_b_im.h5"]["note"], "Reviewed by expert.")
+
+        states_response = self.client.get(f"/api/workflows/{workflow_id}/volumes")
+        self.assertEqual(states_response.status_code, 200)
+        states = states_response.json()
+        self.assertEqual(states["summary"]["total"], 3)
+        self.assertEqual(states["summary"]["ground_truth"], 2)
+        self.assertEqual(states["summary"]["training_ready"], 2)
+        state_by_volume_id = {state["volume_id"]: state for state in states["volumes"]}
+        self.assertEqual(
+            state_by_volume_id[rows["vol_b_im.h5"]["id"]]["status_source"],
+            "manual_override",
+        )
+        self.assertEqual(
+            state_by_volume_id[rows["vol_b_im.h5"]["id"]]["annotation_state"],
+            "proofread_ground_truth",
+        )
+        self.assertEqual(
+            state_by_volume_id[rows["vol_b_im.h5"]["id"]]["note"],
+            "Reviewed by expert.",
+        )
+
+        events_response = self.client.get(f"/api/workflows/{workflow_id}/events")
+        self.assertEqual(events_response.status_code, 200)
+        self.assertIn(
+            "project_volume.status_updated",
+            [event["event_type"] for event in events_response.json()],
+        )
+
+    def test_workflow_volume_state_api_updates_training_and_inference_flags(self):
+        workflow, _ = self._current_workflow()
+        workflow_id = workflow["id"]
+        image_path = pathlib.Path(self.temp_dir.name) / "volume_im.h5"
+        label_path = pathlib.Path(self.temp_dir.name) / "volume_seg.h5"
+        image_path.write_bytes(b"image")
+        label_path.write_bytes(b"label")
+
+        response = self.client.patch(
+            f"/api/workflows/{workflow_id}/volumes",
+            json={
+                "volume_id": "manual/volume_im.h5",
+                "status": "ground_truth",
+                "image_path": str(image_path),
+                "label_path": str(label_path),
+                "note": "Confirmed in test.",
+            },
+        )
+
+        self.assertEqual(response.status_code, 200)
+        payload = response.json()
+        self.assertEqual(payload["status"], "ground_truth")
+        self.assertEqual(payload["status_source"], "manual")
+        self.assertEqual(payload["legacy_status"], "ground_truth")
+        self.assertEqual(payload["canonical_status"], "proofread_ground_truth")
+        self.assertEqual(payload["annotation_state"], "proofread_ground_truth")
+        self.assertEqual(payload["role_state"], "training_source")
+        self.assertEqual(payload["execution_state"], "ready")
+        self.assertEqual(payload["region_scope"]["scope_type"], "full_volume")
+        self.assertEqual(payload["state_schema_version"], "workflow-volume-state/v2")
+        self.assertTrue(payload["eligible_for_training"])
+        self.assertFalse(payload["eligible_for_inference"])
+        self.assertEqual(payload["note"], "Confirmed in test.")
+
+        states_response = self.client.get(
+            f"/api/workflows/{workflow_id}/volumes",
+            params={"refresh": "false"},
+        )
+        self.assertEqual(states_response.status_code, 200)
+        states = states_response.json()
+        self.assertEqual(states["summary"]["training_ready"], 1)
+        self.assertEqual(states["volumes"][0]["volume_id"], "manual/volume_im.h5")
+
+        target_response = self.client.patch(
+            f"/api/workflows/{workflow_id}/volumes",
+            json={
+                "volume_id": "manual/target_im.h5",
+                "annotation_state": "image_only",
+                "role_state": "inference_target",
+                "execution_state": "ready",
+                "image_path": str(image_path),
+            },
+        )
+        self.assertEqual(target_response.status_code, 200)
+        target_payload = target_response.json()
+        self.assertEqual(target_payload["status"], "missing_segmentation")
+        self.assertTrue(target_payload["eligible_for_inference"])
+        self.assertFalse(target_payload["eligible_for_training"])
+
+        contradictory_response = self.client.patch(
+            f"/api/workflows/{workflow_id}/volumes",
+            json={
+                "volume_id": "manual/bad_state.h5",
+                "status": "ground_truth",
+                "annotation_state": "image_only",
+            },
+        )
+        self.assertEqual(contradictory_response.status_code, 400)
+
+    def test_workflow_overview_summarizes_phase_progress_and_next_actions(self):
+        workflow, _ = self._current_workflow()
+        workflow_id = workflow["id"]
+        project_root = pathlib.Path(self.temp_dir.name) / "overview-project"
+        image_dir = project_root / "data" / "image"
+        label_dir = project_root / "data" / "seg"
+        image_dir.mkdir(parents=True)
+        label_dir.mkdir(parents=True)
+        for stem in ["vol_a", "vol_b", "vol_c"]:
+            (image_dir / f"{stem}_im.h5").write_bytes(b"")
+        (label_dir / "vol_a_ground_truth.h5").write_bytes(b"")
+        (label_dir / "vol_b_seg.h5").write_bytes(b"")
+
+        self.client.patch(
+            f"/api/workflows/{workflow_id}",
+            json={
+                "title": "Overview smoke",
+                "stage": "visualization",
+                "dataset_path": str(project_root),
+                "image_path": str(image_dir / "vol_a_im.h5"),
+                "label_path": str(label_dir / "vol_a_ground_truth.h5"),
+            },
+        )
+
+        response = self.client.get(f"/api/workflows/{workflow_id}/overview")
+
+        self.assertEqual(response.status_code, 200)
+        payload = response.json()
+        self.assertEqual(payload["project_name"], "Overview smoke")
+        self.assertEqual(payload["phase"], "proofread")
+        self.assertEqual(payload["phase_label"], "Proofread")
+        self.assertEqual(payload["volume_summary"]["ground_truth"], 1)
+        self.assertEqual(payload["volume_summary"]["needs_proofreading"], 1)
+        self.assertEqual(payload["volume_summary"]["missing_segmentation"], 1)
+        self.assertEqual(payload["project_progress"]["summary"]["total"], 3)
+        stage_by_id = {stage["id"]: stage for stage in payload["stages"]}
+        self.assertTrue(stage_by_id["setup"]["complete"])
+        self.assertTrue(stage_by_id["inspect"]["complete"])
+        self.assertTrue(stage_by_id["proofread"]["current"])
+        action_ids = [action["id"] for action in payload["recommended_next_actions"]]
+        self.assertIn("proofread-draft-masks", action_ids)
+        self.assertIn("train-from-ground-truth", action_ids)
+        blocker_ids = [blocker["id"] for blocker in payload["blockers"]]
+        self.assertIn("draft_masks_need_review", blocker_ids)
+
+    def test_agent_opens_project_progress_tracker_with_counts(self):
+        workflow, _ = self._current_workflow()
+        workflow_id = workflow["id"]
+        project_root = pathlib.Path(self.temp_dir.name) / "agent-progress-project"
+        image_dir = project_root / "data" / "image"
+        label_dir = project_root / "data" / "seg"
+        image_dir.mkdir(parents=True)
+        label_dir.mkdir(parents=True)
+        (image_dir / "vol_a_im.h5").write_bytes(b"")
+        (image_dir / "vol_b_im.h5").write_bytes(b"")
+        (label_dir / "vol_a_gt.h5").write_bytes(b"")
+
+        self.client.patch(
+            f"/api/workflows/{workflow_id}",
+            json={
+                "stage": "visualization",
+                "dataset_path": str(project_root),
+                "image_path": str(image_dir / "vol_a_im.h5"),
+                "label_path": str(label_dir / "vol_a_gt.h5"),
+            },
+        )
+
+        response = self.client.post(
+            f"/api/workflows/{workflow_id}/agent/query",
+            json={"query": "open the project progress tracker"},
+        )
+
+        self.assertEqual(response.status_code, 200)
+        payload = response.json()
+        self.assertEqual(payload["intent"], "project_progress")
+        self.assertEqual(payload["orchestrator_agent"]["type"], "project_manager")
+        self.assertTrue(
+            any(agent["type"] == "training_agent" for agent in payload["subagents"])
+        )
+        self.assertIn("tracked image volume", payload["response"])
+        self.assertEqual(payload["trace_schema_version"], "agent_trace/v1")
+        self.assertTrue(
+            any(item["category"] == "proposed" for item in payload["trace"])
+        )
+        self.assertTrue(
+            any(item["agent_type"] == "project_manager" for item in payload["trace"])
+        )
+        self.assertEqual(payload["actions"][0]["id"], "open-project-progress")
+        self.assertEqual(payload["actions"][0]["agent_type"], "project_manager")
+        self.assertEqual(
+            payload["actions"][0]["specialist_agent"]["type"],
+            "project_manager",
+        )
+        self.assertEqual(payload["actions"][0]["card_type"], "workflow.action_card/v2")
+        self.assertEqual(payload["actions"][0]["risk_tier"], "R0_view")
+        self.assertEqual(
+            payload["actions"][0]["action_card"]["executor"],
+            "bounded_app_routine",
+        )
+        self.assertEqual(
+            payload["actions"][0]["client_effects"]["navigate_to"],
+            "project-progress",
+        )
+
+    def test_agent_scale_update_persists_project_context_and_offers_reload(self):
+        workflow, _ = self._current_workflow()
+        workflow_id = workflow["id"]
+        self.client.patch(
+            f"/api/workflows/{workflow_id}",
+            json={
+                "stage": "visualization",
+                "image_path": "/projects/sample/data/image/train",
+                "label_path": "/projects/sample/data/labels/train",
+            },
+        )
+
+        response = self.client.post(
+            f"/api/workflows/{workflow_id}/agent/query",
+            json={"query": "the scales are off; can we reload with 1-1-1?"},
+        )
+
+        self.assertEqual(response.status_code, 200)
+        payload = response.json()
+        self.assertEqual(payload["intent"], "set_visualization_scales")
+        self.assertIn("1,1,1 nm", payload["response"])
+        self.assertEqual(payload["actions"][0]["id"], "reload-visualization-scales")
+        effects = payload["actions"][0]["client_effects"]
+        self.assertEqual(effects["navigate_to"], "visualization")
+        self.assertEqual(effects["set_visualization_scales"], [1.0, 1.0, 1.0])
+        self.assertEqual(effects["runtime_action"]["kind"], "load_visualization")
+        self.assertEqual(
+            effects["set_visualization_image_path"],
+            "/projects/sample/data/image/train",
+        )
+        self.assertEqual(
+            effects["set_visualization_label_path"],
+            "/projects/sample/data/labels/train",
+        )
+
+        current_workflow, _ = self._current_workflow()
+        self.assertEqual(
+            current_workflow["metadata"]["visualization_scales"],
+            [1.0, 1.0, 1.0],
+        )
+        self.assertEqual(
+            current_workflow["metadata"]["project_context"]["voxel_size_nm"],
+            [1.0, 1.0, 1.0],
+        )
+
+        events_response = self.client.get(f"/api/workflows/{workflow_id}/events")
+        event_types = [event["event_type"] for event in events_response.json()]
+        self.assertIn("visualization.scales_updated", event_types)
+
+    def test_agent_scale_update_requires_three_axis_values(self):
+        workflow, _ = self._current_workflow()
+        workflow_id = workflow["id"]
+
+        response = self.client.post(
+            f"/api/workflows/{workflow_id}/agent/query",
+            json={"query": "reload with 1-1"},
+        )
+
+        self.assertEqual(response.status_code, 200)
+        payload = response.json()
+        self.assertEqual(payload["intent"], "set_visualization_scales")
+        self.assertIn("I need three values", payload["response"])
+        self.assertEqual(payload["actions"][0]["id"], "open-visualization")
+
+    def test_agent_proofread_request_from_setup_offers_runnable_action(self):
+        workflow, _ = self._current_workflow()
+        workflow_id = workflow["id"]
+        self.client.patch(
+            f"/api/workflows/{workflow_id}",
+            json={
+                "stage": "setup",
+                "image_path": "/projects/sample/data/image/train",
+                "label_path": "/projects/sample/data/labels/train",
+                "metadata": {
+                    "project_context": {
+                        "imaging_modality": "EM",
+                        "target_structure": "mitochondria",
+                        "optimization_priority": "accuracy",
+                    }
+                },
+            },
+        )
+
+        response = self.client.post(
+            f"/api/workflows/{workflow_id}/agent/query",
+            json={
+                "query": "can you proofread my data? I have images and segmentations"
+            },
+        )
+        self.assertEqual(response.status_code, 200)
+        payload = response.json()
+        self.assertEqual(payload["intent"], "start_proofreading")
+        self.assertEqual(payload["actions"][0]["id"], "start-proofreading")
+        self.assertEqual(payload["commands"], [])
+        self.assertEqual(
+            payload["actions"][0]["client_effects"]["runtime_action"]["kind"],
+            "start_proofreading",
+        )
+
+    def test_agent_proofread_request_names_blocker_when_inputs_missing(self):
+        workflow, _ = self._current_workflow()
+        workflow_id = workflow["id"]
+        self.client.patch(
+            f"/api/workflows/{workflow_id}",
+            json={
+                "stage": "visualization",
+                "image_path": "/projects/sample/data/image/train",
+                "metadata": {
+                    "project_context": {
+                        "imaging_modality": "EM",
+                        "target_structure": "mitochondria",
+                        "optimization_priority": "accuracy",
+                    }
+                },
+            },
+        )
+
+        response = self.client.post(
+            f"/api/workflows/{workflow_id}/agent/query",
+            json={"query": "proofread this data"},
+        )
+        self.assertEqual(response.status_code, 200)
+        payload = response.json()
+        self.assertEqual(payload["intent"], "start_proofreading")
+        self.assertIn("I can proofread this, but I need", payload["response"])
+        self.assertIn("mask, label, or prediction", payload["response"])
+        self.assertEqual(payload["commands"], [])
+        self.assertEqual(payload["actions"][0]["id"], "open-files")
+
+    def test_agent_routes_segmentation_and_capability_requests_to_app_actions(self):
+        workflow, _ = self._current_workflow()
+        workflow_id = workflow["id"]
+        self.client.patch(
+            f"/api/workflows/{workflow_id}",
+            json={
+                "stage": "inference",
+                "image_path": "/tmp/image.h5",
+                "mask_path": "/tmp/mask.h5",
+                "checkpoint_path": "/tmp/checkpoint.pth.tar",
+                "metadata": {
+                    "project_context": {
+                        "imaging_modality": "EM",
+                        "target_structure": "mitochondria",
+                        "optimization_priority": "speed",
+                    }
+                },
+            },
+        )
+
+        segment_response = self.client.post(
+            f"/api/workflows/{workflow_id}/agent/query",
+            json={"query": "I want to get my volume segmented"},
+        )
+        self.assertEqual(segment_response.status_code, 200)
+        segment_payload = segment_response.json()
+        self.assertIn("run the model", segment_payload["response"].lower())
+        conversation_id = segment_payload["conversationId"]
+        self.assertIsInstance(conversation_id, int)
+        self.assertEqual(segment_payload["actions"][0]["label"], "Run model")
+        self.assertEqual(segment_payload["commands"], [])
+        conversation_response = self.client.get(
+            f"/chat/conversations/{conversation_id}"
+        )
+        self.assertEqual(conversation_response.status_code, 200)
+        messages = conversation_response.json()["messages"]
+        self.assertEqual(
+            [message["role"] for message in messages], ["user", "assistant"]
+        )
+        self.assertEqual(messages[0]["content"], "I want to get my volume segmented")
+        self.assertIn("run the model", messages[1]["content"].lower())
+        self.assertEqual(messages[1]["source"], "workflow_orchestrator")
+        self.assertEqual(messages[1]["actions"][0]["label"], "Run model")
+        self.assertEqual(messages[1]["commands"], [])
+
+        capabilities_response = self.client.post(
+            f"/api/workflows/{workflow_id}/agent/query",
+            json={
+                "query": "what can the agent do then? can it run things?",
+                "conversation_id": conversation_id,
+            },
+        )
+        self.assertEqual(capabilities_response.status_code, 200)
+        capabilities_payload = capabilities_response.json()
+        self.assertEqual(capabilities_payload["conversationId"], conversation_id)
+        self.assertEqual(capabilities_payload["intent"], "capabilities")
+        self.assertIn("run approved app steps", capabilities_payload["response"])
+        self.assertEqual(capabilities_payload["actions"], [])
+        updated_conversation_response = self.client.get(
+            f"/chat/conversations/{conversation_id}"
+        )
+        self.assertEqual(updated_conversation_response.status_code, 200)
+        self.assertEqual(len(updated_conversation_response.json()["messages"]), 4)
+
+    def test_agent_exposes_workspace_configuration_and_runtime_control_actions(self):
+        workflow, _ = self._current_workflow()
+        workflow_id = workflow["id"]
+        self.client.patch(
+            f"/api/workflows/{workflow_id}",
+            json={
+                "title": "Lucchi case study",
+                "dataset_path": "/projects/lucchi",
+                "image_path": "/projects/lucchi/data/image/test_im.h5",
+                "label_path": "/projects/lucchi/data/seg/test_mito.h5",
+                "mask_path": "/projects/lucchi/data/seg/test_mito.h5",
+                "checkpoint_path": "/projects/lucchi/checkpoints/checkpoint.pth.tar",
+                "metadata": {
+                    "project_context": {
+                        "imaging_modality": "EM",
+                        "target_structure": "mitochondria",
+                        "optimization_priority": "accuracy",
+                    }
+                },
+            },
+        )
+
+        mount_response = self.client.post(
+            f"/api/workflows/{workflow_id}/agent/query",
+            json={"query": "remount the lucchi project"},
+        )
+        self.assertEqual(mount_response.status_code, 200)
+        mount_payload = mount_response.json()
+        self.assertEqual(mount_payload["intent"], "mount_project")
+        self.assertEqual(mount_payload["actions"][0]["id"], "mount-project")
+        self.assertEqual(
+            mount_payload["actions"][0]["client_effects"]["mount_project"][
+                "directory_path"
+            ],
+            "/projects/lucchi",
+        )
+
+        configure_response = self.client.post(
+            f"/api/workflows/{workflow_id}/agent/query",
+            json={"query": "configure inference settings before running"},
+        )
+        self.assertEqual(configure_response.status_code, 200)
+        configure_payload = configure_response.json()
+        self.assertEqual(configure_payload["intent"], "configure_inference")
+        configure_effects = configure_payload["actions"][0]["client_effects"]
+        self.assertEqual(configure_effects["navigate_to"], "inference")
+        self.assertNotIn("runtime_action", configure_effects)
+        self.assertEqual(
+            configure_effects["set_inference_image_path"],
+            "/projects/lucchi/data/image/test_im.h5",
+        )
+        self.assertEqual(
+            configure_effects["set_inference_checkpoint_path"],
+            "/projects/lucchi/checkpoints/checkpoint.pth.tar",
+        )
+
+        reset_response = self.client.post(
+            f"/api/workflows/{workflow_id}/agent/query",
+            json={"query": "clear cached workspace state and remount"},
+        )
+        self.assertEqual(reset_response.status_code, 200)
+        reset_payload = reset_response.json()
+        self.assertEqual(reset_payload["intent"], "reset_workspace")
+        reset_effects = reset_payload["actions"][0]["client_effects"]
+        self.assertTrue(reset_effects["reset_workspace"])
+        self.assertEqual(
+            reset_effects["mount_project"]["directory_path"],
+            "/projects/lucchi",
+        )
+
+        stop_response = self.client.post(
+            f"/api/workflows/{workflow_id}/agent/query",
+            json={"query": "stop the training job"},
+        )
+        self.assertEqual(stop_response.status_code, 200)
+        stop_payload = stop_response.json()
+        self.assertEqual(stop_payload["intent"], "stop_runtime")
+        action_ids = [action["id"] for action in stop_payload["actions"]]
+        self.assertIn("stop-inference", action_ids)
+        self.assertEqual(len(action_ids), 1)
+
+    def test_agent_understands_casual_segmentation_language(self):
+        workflow, _ = self._current_workflow()
+        workflow_id = workflow["id"]
+        self.client.patch(
+            f"/api/workflows/{workflow_id}",
+            json={
+                "stage": "visualization",
+                "image_path": "/projects/lucchi/data/image/test_im.h5",
+                "label_path": "/projects/lucchi/data/seg/test_mito.h5",
+                "mask_path": "/projects/lucchi/data/seg/test_mito.h5",
+                "metadata": {
+                    "project_context": {
+                        "imaging_modality": "EM",
+                        "target_structure": "mitochondria",
+                        "optimization_priority": "accuracy",
+                    }
+                },
+            },
+        )
+
+        response = self.client.post(
+            f"/api/workflows/{workflow_id}/agent/query",
+            json={"query": "i wanna segment some dattaaaaaaaaaaa"},
+        )
+        self.assertEqual(response.status_code, 200)
+        payload = response.json()
+        self.assertEqual(payload["intent"], "start_segmentation")
+        self.assertNotIn("did not understand", payload["response"].lower())
+        self.assertIn("checkpoint", payload["response"].lower())
+        action_ids = [action["id"] for action in payload["actions"]]
+        self.assertIn("start-proofreading", action_ids)
+        self.assertEqual(len(action_ids), 1)
+
+    def test_agent_returns_one_app_suggestion_for_segmentation_blockers(self):
+        workflow, _ = self._current_workflow()
+        workflow_id = workflow["id"]
+        self.client.patch(
+            f"/api/workflows/{workflow_id}",
+            json={
+                "stage": "visualization",
+                "image_path": "/projects/lucchi/data/image/test_im.h5",
+                "label_path": "/projects/lucchi/data/seg/test_mito.h5",
+                "mask_path": "/projects/lucchi/data/seg/test_mito.h5",
+                "metadata": {
+                    "project_context": {
+                        "imaging_modality": "EM",
+                        "target_structure": "mitochondria",
+                        "optimization_priority": "accuracy",
+                    }
+                },
+            },
+        )
+
+        response = self.client.post(
+            f"/api/workflows/{workflow_id}/agent/query",
+            json={"query": "can we segment my data with a model?"},
+        )
+        self.assertEqual(response.status_code, 200)
+        payload = response.json()
+        self.assertEqual(payload["intent"], "start_segmentation")
+        self.assertIn("because", payload["response"].lower())
+        self.assertEqual(len(payload["actions"]), 1)
+        self.assertEqual(payload["commands"], [])
+
+    def test_agent_context_followup_updates_without_action_cards(self):
+        workflow, _ = self._current_workflow()
+        workflow_id = workflow["id"]
+        self.client.patch(
+            f"/api/workflows/{workflow_id}",
+            json={
+                "stage": "visualization",
+                "image_path": "/projects/lucchi/data/image/test_im.h5",
+            },
+        )
+
+        response = self.client.post(
+            f"/api/workflows/{workflow_id}/agent/query",
+            json={"query": "what if this is EM mitochondria and we care about speed?"},
+        )
+        self.assertEqual(response.status_code, 200)
+        payload = response.json()
+        self.assertEqual(payload["intent"], "project_context_updated")
+        self.assertEqual(payload["actions"], [])
+        self.assertEqual(payload["commands"], [])
+
+        current_workflow, _ = self._current_workflow()
+        project_context = current_workflow["metadata"]["project_context"]
+        self.assertEqual(project_context["imaging_modality"], "EM")
+        self.assertEqual(project_context["target_structure"], "mitochondria")
+        self.assertEqual(project_context["optimization_priority"], "speed")
+
+    def test_agent_volume_id_question_does_not_mutate_project_context(self):
+        workflow, _ = self._current_workflow()
+        workflow_id = workflow["id"]
+        patch_response = self.client.patch(
+            f"/api/workflows/{workflow_id}",
+            json={
+                "title": "Yixiao TapeReader XRI Case Study",
+                "stage": "visualization",
+                "dataset_path": "/projects/yixiao",
+                "metadata": {
+                    "project_context": {
+                        "imaging_modality": "X-ray / XRI volumetric microscopy",
+                        "target_structure": "CytoTape fibres",
+                        "voxel_size_nm": [40, 16.3, 16.3],
+                        "training_policy": "train only on confirmed ground-truth masks",
+                    }
+                },
+            },
+        )
+        self.assertEqual(patch_response.status_code, 200)
+
+        response = self.client.post(
+            f"/api/workflows/{workflow_id}/agent/query",
+            json={"query": "Why did you leave out 5_1, 5_2, 6_1, and 6_2?"},
+        )
+
+        self.assertEqual(response.status_code, 200)
+        payload = response.json()
+        self.assertNotEqual(payload["intent"], "project_context_updated")
+
+        current_workflow, _ = self._current_workflow()
+        project_context = current_workflow["metadata"]["project_context"]
+        self.assertEqual(project_context["voxel_size_nm"], [40, 16.3, 16.3])
+        self.assertNotEqual(project_context["voxel_size_nm"], [5, 1, 5])
+
+    def test_project_progress_response_names_volume_groups(self):
+        response = workflows_router_module._format_project_progress_response(
+            {
+                "summary": {
+                    "tracked_total": 10,
+                    "ground_truth": 6,
+                    "needs_proofreading": 2,
+                    "missing_segmentation": 2,
+                    "completion_pct": 60.0,
+                },
+                "volumes": [
+                    {"name": "1-xri_raw.tif", "status": "ground_truth"},
+                    {"name": "5_1-xri-raw.tif", "status": "needs_proofreading"},
+                    {"name": "5_2-xri_raw.tif", "status": "needs_proofreading"},
+                    {"name": "6_1-xri_raw.tif", "status": "missing_segmentation"},
+                    {"name": "6_2-xri-raw.tif", "status": "missing_segmentation"},
+                ],
+            }
+        )
+
+        self.assertIn("ready for training: 1-xri_raw.tif", response)
+        self.assertIn(
+            "proofread before training: 5_1-xri-raw.tif, 5_2-xri_raw.tif",
+            response,
+        )
+        self.assertIn(
+            "image-only/inference targets: 6_1-xri_raw.tif, 6_2-xri-raw.tif",
+            response,
+        )
+
+    def test_agent_handles_repair_language_without_repeating_recommendation_cards(self):
+        workflow, _ = self._current_workflow()
+        workflow_id = workflow["id"]
+        self.client.patch(
+            f"/api/workflows/{workflow_id}",
+            json={
+                "stage": "proofreading",
+                "image_path": "/tmp/image.h5",
+                "mask_path": "/tmp/mask.h5",
+            },
+        )
+
+        response = self.client.post(
+            f"/api/workflows/{workflow_id}/agent/query",
+            json={"query": "bruh"},
+        )
+        self.assertEqual(response.status_code, 200)
+        payload = response.json()
+        self.assertEqual(payload["intent"], "repair")
+        self.assertIn("too generic", payload["response"])
+        self.assertEqual(payload["actions"], [])
+        self.assertEqual(payload["commands"], [])
+
+    def test_agent_handles_unknown_text_without_recommendation_cards(self):
+        workflow, _ = self._current_workflow()
+        workflow_id = workflow["id"]
+        self.client.patch(
+            f"/api/workflows/{workflow_id}",
+            json={
+                "stage": "proofreading",
+                "image_path": "/tmp/image.h5",
+                "mask_path": "/tmp/mask.h5",
+            },
+        )
+
+        response = self.client.post(
+            f"/api/workflows/{workflow_id}/agent/query",
+            json={"query": "mmajkf,ansdjs"},
+        )
+        self.assertEqual(response.status_code, 200)
+        payload = response.json()
+        self.assertEqual(payload["intent"], "clarify_next_job")
+        self.assertIn("not sure which app step", payload["response"])
+        self.assertNotIn("did not understand", payload["response"].lower())
+        self.assertEqual(payload["actions"], [])
+        self.assertEqual(payload["commands"], [])
+
+    def test_agent_answers_current_workflow_context_instead_of_repeating_next_step(
+        self,
+    ):
+        workflow, _ = self._current_workflow()
+        workflow_id = workflow["id"]
+        self.client.patch(
+            f"/api/workflows/{workflow_id}",
+            json={
+                "title": "mito25-paper-loop-smoke",
+                "stage": "proofreading",
+                "image_path": "/projects/mito25/data/image/mito25_im.h5",
+                "mask_path": "/projects/mito25/data/seg/mito25_seg.h5",
+                "metadata": {
+                    "project_context": {
+                        "imaging_modality": "EM",
+                        "target_structure": "mitochondria",
+                        "optimization_priority": "accuracy",
+                    }
+                },
+            },
+        )
+
+        response = self.client.post(
+            f"/api/workflows/{workflow_id}/agent/query",
+            json={"query": "what exactly is the project I am on right now?"},
+        )
+        self.assertEqual(response.status_code, 200)
+        payload = response.json()
+        self.assertEqual(payload["intent"], "project_context")
+        self.assertIn("mito25-paper-loop-smoke", payload["response"])
+        self.assertIn("EM", payload["response"])
+        self.assertIn("mitochondria", payload["response"])
+        self.assertIn("accuracy", payload["response"])
+        self.assertIn("proofreading", payload["response"])
+        self.assertIn("mito25_im.h5", payload["response"])
+        self.assertNotIn("0 inference failures", payload["response"])
+
+    def test_agent_asks_for_biological_context_before_running_inference(self):
+        workflow, _ = self._current_workflow()
+        workflow_id = workflow["id"]
+        self.client.patch(
+            f"/api/workflows/{workflow_id}",
+            json={
+                "stage": "inference",
+                "image_path": "/projects/unknown/image.tif",
+                "checkpoint_path": "/projects/unknown/checkpoint.pth.tar",
+            },
+        )
+
+        response = self.client.post(
+            f"/api/workflows/{workflow_id}/agent/query",
+            json={"query": "run inference"},
+        )
+        self.assertEqual(response.status_code, 200)
+        payload = response.json()
+        self.assertEqual(payload["intent"], "collect_project_context")
+        self.assertIn("imaging modality", payload["response"])
+        self.assertIn("target structure", payload["response"])
+        self.assertEqual(payload["policy_decision"]["decision"], "blocked")
+        self.assertFalse(payload["policy_decision"]["requires_approval"])
+        self.assertEqual(payload["freshness"]["scope"], "project_context")
+        self.assertEqual(payload["freshness"]["state"], "missing")
+        self.assertCountEqual(
+            payload["freshness"]["missing"],
+            ["imaging_modality", "target_structure"],
+        )
+        self.assertEqual(
+            payload["blocking_reasons"][0]["code"],
+            "project_context.missing_imaging_modality",
+        )
+        self.assertEqual(
+            payload["blocking_reasons"][1]["code"],
+            "project_context.missing_target_structure",
+        )
+        self.assertEqual(payload["actions"], [])
+        self.assertEqual(payload["commands"], [])
+
+    def test_project_context_freshness_reports_missing_and_stale_states(self):
+        missing_context_workflow = type(
+            "WorkflowSession",
+            (),
+            {"metadata_json": json.dumps({"project_context": {}})},
+        )()
+        missing_freshness = workflows_router_module._project_context_freshness(
+            missing_context_workflow
+        )
+        self.assertEqual(missing_freshness["scope"], "project_context")
+        self.assertEqual(missing_freshness["state"], "missing")
+        self.assertCountEqual(
+            missing_freshness["missing"],
+            ["imaging_modality", "target_structure"],
+        )
+
+        stale_context_workflow = type(
+            "WorkflowSession",
+            (),
+            {
+                "metadata_json": json.dumps(
+                    {
+                        "project_context": {
+                            "imaging_modality": "EM",
+                            "target_structure": "mitochondria",
+                            "source": "initial_project_default",
+                        }
+                    }
+                )
+            },
+        )()
+        stale_freshness = workflows_router_module._project_context_freshness(
+            stale_context_workflow
+        )
+        self.assertEqual(stale_freshness["scope"], "project_context")
+        self.assertEqual(stale_freshness["state"], "stale")
+        self.assertEqual(stale_freshness["missing"], [])
+        self.assertEqual(
+            stale_freshness["present"],
+            ["imaging_modality", "target_structure"],
+        )
+
+    def test_agent_stores_context_and_then_runs_inference(self):
+        workflow, _ = self._current_workflow()
+        workflow_id = workflow["id"]
+        self.client.patch(
+            f"/api/workflows/{workflow_id}",
+            json={
+                "stage": "inference",
+                "image_path": "/projects/unknown/image.tif",
+                "checkpoint_path": "/projects/unknown/checkpoint.pth.tar",
+            },
+        )
+
+        response = self.client.post(
+            f"/api/workflows/{workflow_id}/agent/query",
+            json={"query": "run inference on EM mitochondria; prioritize accuracy"},
+        )
+        self.assertEqual(response.status_code, 200)
+        payload = response.json()
+        self.assertEqual(payload["intent"], "start_inference")
+        self.assertTrue(payload["actions"])
+
+        current_workflow, _ = self._current_workflow()
+        project_context = current_workflow["metadata"]["project_context"]
+        self.assertEqual(project_context["imaging_modality"], "EM")
+        self.assertEqual(project_context["target_structure"], "mitochondria")
+        self.assertEqual(project_context["optimization_priority"], "accuracy")
+
+    def test_agent_start_training_uses_data_derived_defaults(self):
+        workflow, _ = self._current_workflow()
+        workflow_id = workflow["id"]
+        self.client.patch(
+            f"/api/workflows/{workflow_id}",
+            json={
+                "title": "mito25-paper-loop-smoke",
+                "stage": "retraining_staged",
+                "image_path": "/projects/mito25/data/image/mito25_im.h5",
+                "corrected_mask_path": "/projects/mito25/data/seg/corrected.tif",
+                "metadata": {
+                    "project_context": {
+                        "imaging_modality": "EM",
+                        "target_structure": "mitochondria",
+                        "optimization_priority": "accuracy",
+                    }
+                },
+            },
+        )
+
+        response = self.client.post(
+            f"/api/workflows/{workflow_id}/agent/query",
+            json={"query": "train the model for me"},
+        )
+        self.assertEqual(response.status_code, 200)
+        payload = response.json()
+        self.assertEqual(payload["intent"], "start_training")
+        self.assertIn("safe defaults", payload["response"])
+        self.assertEqual(payload["policy_decision"]["decision"], "allowed")
+        self.assertTrue(payload["policy_decision"]["requires_approval"])
+        effects = payload["actions"][0]["client_effects"]
+        self.assertEqual(effects["navigate_to"], "training")
+        self.assertEqual(
+            effects["set_training_image_path"],
+            "/projects/mito25/data/image/mito25_im.h5",
+        )
+        self.assertEqual(
+            effects["set_training_label_path"],
+            "/projects/mito25/data/seg/corrected.tif",
+        )
+        self.assertEqual(
+            effects["set_training_config_preset"],
+            "configs/MitoEM/Mito25-Local-BC.yaml",
+        )
+        self.assertTrue(effects["runtime_action"]["autopick_parameters"])
+        self.assertEqual(
+            effects["runtime_action"]["parameter_mode"],
+            "agent_default",
+        )
+        self.assertEqual(
+            payload["actions"][0]["policy_decision"]["decision"], "allowed"
+        )
+        self.assertTrue(payload["actions"][0]["policy_decision"]["requires_approval"])
+        self.assertEqual(payload["actions"][0]["freshness"]["scope"], "training")
+        self.assertEqual(payload["actions"][0]["freshness"]["state"], "ready")
+
+    def test_approved_training_run_proposal_returns_runtime_launch_effects(self):
+        workflow, _ = self._current_workflow()
+        workflow_id = workflow["id"]
+        self.client.patch(
+            f"/api/workflows/{workflow_id}",
+            json={
+                "stage": "retraining_staged",
+                "image_path": "/projects/mito25/data/image/mito25_im.h5",
+                "corrected_mask_path": "/projects/mito25/data/seg/corrected.tif",
+            },
+        )
+        client_effects = {
+            "navigate_to": "training",
+            "runtime_action": {
+                "kind": "start_training",
+                "autopick_parameters": True,
+                "parameter_mode": "agent_default",
+            },
+            "set_training_config_preset": "configs/MitoEM/Mito25-Local-BC.yaml",
+            "set_training_image_path": "/projects/mito25/data/image/mito25_im.h5",
+            "set_training_label_path": "/projects/mito25/data/seg/corrected.tif",
+            "set_training_output_path": "/projects/mito25/outputs/training",
+            "set_training_log_path": "/projects/mito25/outputs/training",
+        }
+
+        proposal = self.client.post(
+            f"/api/workflows/{workflow_id}/agent-actions",
+            json={
+                "action": "start_training_run",
+                "summary": "Approve training run.",
+                "payload": {
+                    "client_effects": client_effects,
+                    "config_preset": client_effects["set_training_config_preset"],
+                    "image_path": client_effects["set_training_image_path"],
+                    "label_path": client_effects["set_training_label_path"],
+                    "output_path": client_effects["set_training_output_path"],
+                    "parameter_mode": "agent_default",
+                    "autopick_parameters": True,
+                },
+            },
+        )
+        self.assertEqual(proposal.status_code, 200)
+
+        approval = self.client.post(
+            f"/api/workflows/{workflow_id}/agent-actions/"
+            f"{proposal.json()['id']}/approve"
+        )
+        self.assertEqual(approval.status_code, 200)
+        payload = approval.json()
+        self.assertEqual(payload["workflow"]["stage"], "retraining_staged")
+        self.assertEqual(
+            payload["client_effects"]["runtime_action"]["kind"], "start_training"
+        )
+        self.assertEqual(len(payload["commands"]), 1)
+        self.assertEqual(payload["commands"][0]["command_type"], "start_training")
+        self.assertEqual(payload["commands"][0]["status"], "queued")
+        self.assertEqual(
+            payload["commands"][0]["input"]["client_effects"]["runtime_action"]["kind"],
+            "start_training",
+        )
+        self.assertTrue(
+            payload["client_effects"]["runtime_action"]["autopick_parameters"]
+        )
+        self.assertEqual(
+            payload["client_effects"]["set_training_config_preset"],
+            "configs/MitoEM/Mito25-Local-BC.yaml",
+        )
+        self.assertEqual(
+            payload["client_effects"]["set_training_output_path"],
+            "/projects/mito25/outputs/training",
+        )
+
+        command_list = self.client.get(f"/api/workflows/{workflow_id}/commands")
+        self.assertEqual(command_list.status_code, 200)
+        self.assertEqual(len(command_list.json()), 1)
+        self.assertEqual(command_list.json()[0]["id"], payload["commands"][0]["id"])
+
+    def test_approved_training_run_applies_user_field_overrides(self):
+        workflow, _ = self._current_workflow()
+        workflow_id = workflow["id"]
+        self.client.patch(
+            f"/api/workflows/{workflow_id}",
+            json={
+                "stage": "retraining_staged",
+                "image_path": "/projects/mito25/data/image/original_im.h5",
+                "corrected_mask_path": "/projects/mito25/data/seg/original_seg.h5",
+            },
+        )
+        client_effects = {
+            "navigate_to": "training",
+            "runtime_action": {
+                "kind": "start_training",
+                "autopick_parameters": True,
+                "parameter_mode": "agent_default",
+            },
+            "set_training_config_preset": "configs/original.yaml",
+            "set_training_image_path": "/projects/mito25/subsets/original_image",
+            "set_training_label_path": "/projects/mito25/subsets/original_seg",
+            "set_training_output_path": "/projects/mito25/outputs/original",
+            "set_training_log_path": "/projects/mito25/outputs/original",
+        }
+        proposal = self.client.post(
+            f"/api/workflows/{workflow_id}/agent-actions",
+            json={
+                "action": "start_training_run",
+                "summary": "Approve training run.",
+                "payload": {
+                    "client_effects": client_effects,
+                    "config_preset": client_effects["set_training_config_preset"],
+                    "image_path": client_effects["set_training_image_path"],
+                    "label_path": client_effects["set_training_label_path"],
+                    "output_path": client_effects["set_training_output_path"],
+                },
+            },
+        )
+        self.assertEqual(proposal.status_code, 200)
+
+        approval = self.client.post(
+            f"/api/workflows/{workflow_id}/agent-actions/"
+            f"{proposal.json()['id']}/approve",
+            json={
+                "overrides": {
+                    "config_preset": "configs/edited.yaml",
+                    "image_path": "/projects/mito25/subsets/edited_image",
+                    "label_path": "/projects/mito25/subsets/edited_seg",
+                    "output_path": "/projects/mito25/outputs/edited",
+                }
+            },
+        )
+        self.assertEqual(approval.status_code, 200)
+        payload = approval.json()
+        self.assertEqual(
+            payload["client_effects"]["set_training_config_preset"],
+            "configs/edited.yaml",
+        )
+        self.assertEqual(
+            payload["client_effects"]["set_training_image_path"],
+            "/projects/mito25/subsets/edited_image",
+        )
+        self.assertEqual(
+            payload["client_effects"]["set_training_label_path"],
+            "/projects/mito25/subsets/edited_seg",
+        )
+        self.assertEqual(
+            payload["client_effects"]["set_training_output_path"],
+            "/projects/mito25/outputs/edited",
+        )
+        self.assertEqual(
+            payload["commands"][0]["input"]["client_effects"][
+                "set_training_output_path"
+            ],
+            "/projects/mito25/outputs/edited",
+        )
+        approved_payload = payload["events"][0]["payload"]
+        self.assertEqual(
+            approved_payload["user_edits"]["output_path"],
+            "/projects/mito25/outputs/edited",
+        )
+
+    def test_agent_train_short_phrases_do_not_fall_to_unknown(self):
+        workflow, _ = self._current_workflow()
+        workflow_id = workflow["id"]
+
+        response = self.client.post(
+            f"/api/workflows/{workflow_id}/agent/query",
+            json={"query": "train"},
+        )
+        self.assertEqual(response.status_code, 200)
+        payload = response.json()
+        self.assertEqual(payload["intent"], "collect_project_context")
+        self.assertIn("Before I choose a training preset", payload["response"])
+        self.assertNotIn("did not understand", payload["response"].lower())
+
+    def test_agent_train_model_from_current_labels(self):
+        workflow, _ = self._current_workflow()
+        workflow_id = workflow["id"]
+        self.client.patch(
+            f"/api/workflows/{workflow_id}",
+            json={
+                "stage": "setup",
+                "image_path": "/projects/sample/data/image/train",
+                "label_path": "/projects/sample/data/labels/train",
+                "metadata": {"project_context": {"use_defaults": True}},
+            },
+        )
+
+        response = self.client.post(
+            f"/api/workflows/{workflow_id}/agent/query",
+            json={"query": "can we train a model for this?"},
+        )
+        self.assertEqual(response.status_code, 200)
+        payload = response.json()
+        self.assertEqual(payload["intent"], "start_training")
+        self.assertIn("train a model", payload["response"].lower())
+        self.assertEqual(payload["policy_decision"]["decision"], "allowed")
+        self.assertTrue(payload["policy_decision"]["requires_approval"])
+        self.assertEqual(payload["actions"][0]["id"], "start-training")
+        effects = payload["actions"][0]["client_effects"]
+        self.assertEqual(effects["navigate_to"], "training")
+        self.assertEqual(
+            effects["set_training_image_path"],
+            "/projects/sample/data/image/train",
+        )
+        self.assertEqual(
+            effects["set_training_label_path"],
+            "/projects/sample/data/labels/train",
+        )
+        self.assertEqual(effects["runtime_action"]["kind"], "start_training")
+        self.assertEqual(
+            payload["actions"][0]["policy_decision"]["decision"], "allowed"
+        )
+        self.assertTrue(payload["actions"][0]["policy_decision"]["requires_approval"])
+        self.assertEqual(payload["actions"][0]["freshness"]["scope"], "training")
+        self.assertEqual(payload["actions"][0]["freshness"]["state"], "ready")
+
+    def test_agent_train_model_uses_ground_truth_progress_subset(self):
+        workflow, _ = self._current_workflow()
+        workflow_id = workflow["id"]
+        project_root = pathlib.Path(self.temp_dir.name) / "progress-training-project"
+        image_dir = project_root / "data" / "image"
+        label_dir = project_root / "data" / "seg"
+        config_path = project_root / "configs" / "MitoEM2-Pyra-Demo-BC.yaml"
+        image_dir.mkdir(parents=True)
+        label_dir.mkdir(parents=True)
+        config_path.parent.mkdir(parents=True)
+        config_path.write_text("SYSTEM: PyTC\n", encoding="utf-8")
+        for stem in ["vol_a", "vol_b", "vol_c"]:
+            (image_dir / f"{stem}_im.h5").write_bytes(b"")
+        (label_dir / "vol_a_curated_seg.h5").write_bytes(b"")
+        (label_dir / "vol_b_seg.h5").write_bytes(b"")
+
+        self.client.patch(
+            f"/api/workflows/{workflow_id}",
+            json={
+                "stage": "setup",
+                "dataset_path": str(project_root),
+                "image_path": str(image_dir),
+                "label_path": str(label_dir),
+                "config_path": str(config_path),
+                "metadata": {
+                    "project_context": {
+                        "imaging_modality": "EM",
+                        "target_structure": "mitochondria",
+                        "optimization_priority": "accuracy",
+                    }
+                },
+            },
+        )
+
+        response = self.client.post(
+            f"/api/workflows/{workflow_id}/agent/query",
+            json={
+                "query": "can we train a model on my ground truth to segment the rest"
+            },
+        )
+
+        self.assertEqual(response.status_code, 200)
+        payload = response.json()
+        self.assertEqual(payload["intent"], "start_training")
+        self.assertIn("ground-truth", payload["response"])
+        self.assertNotEqual(payload["intent"], "project_progress")
+        action = payload["actions"][0]
+        self.assertEqual(action["card_type"], "workflow.action_card/v2")
+        self.assertEqual(action["agent_type"], "training_agent")
+        self.assertEqual(action["specialist_agent"]["label"], "Training Agent")
+        self.assertEqual(action["agent_icon_key"], "experiment")
+        self.assertEqual(action["agent_border_style"], "thick")
+        self.assertEqual(action["specialist_agent"]["icon_key"], "experiment")
+        self.assertEqual(action["risk_tier"], "R4_runtime_job")
+        self.assertTrue(action["requires_approval"])
+        self.assertIn("input_artifacts", action)
+        self.assertTrue(action["input_artifacts"])
+        self.assertTrue(action["output_artifacts"])
+        self.assertEqual(action["action_card"]["action_type"], "start_training")
+        self.assertEqual(
+            action["action_card"]["orchestrator_agent"]["type"],
+            "project_manager",
+        )
+        self.assertEqual(
+            action["action_card"]["specialist_agent"]["type"],
+            "training_agent",
+        )
+        effects = action["client_effects"]
+        subset = effects["training_volume_subset"]
+        self.assertEqual(subset["train_volume_count"], 1)
+        self.assertEqual(subset["target_volume_count"], 1)
+        self.assertEqual(subset["review_volume_count"], 1)
+        self.assertEqual(subset["training_statuses"], ["ground_truth"])
+        self.assertEqual(effects["set_training_config_preset"], str(config_path))
+        self.assertTrue(pathlib.Path(effects["set_training_image_path"]).is_dir())
+        self.assertTrue(pathlib.Path(effects["set_training_label_path"]).is_dir())
+        self.assertTrue(pathlib.Path(subset["manifest_path"]).is_file())
+        self.assertIn(
+            "volume_subset",
+            effects["runtime_action"],
+        )
+        self.assertEqual(
+            effects["runtime_action"]["volume_subset"]["train_volume_count"],
+            1,
+        )
+
+    def test_agent_train_model_names_missing_label_blocker(self):
+        workflow, _ = self._current_workflow()
+        workflow_id = workflow["id"]
+        self.client.patch(
+            f"/api/workflows/{workflow_id}",
+            json={
+                "stage": "setup",
+                "image_path": "/projects/sample/data/image/train",
+                "metadata": {"project_context": {"use_defaults": True}},
+            },
+        )
+
+        response = self.client.post(
+            f"/api/workflows/{workflow_id}/agent/query",
+            json={"query": "train on saved edits"},
+        )
+        self.assertEqual(response.status_code, 200)
+        payload = response.json()
+        self.assertEqual(payload["intent"], "start_training")
+        self.assertIn("need labels or saved proofreading edits", payload["response"])
+        self.assertEqual(payload["commands"], [])
+        self.assertEqual(payload["actions"][0]["risk_level"], "prefills_form")
+        self.assertFalse(payload["actions"][0]["requires_approval"])
+        self.assertEqual(payload["policy_decision"]["decision"], "blocked")
+        self.assertFalse(payload["policy_decision"]["requires_approval"])
+        self.assertEqual(
+            payload["actions"][0]["policy_decision"]["decision"],
+            "blocked",
+        )
+        self.assertFalse(payload["actions"][0]["policy_decision"]["requires_approval"])
+        self.assertEqual(
+            payload["actions"][0]["policy_decision"]["blocking_reasons"][0]["code"],
+            "training.missing_labels",
+        )
+        self.assertEqual(payload["actions"][0]["freshness"]["scope"], "training")
+        self.assertEqual(payload["actions"][0]["freshness"]["state"], "missing")
+        self.assertEqual(
+            payload["actions"][0]["client_effects"]["runtime_action"]["kind"],
+            "choose_project_data",
+        )
+
+    def test_agent_train_on_trusted_masks_only_for_tapereader_context(self):
+        workflow, _ = self._current_workflow()
+        workflow_id = workflow["id"]
+        self.client.patch(
+            f"/api/workflows/{workflow_id}",
+            json={
+                "stage": "setup",
+                "image_path": "/tmp/yixiao/image.h5",
+                "metadata": {
+                    "project_context": {
+                        "imaging_modality": "X-ray / XRI volumetric microscopy",
+                        "target_structure": "CytoTape fibres",
+                        "training_policy": "train only on confirmed ground-truth masks",
+                    }
+                },
+            },
+        )
+
+        response = self.client.post(
+            f"/api/workflows/{workflow_id}/agent/query",
+            json={"query": "train the model now"},
+        )
+        self.assertEqual(response.status_code, 200)
+        payload = response.json()
+        self.assertEqual(payload["intent"], "start_training")
+        self.assertIn(
+            "confirmed labels or saved proofreading edits", payload["response"].lower()
+        )
+        self.assertEqual(payload["policy_decision"]["decision"], "blocked")
+        self.assertFalse(payload["policy_decision"]["requires_approval"])
+        self.assertEqual(
+            payload["actions"][0]["policy_decision"]["reason_code"],
+            "training_missing_inputs",
+        )
+        self.assertEqual(payload["actions"][0]["id"], "open-files")
+
+        self.client.patch(
+            f"/api/workflows/{workflow_id}",
+            json={"corrected_mask_path": "/tmp/yixiao/saved-edits.tif"},
+        )
+        response = self.client.post(
+            f"/api/workflows/{workflow_id}/agent/query",
+            json={"query": "train this image"},
+        )
+        self.assertEqual(response.status_code, 200)
+        payload = response.json()
+        self.assertEqual(payload["intent"], "start_training")
+        self.assertEqual(payload["policy_decision"]["decision"], "allowed")
+        self.assertTrue(payload["policy_decision"]["requires_approval"])
+        self.assertEqual(
+            payload["actions"][0]["policy_decision"]["decision"], "allowed"
+        )
+        self.assertTrue(payload["actions"][0]["policy_decision"]["requires_approval"])
+        self.assertEqual(payload["actions"][0]["id"], "start-training")
+        self.assertEqual(
+            payload["actions"][0]["client_effects"]["set_training_label_path"],
+            "/tmp/yixiao/saved-edits.tif",
+        )
+
+    def test_agent_infer_on_image_only_projects_only_with_checkpoint(self):
+        workflow, _ = self._current_workflow()
+        workflow_id = workflow["id"]
+        self.client.patch(
+            f"/api/workflows/{workflow_id}",
+            json={
+                "stage": "setup",
+                "image_path": "/tmp/yixiao/image-only-project.tif",
+                "metadata": {
+                    "project_context": {
+                        "imaging_modality": "X-ray / XRI volumetric microscopy",
+                        "target_structure": "CytoTape fibres",
+                    }
+                },
+            },
+        )
+
+        checkpoint_missing = self.client.post(
+            f"/api/workflows/{workflow_id}/agent/query",
+            json={"query": "run inference"},
+        )
+        self.assertEqual(checkpoint_missing.status_code, 200)
+        checkpoint_payload = checkpoint_missing.json()
+        self.assertEqual(checkpoint_payload["intent"], "start_inference")
+        self.assertIn("need model checkpoint", checkpoint_payload["response"].lower())
+        self.assertEqual(checkpoint_payload["policy_decision"]["decision"], "blocked")
+        self.assertFalse(checkpoint_payload["policy_decision"]["requires_approval"])
+        self.assertEqual(checkpoint_payload["freshness"]["scope"], "inference")
+        self.assertEqual(checkpoint_payload["freshness"]["state"], "missing")
+        self.assertEqual(
+            checkpoint_payload["actions"][0]["policy_decision"]["decision"],
+            "blocked",
+        )
+        self.assertFalse(
+            checkpoint_payload["actions"][0]["policy_decision"]["requires_approval"]
+        )
+        self.assertEqual(checkpoint_payload["actions"][0]["id"], "open-inference")
+
+        self.client.patch(
+            f"/api/workflows/{workflow_id}",
+            json={"checkpoint_path": "/tmp/yixiao/model-checkpoint.pt"},
+        )
+        checkpoint_present = self.client.post(
+            f"/api/workflows/{workflow_id}/agent/query",
+            json={"query": "run model"},
+        )
+        self.assertEqual(checkpoint_present.status_code, 200)
+        ready_payload = checkpoint_present.json()
+        self.assertEqual(ready_payload["intent"], "start_inference")
+        self.assertEqual(ready_payload["policy_decision"]["decision"], "allowed")
+        self.assertTrue(ready_payload["policy_decision"]["requires_approval"])
+        self.assertEqual(ready_payload["freshness"]["scope"], "inference")
+        self.assertEqual(ready_payload["freshness"]["state"], "ready")
+        self.assertEqual(ready_payload["actions"][0]["id"], "start-inference")
+        self.assertEqual(
+            ready_payload["actions"][0]["policy_decision"]["decision"],
+            "allowed",
+        )
+        self.assertTrue(
+            ready_payload["actions"][0]["policy_decision"]["requires_approval"]
+        )
+
+    def test_agent_segment_request_does_not_retrain_from_untrusted_prediction(self):
+        workflow, _ = self._current_workflow()
+        workflow_id = workflow["id"]
+        self.client.patch(
+            f"/api/workflows/{workflow_id}",
+            json={
+                "stage": "setup",
+                "image_path": "/tmp/yixiao/tape-seg-image.h5",
+                "inference_output_path": "/tmp/yixiao/untrusted-prediction.tif",
+                "metadata": {
+                    "project_context": {
+                        "imaging_modality": "X-ray / XRI volumetric microscopy",
+                        "target_structure": "CytoTape fibres",
+                    }
+                },
+            },
+        )
+
+        response = self.client.post(
+            f"/api/workflows/{workflow_id}/agent/query",
+            json={"query": "segment this dataset"},
+        )
+        self.assertEqual(response.status_code, 200)
+        payload = response.json()
+        self.assertEqual(payload["intent"], "start_segmentation")
+        self.assertIn("running inference needs model checkpoint", payload["response"])
+        action_ids = [action["id"] for action in payload["actions"]]
+        self.assertNotIn("start-training", action_ids)
+
+    def test_general_chat_direct_guard_answers_meta_run_questions(self):
+        with patch("server_api.main._ensure_chatbot") as ensure_chatbot:
+            response = self.client.post(
+                "/chat/query",
+                json={"query": "how do you run so quickly?"},
+            )
+
+        self.assertEqual(response.status_code, 200)
+        payload = response.json()
+        self.assertEqual(payload["source"], "direct_guard")
+        self.assertIn("did not run training or inference", payload["response"])
+        ensure_chatbot.assert_not_called()
+
+        conversation_response = self.client.get(
+            f"/chat/conversations/{payload['conversationId']}"
+        )
+        self.assertEqual(conversation_response.status_code, 200)
+        messages = conversation_response.json()["messages"]
+        self.assertEqual(
+            [message["role"] for message in messages], ["user", "assistant"]
+        )
+        self.assertEqual(messages[1]["source"], "direct_guard")
+
+    def test_general_chat_direct_guard_handles_gibberish_without_llm(self):
+        with patch("server_api.main._ensure_chatbot") as ensure_chatbot:
+            response = self.client.post(
+                "/chat/query",
+                json={"query": "mmajkf,ansdjs"},
+            )
+
+        self.assertEqual(response.status_code, 200)
+        payload = response.json()
+        self.assertEqual(payload["source"], "direct_guard")
+        self.assertIn("did not understand", payload["response"])
+        ensure_chatbot.assert_not_called()
+
+    def test_general_chat_llm_unavailable_returns_degraded_response(self):
+        import server_api.main as server_api_main
+
+        original_error = server_api_main._chatbot_error
+        server_api_main._chatbot_error = RuntimeError('model "missing-model" not found')
+        try:
+            with patch("server_api.main._ensure_chatbot", return_value=False):
+                response = self.client.post(
+                    "/chat/query",
+                    json={"query": "how do I configure the docs assistant?"},
+                )
+        finally:
+            server_api_main._chatbot_error = original_error
+
+        self.assertEqual(response.status_code, 200)
+        payload = response.json()
+        self.assertEqual(payload["source"], "llm_unavailable")
+        self.assertIn("documentation assistant", payload["response"])
+        self.assertNotIn("missing-model", payload["response"])
+
+        conversation_response = self.client.get(
+            f"/chat/conversations/{payload['conversationId']}"
+        )
+        self.assertEqual(conversation_response.status_code, 200)
+        messages = conversation_response.json()["messages"]
+        self.assertEqual(messages[1]["source"], "llm_unavailable")
+
+    def test_clear_chat_does_not_initialize_llm(self):
+        import server_api.main as server_api_main
+
+        original_history = list(server_api_main._chat_history)
+        original_active_convo_id = server_api_main._active_convo_id
+        server_api_main._chat_history[:] = [{"role": "user", "content": "status"}]
+        server_api_main._active_convo_id = 123
+        try:
+            with patch(
+                "server_api.main._ensure_chatbot",
+                side_effect=AssertionError("clear should not initialize chat"),
+            ) as ensure_chatbot:
+                response = self.client.post("/chat/clear")
+        finally:
+            server_api_main._chat_history[:] = original_history
+            server_api_main._active_convo_id = original_active_convo_id
+
+        self.assertEqual(response.status_code, 200)
+        ensure_chatbot.assert_not_called()
+
+    def test_agent_handles_greetings_without_prompt_leakage(self):
+        workflow, _ = self._current_workflow()
+        workflow_id = workflow["id"]
+        self.client.patch(
+            f"/api/workflows/{workflow_id}",
+            json={
+                "stage": "proofreading",
+                "image_path": "/tmp/image.h5",
+                "mask_path": "/tmp/mask.h5",
+            },
+        )
+
+        response = self.client.post(
+            f"/api/workflows/{workflow_id}/agent/query",
+            json={"query": "hi!"},
+        )
+        self.assertEqual(response.status_code, 200)
+        payload = response.json()
+        self.assertIn("Hey", payload["response"])
+        self.assertIn("I would probably", payload["response"])
+        self.assertNotIn("Next:", payload["response"])
+        self.assertNotIn("Tell me the job", payload["response"])
+        self.assertNotIn("Supervisor Agent", payload["response"])
+        self.assertNotIn("RESPONSE STYLE", payload["response"])
+        self.assertEqual(payload["actions"], [])
+        self.assertEqual(payload["commands"], [])
+        self.assertEqual(payload["intent"], "greeting")
+
+    def test_agent_acknowledges_chat_tone_feedback_without_status_template(self):
+        workflow, _ = self._current_workflow()
+        workflow_id = workflow["id"]
+        self.client.patch(
+            f"/api/workflows/{workflow_id}",
+            json={
+                "stage": "setup",
+                "image_path": "/tmp/image.h5",
+                "mask_path": "/tmp/mask.h5",
+                "metadata": {
+                    "project_context": {
+                        "imaging_modality": "EM",
+                        "target_structure": "mitochondria",
+                    }
+                },
+            },
+        )
+
+        response = self.client.post(
+            f"/api/workflows/{workflow_id}/agent/query",
+            json={"query": "ok cool, a bit of a robotic response though"},
+        )
+        self.assertEqual(response.status_code, 200)
+        payload = response.json()
+        self.assertEqual(payload["intent"], "style_feedback")
+        self.assertIn("Yeah, agreed", payload["response"])
+        self.assertIn("more conversational", payload["response"])
+        self.assertIn("EM", payload["response"])
+        self.assertIn("mitochondria", payload["response"])
+        self.assertNotIn("My read:", payload["response"])
+        self.assertNotIn("Current read:", payload["response"])
+        self.assertNotIn("Why this fits:", payload["response"])
+        self.assertEqual(payload["actions"], [])
+        self.assertEqual(payload["commands"], [])
+
+    def test_agent_can_offer_evaluation_and_export_actions(self):
+        workflow, _ = self._current_workflow()
+        workflow_id = workflow["id"]
+        self.client.patch(
+            f"/api/workflows/{workflow_id}",
+            json={
+                "stage": "evaluation",
+                "label_path": "/tmp/ground-truth.tif",
+                "inference_output_path": "/tmp/candidate.tif",
+            },
+        )
+        baseline_run = self.client.post(
+            f"/api/workflows/{workflow_id}/model-runs",
+            json={
+                "run_type": "inference",
+                "status": "completed",
+                "output_path": "/tmp/baseline.tif",
+            },
+        )
+        self.assertEqual(baseline_run.status_code, 200)
+        candidate_run = self.client.post(
+            f"/api/workflows/{workflow_id}/model-runs",
+            json={
+                "run_type": "inference",
+                "status": "completed",
+                "output_path": "/tmp/candidate.tif",
+            },
+        )
+        self.assertEqual(candidate_run.status_code, 200)
+
+        evaluation_response = self.client.post(
+            f"/api/workflows/{workflow_id}/agent/query",
+            json={"query": "compare results and compute metrics"},
+        )
+        self.assertEqual(evaluation_response.status_code, 200)
+        evaluation_payload = evaluation_response.json()
+        self.assertIn("compute before/after metrics", evaluation_payload["response"])
+        self.assertEqual(evaluation_payload["policy_decision"]["decision"], "allowed")
+        self.assertTrue(evaluation_payload["policy_decision"]["requires_approval"])
+        self.assertEqual(evaluation_payload["freshness"]["scope"], "evaluation")
+        self.assertEqual(evaluation_payload["freshness"]["state"], "ready")
+        compute_action = evaluation_payload["actions"][0]
+        self.assertEqual(compute_action["id"], "compute-evaluation")
+        self.assertEqual(compute_action["risk_level"], "writes_workflow_record")
+        self.assertTrue(compute_action["requires_approval"])
+        self.assertEqual(compute_action["policy_decision"]["decision"], "allowed")
+        self.assertTrue(compute_action["policy_decision"]["requires_approval"])
+        self.assertEqual(compute_action["freshness"]["scope"], "evaluation")
+        self.assertEqual(compute_action["freshness"]["state"], "ready")
+        self.assertEqual(
+            compute_action["client_effects"]["workflow_action"]["kind"],
+            "compute_evaluation",
+        )
+        self.assertEqual(
+            compute_action["client_effects"]["workflow_action"][
+                "baseline_prediction_path"
+            ],
+            "/tmp/baseline.tif",
+        )
+
+    def test_agent_evaluation_blocks_when_reference_mask_missing(self):
+        workflow, _ = self._current_workflow()
+        workflow_id = workflow["id"]
+        self.client.patch(
+            f"/api/workflows/{workflow_id}",
+            json={
+                "stage": "evaluation",
+                "image_path": "/tmp/yixiao/eval-image.h5",
+            },
+        )
+
+        baseline_response = self.client.post(
+            f"/api/workflows/{workflow_id}/model-runs",
+            json={
+                "run_type": "inference",
+                "status": "completed",
+                "output_path": "/tmp/baseline-reference-case.tif",
+            },
+        )
+        self.assertEqual(baseline_response.status_code, 200)
+        candidate_response = self.client.post(
+            f"/api/workflows/{workflow_id}/model-runs",
+            json={
+                "run_type": "inference",
+                "status": "completed",
+                "output_path": "/tmp/candidate-reference-case.tif",
+            },
+        )
+        self.assertEqual(candidate_response.status_code, 200)
+
+        response = self.client.post(
+            f"/api/workflows/{workflow_id}/agent/query",
+            json={"query": "compare results and compute metrics"},
+        )
+        self.assertEqual(response.status_code, 200)
+        payload = response.json()
+        self.assertEqual(payload["intent"], "compute_evaluation")
+        self.assertIn("collect reference mask first.", payload["response"])
+        self.assertEqual(payload["policy_decision"]["decision"], "blocked")
+        self.assertFalse(payload["policy_decision"]["requires_approval"])
+        self.assertEqual(
+            payload["policy_decision"]["reason_code"],
+            "evaluation_missing_inputs",
+        )
+        self.assertEqual(payload["actions"][0]["id"], "show-evaluation-status")
+        self.assertEqual(
+            payload["actions"][0]["policy_decision"]["decision"],
+            "blocked",
+        )
+        self.assertFalse(payload["actions"][0]["policy_decision"]["requires_approval"])
+        self.assertEqual(
+            payload["blocking_reasons"][0]["code"],
+            "evaluation.missing_reference_mask",
+        )
+
+        export_response = self.client.post(
+            f"/api/workflows/{workflow_id}/agent/query",
+            json={"query": "export evidence bundle"},
+        )
+        self.assertEqual(export_response.status_code, 200)
+        export_payload = export_response.json()
+        self.assertEqual(export_payload["actions"][0]["id"], "export-workflow-bundle")
+        self.assertEqual(export_payload["actions"][0]["risk_level"], "exports_evidence")
+        self.assertTrue(export_payload["actions"][0]["requires_approval"])
+        self.assertEqual(
+            export_payload["actions"][0]["policy_decision"]["decision"], "allowed"
+        )
+        self.assertTrue(
+            export_payload["actions"][0]["policy_decision"]["requires_approval"]
+        )
+        self.assertEqual(
+            export_payload["actions"][0]["client_effects"]["workflow_action"]["kind"],
+            "export_bundle",
+        )
+
+    def test_agent_slash_command_aliases_route_to_actions(self):
+        workflow, _ = self._current_workflow()
+        workflow_id = workflow["id"]
+        self.client.patch(
+            f"/api/workflows/{workflow_id}",
+            json={
+                "stage": "inference",
+                "image_path": "/tmp/image.h5",
+                "checkpoint_path": "/tmp/checkpoint.pth.tar",
+                "metadata": {
+                    "project_context": {
+                        "imaging_modality": "EM",
+                        "target_structure": "mitochondria",
+                        "optimization_priority": "accuracy",
+                    }
+                },
+            },
+        )
+
+        response = self.client.post(
+            f"/api/workflows/{workflow_id}/agent/query",
+            json={"query": "/infer"},
+        )
+        self.assertEqual(response.status_code, 200)
+        payload = response.json()
+        self.assertEqual(payload["intent"], "start_inference")
+        self.assertEqual(payload["actions"][0]["id"], "start-inference")
+        self.assertEqual(payload["actions"][0]["risk_level"], "runs_job")
+        self.assertTrue(payload["actions"][0]["requires_approval"])
+        self.assertTrue(payload["tasks"])
+
     def test_ehtool_load_classify_save_and_export_append_workflow_events(self):
         workflow, _ = self._current_workflow()
         workflow_id = workflow["id"]
diff --git a/tests/test_workflow_spine_smoke.py b/tests/test_workflow_spine_smoke.py
index d46ace5c..802f8d15 100644
--- a/tests/test_workflow_spine_smoke.py
+++ b/tests/test_workflow_spine_smoke.py
@@ -3,6 +3,7 @@
 import unittest
 
 import pytest
+
 pytest.importorskip("sqlalchemy")
 from sqlalchemy import create_engine
 from sqlalchemy.orm import sessionmaker
@@ -12,6 +13,7 @@
 
 from server_api.auth import database as auth_database
 from server_api.auth import models
+import server_api.main as server_api_main
 from server_api.main import app as server_api_app
 
 
@@ -42,6 +44,9 @@ def tearDown(self):
         self.engine.dispose()
         self.temp_dir.cleanup()
 
+    def test_chatbot_backend_import_contract_is_available(self):
+        self.assertIsNotNone(server_api_main.build_chain)
+
     def test_spine_loop_load_proofread_stage_and_export_evidence(self):
         workflow_response = self.client.get("/api/workflows/current")
         self.assertEqual(workflow_response.status_code, 200)
@@ -53,7 +58,19 @@ def test_spine_loop_load_proofread_stage_and_export_evidence(self):
 
         self.client.patch(
             f"/api/workflows/{workflow_id}",
-            json={"stage": "proofreading", "corrected_mask_path": str(export_path)},
+            json={
+                "title": "mito25-paper-loop-smoke",
+                "stage": "proofreading",
+                "image_path": "/projects/mito25/data/image/mito25_im.h5",
+                "corrected_mask_path": str(export_path),
+                "metadata": {
+                    "project_context": {
+                        "imaging_modality": "EM",
+                        "target_structure": "mitochondria",
+                        "optimization_priority": "speed",
+                    }
+                },
+            },
         )
         self.client.post(
             f"/api/workflows/{workflow_id}/events",
@@ -71,8 +88,15 @@ def test_spine_loop_load_proofread_stage_and_export_evidence(self):
             json={"query": "stage corrected masks for retraining"},
         )
         self.assertEqual(query_response.status_code, 200)
-        proposals = query_response.json()["proposals"]
+        query_payload = query_response.json()
+        proposals = query_payload["proposals"]
         self.assertEqual(len(proposals), 1)
+        self.assertGreaterEqual(len(query_payload["actions"]), 1)
+        self.assertEqual(query_payload["commands"], [])
+        self.assertEqual(
+            query_payload["actions"][0]["client_effects"]["navigate_to"],
+            "training",
+        )
         proposal_id = proposals[0]["id"]
 
         approve_response = self.client.post(
@@ -83,8 +107,39 @@ def test_spine_loop_load_proofread_stage_and_export_evidence(self):
             approve_response.json()["workflow"]["stage"], "retraining_staged"
         )
 
+        launch_query_response = self.client.post(
+            f"/api/workflows/{workflow_id}/agent/query",
+            json={"query": "start training"},
+        )
+        self.assertEqual(launch_query_response.status_code, 200)
+        launch_query_payload = launch_query_response.json()
+        self.assertEqual(
+            launch_query_payload["actions"][0]["client_effects"]["runtime_action"][
+                "kind"
+            ],
+            "start_training",
+        )
+        training_effects = launch_query_payload["actions"][0]["client_effects"]
+        self.assertEqual(
+            training_effects["set_training_config_preset"],
+            "configs/MitoEM/Mito25-Local-BC.yaml",
+        )
+        self.assertEqual(
+            training_effects["set_training_image_path"],
+            "/projects/mito25/data/image/mito25_im.h5",
+        )
+        self.assertTrue(
+            training_effects["runtime_action"]["autopick_parameters"],
+        )
+        self.assertEqual(
+            launch_query_payload["actions"][0]["client_effects"]["navigate_to"],
+            "training",
+        )
+
         hotspots_response = self.client.get(f"/api/workflows/{workflow_id}/hotspots")
-        impact_response = self.client.get(f"/api/workflows/{workflow_id}/impact-preview")
+        impact_response = self.client.get(
+            f"/api/workflows/{workflow_id}/impact-preview"
+        )
         metrics_response = self.client.get(f"/api/workflows/{workflow_id}/metrics")
         bundle_response = self.client.post(
             f"/api/workflows/{workflow_id}/export-bundle"
diff --git a/tests/test_yixiao_pre_demo_smoke.py b/tests/test_yixiao_pre_demo_smoke.py
new file mode 100644
index 00000000..e4cfd471
--- /dev/null
+++ b/tests/test_yixiao_pre_demo_smoke.py
@@ -0,0 +1,326 @@
+from argparse import Namespace
+
+import pytest
+
+from scripts import run_yixiao_case_study_smoke as smoke
+
+
+def _fake_pre_demo_args(
+    tmp_path, *, skip_readiness_check=False, skip_export_check=False
+):
+    return Namespace(
+        base_url="http://127.0.0.1:4342",
+        project_root=str(tmp_path),
+        holdout_root=str(tmp_path / "holdout"),
+        workflow_id=None,
+        report=str(tmp_path / "pre-demo-gate.json"),
+        agent_timeout=10,
+        closed_loop_rehearsal=False,
+        closed_loop_crop="0:8,0:128,0:128",
+        closed_loop_training_iterations=2,
+        closed_loop_inference_iterations=1,
+        pre_demo_gate=True,
+        skip_readiness_check=skip_readiness_check,
+        skip_export_check=skip_export_check,
+        reset_fixture=False,
+        reset_workspace=True,
+        mount_project=True,
+        reset_workflow=True,
+        exercise_promotion=False,
+        prepare_live=True,
+        skip_agent=True,
+        verbose=False,
+    )
+
+
+def _setup_fake_run(monkeypatch):
+    calls = []
+
+    def fake_run(args):
+        calls.append(args.report)
+        if "baseline" in args.report:
+            return {
+                "workflow_id": 100,
+                "viewer_url": "https://demo.seg.bio/neuroglancer/v/base/",
+                "passed": True,
+            }
+        if "promotion" in args.report:
+            return {
+                "workflow_id": 100,
+                "viewer_url": "https://demo.seg.bio/neuroglancer/v/promo/",
+                "passed": True,
+            }
+        return {
+            "workflow_id": 101,
+            "viewer_url": "https://demo.seg.bio/neuroglancer/v/restore/",
+            "passed": True,
+        }
+
+    monkeypatch.setattr(smoke, "run", fake_run)
+    return calls
+
+
+def test_pre_demo_gate_reports_residual_readiness_caveat(monkeypatch, tmp_path):
+    _setup_fake_run(monkeypatch)
+
+    manifest_path = tmp_path / "bundle-manifest.json"
+    manifest_path.write_text("{}", encoding="utf-8")
+
+    def fake_request_json(self, method, path, payload=None, timeout=30):
+        if path.endswith("/case-study-readiness"):
+            return {
+                "workflow_id": 101,
+                "ready_for_case_study": False,
+                "completed_count": 1,
+                "total_count": 3,
+                "gates": [],
+                "next_required_items": ["before/after evaluation"],
+            }
+        if path.endswith("/export-bundle"):
+            return {
+                "schema_version": "workflow-export-bundle/v1",
+                "workflow_id": 101,
+                "events": [],
+                "artifacts": [],
+                "model_runs": [],
+                "model_versions": [],
+                "correction_sets": [],
+                "agent_plans": [],
+                "bundle_directory": str(tmp_path),
+                "bundle_manifest_path": str(manifest_path),
+            }
+        pytest.fail(f"unexpected path: {path}")
+
+    monkeypatch.setattr(smoke.SmokeHarness, "request_json", fake_request_json)
+    args = _fake_pre_demo_args(tmp_path)
+
+    report = smoke._build_pre_demo_gate_report(args)
+
+    assert report["passed"]
+    names = [step.get("name") for step in report["steps"]]
+    assert names == [
+        "normal_smoke",
+        "promotion_roundtrip",
+        "restore_state",
+        "readiness_check",
+        "export_sanity",
+    ]
+    assert len(report["caveats"]) == 1
+    assert report["caveats"][0].startswith("case-study readiness is not fully met")
+
+
+def test_pre_demo_gate_fails_when_export_payload_is_incomplete(monkeypatch, tmp_path):
+    _setup_fake_run(monkeypatch)
+
+    def fake_request_json(self, method, path, payload=None, timeout=30):
+        if path.endswith("/case-study-readiness"):
+            return {
+                "workflow_id": 101,
+                "ready_for_case_study": True,
+                "completed_count": 3,
+                "total_count": 3,
+                "gates": [],
+                "next_required_items": [],
+            }
+        if path.endswith("/export-bundle"):
+            return {
+                "schema_version": "workflow-export-bundle/v1",
+                "workflow_id": 101,
+            }
+        pytest.fail(f"unexpected path: {path}")
+
+    monkeypatch.setattr(smoke.SmokeHarness, "request_json", fake_request_json)
+    args = _fake_pre_demo_args(tmp_path)
+
+    report = smoke._build_pre_demo_gate_report(args)
+
+    assert not report["passed"]
+    export_step = next(
+        step for step in report["steps"] if step["name"] == "export_sanity"
+    )
+    assert not export_step["passed"]
+    assert "export payload missing required fields" in report["caveats"]
+
+
+def test_pre_demo_gate_records_readiness_and_export_check_failures_as_caveats(
+    monkeypatch, tmp_path
+):
+    _setup_fake_run(monkeypatch)
+
+    def fake_request_json(self, method, path, payload=None, timeout=30):
+        raise smoke.SmokeFailure(f"API unavailable for {path}")
+
+    monkeypatch.setattr(smoke.SmokeHarness, "request_json", fake_request_json)
+    args = _fake_pre_demo_args(tmp_path)
+
+    report = smoke._build_pre_demo_gate_report(args)
+
+    assert not report["passed"]
+    readiness_step = next(
+        step for step in report["steps"] if step["name"] == "readiness_check"
+    )
+    export_step = next(
+        step for step in report["steps"] if step["name"] == "export_sanity"
+    )
+    assert not readiness_step["passed"]
+    assert not export_step["passed"]
+    assert any("readiness check failed" in caveat for caveat in report["caveats"])
+    assert any("export sanity check failed" in caveat for caveat in report["caveats"])
+
+
+def test_closed_loop_rehearsal_uses_explicit_external_holdout_masks(
+    monkeypatch, tmp_path
+):
+    project_root = tmp_path / "project"
+    holdout_root = tmp_path / "holdout"
+    project_root.mkdir()
+    holdout_root.mkdir()
+    for target_id, raw_name in {
+        "6_1": "6_1-xri_raw.tif",
+        "6_2": "6_2-xri-raw.tif",
+    }.items():
+        raw_dir = project_root / "data" / "raw" / target_id
+        raw_dir.mkdir(parents=True)
+        (raw_dir / raw_name).write_text("raw", encoding="utf-8")
+        (holdout_root / f"{target_id}-mask.tif").write_text("mask", encoding="utf-8")
+
+    manifest = {
+        "volumes": [
+            {
+                "id": "6_1",
+                "status": "missing_segmentation",
+                "image": "data/raw/6_1/6_1-xri_raw.tif",
+                "segmentation": None,
+                "withheld_ground_truth": str(holdout_root / "6_1-mask.tif"),
+            },
+            {
+                "id": "6_2",
+                "status": "missing_segmentation",
+                "image": "data/raw/6_2/6_2-xri-raw.tif",
+                "segmentation": None,
+                "withheld_ground_truth": str(holdout_root / "6_2-mask.tif"),
+            },
+        ]
+    }
+    (project_root / "project_manifest.json").write_text(
+        smoke.json.dumps(manifest), encoding="utf-8"
+    )
+
+    calls = []
+
+    def fake_rehearsal_target(
+        *, output_dir, image_path, ground_truth_path, crop, **kwargs
+    ):
+        calls.append(
+            {
+                "output_dir": str(output_dir),
+                "image_path": str(image_path),
+                "ground_truth_path": str(ground_truth_path),
+                "crop": crop,
+            }
+        )
+        return {
+            "passed": True,
+            "artifact_mode": "real_pair_derived_predictions",
+            "runtime_overrides": {
+                "training_iterations": kwargs.get("training_iterations"),
+                "inference_iterations": kwargs.get("inference_iterations"),
+            },
+            "runtime_checkpoints": {
+                "checkpoint": "simulated-checkpoint.pth",
+                "training_run_checkpoint": "sim-checkpoint.pth",
+                "inference_run_checkpoint": "sim-inference-checkpoint.pth",
+                "model_version_checkpoint": "sim-model-version.pth",
+            },
+            "source_data": {
+                "image_path": str(image_path),
+                "mask_path": str(ground_truth_path),
+                "ground_truth_path": str(ground_truth_path),
+            },
+        }
+
+    monkeypatch.setattr(
+        smoke, "_run_closed_loop_rehearsal_target", fake_rehearsal_target
+    )
+    args = Namespace(
+        project_root=str(project_root),
+        holdout_root=str(holdout_root),
+        report=str(tmp_path / "closed-loop.json"),
+        closed_loop_crop="0:2,0:16,0:16",
+        closed_loop_training_iterations=7,
+        closed_loop_inference_iterations=5,
+    )
+
+    report = smoke._build_closed_loop_rehearsal_report(args)
+
+    assert report["passed"]
+    assert report["runtime_overrides"] == {
+        "training_iterations": 7,
+        "inference_iterations": 5,
+    }
+    assert [target["target_id"] for target in report["targets"]] == ["6_1", "6_2"]
+    assert len(calls) == 2
+    assert calls[0]["ground_truth_path"] == str(holdout_root / "6_1-mask.tif")
+    assert calls[1]["ground_truth_path"] == str(holdout_root / "6_2-mask.tif")
+    assert all("project/data/seg" not in call["ground_truth_path"] for call in calls)
+    assert report["targets"][0]["runtime_overrides"]["training_iterations"] == 7
+    assert report["targets"][0]["runtime_overrides"]["inference_iterations"] == 5
+
+
+def test_withheld_ground_truth_must_live_outside_project(monkeypatch, tmp_path):
+    project_root = tmp_path / "project"
+    holdout_root = tmp_path / "holdout"
+    project_root.mkdir()
+    holdout_root.mkdir()
+    raw_dir = project_root / "data" / "raw" / "6_1"
+    raw_dir.mkdir(parents=True)
+    (raw_dir / "6_1-xri_raw.tif").write_text("raw", encoding="utf-8")
+
+    seg_path = project_root / "data" / "seg" / "6_1-mask.tif"
+    seg_path.parent.mkdir(parents=True)
+    seg_path.write_text("seg", encoding="utf-8")
+
+    manifest = {
+        "volumes": [
+            {
+                "id": "6_1",
+                "status": "missing_segmentation",
+                "image": "data/raw/6_1/6_1-xri_raw.tif",
+                "segmentation": None,
+                "withheld_ground_truth": str(seg_path),
+            },
+            {
+                "id": "6_2",
+                "status": "missing_segmentation",
+                "image": "data/raw/6_1/6_1-xri_raw.tif",
+                "segmentation": None,
+                "withheld_ground_truth": str(holdout_root / "6_2-mask.tif"),
+            },
+        ]
+    }
+    (project_root / "project_manifest.json").write_text(
+        smoke.json.dumps(manifest), encoding="utf-8"
+    )
+    (holdout_root / "6_2-mask.tif").write_text("mask", encoding="utf-8")
+
+    def fake_rehearsal_target(*args, **kwargs):
+        return {}
+
+    monkeypatch.setattr(
+        smoke, "_run_closed_loop_rehearsal_target", fake_rehearsal_target
+    )
+
+    report = smoke._build_closed_loop_rehearsal_report(
+        Namespace(
+            project_root=str(project_root),
+            holdout_root=str(holdout_root),
+            report=str(tmp_path / "closed-loop.json"),
+            closed_loop_crop=None,
+            closed_loop_training_iterations=2,
+            closed_loop_inference_iterations=1,
+        )
+    )
+
+    assert not report["passed"]
+    assert report["targets"][0]["passed"] is False
+    assert "must live outside the mounted project root" in report["targets"][0]["error"]
diff --git a/uv.lock b/uv.lock
index 44b6b7d0..b6546c54 100644
--- a/uv.lock
+++ b/uv.lock
@@ -1,5 +1,5 @@
 version = 1
-revision = 3
+revision = 2
 requires-python = ">=3.10, <3.12"
 resolution-markers = [
     "python_full_version >= '3.11' and sys_platform == 'darwin'",
@@ -293,7 +293,7 @@ wheels = [
 
 [[package]]
 name = "black"
-version = "26.1.0"
+version = "26.5.1"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "click" },
@@ -305,19 +305,19 @@ dependencies = [
     { name = "tomli", marker = "python_full_version < '3.11'" },
     { name = "typing-extensions", marker = "python_full_version < '3.11'" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/13/88/560b11e521c522440af991d46848a2bde64b5f7202ec14e1f46f9509d328/black-26.1.0.tar.gz", hash = "sha256:d294ac3340eef9c9eb5d29288e96dc719ff269a88e27b396340459dd85da4c58", size = 658785, upload-time = "2026-01-18T04:50:11.993Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/c0/37/5628dd55bf2b34257fc7603f0fe97c40e3aaf24265f416a9c85c95ca1436/black-26.5.1.tar.gz", hash = "sha256:dd321f668053961824bcc1be1cc1df748b2d7e4fa28086b08331e577b0100a73", size = 679439, upload-time = "2026-05-18T16:53:36.107Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/51/1b/523329e713f965ad0ea2b7a047eeb003007792a0353622ac7a8cb2ee6fef/black-26.1.0-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:ca699710dece84e3ebf6e92ee15f5b8f72870ef984bf944a57a777a48357c168", size = 1849661, upload-time = "2026-01-18T04:59:12.425Z" },
-    { url = "https://files.pythonhosted.org/packages/14/82/94c0640f7285fa71c2f32879f23e609dd2aa39ba2641f395487f24a578e7/black-26.1.0-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:5e8e75dabb6eb83d064b0db46392b25cabb6e784ea624219736e8985a6b3675d", size = 1689065, upload-time = "2026-01-18T04:59:13.993Z" },
-    { url = "https://files.pythonhosted.org/packages/f0/78/474373cbd798f9291ed8f7107056e343fd39fef42de4a51c7fd0d360840c/black-26.1.0-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:eb07665d9a907a1a645ee41a0df8a25ffac8ad9c26cdb557b7b88eeeeec934e0", size = 1751502, upload-time = "2026-01-18T04:59:15.971Z" },
-    { url = "https://files.pythonhosted.org/packages/29/89/59d0e350123f97bc32c27c4d79563432d7f3530dca2bff64d855c178af8b/black-26.1.0-cp310-cp310-win_amd64.whl", hash = "sha256:7ed300200918147c963c87700ccf9966dceaefbbb7277450a8d646fc5646bf24", size = 1400102, upload-time = "2026-01-18T04:59:17.8Z" },
-    { url = "https://files.pythonhosted.org/packages/e1/bc/5d866c7ae1c9d67d308f83af5462ca7046760158bbf142502bad8f22b3a1/black-26.1.0-cp310-cp310-win_arm64.whl", hash = "sha256:c5b7713daea9bf943f79f8c3b46f361cc5229e0e604dcef6a8bb6d1c37d9df89", size = 1207038, upload-time = "2026-01-18T04:59:19.543Z" },
-    { url = "https://files.pythonhosted.org/packages/30/83/f05f22ff13756e1a8ce7891db517dbc06200796a16326258268f4658a745/black-26.1.0-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:3cee1487a9e4c640dc7467aaa543d6c0097c391dc8ac74eb313f2fbf9d7a7cb5", size = 1831956, upload-time = "2026-01-18T04:59:21.38Z" },
-    { url = "https://files.pythonhosted.org/packages/7d/f2/b2c570550e39bedc157715e43927360312d6dd677eed2cc149a802577491/black-26.1.0-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:d62d14ca31c92adf561ebb2e5f2741bf8dea28aef6deb400d49cca011d186c68", size = 1672499, upload-time = "2026-01-18T04:59:23.257Z" },
-    { url = "https://files.pythonhosted.org/packages/7a/d7/990d6a94dc9e169f61374b1c3d4f4dd3037e93c2cc12b6f3b12bc663aa7b/black-26.1.0-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:fb1dafbbaa3b1ee8b4550a84425aac8874e5f390200f5502cf3aee4a2acb2f14", size = 1735431, upload-time = "2026-01-18T04:59:24.729Z" },
-    { url = "https://files.pythonhosted.org/packages/36/1c/cbd7bae7dd3cb315dfe6eeca802bb56662cc92b89af272e014d98c1f2286/black-26.1.0-cp311-cp311-win_amd64.whl", hash = "sha256:101540cb2a77c680f4f80e628ae98bd2bd8812fb9d72ade4f8995c5ff019e82c", size = 1400468, upload-time = "2026-01-18T04:59:27.381Z" },
-    { url = "https://files.pythonhosted.org/packages/59/b1/9fe6132bb2d0d1f7094613320b56297a108ae19ecf3041d9678aec381b37/black-26.1.0-cp311-cp311-win_arm64.whl", hash = "sha256:6f3977a16e347f1b115662be07daa93137259c711e526402aa444d7a88fdc9d4", size = 1207332, upload-time = "2026-01-18T04:59:28.711Z" },
-    { url = "https://files.pythonhosted.org/packages/e4/3d/51bdb3ecbfadfaf825ec0c75e1de6077422b4afa2091c6c9ba34fbfc0c2d/black-26.1.0-py3-none-any.whl", hash = "sha256:1054e8e47ebd686e078c0bb0eaf31e6ce69c966058d122f2c0c950311f9f3ede", size = 204010, upload-time = "2026-01-18T04:50:09.978Z" },
+    { url = "https://files.pythonhosted.org/packages/be/84/b3f55026206a9e8820a91503308075ca48eadc515e436731ca01dbe043b3/black-26.5.1-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:9942db8888e06943c5dde66ca0037dcff82a2a4ec1ad0ada9e0d2ee9d9823893", size = 1987719, upload-time = "2026-05-18T17:05:02.757Z" },
+    { url = "https://files.pythonhosted.org/packages/c6/34/7db312c5e5783d6e76cffd9d5ac8972a32badae4c6e3288dac0eed8d3bed/black-26.5.1-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:89c93167a74d3a75dfaa38a5c7cca015537d5820dd7f17d63267d674a61cae90", size = 1810083, upload-time = "2026-05-18T17:05:04.302Z" },
+    { url = "https://files.pythonhosted.org/packages/33/e2/e0101e73c2c8727634e2efcb35e2b34bd23ad70dfa673789f5773a591b21/black-26.5.1-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:22f2cd76d069cc54c71f10360744ba8983fbb616903b4304a85b734915c8e1b4", size = 1860633, upload-time = "2026-05-18T17:05:06.391Z" },
+    { url = "https://files.pythonhosted.org/packages/b0/4c/e15c0c5b23cf3651035fe5addcce90e283af3548a3f91bb03d81b83106ab/black-26.5.1-cp310-cp310-win_amd64.whl", hash = "sha256:87ed5c6f450580a2f6790bc7cbfb016dfc73bc750249762268a3695361315eef", size = 1477886, upload-time = "2026-05-18T17:05:07.96Z" },
+    { url = "https://files.pythonhosted.org/packages/9f/3f/59d43ade98d2ce5c8dc34a4e46cbecd177e6d55d7d4092969c6003ccc655/black-26.5.1-cp310-cp310-win_arm64.whl", hash = "sha256:58b4bd92cf88aacf83d88479c8f9caee044b1ec55f2451a337354a7ea2590a22", size = 1277111, upload-time = "2026-05-18T17:05:09.473Z" },
+    { url = "https://files.pythonhosted.org/packages/4b/96/3c3e09f09f44a37aac36b178a279cd19aa7001bd796187a7b162a294c81f/black-26.5.1-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:96ae2c733b2aabdd9986e2c5df628ff3473676cd1c5faded1ff496cf6d74083c", size = 1970639, upload-time = "2026-05-18T17:05:11.461Z" },
+    { url = "https://files.pythonhosted.org/packages/83/ea/5ad117b9ee3ecd933c712bcbae610006e5b7cc9f41c526cd7ed3b6c4124c/black-26.5.1-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:0e48b87e03bf109288e55cfceadcfa15ff5470aca2851a851950ed2926f450d7", size = 1792130, upload-time = "2026-05-18T17:05:12.983Z" },
+    { url = "https://files.pythonhosted.org/packages/06/3a/7c448bc623fcdfa96672531beb5a616ea5e64f6975955254d7731ffb0ad9/black-26.5.1-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:5119fa92ae61f786e8c3662fd60aece1d0a2dd5cca5d0c79417a95e7a4272a59", size = 1846134, upload-time = "2026-05-18T17:05:14.506Z" },
+    { url = "https://files.pythonhosted.org/packages/a1/5b/0b39b3a5917f0657ac014ad2edb58c139553a478adfe7f817abf1622ff6e/black-26.5.1-cp311-cp311-win_amd64.whl", hash = "sha256:30d3c14661f2792e9142cce3eeeb1cbc175b3eb5f733be0c8eeb99651e52b0c3", size = 1478883, upload-time = "2026-05-18T17:05:16.542Z" },
+    { url = "https://files.pythonhosted.org/packages/4c/48/dc222692e0f95030db1bbfb6c857e76858bad09058221ea7aae815255327/black-26.5.1-cp311-cp311-win_arm64.whl", hash = "sha256:1ef92b76f7733f282fd096ea406200b5a286c42947412b0eaff3a74e3616cefe", size = 1277776, upload-time = "2026-05-18T17:05:18.029Z" },
+    { url = "https://files.pythonhosted.org/packages/94/51/f975cae76d44274cc2868dc9040ac5d58d464784610234455b4e7b19c6ef/black-26.5.1-py3-none-any.whl", hash = "sha256:4ed7f7da04046d2e488437170797d3b4a4ad83906683bcb7dfc68b673bbce5e2", size = 213693, upload-time = "2026-05-18T16:53:33.964Z" },
 ]
 
 [[package]]
@@ -1143,6 +1143,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/cb/bd/b394387b598ed84d8d0fa90611a90bee0adc2021820ad5729f7ced74a8e2/imageio-2.37.0-py3-none-any.whl", hash = "sha256:11efa15b87bc7871b61590326b2d635439acc321cf7f8ce996f812543ce10eed", size = 315796, upload-time = "2025-01-20T02:42:34.931Z" },
 ]
 
+[[package]]
+name = "iniconfig"
+version = "2.3.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/72/34/14ca021ce8e5dfedc35312d08ba8bf51fdd999c576889fc2c24cb97f4f10/iniconfig-2.3.0.tar.gz", hash = "sha256:c76315c77db068650d49c5b56314774a7804df16fee4402c1f19d6d15d8c4730", size = 20503, upload-time = "2025-10-18T21:55:43.219Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/cb/b1/3846dd7f199d53cb17f49cba7e651e9ce294d8497c8c150530ed11865bb8/iniconfig-2.3.0-py3-none-any.whl", hash = "sha256:f631c04d2c48c52b84d0d0549c99ff3859c98df65b3101406327ecc7d53fbf12", size = 7484, upload-time = "2025-10-18T21:55:41.639Z" },
+]
+
 [[package]]
 name = "ipykernel"
 version = "7.2.0"
@@ -2569,6 +2578,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/cb/28/3bfe2fa5a7b9c46fe7e13c97bda14c895fb10fa2ebf1d0abb90e0cea7ee1/platformdirs-4.5.1-py3-none-any.whl", hash = "sha256:d03afa3963c806a9bed9d5125c8f4cb2fdaf74a55ab60e5d59b3fde758104d31", size = 18731, upload-time = "2025-12-05T13:52:56.823Z" },
 ]
 
+[[package]]
+name = "pluggy"
+version = "1.6.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/f9/e2/3e91f31a7d2b083fe6ef3fa267035b518369d9511ffab804f839851d2779/pluggy-1.6.0.tar.gz", hash = "sha256:7dcc130b76258d33b90f61b658791dede3486c3e6bfb003ee5c9bfb396dd22f3", size = 69412, upload-time = "2025-05-15T12:30:07.975Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/54/20/4d324d65cc6d9205fabedc306948156824eb9f0ee1633355a8f7ec5c66bf/pluggy-1.6.0-py3-none-any.whl", hash = "sha256:e920276dd6813095e9377c0bc5566d94c932c33b27a3e3945d8389c374dd4746", size = 20538, upload-time = "2025-05-15T12:30:06.134Z" },
+]
+
 [[package]]
 name = "prometheus-client"
 version = "0.25.0"
@@ -2829,6 +2847,7 @@ dependencies = [
     { name = "langchain-classic" },
     { name = "langchain-community" },
     { name = "langchain-ollama" },
+    { name = "langgraph" },
     { name = "neuroglancer" },
     { name = "numpy" },
     { name = "opencv-python" },
@@ -2838,6 +2857,8 @@ dependencies = [
     { name = "python-jose" },
     { name = "python-multipart" },
     { name = "requests" },
+    { name = "scikit-image", version = "0.25.2", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
+    { name = "scikit-image", version = "0.26.0", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" },
     { name = "scipy", version = "1.15.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
     { name = "scipy", version = "1.17.0", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" },
     { name = "tensorboard" },
@@ -2854,6 +2875,7 @@ dependencies = [
 [package.dev-dependencies]
 dev = [
     { name = "black" },
+    { name = "pytest" },
 ]
 
 [package.metadata]
@@ -2869,6 +2891,7 @@ requires-dist = [
     { name = "langchain-classic", specifier = "==1.0.0" },
     { name = "langchain-community", specifier = "==0.4.1" },
     { name = "langchain-ollama", specifier = "==1.0.0" },
+    { name = "langgraph", specifier = ">=1.0.0" },
     { name = "neuroglancer", specifier = "==2.38" },
     { name = "numpy", specifier = ">=1.24,<2.0" },
     { name = "opencv-python", specifier = ">=4.11.0.86" },
@@ -2878,6 +2901,7 @@ requires-dist = [
     { name = "python-jose", specifier = ">=3.5.0" },
     { name = "python-multipart", specifier = "==0.0.20" },
     { name = "requests", specifier = ">=2.31" },
+    { name = "scikit-image", specifier = ">=0.25" },
     { name = "scipy", specifier = ">=1.11" },
     { name = "tensorboard", specifier = "==2.20.0" },
     { name = "tensorboard-data-server", specifier = "==0.7.2" },
@@ -2889,7 +2913,28 @@ requires-dist = [
 ]
 
 [package.metadata.requires-dev]
-dev = [{ name = "black", specifier = ">=26.1.0" }]
+dev = [
+    { name = "black", specifier = "==26.5.1" },
+    { name = "pytest", specifier = "==9.0.2" },
+]
+
+[[package]]
+name = "pytest"
+version = "9.0.2"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "colorama", marker = "sys_platform == 'win32'" },
+    { name = "exceptiongroup", marker = "python_full_version < '3.11'" },
+    { name = "iniconfig" },
+    { name = "packaging" },
+    { name = "pluggy" },
+    { name = "pygments" },
+    { name = "tomli", marker = "python_full_version < '3.11'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/d1/db/7ef3487e0fb0049ddb5ce41d3a49c235bf9ad299b6a25d5780a89f19230f/pytest-9.0.2.tar.gz", hash = "sha256:75186651a92bd89611d1d9fc20f0b4345fd827c41ccd5c299a868a05d70edf11", size = 1568901, upload-time = "2025-12-06T21:30:51.014Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/3b/ab/b3226f0bd7cdcf710fbede2b3548584366da3b19b5021e74f5bde2a8fa3f/pytest-9.0.2-py3-none-any.whl", hash = "sha256:711ffd45bf766d5264d487b917733b453d917afd2b0ad65223959f59089f875b", size = 374801, upload-time = "2025-12-06T21:30:49.154Z" },
+]
 
 [[package]]
 name = "python-dateutil"