diff --git a/.github/workflows/desktop-release.yml b/.github/workflows/desktop-release.yml
index 3ad529671..7955adcbe 100644
--- a/.github/workflows/desktop-release.yml
+++ b/.github/workflows/desktop-release.yml
@@ -75,6 +75,21 @@ jobs:
             echo "Windows signing: skipped"
           fi
 
+      - name: Verify Apple notarization credentials
+        if: matrix.os == 'macos-latest'
+        shell: bash
+        # Fails in seconds with the same 401 notarytool would throw after the
+        # full build, instead of wasting ~15 min of build time on bad secrets.
+        run: |
+          xcrun notarytool history \
+            --apple-id "$APPLE_ID" \
+            --password "$APPLE_APP_SPECIFIC_PASSWORD" \
+            --team-id "$APPLE_TEAM_ID" > /dev/null
+        env:
+          APPLE_ID: ${{ secrets.APPLE_ID }}
+          APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
+          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+
       - name: Setup pnpm
         uses: pnpm/action-setup@v5
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 493f24c02..1998bd74e 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -79,7 +79,7 @@ We follow a **branch protection model** to keep `main` stable:
    ```
 
 3. **Choose your setup method**:
-   - **Docker Setup**: Follow the [Docker Setup Guide](./DOCKER_SETUP.md)
+   - **Docker Setup**: Follow the [Building from Source (Contributors)](https://www.surfsense.com/docs/docker-installation#building-from-source-contributors) section of the Docker Installation guide
    - **Manual Setup**: Follow the [Installation Guide](https://www.surfsense.com/docs/)
 
 4. **Configure services**:
diff --git a/README.es.md b/README.es.md
index 70ccd5eb1..08231b5ab 100644
--- a/README.es.md
+++ b/README.es.md
@@ -20,9 +20,9 @@
 <a href="https://trendshift.io/repositories/13606" target="_blank"><img src="https://trendshift.io/api/badge/repositories/13606" alt="MODSetter%2FSurfSense | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
 </div>
 
-# SurfSense: Dale inteligencia competitiva a tus agentes de IA
+# SurfSense: NotebookLM para investigación de inteligencia competitiva
 
-SurfSense es la **plataforma de inteligencia competitiva de código abierto para agentes de IA**. Tus agentes monitorean a la competencia, siguen los rankings y escuchan a tu mercado con datos en vivo de **Reddit, YouTube, Google Maps, Google Search y la web abierta**, a través de una única **API REST** o un **servidor MCP**. Agentes programados y activados por eventos convierten lo que encuentran en informes y alertas, y una base de conocimiento integrada mantiene cada hallazgo disponible para búsqueda con citas.
+SurfSense es la **plataforma de inteligencia competitiva de código abierto para agentes de IA**, como NotebookLM pero con conectores de scraping en vivo. Tus agentes monitorean a la competencia, siguen los rankings y escuchan a tu mercado con datos en vivo de **Reddit, YouTube, Instagram, TikTok, Google Maps, Google Search y la web abierta**, a través de una única **API REST** o un **servidor MCP**. Agentes programados y activados por eventos convierten lo que encuentran en informes y alertas, y una base de conocimiento integrada mantiene cada hallazgo disponible para búsqueda con citas.
 
 > [!NOTE]
 > **📢 Una nota para nuestros usuarios de la alternativa a NotebookLM**
@@ -103,6 +103,8 @@ Las automatizaciones ejecutan turnos completos de agente según un horario o en
 |---|---|---|
 | **Reddit** | Publicaciones, comentarios y flujos de subreddits sin los límites de tasa de la API oficial | [Reddit Scraper API](https://www.surfsense.com/reddit) |
 | **YouTube** | Videos, transcripciones e hilos de comentarios para escuchar a tu marca y productos | [YouTube Scraper API](https://www.surfsense.com/youtube) |
+| **Instagram** | Perfiles, publicaciones y reels públicos sin la Graph API | [Instagram Scraper API](https://www.surfsense.com/instagram) |
+| **TikTok** | Videos, comentarios, hashtags y perfiles sin aprobación de la Research API | [TikTok Scraper API](https://www.surfsense.com/tiktok) |
 | **Google Maps** | Lugares, calificaciones y reseñas para investigar competidores locales y prospectos | [Google Maps Scraper API](https://www.surfsense.com/google-maps) |
 | **Google Search** | SERPs en vivo para seguimiento de posiciones y monitoreo de mercado | [Google Search API](https://www.surfsense.com/google-search) |
 | **Web Crawl** (rastreo web) | Cualquier página de la web abierta como contenido limpio y estructurado | [Web Crawling API](https://www.surfsense.com/web-crawl) |
@@ -244,7 +246,7 @@ https://github.com/user-attachments/assets/a0a16566-6967-4374-ac51-9b3e07fbecd7
 
 | Característica | Google NotebookLM | SurfSense |
 |---------|-------------------|-----------|
-| **Datos de mercado en vivo para agentes** | No | Conectores de Reddit, YouTube, Google Maps, Google Search y rastreo web vía API REST y MCP |
+| **Datos de mercado en vivo para agentes** | No | Conectores de Reddit, YouTube, Instagram, TikTok, Google Maps, Google Search y rastreo web vía API REST y MCP |
 | **Servidor MCP** | No | Cada conector expuesto como herramienta nativa de agente, más servidores MCP propios con aplicaciones OAuth de un clic |
 | **Fuentes por Notebook** | 50 (gratis) a 600 (Ultra, $249.99/mes) | Ilimitadas |
 | **Número de Notebooks** | 100 (gratis) a 500 (niveles de pago) | Ilimitado |
diff --git a/README.hi.md b/README.hi.md
index cbf9ae8fa..eb65ff489 100644
--- a/README.hi.md
+++ b/README.hi.md
@@ -20,9 +20,9 @@
 <a href="https://trendshift.io/repositories/13606" target="_blank"><img src="https://trendshift.io/api/badge/repositories/13606" alt="MODSetter%2FSurfSense | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
 </div>
 
-# SurfSense: अपने AI एजेंट्स को दें कॉम्पिटिटिव इंटेलिजेंस
+# SurfSense: कॉम्पिटिटिव इंटेलिजेंस रिसर्च के लिए NotebookLM
 
-SurfSense **AI एजेंट्स के लिए ओपन सोर्स कॉम्पिटिटिव इंटेलिजेंस प्लेटफ़ॉर्म** है। आपके एजेंट प्रतिस्पर्धियों पर नज़र रखते हैं, रैंकिंग ट्रैक करते हैं, और **Reddit, YouTube, Google Maps, Google Search और ओपन वेब** से लाइव डेटा के साथ आपके बाज़ार की बात सुनते हैं, वह भी एक ही **REST API** या **MCP सर्वर** के ज़रिए। शेड्यूल्ड और इवेंट-ट्रिगर्ड एजेंट अपनी खोजों को ब्रीफ़ और अलर्ट में बदलते हैं, और एक बिल्ट-इन नॉलेज बेस हर खोज को साइटेशन के साथ खोजने योग्य बनाए रखता है।
+SurfSense **AI एजेंट्स के लिए ओपन सोर्स कॉम्पिटिटिव इंटेलिजेंस प्लेटफ़ॉर्म** है, बिलकुल NotebookLM जैसा, पर लाइव स्क्रैपिंग कनेक्टर्स के साथ। आपके एजेंट प्रतिस्पर्धियों पर नज़र रखते हैं, रैंकिंग ट्रैक करते हैं, और **Reddit, YouTube, Instagram, TikTok, Google Maps, Google Search और ओपन वेब** से लाइव डेटा के साथ आपके बाज़ार की बात सुनते हैं, वह भी एक ही **REST API** या **MCP सर्वर** के ज़रिए। शेड्यूल्ड और इवेंट-ट्रिगर्ड एजेंट अपनी खोजों को ब्रीफ़ और अलर्ट में बदलते हैं, और एक बिल्ट-इन नॉलेज बेस हर खोज को साइटेशन के साथ खोजने योग्य बनाए रखता है।
 
 > [!NOTE]
 > **📢 हमारे NotebookLM-विकल्प उपयोगकर्ताओं के लिए एक सूचना**
@@ -103,6 +103,8 @@ SurfSense **AI एजेंट्स के लिए ओपन सोर्स
 |---|---|---|
 | **Reddit** | आधिकारिक API की रेट लिमिट के बिना पोस्ट, कमेंट और सबरेडिट स्ट्रीम | [Reddit Scraper API](https://www.surfsense.com/reddit) |
 | **YouTube** | ब्रांड और प्रोडक्ट लिसनिंग के लिए वीडियो, ट्रांसक्रिप्ट और कमेंट थ्रेड | [YouTube Scraper API](https://www.surfsense.com/youtube) |
+| **Instagram** | Graph API के बिना सार्वजनिक प्रोफ़ाइल, पोस्ट और रील्स | [Instagram Scraper API](https://www.surfsense.com/instagram) |
+| **TikTok** | Research API अप्रूवल के बिना वीडियो, कमेंट, हैशटैग और प्रोफ़ाइल | [TikTok Scraper API](https://www.surfsense.com/tiktok) |
 | **Google Maps** | स्थानीय प्रतिस्पर्धी और लीड रिसर्च के लिए स्थान, रेटिंग और रिव्यू | [Google Maps Scraper API](https://www.surfsense.com/google-maps) |
 | **Google Search** | रैंक ट्रैकिंग और मार्केट मॉनिटरिंग के लिए लाइव SERP | [Google Search API](https://www.surfsense.com/google-search) |
 | **Web Crawl** | ओपन वेब का कोई भी पेज साफ़-सुथरे, स्ट्रक्चर्ड कंटेंट के रूप में | [Web Crawling API](https://www.surfsense.com/web-crawl) |
@@ -244,7 +246,7 @@ https://github.com/user-attachments/assets/a0a16566-6967-4374-ac51-9b3e07fbecd7
 
 | फ़ीचर | Google NotebookLM | SurfSense |
 |---------|-------------------|-----------|
-| **एजेंट्स के लिए लाइव मार्केट डेटा** | नहीं | REST API और MCP के ज़रिए Reddit, YouTube, Google Maps, Google Search और वेब क्रॉल कनेक्टर |
+| **एजेंट्स के लिए लाइव मार्केट डेटा** | नहीं | REST API और MCP के ज़रिए Reddit, YouTube, Instagram, TikTok, Google Maps, Google Search और वेब क्रॉल कनेक्टर |
 | **MCP सर्वर** | नहीं | हर कनेक्टर नेटिव एजेंट टूल के रूप में उपलब्ध, साथ ही वन-क्लिक OAuth ऐप्स के साथ अपने MCP सर्वर लाने की सुविधा |
 | **प्रति नोटबुक स्रोत** | 50 (Free) से 600 (Ultra, $249.99/माह) | असीमित |
 | **नोटबुक की संख्या** | 100 (Free) से 500 (सशुल्क टियर) | असीमित |
diff --git a/README.md b/README.md
index 8f2e65118..ba289ada4 100644
--- a/README.md
+++ b/README.md
@@ -20,9 +20,9 @@
 <a href="https://trendshift.io/repositories/13606" target="_blank"><img src="https://trendshift.io/api/badge/repositories/13606" alt="MODSetter%2FSurfSense | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
 </div>
 
-# SurfSense: Give Your AI Agents Competitive Intelligence
+# SurfSense: NotebookLM for Competitive Intelligence Research
 
-SurfSense is the **open-source competitive intelligence platform for AI agents**. Your agents monitor competitors, track rankings, and listen to your market with live data from **Reddit, YouTube, Google Maps, Google Search, and the open web**, through one **REST API** or **MCP server**. Scheduled and event-triggered agents turn what they find into briefs and alerts, and a built-in knowledge base keeps every finding searchable with citations.
+SurfSense is the **open-source competitive intelligence platform for AI agents**, like NotebookLM but with live scraping connectors. Your agents monitor competitors, track rankings, and listen to your market with live data from **Reddit, YouTube, Instagram, TikTok, Google Maps, Google Search, and the open web**, through one **REST API** or **MCP server**. Scheduled and event-triggered agents turn what they find into briefs and alerts, and a built-in knowledge base keeps every finding searchable with citations.
 
 > [!NOTE]
 > **📢 A note for our NotebookLM-alternative users**
@@ -103,6 +103,8 @@ Automations run full agent turns on a schedule or in response to events, then wr
 |---|---|---|
 | **Reddit** | Posts, comments, and subreddit streams without the official API's rate limits | [Reddit Scraper API](https://www.surfsense.com/reddit) |
 | **YouTube** | Videos, transcripts, and comment threads for brand and product listening | [YouTube Scraper API](https://www.surfsense.com/youtube) |
+| **Instagram** | Public profiles, posts, and reels without the Graph API | [Instagram Scraper API](https://www.surfsense.com/instagram) |
+| **TikTok** | Videos, comments, hashtags, and profiles without Research API approval | [TikTok Scraper API](https://www.surfsense.com/tiktok) |
 | **Google Maps** | Places, ratings, and reviews for local competitor and lead research | [Google Maps Scraper API](https://www.surfsense.com/google-maps) |
 | **Google Search** | Live SERPs for rank tracking and market monitoring | [Google Search API](https://www.surfsense.com/google-search) |
 | **Web Crawl** | Any page on the open web as clean, structured content | [Web Crawling API](https://www.surfsense.com/web-crawl) |
@@ -243,7 +245,7 @@ Still comparing us as a NotebookLM alternative? Here is the honest breakdown.
 
 | Feature | Google NotebookLM | SurfSense |
 |---------|-------------------|-----------|
-| **Live market data for agents** | No | Reddit, YouTube, Google Maps, Google Search, and web crawl connectors via REST API and MCP |
+| **Live market data for agents** | No | Reddit, YouTube, Instagram, TikTok, Google Maps, Google Search, and web crawl connectors via REST API and MCP |
 | **MCP server** | No | Every connector exposed as a native agent tool, plus bring-your-own MCP servers with one-click OAuth apps |
 | **Sources per Notebook** | 50 (Free) to 600 (Ultra, $249.99/mo) | Unlimited |
 | **Number of Notebooks** | 100 (Free) to 500 (paid tiers) | Unlimited |
diff --git a/README.pt-BR.md b/README.pt-BR.md
index 076736bcf..327e3373c 100644
--- a/README.pt-BR.md
+++ b/README.pt-BR.md
@@ -20,9 +20,9 @@
 <a href="https://trendshift.io/repositories/13606" target="_blank"><img src="https://trendshift.io/api/badge/repositories/13606" alt="MODSetter%2FSurfSense | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
 </div>
 
-# SurfSense: Dê Inteligência Competitiva aos Seus Agentes de IA
+# SurfSense: NotebookLM para Pesquisa de Inteligência Competitiva
 
-O SurfSense é a **plataforma open source de inteligência competitiva para agentes de IA**. Seus agentes monitoram concorrentes, acompanham rankings e escutam o seu mercado com dados ao vivo do **Reddit, YouTube, Google Maps, Google Search e da web aberta**, por meio de uma única **API REST** ou de um **servidor MCP**. Agentes agendados ou acionados por eventos transformam o que encontram em relatórios e alertas, e uma base de conhecimento integrada mantém cada descoberta pesquisável, com citações.
+O SurfSense é a **plataforma open source de inteligência competitiva para agentes de IA**, como o NotebookLM, mas com conectores de scraping ao vivo. Seus agentes monitoram concorrentes, acompanham rankings e escutam o seu mercado com dados ao vivo do **Reddit, YouTube, Instagram, TikTok, Google Maps, Google Search e da web aberta**, por meio de uma única **API REST** ou de um **servidor MCP**. Agentes agendados ou acionados por eventos transformam o que encontram em relatórios e alertas, e uma base de conhecimento integrada mantém cada descoberta pesquisável, com citações.
 
 > [!NOTE]
 > **📢 Um recado para nossos usuários que buscavam uma alternativa ao NotebookLM**
@@ -103,6 +103,8 @@ As automações executam turnos completos de agente de forma agendada ou em resp
 |---|---|---|
 | **Reddit** | Posts, comentários e fluxos de subreddits sem os limites de requisição da API oficial | [Reddit Scraper API](https://www.surfsense.com/reddit) |
 | **YouTube** | Vídeos, transcrições e threads de comentários para monitoramento de marca e produto | [YouTube Scraper API](https://www.surfsense.com/youtube) |
+| **Instagram** | Perfis, posts e reels públicos sem a Graph API | [Instagram Scraper API](https://www.surfsense.com/instagram) |
+| **TikTok** | Vídeos, comentários, hashtags e perfis sem aprovação da Research API | [TikTok Scraper API](https://www.surfsense.com/tiktok) |
 | **Google Maps** | Estabelecimentos, avaliações e reviews para pesquisa local de concorrentes e leads | [Google Maps Scraper API](https://www.surfsense.com/google-maps) |
 | **Google Search** | SERPs ao vivo para acompanhamento de rankings e monitoramento de mercado | [Google Search API](https://www.surfsense.com/google-search) |
 | **Web Crawl** (rastreamento web) | Qualquer página da web aberta como conteúdo limpo e estruturado | [Web Crawling API](https://www.surfsense.com/web-crawl) |
@@ -244,7 +246,7 @@ Ainda nos comparando como alternativa ao NotebookLM? Aqui está o comparativo ho
 
 | Recurso | Google NotebookLM | SurfSense |
 |---------|-------------------|-----------|
-| **Dados de mercado ao vivo para agentes** | Não | Conectores de Reddit, YouTube, Google Maps, Google Search e rastreamento web via API REST e MCP |
+| **Dados de mercado ao vivo para agentes** | Não | Conectores de Reddit, YouTube, Instagram, TikTok, Google Maps, Google Search e rastreamento web via API REST e MCP |
 | **Servidor MCP** | Não | Cada conector exposto como ferramenta nativa de agente, além de servidores MCP próprios com apps OAuth em um clique |
 | **Fontes por Notebook** | 50 (gratuito) a 600 (Ultra, US$ 249,99/mês) | Ilimitadas |
 | **Número de Notebooks** | 100 (gratuito) a 500 (planos pagos) | Ilimitado |
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 7d2ae35c3..53a95968b 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -20,9 +20,9 @@
 <a href="https://trendshift.io/repositories/13606" target="_blank"><img src="https://trendshift.io/api/badge/repositories/13606" alt="MODSetter%2FSurfSense | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
 </div>
 
-# SurfSense：为你的 AI 智能体注入竞争情报能力
+# SurfSense：面向竞争情报研究的 NotebookLM
 
-SurfSense 是**面向 AI 智能体的开源竞争情报平台**。你的智能体可以通过一个 **REST API** 或 **MCP 服务器**，利用来自 **Reddit、YouTube、Google Maps、Google Search 和开放网络**的实时数据，监控竞争对手、追踪排名、倾听市场动态。定时和事件触发的智能体会把发现的内容转化为简报和预警，内置的知识库则让每一条发现都可搜索、可引用。
+SurfSense 是**面向 AI 智能体的开源竞争情报平台**，就像 NotebookLM，但配备了实时抓取连接器。你的智能体可以通过一个 **REST API** 或 **MCP 服务器**，利用来自 **Reddit、YouTube、Instagram、TikTok、Google Maps、Google Search 和开放网络**的实时数据，监控竞争对手、追踪排名、倾听市场动态。定时和事件触发的智能体会把发现的内容转化为简报和预警，内置的知识库则让每一条发现都可搜索、可引用。
 
 > [!NOTE]
 > **📢 致我们的 NotebookLM 替代品用户**
@@ -103,6 +103,8 @@ SurfSense 是**面向 AI 智能体的开源竞争情报平台**。你的智能
 |---|---|---|
 | **Reddit** | 帖子、评论和子版块信息流，不受官方 API 速率限制 | [Reddit Scraper API](https://www.surfsense.com/reddit) |
 | **YouTube** | 视频、字幕转录和评论串，用于品牌和产品舆情监听 | [YouTube Scraper API](https://www.surfsense.com/youtube) |
+| **Instagram** | 公开主页、帖子和 Reels，无需 Graph API | [Instagram Scraper API](https://www.surfsense.com/instagram) |
+| **TikTok** | 视频、评论、话题标签和主页，无需 Research API 审批 | [TikTok Scraper API](https://www.surfsense.com/tiktok) |
 | **Google Maps** | 地点、评分和评论，用于本地竞争对手和潜在客户调研 | [Google Maps Scraper API](https://www.surfsense.com/google-maps) |
 | **Google Search** | 实时搜索结果页，用于排名追踪和市场监控 | [Google Search API](https://www.surfsense.com/google-search) |
 | **Web Crawl** | 把开放网络上的任意页面转为干净、结构化的内容 | [Web Crawling API](https://www.surfsense.com/web-crawl) |
@@ -244,7 +246,7 @@ https://github.com/user-attachments/assets/a0a16566-6967-4374-ac51-9b3e07fbecd7
 
 | 功能 | Google NotebookLM | SurfSense |
 |---------|-------------------|-----------|
-| **面向智能体的实时市场数据** | 无 | 通过 REST API 和 MCP 提供 Reddit、YouTube、Google Maps、Google Search 和网页爬取连接器 |
+| **面向智能体的实时市场数据** | 无 | 通过 REST API 和 MCP 提供 Reddit、YouTube、Instagram、TikTok、Google Maps、Google Search 和网页爬取连接器 |
 | **MCP 服务器** | 无 | 每个连接器都作为原生智能体工具暴露，还可自带 MCP 服务器并使用一键 OAuth 应用 |
 | **每个笔记本的来源数** | 50 个（免费版）至 600 个（Ultra 版，249.99 美元/月） | 无限制 |
 | **笔记本数量** | 100 个（免费版）至 500 个（付费档位） | 无限制 |
diff --git a/VERSION b/VERSION
index d788d4335..78bae5bb6 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-0.0.31
+0.0.32
diff --git a/surfsense_backend/.env.example b/surfsense_backend/.env.example
index 2c0cf38ff..3d2355460 100644
--- a/surfsense_backend/.env.example
+++ b/surfsense_backend/.env.example
@@ -120,8 +120,10 @@ STRIPE_RECONCILIATION_BATCH_SIZE=100
 # BACKEND_URL=https://api.yourdomain.com
 
 # Auth
-AUTH_TYPE=GOOGLE or LOCAL
-REGISTRATION_ENABLED=TRUE or FALSE
+# AUTH_TYPE: GOOGLE or LOCAL
+AUTH_TYPE=LOCAL
+# REGISTRATION_ENABLED: TRUE or FALSE
+REGISTRATION_ENABLED=TRUE
 # For Google Auth Only
 GOOGLE_OAUTH_CLIENT_ID=924507538m
 GOOGLE_OAUTH_CLIENT_SECRET=GOCSV
diff --git a/surfsense_backend/app/agents/chat/multi_agent_chat/subagents/builtins/instagram/system_prompt.md b/surfsense_backend/app/agents/chat/multi_agent_chat/subagents/builtins/instagram/system_prompt.md
index 42713cc38..ce9182771 100644
--- a/surfsense_backend/app/agents/chat/multi_agent_chat/subagents/builtins/instagram/system_prompt.md
+++ b/surfsense_backend/app/agents/chat/multi_agent_chat/subagents/builtins/instagram/system_prompt.md
@@ -13,7 +13,7 @@ Answer the delegated question from live Instagram data gathered with your verbs,
 
 <playbook>
 - Known profile/post/reel links: call `instagram_scrape` with the links in `urls` (use `result_type` to pick posts or reels). Hashtag/place URLs are unsupported (login-walled).
-- Finding a profile on a topic: call `instagram_scrape` with `search_queries` (resolved to public profiles via Google; `search_type` is profile-only).
+- Finding a profile on a topic: call `instagram_scrape` with `search_queries` (resolved to public profiles via Google; `search_type` is profile-only). Google-backed discovery is slow (~30-60s per query), so start with **at most 3** distinct queries per task and only add more if the first round returns nothing significant — never batch many phrasing variants of the same intent.
 - Profile metadata (follower counts, bio, post count): call `instagram_details`.
 - Batch multiple URLs (or queries) into one call rather than many single-item calls.
 <include snippet="run_reader"/>
diff --git a/surfsense_backend/app/agents/chat/multi_agent_chat/subagents/builtins/tiktok/system_prompt.md b/surfsense_backend/app/agents/chat/multi_agent_chat/subagents/builtins/tiktok/system_prompt.md
index 03114cd12..cd0b05e0e 100644
--- a/surfsense_backend/app/agents/chat/multi_agent_chat/subagents/builtins/tiktok/system_prompt.md
+++ b/surfsense_backend/app/agents/chat/multi_agent_chat/subagents/builtins/tiktok/system_prompt.md
@@ -14,11 +14,11 @@ Answer the delegated question from live TikTok data gathered with your verb, com
 </available_tools>
 
 <playbook>
-- Finding videos on a topic: call `tiktok_scrape` with `hashtags` (no leading '#'), or pass a TikTok URL in `urls`.
+- Finding videos on a topic: call `tiktok_scrape` with `hashtags` (no leading '#'), or pass a TikTok URL in `urls`. There is no keyword-video search — use hashtags or a video URL.
 - Scraping a specific video, profile, hashtag, or search page: pass its TikTok URL in `urls`.
 - Profiles: a creator's `profiles` feed returns the account's metadata (name, followers, bio, verification) reliably, but its video list is often withheld by TikTok — treat an empty video list as a known limit, not a failure to retry endlessly. Prefer `hashtags` or a direct video URL for videos.
 - Comments on a video: call `tiktok_comments` with the video URL(s) in `video_urls`.
-- Finding accounts by keyword: call `tiktok_user_search` with `queries`. Keyword search returns no videos, so do not use `search_queries` for videos — use `hashtags` or a video URL.
+- Finding accounts by keyword: call `tiktok_user_search` with `queries` — that is the path for accounts.
 - "What's trending now": call `tiktok_trending` (no query needed); set `max_items` for how many.
 - Controlling volume: use `max_items` for the total cap and `results_per_page` per target (per-verb equivalents: `comments_per_video`, `results_per_query`).
 - Requested counts: `max_items` defaults low — when the task asks for N items, set `max_items` (and the per-target count) above N. A call that caps below the target can never satisfy it.
diff --git a/surfsense_backend/app/capabilities/instagram/details/schemas.py b/surfsense_backend/app/capabilities/instagram/details/schemas.py
index 1372f881f..8ec21335b 100644
--- a/surfsense_backend/app/capabilities/instagram/details/schemas.py
+++ b/surfsense_backend/app/capabilities/instagram/details/schemas.py
@@ -54,9 +54,7 @@ class DetailsInput(BaseModel):
     @model_validator(mode="after")
     def _exactly_one_source(self) -> DetailsInput:
         if not self.urls and not self.search_queries:
-            raise ValueError(
-                "Provide at least one of 'urls' or 'search_queries'."
-            )
+            raise ValueError("Provide at least one of 'urls' or 'search_queries'.")
         if self.urls and self.search_queries:
             raise ValueError(
                 "Provide 'urls' OR 'search_queries', not both (they cannot be combined)."
diff --git a/surfsense_backend/app/capabilities/instagram/scrape/schemas.py b/surfsense_backend/app/capabilities/instagram/scrape/schemas.py
index f30078d9b..bfb95cfac 100644
--- a/surfsense_backend/app/capabilities/instagram/scrape/schemas.py
+++ b/surfsense_backend/app/capabilities/instagram/scrape/schemas.py
@@ -77,9 +77,7 @@ class ScrapeInput(BaseModel):
     @model_validator(mode="after")
     def _exactly_one_source(self) -> ScrapeInput:
         if not self.urls and not self.search_queries:
-            raise ValueError(
-                "Provide at least one of 'urls' or 'search_queries'."
-            )
+            raise ValueError("Provide at least one of 'urls' or 'search_queries'.")
         if self.urls and self.search_queries:
             raise ValueError(
                 "Provide 'urls' OR 'search_queries', not both (they cannot be combined)."
diff --git a/surfsense_backend/app/capabilities/tiktok/scrape/definition.py b/surfsense_backend/app/capabilities/tiktok/scrape/definition.py
index 9f8632f3b..72bc16ace 100644
--- a/surfsense_backend/app/capabilities/tiktok/scrape/definition.py
+++ b/surfsense_backend/app/capabilities/tiktok/scrape/definition.py
@@ -10,8 +10,8 @@ from app.capabilities.tiktok.scrape.schemas import ScrapeInput, ScrapeOutput
 TIKTOK_SCRAPE = Capability(
     name="tiktok.scrape",
     description=(
-        "Scrape public TikTok videos. Use urls, profiles, hashtags, or "
-        "search_queries."
+        "Scrape public TikTok videos. Use urls, profiles, or hashtags. To find "
+        "accounts by keyword, use tiktok.user_search."
     ),
     input_schema=ScrapeInput,
     output_schema=ScrapeOutput,
diff --git a/surfsense_backend/app/capabilities/tiktok/scrape/executor.py b/surfsense_backend/app/capabilities/tiktok/scrape/executor.py
index 7ef71486d..8ce1d5be5 100644
--- a/surfsense_backend/app/capabilities/tiktok/scrape/executor.py
+++ b/surfsense_backend/app/capabilities/tiktok/scrape/executor.py
@@ -26,7 +26,6 @@ def build_scrape_executor(scrape_fn: ScrapeFn | None = None) -> Executor:
             startUrls=[{"url": url} for url in payload.urls],
             profiles=payload.profiles,
             hashtags=payload.hashtags,
-            searchQueries=payload.search_queries,
             resultsPerPage=payload.results_per_page,
         )
         emit_progress(
diff --git a/surfsense_backend/app/capabilities/tiktok/scrape/schemas.py b/surfsense_backend/app/capabilities/tiktok/scrape/schemas.py
index 2f5005353..ac3792712 100644
--- a/surfsense_backend/app/capabilities/tiktok/scrape/schemas.py
+++ b/surfsense_backend/app/capabilities/tiktok/scrape/schemas.py
@@ -4,7 +4,8 @@ A lean, agent-friendly surface over ``TikTokScrapeInput``
 (``app/proprietary/platforms/tiktok``). The executor maps this to the full
 scraper input; the scraper's ``TikTokVideoItem`` is reused verbatim as the
 output element. Any TikTok URL kind (video, profile, hashtag, search) goes in
-``urls``; ``profiles``/``hashtags``/``search_queries`` are typed shortcuts.
+``urls``; ``profiles``/``hashtags`` are typed shortcuts. Keyword search is not a
+video source here — use ``tiktok.user_search`` to find accounts by keyword.
 """
 
 from __future__ import annotations
@@ -26,8 +27,8 @@ class ScrapeInput(BaseModel):
         max_length=MAX_TIKTOK_SOURCES,
         description=(
             "TikTok URLs to scrape: a video, a profile (/@<user>), a hashtag "
-            "(/tag/<name>), or a search URL. Provide these OR profiles/hashtags/"
-            "search_queries (at least one source is required)."
+            "(/tag/<name>), or a search URL. Provide these OR profiles/hashtags "
+            "(at least one source is required)."
         ),
     )
     profiles: list[str] = Field(
@@ -40,16 +41,11 @@ class ScrapeInput(BaseModel):
         max_length=MAX_TIKTOK_SOURCES,
         description="Hashtag names to scrape, without the leading '#'.",
     )
-    search_queries: list[str] = Field(
-        default_factory=list,
-        max_length=MAX_TIKTOK_SOURCES,
-        description="Search terms to run on TikTok.",
-    )
     results_per_page: int = Field(
         default=10,
         ge=1,
         le=MAX_TIKTOK_ITEMS,
-        description="Max videos to pull per profile/hashtag/search target.",
+        description="Max videos to pull per profile/hashtag target.",
     )
     max_items: int = Field(
         default=10,
@@ -60,10 +56,9 @@ class ScrapeInput(BaseModel):
 
     @model_validator(mode="after")
     def _require_a_source(self) -> ScrapeInput:
-        if not any((self.urls, self.profiles, self.hashtags, self.search_queries)):
+        if not any((self.urls, self.profiles, self.hashtags)):
             raise ValueError(
-                "Provide at least one of 'urls', 'profiles', 'hashtags', or "
-                "'search_queries'."
+                "Provide at least one of 'urls', 'profiles', or 'hashtags'."
             )
         return self
 
diff --git a/surfsense_backend/app/proprietary/platforms/instagram/fetch.py b/surfsense_backend/app/proprietary/platforms/instagram/fetch.py
index 41f692bf1..ab94f81a0 100644
--- a/surfsense_backend/app/proprietary/platforms/instagram/fetch.py
+++ b/surfsense_backend/app/proprietary/platforms/instagram/fetch.py
@@ -222,9 +222,7 @@ class _RotatingSession:
         await self.close()
         self.rotations += 1
         await self._open()
-        logger.info(
-            "[instagram] rotated proxy session (rotation #%d)", self.rotations
-        )
+        logger.info("[instagram] rotated proxy session (rotation #%d)", self.rotations)
         return self.session
 
     async def pace(self) -> None:
@@ -378,9 +376,7 @@ async def _fetch(
             if status == _BACKOFF_STATUS and backoffs < _MAX_BACKOFFS:
                 backoffs += 1
                 delay = _BACKOFF_BASE_S * (2 ** (backoffs - 1))
-                logger.warning(
-                    "[instagram] 429 on %s; backing off %.1fs", path, delay
-                )
+                logger.warning("[instagram] 429 on %s; backing off %.1fs", path, delay)
                 await asyncio.sleep(delay + random.uniform(0, 1))
                 continue
             if status in _ROTATE_STATUSES:
diff --git a/surfsense_backend/app/proprietary/platforms/instagram/parsers.py b/surfsense_backend/app/proprietary/platforms/instagram/parsers.py
index 5c4e8ea03..c76d32e5b 100644
--- a/surfsense_backend/app/proprietary/platforms/instagram/parsers.py
+++ b/surfsense_backend/app/proprietary/platforms/instagram/parsers.py
@@ -171,7 +171,9 @@ def _relay_child(node: dict[str, Any]) -> dict[str, Any]:
     mt = node.get("media_type")
     vv = node.get("video_versions")
     video_url = (
-        vv[0].get("url") if isinstance(vv, list) and vv and isinstance(vv[0], dict) else None
+        vv[0].get("url")
+        if isinstance(vv, list) and vv and isinstance(vv[0], dict)
+        else None
     )
     is_video = mt == 2 or bool(video_url)
     return {
@@ -290,9 +292,7 @@ def parse_profile(user: dict[str, Any]) -> dict[str, Any]:
 _APP_JSON_RE = re.compile(
     r'<script type="application/json"[^>]*>(.*?)</script>', re.DOTALL
 )
-_OG_RE = re.compile(
-    r'<meta\s+property="og:([^"]+)"\s+content="([^"]*)"', re.IGNORECASE
-)
+_OG_RE = re.compile(r'<meta\s+property="og:([^"]+)"\s+content="([^"]*)"', re.IGNORECASE)
 # og tags are the fallback source (used only when the relay blob is absent). They
 # follow a fixed English shape because the fetch layer pins Accept-Language en-US:
 #   og:description = "{likes} likes, {comments} comments - {username} on {Month D, YYYY}: "{caption}""
@@ -321,7 +321,9 @@ _MEDIA_ID_RE = re.compile(r"instagram://media\?id=(\d+)")
 def _og_date_to_iso(value: str) -> str | None:
     """``"July 9, 2026"`` -> ``"2026-07-09"`` (date-only; og carries no time)."""
     try:
-        return datetime.strptime(value, "%B %d, %Y").replace(tzinfo=UTC).date().isoformat()
+        return (
+            datetime.strptime(value, "%B %d, %Y").replace(tzinfo=UTC).date().isoformat()
+        )
     except ValueError:
         return None
 
@@ -359,7 +361,7 @@ def _parse_og_meta(og: dict[str, str]) -> dict[str, Any]:
     elif owner_date:
         # No usable og:title: fall back to the caption after og:description's
         # date prefix — still clean (the counts/username/date are stripped).
-        out["caption"] = _clean_caption(desc[owner_date.end():])
+        out["caption"] = _clean_caption(desc[owner_date.end() :])
     return out
 
 
@@ -438,13 +440,21 @@ def _media_from_relay(
     mt = media.get("media_type")
     cap = media.get("caption")
     caption = (
-        cap.get("text") if isinstance(cap, dict) else (cap if isinstance(cap, str) else None)
+        cap.get("text")
+        if isinstance(cap, dict)
+        else (cap if isinstance(cap, str) else None)
     )
     carousel = media.get("carousel_media")
-    carousel = [c for c in carousel if isinstance(c, dict)] if isinstance(carousel, list) else []
+    carousel = (
+        [c for c in carousel if isinstance(c, dict)]
+        if isinstance(carousel, list)
+        else []
+    )
     vv = media.get("video_versions")
     video_url = (
-        vv[0].get("url") if isinstance(vv, list) and vv and isinstance(vv[0], dict) else None
+        vv[0].get("url")
+        if isinstance(vv, list) and vv and isinstance(vv[0], dict)
+        else None
     )
     is_video = mt == 2 or bool(video_url)
     owner = media.get("user") if isinstance(media.get("user"), dict) else {}
@@ -469,13 +479,18 @@ def _media_from_relay(
         "type": _MEDIA_TYPE.get(mt) or ("Video" if is_video else "Image"),
         "shortCode": media.get("code") or shortcode,
         "caption": caption,
-        "hashtags": list(dict.fromkeys(_HASHTAG_RE.findall(caption))) if caption else [],
-        "mentions": list(dict.fromkeys(_MENTION_RE.findall(caption))) if caption else [],
+        "hashtags": list(dict.fromkeys(_HASHTAG_RE.findall(caption)))
+        if caption
+        else [],
+        "mentions": list(dict.fromkeys(_MENTION_RE.findall(caption)))
+        if caption
+        else [],
         "url": url,
         "commentsCount": _int(media.get("comment_count")),
         "dimensionsHeight": _int(media.get("original_height")),
         "dimensionsWidth": _int(media.get("original_width")),
-        "displayUrl": _iv2_url(media.get("image_versions2")) or media.get("display_uri"),
+        "displayUrl": _iv2_url(media.get("image_versions2"))
+        or media.get("display_uri"),
         "images": [
             u
             for c in carousel
@@ -535,8 +550,12 @@ def parse_post(
         "type": "Video" if is_video else "Image",
         "shortCode": shortcode,
         "caption": caption,
-        "hashtags": list(dict.fromkeys(_HASHTAG_RE.findall(caption))) if caption else [],
-        "mentions": list(dict.fromkeys(_MENTION_RE.findall(caption))) if caption else [],
+        "hashtags": list(dict.fromkeys(_HASHTAG_RE.findall(caption)))
+        if caption
+        else [],
+        "mentions": list(dict.fromkeys(_MENTION_RE.findall(caption)))
+        if caption
+        else [],
         "url": url,
         "commentsCount": og_meta.get("comments"),
         "displayUrl": og.get("image"),
diff --git a/surfsense_backend/app/proprietary/platforms/instagram/scraper.py b/surfsense_backend/app/proprietary/platforms/instagram/scraper.py
index a4c22bde7..f248b5653 100644
--- a/surfsense_backend/app/proprietary/platforms/instagram/scraper.py
+++ b/surfsense_backend/app/proprietary/platforms/instagram/scraper.py
@@ -306,9 +306,9 @@ async def _discover_via_google(
     """
     serps = await scrape_serps(
         GoogleSearchScrapeInput(
-            queries=query, site="instagram.com", maxPagesPerQuery=2
+            queries=query, site="instagram.com", maxPagesPerQuery=1
         ),
-        limit=2,
+        limit=1,
     )
     resolved: list[ResolvedUrl] = []
     seen: set[tuple[str, str]] = set()
@@ -328,9 +328,7 @@ async def _discover_via_google(
     return resolved
 
 
-async def _discover(
-    query: str, *, search_type: str, limit: int
-) -> list[ResolvedUrl]:
+async def _discover(query: str, *, search_type: str, limit: int) -> list[ResolvedUrl]:
     """Resolve a discovery query into profile targets - anonymously.
 
     A query that is a valid handle resolves directly against the anonymous
@@ -397,9 +395,7 @@ async def iter_instagram(
 
     # posts / reels -> media feeds, de-duped by id across targets.
     jobs = [
-        _media_flow(
-            r, input_model=input_model, cutoff=cutoff, per_target=per_target
-        )
+        _media_flow(r, input_model=input_model, cutoff=cutoff, per_target=per_target)
         for r in targets
     ]
     seen: set[str] = set()
diff --git a/surfsense_backend/app/proprietary/platforms/instagram/url_resolver.py b/surfsense_backend/app/proprietary/platforms/instagram/url_resolver.py
index 08f5c6553..197a90276 100644
--- a/surfsense_backend/app/proprietary/platforms/instagram/url_resolver.py
+++ b/surfsense_backend/app/proprietary/platforms/instagram/url_resolver.py
@@ -25,9 +25,7 @@ from urllib.parse import urlparse
 
 ResolvedKind = Literal["profile", "post", "reel"]
 
-_INSTAGRAM_HOSTS = frozenset(
-    {"m.instagram.com", "www.instagram.com", "instagram.com"}
-)
+_INSTAGRAM_HOSTS = frozenset({"m.instagram.com", "www.instagram.com", "instagram.com"})
 _STRIP_SEGMENTS = frozenset({"_u", "profilecard"})
 _RESERVED = frozenset(
     {"p", "s", "tv", "reel", "reels", "share", "explore", "stories", "accounts"}
@@ -68,9 +66,7 @@ def resolve_url(url: str) -> ResolvedUrl | None:
     if "instagram.com" not in url.lower():
         token = url.strip().lstrip("@")
         if token and "/" not in token and "." not in token:
-            return ResolvedUrl(
-                "profile", token, f"https://www.instagram.com/{token}/"
-            )
+            return ResolvedUrl("profile", token, f"https://www.instagram.com/{token}/")
     segments = _segments(url)
     if not segments:
         return None
@@ -83,9 +79,7 @@ def resolve_url(url: str) -> ResolvedUrl | None:
         return ResolvedUrl("reel", code, url, numeric_post_id=code.isdigit())
     if head == "stories" and len(segments) >= 2:
         user = segments[1]
-        return ResolvedUrl(
-            "profile", user, f"https://www.instagram.com/{user}/"
-        )
+        return ResolvedUrl("profile", user, f"https://www.instagram.com/{user}/")
     if head not in _RESERVED:
         return ResolvedUrl("profile", head, url)
     return None
diff --git a/surfsense_backend/app/proprietary/platforms/tiktok/extraction/timestamps.py b/surfsense_backend/app/proprietary/platforms/tiktok/extraction/timestamps.py
index 4b155c137..ed45baa8f 100644
--- a/surfsense_backend/app/proprietary/platforms/tiktok/extraction/timestamps.py
+++ b/surfsense_backend/app/proprietary/platforms/tiktok/extraction/timestamps.py
@@ -5,11 +5,11 @@ from __future__ import annotations
 from datetime import UTC, datetime
 
 
-def epoch_to_iso(seconds: int | None) -> str | None:
+def epoch_to_iso(seconds: int | str | None) -> str | None:
     """Convert a Unix-seconds timestamp to ``YYYY-MM-DDTHH:MM:SS.000Z``."""
     if not seconds:
         return None
-    stamp = datetime.fromtimestamp(seconds, tz=UTC)
+    stamp = datetime.fromtimestamp(int(seconds), tz=UTC)
     return stamp.strftime("%Y-%m-%dT%H:%M:%S.000Z")
 
 
diff --git a/surfsense_backend/app/proprietary/platforms/tiktok/flows/video.py b/surfsense_backend/app/proprietary/platforms/tiktok/flows/video.py
index 48e558677..0cdefe1c4 100644
--- a/surfsense_backend/app/proprietary/platforms/tiktok/flows/video.py
+++ b/surfsense_backend/app/proprietary/platforms/tiktok/flows/video.py
@@ -11,7 +11,9 @@ from ..targets.types import TikTokTarget
 from . import FetchFn
 
 
-async def iter_video(target: TikTokTarget, *, fetch: FetchFn) -> AsyncIterator[dict[str, Any]]:
+async def iter_video(
+    target: TikTokTarget, *, fetch: FetchFn
+) -> AsyncIterator[dict[str, Any]]:
     html = await fetch(target.url)
     if not html:
         return
diff --git a/surfsense_backend/app/proprietary/platforms/tiktok/orchestrator.py b/surfsense_backend/app/proprietary/platforms/tiktok/orchestrator.py
index 5d6a24545..a738233a6 100644
--- a/surfsense_backend/app/proprietary/platforms/tiktok/orchestrator.py
+++ b/surfsense_backend/app/proprietary/platforms/tiktok/orchestrator.py
@@ -10,7 +10,6 @@ from __future__ import annotations
 
 from collections.abc import AsyncIterator
 from typing import Any
-from urllib.parse import quote
 
 from .extraction.timestamps import now_iso
 from .flows import FetchCommentsFn, FetchFn, FetchListingFn, FetchUsersFn
@@ -32,12 +31,16 @@ from .targets.types import TikTokTarget
 
 _PROFILE_URL = "https://www.tiktok.com/@{name}"
 _HASHTAG_URL = "https://www.tiktok.com/tag/{tag}"
-_SEARCH_URL = "https://www.tiktok.com/search?q={query}"
 _EXPLORE_URL = "https://www.tiktok.com/explore"
 
 
 def _resolve_targets(input_model: TikTokScrapeInput) -> list[TikTokTarget]:
-    """Build the target list from every input source, dropping unresolved URLs."""
+    """Build the target list from the URL/profile/hashtag sources.
+
+    A raw ``tiktok.com/search?...`` URL passed explicitly in
+    ``startUrls``/``postURLs`` still resolves here and keeps its native listing
+    routing; there is no keyword-search shortcut.
+    """
     targets: list[TikTokTarget] = []
     for entry in input_model.startUrls:
         resolved = resolve_target(entry.url)
@@ -52,10 +55,6 @@ def _resolve_targets(input_model: TikTokScrapeInput) -> list[TikTokTarget]:
         targets.append(TikTokTarget("profile", name, _PROFILE_URL.format(name=name)))
     for tag in input_model.hashtags:
         targets.append(TikTokTarget("hashtag", tag, _HASHTAG_URL.format(tag=tag)))
-    for query in input_model.searchQueries:
-        targets.append(
-            TikTokTarget("search", query, _SEARCH_URL.format(query=quote(query)))
-        )
     return targets
 
 
@@ -104,7 +103,9 @@ async def scrape_tiktok(
     from app.capabilities.core.progress import emit_progress
 
     results: list[dict[str, Any]] = []
-    async for item in iter_tiktok(input_model, fetch=fetch, fetch_listing=fetch_listing):
+    async for item in iter_tiktok(
+        input_model, fetch=fetch, fetch_listing=fetch_listing
+    ):
         results.append(item)
         emit_progress("scraping", current=len(results), total=limit, unit="item")
         if limit is not None and len(results) >= limit:
diff --git a/surfsense_backend/app/services/model_connection_service.py b/surfsense_backend/app/services/model_connection_service.py
index cdfd1d725..54d0a3c3f 100644
--- a/surfsense_backend/app/services/model_connection_service.py
+++ b/surfsense_backend/app/services/model_connection_service.py
@@ -15,6 +15,7 @@ from app.db import Connection, Model, ModelSource
 from app.services.model_resolver import ensure_v1, to_litellm
 from app.services.openrouter_model_normalizer import normalize_openrouter_models
 from app.services.provider_registry import Transport, provider_label, spec_for
+from app.services.requesty_model_normalizer import normalize_requesty_models
 
 logger = logging.getLogger(__name__)
 
@@ -148,7 +149,7 @@ async def verify_connection(conn: Connection) -> VerifyResult:
 
     if spec.transport == Transport.OLLAMA and base_url:
         url = f"{base_url.rstrip('/')}/api/version"
-    elif spec.discovery in {"openai_models", "openrouter"} and base_url:
+    elif spec.discovery in {"openai_models", "openrouter", "requesty"} and base_url:
         url = f"{ensure_v1(base_url)}/models"
     elif spec.discovery == "anthropic_models" and base_url:
         url = f"{base_url.rstrip('/')}/models"
@@ -363,6 +364,16 @@ async def _openrouter_models(conn: Connection) -> list[dict[str, Any]]:
     return normalize_openrouter_models(response.json().get("data", []))
 
 
+async def _requesty_models(conn: Connection) -> list[dict[str, Any]]:
+    base_url = _base_url_or_default(conn) or "https://router.requesty.ai/v1"
+    async with httpx.AsyncClient(timeout=DISCOVERY_TIMEOUT_SECONDS) as client:
+        response = await client.get(
+            f"{ensure_v1(base_url)}/models", headers=_auth_headers(conn)
+        )
+    response.raise_for_status()
+    return normalize_requesty_models(response.json().get("data", []))
+
+
 def _litellm_static_models(conn: Connection) -> list[dict[str, Any]]:
     provider = conn.provider
     prefix = spec_for(provider).litellm_prefix or provider
@@ -446,6 +457,8 @@ async def discover_models(conn: Connection) -> list[dict[str, Any]]:
             results = await _ollama_tags_then_show(conn)
         elif spec.discovery == "openrouter":
             results = await _openrouter_models(conn)
+        elif spec.discovery == "requesty":
+            results = await _requesty_models(conn)
         elif spec.discovery == "anthropic_models":
             results = await _discover_anthropic_models(conn)
         elif spec.discovery == "openai_models":
diff --git a/surfsense_backend/app/services/provider_registry.py b/surfsense_backend/app/services/provider_registry.py
index 67d1c4db4..87c1afee3 100644
--- a/surfsense_backend/app/services/provider_registry.py
+++ b/surfsense_backend/app/services/provider_registry.py
@@ -23,6 +23,7 @@ DiscoveryKind = Literal[
     "anthropic_models",
     "bedrock_models",
     "openrouter",
+    "requesty",
     "static",
     "none",
 ]
@@ -78,6 +79,15 @@ REGISTRY: dict[str, ProviderSpec] = {
         "bearer",
         "OpenRouter",
     ),
+    "requesty": ProviderSpec(
+        Transport.OPENAI_COMPATIBLE,
+        "openai",
+        "requesty",
+        "https://router.requesty.ai/v1",
+        False,
+        "bearer",
+        "Requesty",
+    ),
     "openai_compatible": ProviderSpec(
         Transport.OPENAI_COMPATIBLE,
         "openai",
@@ -87,6 +97,15 @@ REGISTRY: dict[str, ProviderSpec] = {
         "bearer",
         "OpenAI-compatible provider",
     ),
+    "openai_compatible_raw": ProviderSpec(
+        Transport.NATIVE,
+        "openai",
+        "none",
+        None,
+        True,
+        "bearer",
+        "OpenAI-compatible raw endpoint",
+    ),
     "lm_studio": ProviderSpec(
         Transport.OPENAI_COMPATIBLE,
         "openai",
diff --git a/surfsense_backend/app/services/quality_score.py b/surfsense_backend/app/services/quality_score.py
index 737dd7c2f..1aa3e7eda 100644
--- a/surfsense_backend/app/services/quality_score.py
+++ b/surfsense_backend/app/services/quality_score.py
@@ -123,6 +123,7 @@ PROVIDER_PRESTIGE_YAML: dict[str, int] = {
     "perplexity": 28,
     "bedrock": 28,
     "openrouter": 25,
+    "requesty": 25,
     "ollama_chat": 12,
     "custom": 12,
 }
diff --git a/surfsense_backend/app/services/requesty_model_normalizer.py b/surfsense_backend/app/services/requesty_model_normalizer.py
new file mode 100644
index 000000000..7710eb174
--- /dev/null
+++ b/surfsense_backend/app/services/requesty_model_normalizer.py
@@ -0,0 +1,123 @@
+"""Shared Requesty model normalization.
+
+Requesty (https://router.requesty.ai) is an OpenAI-compatible LLM router.
+Its ``/v1/models`` catalogue carries richer, Requesty-specific capability
+metadata than a generic OpenAI-compatible ``/models`` response, so keep all
+Requesty filtering and capability extraction here -- mirroring
+``openrouter_model_normalizer`` -- so GLOBAL catalogue generation and BYOK
+discovery agree.
+
+Unlike OpenRouter, Requesty exposes capabilities as flat booleans
+(``supports_tool_calling`` / ``supports_reasoning`` / ``supports_vision`` /
+``supports_image_generation``) rather than an ``architecture`` block plus a
+``supported_parameters`` array, and it reports context size as
+``context_window`` rather than ``context_length``. This module maps those
+fields onto the same normalized shape the rest of the backend consumes.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from app.db import ModelSource
+
+MIN_CONTEXT_LENGTH = 100_000
+
+EXCLUDED_PROVIDER_SLUGS: set[str] = {"amazon"}
+EXCLUDED_MODEL_IDS: set[str] = set()
+EXCLUDED_MODEL_SUFFIXES: tuple[str, ...] = ("-deep-research",)
+
+
+def is_image_output_model(model: dict[str, Any]) -> bool:
+    return bool(model.get("supports_image_generation"))
+
+
+def is_text_output_model(model: dict[str, Any]) -> bool:
+    # Requesty entries are chat-completion models (``api == "chat"``). Treat a
+    # model as text output whenever it is not an image-generation model.
+    return not is_image_output_model(model)
+
+
+def supports_image_input(model: dict[str, Any]) -> bool:
+    return bool(model.get("supports_vision"))
+
+
+def supports_tool_calling(model: dict[str, Any]) -> bool:
+    return bool(model.get("supports_tool_calling"))
+
+
+def has_sufficient_context(model: dict[str, Any]) -> bool:
+    return int(model.get("context_window") or 0) >= MIN_CONTEXT_LENGTH
+
+
+def is_compatible_provider(model: dict[str, Any]) -> bool:
+    model_id = str(model.get("id") or "")
+    slug = model_id.split("/", 1)[0] if "/" in model_id else ""
+    return slug not in EXCLUDED_PROVIDER_SLUGS
+
+
+def is_allowed_model(model: dict[str, Any]) -> bool:
+    model_id = str(model.get("id") or "")
+    if model_id in EXCLUDED_MODEL_IDS:
+        return False
+    base_id = model_id.split(":")[0]
+    return not base_id.endswith(EXCLUDED_MODEL_SUFFIXES)
+
+
+def is_requesty_chat_model(model: dict[str, Any]) -> bool:
+    return (
+        "/" in str(model.get("id") or "")
+        and is_text_output_model(model)
+        and supports_tool_calling(model)
+        and has_sufficient_context(model)
+        and is_compatible_provider(model)
+        and is_allowed_model(model)
+    )
+
+
+def is_requesty_image_model(model: dict[str, Any]) -> bool:
+    return (
+        "/" in str(model.get("id") or "")
+        and is_image_output_model(model)
+        and is_compatible_provider(model)
+        and is_allowed_model(model)
+    )
+
+
+def normalize_requesty_models(
+    raw_models: list[dict[str, Any]],
+) -> list[dict[str, Any]]:
+    normalized: list[dict[str, Any]] = []
+    for model in raw_models:
+        if not is_requesty_chat_model(model):
+            continue
+        model_id = str(model.get("id") or "")
+        normalized.append(
+            {
+                "model_id": model_id,
+                "display_name": model.get("name") or model_id,
+                "source": ModelSource.DISCOVERED,
+                "supports_chat": True,
+                "max_input_tokens": model.get("context_window"),
+                "supports_image_input": supports_image_input(model),
+                "supports_tools": supports_tool_calling(model),
+                "supports_image_generation": False,
+                "metadata": model,
+            }
+        )
+    return normalized
+
+
+__all__ = [
+    "MIN_CONTEXT_LENGTH",
+    "has_sufficient_context",
+    "is_allowed_model",
+    "is_compatible_provider",
+    "is_image_output_model",
+    "is_requesty_chat_model",
+    "is_requesty_image_model",
+    "is_text_output_model",
+    "normalize_requesty_models",
+    "supports_image_input",
+    "supports_tool_calling",
+]
diff --git a/surfsense_backend/pyproject.toml b/surfsense_backend/pyproject.toml
index 2faa2be17..30bb7ea5c 100644
--- a/surfsense_backend/pyproject.toml
+++ b/surfsense_backend/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "surf-new-backend"
-version = "0.0.31"
+version = "0.0.32"
 description = "SurfSense Backend"
 requires-python = ">=3.12"
 dependencies = [
diff --git a/surfsense_backend/scripts/e2e_instagram_scraper.py b/surfsense_backend/scripts/e2e_instagram_scraper.py
index c81075932..a5e356f99 100644
--- a/surfsense_backend/scripts/e2e_instagram_scraper.py
+++ b/surfsense_backend/scripts/e2e_instagram_scraper.py
@@ -54,9 +54,7 @@ from app.proprietary.platforms.instagram.url_resolver import resolve_url  # noqa
 _PROFILE = "natgeo"
 _SEARCH_TERM = "national geographic"
 
-_FIXTURE_DIR = (
-    _BACKEND_ROOT / "tests" / "unit" / "platforms" / "instagram" / "fixtures"
-)
+_FIXTURE_DIR = _BACKEND_ROOT / "tests" / "unit" / "platforms" / "instagram" / "fixtures"
 
 # Fields to strip from dumped fixtures so we never commit PII / volatile tokens.
 _PII_KEYS = frozenset(
@@ -98,7 +96,9 @@ async def step0_probe() -> bool:
         data = await fetch_json(
             "api/v1/users/web_profile_info/", {"username": _PROFILE}
         )
-        user = (data or {}).get("data", {}).get("user") if isinstance(data, dict) else None
+        user = (
+            (data or {}).get("data", {}).get("user") if isinstance(data, dict) else None
+        )
         print(f"    web_profile_info({_PROFILE}) -> user={'yes' if user else 'no'}")
         return _check("sticky web_profile_info", minted and bool(user))
 
@@ -179,9 +179,7 @@ async def step5_search() -> bool:
 
 async def step6_dump_fixtures(post_url: str | None) -> bool:
     _hr("STEP 6 — dump trimmed, anonymized fixtures for offline tests")
-    profile = await fetch_json(
-        "api/v1/users/web_profile_info/", {"username": _PROFILE}
-    )
+    profile = await fetch_json("api/v1/users/web_profile_info/", {"username": _PROFILE})
     _FIXTURE_DIR.mkdir(parents=True, exist_ok=True)
     wrote = []
     if isinstance(profile, dict) and profile.get("data", {}).get("user"):
diff --git a/surfsense_backend/scripts/e2e_tiktok_scrape.py b/surfsense_backend/scripts/e2e_tiktok_scrape.py
index b399ca3fb..4a0063303 100644
--- a/surfsense_backend/scripts/e2e_tiktok_scrape.py
+++ b/surfsense_backend/scripts/e2e_tiktok_scrape.py
@@ -178,7 +178,9 @@ async def stage_pipeline() -> bool:
         f"{len(items)} item(s)",
     )
     if items:
-        print(f"  sample: {items[0].get('webVideoUrl')} — {items[0].get('text', '')[:60]!r}")
+        print(
+            f"  sample: {items[0].get('webVideoUrl')} — {items[0].get('text', '')[:60]!r}"
+        )
     return ok
 
 
@@ -210,9 +212,7 @@ async def stage_comments(video_url: str) -> tuple[bool, list[dict[str, Any]]]:
     # Comments load over a signed /api/comment/list XHR that TikTok serves to
     # anonymous sessions once the panel opens. Pass if real comments come back
     # OR a graceful ErrorItem (video has none / disabled / withheld).
-    items = await scrape_tiktok_comments(
-        [video_url], per_video=_COUNT, limit=_COUNT
-    )
+    items = await scrape_tiktok_comments([video_url], per_video=_COUNT, limit=_COUNT)
     has_comment = any(it.get("id") and not it.get("errorCode") for it in items)
     has_error = any(it.get("errorCode") == "no_comments" for it in items)
     ok = _check(
@@ -253,7 +253,9 @@ async def stage_trending() -> tuple[bool, list[dict[str, Any]]]:
         f"{len(items)} item(s); videos={len(real)}",
     )
     if real:
-        print(f"  sample: {real[0].get('webVideoUrl')} — {real[0].get('text', '')[:60]!r}")
+        print(
+            f"  sample: {real[0].get('webVideoUrl')} — {real[0].get('text', '')[:60]!r}"
+        )
     return ok, items
 
 
diff --git a/surfsense_backend/tests/unit/capabilities/instagram/test_schemas.py b/surfsense_backend/tests/unit/capabilities/instagram/test_schemas.py
index afabbf833..fde5b07ab 100644
--- a/surfsense_backend/tests/unit/capabilities/instagram/test_schemas.py
+++ b/surfsense_backend/tests/unit/capabilities/instagram/test_schemas.py
@@ -66,6 +66,4 @@ def test_details_wraps_profile_items():
 
 def test_details_rejects_both_sources():
     with pytest.raises(ValidationError):
-        DetailsInput(
-            urls=["https://www.instagram.com/natgeo/"], search_queries=["x"]
-        )
+        DetailsInput(urls=["https://www.instagram.com/natgeo/"], search_queries=["x"])
diff --git a/surfsense_backend/tests/unit/capabilities/tiktok/scrape/test_executor.py b/surfsense_backend/tests/unit/capabilities/tiktok/scrape/test_executor.py
index 1bf07b0c3..367831c76 100644
--- a/surfsense_backend/tests/unit/capabilities/tiktok/scrape/test_executor.py
+++ b/surfsense_backend/tests/unit/capabilities/tiktok/scrape/test_executor.py
@@ -54,7 +54,6 @@ async def test_forwards_typed_sources_and_limit():
         ScrapeInput(
             profiles=["nasa"],
             hashtags=["food"],
-            search_queries=["cats"],
             results_per_page=7,
             max_items=25,
         )
@@ -63,7 +62,6 @@ async def test_forwards_typed_sources_and_limit():
     (actor_input, limit) = scraper.calls[0]
     assert actor_input.profiles == ["nasa"]
     assert actor_input.hashtags == ["food"]
-    assert actor_input.searchQueries == ["cats"]
     assert actor_input.resultsPerPage == 7
     # The outer collection limit is the caller's total-item cap.
     assert limit == 25
diff --git a/surfsense_backend/tests/unit/platforms/instagram/test_budget.py b/surfsense_backend/tests/unit/platforms/instagram/test_budget.py
index ea500be40..703002f0c 100644
--- a/surfsense_backend/tests/unit/platforms/instagram/test_budget.py
+++ b/surfsense_backend/tests/unit/platforms/instagram/test_budget.py
@@ -42,8 +42,7 @@ def _profile_payload(n: int) -> dict:
                 "edge_owner_to_timeline_media": {
                     "count": n,
                     "edges": [
-                        {"node": {"id": str(i), "shortcode": f"S{i}"}}
-                        for i in range(n)
+                        {"node": {"id": str(i), "shortcode": f"S{i}"}} for i in range(n)
                     ],
                 },
             }
diff --git a/surfsense_backend/tests/unit/platforms/instagram/test_discovery.py b/surfsense_backend/tests/unit/platforms/instagram/test_discovery.py
index c95a80315..379e3ba28 100644
--- a/surfsense_backend/tests/unit/platforms/instagram/test_discovery.py
+++ b/surfsense_backend/tests/unit/platforms/instagram/test_discovery.py
@@ -33,9 +33,7 @@ async def test_google_discovery_keeps_only_profiles(monkeypatch):
             "https://example.com/not-instagram",
         ),
     )
-    targets = await scraper._discover(
-        "nat geo photos", search_type="profile", limit=10
-    )
+    targets = await scraper._discover("nat geo photos", search_type="profile", limit=10)
     assert [(t.kind, t.value) for t in targets] == [("profile", "natgeo")]
 
 
@@ -48,9 +46,7 @@ async def test_google_discovery_dedupes(monkeypatch):
             "https://www.instagram.com/natgeo/",
         ),
     )
-    targets = await scraper._discover(
-        "nat geo photos", search_type="profile", limit=10
-    )
+    targets = await scraper._discover("nat geo photos", search_type="profile", limit=10)
     assert len(targets) == 1
 
 
diff --git a/surfsense_backend/tests/unit/platforms/instagram/test_fetch_resilience.py b/surfsense_backend/tests/unit/platforms/instagram/test_fetch_resilience.py
index 859c70443..44fefa430 100644
--- a/surfsense_backend/tests/unit/platforms/instagram/test_fetch_resilience.py
+++ b/surfsense_backend/tests/unit/platforms/instagram/test_fetch_resilience.py
@@ -102,7 +102,9 @@ async def test_warms_then_returns_json():
     holder = _FakeHolder([_FakeSession(200, csrftoken=True)])
     token = _current_session.set(holder)
     try:
-        result = await fetch_json("api/v1/users/web_profile_info/", {"username": "natgeo"})
+        result = await fetch_json(
+            "api/v1/users/web_profile_info/", {"username": "natgeo"}
+        )
     finally:
         _current_session.reset(token)
     assert result == _PAYLOAD
diff --git a/surfsense_backend/tests/unit/platforms/instagram/test_parsers.py b/surfsense_backend/tests/unit/platforms/instagram/test_parsers.py
index 8cba74b3a..1cfa386a7 100644
--- a/surfsense_backend/tests/unit/platforms/instagram/test_parsers.py
+++ b/surfsense_backend/tests/unit/platforms/instagram/test_parsers.py
@@ -175,8 +175,14 @@ def test_parse_post_prefers_relay_json():
                 "image_versions2": {"candidates": [{"url": "https://cdn/c2.jpg"}]},
             },
         ],
-        "usertags": {"in": [{"position": [0.5, 0.5], "user": {"username": "tagged1", "id": "77"}}]},
-        "coauthor_producers": [{"username": "coauthor1", "id": "88", "is_verified": True}],
+        "usertags": {
+            "in": [
+                {"position": [0.5, 0.5], "user": {"username": "tagged1", "id": "77"}}
+            ]
+        },
+        "coauthor_producers": [
+            {"username": "coauthor1", "id": "88", "is_verified": True}
+        ],
         "location": {"id": "123", "name": "Bali"},
     }
     html = (
diff --git a/surfsense_backend/tests/unit/platforms/tiktok/test_fetch_resilience.py b/surfsense_backend/tests/unit/platforms/tiktok/test_fetch_resilience.py
index 484157964..a2177233e 100644
--- a/surfsense_backend/tests/unit/platforms/tiktok/test_fetch_resilience.py
+++ b/surfsense_backend/tests/unit/platforms/tiktok/test_fetch_resilience.py
@@ -84,7 +84,9 @@ async def test_warms_then_returns_html():
 
 
 async def test_rotates_when_warm_fails_then_succeeds():
-    holder = _FakeHolder([_FakeSession(200, warms=False), _FakeSession(200, warms=True)])
+    holder = _FakeHolder(
+        [_FakeSession(200, warms=False), _FakeSession(200, warms=True)]
+    )
     token = _current_session.set(holder)
     try:
         result = await client.fetch_html("https://www.tiktok.com/@scout2015")
@@ -119,9 +121,7 @@ async def test_rotates_and_rewarms_on_403():
 
 async def test_persistent_403_raises_blocked(monkeypatch):
     _no_sleep(monkeypatch)
-    holder = _FakeHolder(
-        [_FakeSession(403) for _ in range(client._MAX_ROTATIONS + 1)]
-    )
+    holder = _FakeHolder([_FakeSession(403) for _ in range(client._MAX_ROTATIONS + 1)])
     token = _current_session.set(holder)
     try:
         raised = False
diff --git a/surfsense_backend/tests/unit/platforms/tiktok/test_target_resolver.py b/surfsense_backend/tests/unit/platforms/tiktok/test_target_resolver.py
index c118f4f86..d246085ae 100644
--- a/surfsense_backend/tests/unit/platforms/tiktok/test_target_resolver.py
+++ b/surfsense_backend/tests/unit/platforms/tiktok/test_target_resolver.py
@@ -6,7 +6,9 @@ from app.proprietary.platforms.tiktok.targets import resolve_target
 
 
 def test_resolve_video_carries_username_and_id():
-    target = resolve_target("https://www.tiktok.com/@scout2015/video/6718335390845095173")
+    target = resolve_target(
+        "https://www.tiktok.com/@scout2015/video/6718335390845095173"
+    )
     assert target is not None
     assert target.kind == "video"
     assert target.value == "6718335390845095173"
diff --git a/surfsense_backend/tests/unit/platforms/tiktok/test_user_search.py b/surfsense_backend/tests/unit/platforms/tiktok/test_user_search.py
index 845b5e22d..c4b89e390 100644
--- a/surfsense_backend/tests/unit/platforms/tiktok/test_user_search.py
+++ b/surfsense_backend/tests/unit/platforms/tiktok/test_user_search.py
@@ -28,9 +28,7 @@ async def test_user_search_parses_dedupes_and_caps():
     async def fake_fetch(_url: str, _cap: int) -> list[dict]:
         return [_user("1", "nasa"), _user("1", "nasa"), _user("2", "nasa2")]
 
-    items = await search_tiktok_users(
-        ["nasa"], per_query=2, fetch_users=fake_fetch
-    )
+    items = await search_tiktok_users(["nasa"], per_query=2, fetch_users=fake_fetch)
 
     assert [i["id"] for i in items] == ["1", "2"]
     first = items[0]
@@ -49,9 +47,7 @@ async def test_user_search_empty_query_emits_error_item():
     async def fake_fetch(_url: str, _cap: int) -> list[dict]:
         return []
 
-    items = await search_tiktok_users(
-        ["ghost"], per_query=5, fetch_users=fake_fetch
-    )
+    items = await search_tiktok_users(["ghost"], per_query=5, fetch_users=fake_fetch)
 
     assert len(items) == 1
     assert items[0]["errorCode"] == "no_users"
diff --git a/surfsense_backend/tests/unit/services/test_model_connections.py b/surfsense_backend/tests/unit/services/test_model_connections.py
index b4e7c18d7..bb5ca318e 100644
--- a/surfsense_backend/tests/unit/services/test_model_connections.py
+++ b/surfsense_backend/tests/unit/services/test_model_connections.py
@@ -64,6 +64,22 @@ def test_openai_compatible_resolver_uses_explicit_api_base() -> None:
     assert ensure_v1("http://example.com/v1") == "http://example.com/v1"
 
 
+def test_openai_compatible_raw_resolver_does_not_append_v1() -> None:
+    model, kwargs = to_litellm(
+        {
+            "provider": "openai_compatible_raw",
+            "base_url": "https://ark.cn-beijing.volces.com/api/v3",
+            "api_key": "ark-key",
+            "extra": {},
+        },
+        "ep-20260101000000-test",
+    )
+
+    assert model == "openai/ep-20260101000000-test"
+    assert kwargs["api_base"] == "https://ark.cn-beijing.volces.com/api/v3"
+    assert kwargs["api_key"] == "ark-key"
+
+
 def test_ollama_resolver_uses_native_api_base() -> None:
     model, kwargs = to_litellm(
         {
diff --git a/surfsense_backend/tests/unit/services/test_requesty_model_normalizer.py b/surfsense_backend/tests/unit/services/test_requesty_model_normalizer.py
new file mode 100644
index 000000000..2adae3ada
--- /dev/null
+++ b/surfsense_backend/tests/unit/services/test_requesty_model_normalizer.py
@@ -0,0 +1,103 @@
+"""Unit tests for Requesty model normalization.
+
+Mirrors the OpenRouter normalizer coverage but exercises Requesty's flat
+boolean capability fields (``supports_tool_calling`` / ``supports_vision``)
+and ``context_window`` sizing.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from app.services.requesty_model_normalizer import (
+    is_requesty_chat_model,
+    is_requesty_image_model,
+    normalize_requesty_models,
+    supports_image_input,
+    supports_tool_calling,
+)
+
+pytestmark = pytest.mark.unit
+
+
+def _requesty_model(
+    *,
+    model_id: str,
+    context_window: int = 128_000,
+    tools: bool = True,
+    vision: bool = False,
+    image_generation: bool = False,
+    name: str | None = None,
+) -> dict:
+    """Return a synthetic Requesty ``/v1/models`` entry.
+
+    Only the fields the normalizer inspects are populated; the live payload
+    carries many more (pricing, ``supports_caching``, ``description``, ...).
+    """
+    return {
+        "id": model_id,
+        "name": name or model_id,
+        "api": "chat",
+        "object": "model",
+        "context_window": context_window,
+        "supports_tool_calling": tools,
+        "supports_vision": vision,
+        "supports_image_generation": image_generation,
+    }
+
+
+def test_chat_model_requires_slash_tools_and_context():
+    assert is_requesty_chat_model(_requesty_model(model_id="openai/gpt-4o-mini"))
+    assert not is_requesty_chat_model(
+        _requesty_model(model_id="openai/gpt-4o-mini", tools=False)
+    )
+    assert not is_requesty_chat_model(
+        _requesty_model(model_id="openai/gpt-4o-mini", context_window=8_000)
+    )
+    assert not is_requesty_chat_model(_requesty_model(model_id="bare-model"))
+
+
+def test_excluded_provider_slug_is_filtered():
+    assert not is_requesty_chat_model(_requesty_model(model_id="amazon/nova-pro-v1"))
+
+
+def test_image_generation_models_excluded_from_chat_and_flagged():
+    image_model = _requesty_model(
+        model_id="google/gemini-2.5-flash-image", image_generation=True
+    )
+    assert not is_requesty_chat_model(image_model)
+    assert is_requesty_image_model(image_model)
+
+
+def test_capability_helpers_read_flat_booleans():
+    model = _requesty_model(
+        model_id="anthropic/claude-sonnet-4-5", vision=True, tools=True
+    )
+    assert supports_image_input(model) is True
+    assert supports_tool_calling(model) is True
+
+
+def test_normalize_maps_context_window_and_capabilities():
+    normalized = normalize_requesty_models(
+        [
+            _requesty_model(
+                model_id="openai/gpt-4o-mini",
+                context_window=128_000,
+                vision=True,
+                name="GPT-4o mini",
+            ),
+            _requesty_model(model_id="openai/gpt-4o-mini", tools=False),
+            _requesty_model(model_id="black-forest-labs/flux", image_generation=True),
+        ]
+    )
+
+    assert len(normalized) == 1
+    entry = normalized[0]
+    assert entry["model_id"] == "openai/gpt-4o-mini"
+    assert entry["display_name"] == "GPT-4o mini"
+    assert entry["supports_chat"] is True
+    assert entry["max_input_tokens"] == 128_000
+    assert entry["supports_image_input"] is True
+    assert entry["supports_tools"] is True
+    assert entry["supports_image_generation"] is False
+    assert entry["metadata"]["id"] == "openai/gpt-4o-mini"
diff --git a/surfsense_backend/uv.lock b/surfsense_backend/uv.lock
index a5b492fc8..2b1272363 100644
--- a/surfsense_backend/uv.lock
+++ b/surfsense_backend/uv.lock
@@ -36,6 +36,9 @@ resolution-markers = [
     "python_version < '0'",
     "python_version < '0'",
     "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
     "python_full_version == '3.13.*' and sys_platform == 'linux' and extra != 'extra-16-surf-new-backend-cpu' and extra != 'extra-16-surf-new-backend-cu126' and extra == 'extra-16-surf-new-backend-cu128'",
     "python_version < '0'",
     "python_version < '0'",
@@ -70,6 +73,9 @@ resolution-markers = [
     "python_version < '0'",
     "python_version < '0'",
     "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
     "python_full_version < '3.13' and sys_platform == 'linux' and extra != 'extra-16-surf-new-backend-cpu' and extra != 'extra-16-surf-new-backend-cu126' and extra == 'extra-16-surf-new-backend-cu128'",
     "python_version < '0'",
     "python_version < '0'",
@@ -104,6 +110,9 @@ resolution-markers = [
     "python_version < '0'",
     "python_version < '0'",
     "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
     "python_full_version >= '3.14' and sys_platform == 'win32' and extra != 'extra-16-surf-new-backend-cpu' and extra != 'extra-16-surf-new-backend-cu126' and extra == 'extra-16-surf-new-backend-cu128'",
     "python_version < '0'",
     "python_version < '0'",
@@ -138,6 +147,9 @@ resolution-markers = [
     "python_version < '0'",
     "python_version < '0'",
     "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
     "python_full_version >= '3.14' and sys_platform == 'emscripten' and extra != 'extra-16-surf-new-backend-cpu' and extra != 'extra-16-surf-new-backend-cu126' and extra == 'extra-16-surf-new-backend-cu128'",
     "python_version < '0'",
     "python_version < '0'",
@@ -172,6 +184,9 @@ resolution-markers = [
     "python_version < '0'",
     "python_version < '0'",
     "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
     "python_full_version >= '3.14' and sys_platform != 'emscripten' and sys_platform != 'linux' and sys_platform != 'win32' and extra != 'extra-16-surf-new-backend-cpu' and extra != 'extra-16-surf-new-backend-cu126' and extra == 'extra-16-surf-new-backend-cu128'",
     "python_version < '0'",
     "python_version < '0'",
@@ -206,6 +221,9 @@ resolution-markers = [
     "python_version < '0'",
     "python_version < '0'",
     "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
     "python_full_version == '3.13.*' and sys_platform == 'win32' and extra != 'extra-16-surf-new-backend-cpu' and extra != 'extra-16-surf-new-backend-cu126' and extra == 'extra-16-surf-new-backend-cu128'",
     "python_version < '0'",
     "python_version < '0'",
@@ -240,6 +258,9 @@ resolution-markers = [
     "python_version < '0'",
     "python_version < '0'",
     "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
     "python_full_version == '3.13.*' and sys_platform == 'emscripten' and extra != 'extra-16-surf-new-backend-cpu' and extra != 'extra-16-surf-new-backend-cu126' and extra == 'extra-16-surf-new-backend-cu128'",
     "python_version < '0'",
     "python_version < '0'",
@@ -274,6 +295,9 @@ resolution-markers = [
     "python_version < '0'",
     "python_version < '0'",
     "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
     "python_full_version == '3.13.*' and sys_platform != 'emscripten' and sys_platform != 'linux' and sys_platform != 'win32' and extra != 'extra-16-surf-new-backend-cpu' and extra != 'extra-16-surf-new-backend-cu126' and extra == 'extra-16-surf-new-backend-cu128'",
     "python_version < '0'",
     "python_version < '0'",
@@ -308,6 +332,9 @@ resolution-markers = [
     "python_version < '0'",
     "python_version < '0'",
     "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
     "python_full_version < '3.13' and sys_platform != 'linux' and sys_platform != 'win32' and extra != 'extra-16-surf-new-backend-cpu' and extra != 'extra-16-surf-new-backend-cu126' and extra == 'extra-16-surf-new-backend-cu128'",
     "python_version < '0'",
     "python_version < '0'",
@@ -342,6 +369,9 @@ resolution-markers = [
     "python_version < '0'",
     "python_version < '0'",
     "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
     "python_full_version < '3.13' and sys_platform == 'win32' and extra != 'extra-16-surf-new-backend-cpu' and extra != 'extra-16-surf-new-backend-cu126' and extra == 'extra-16-surf-new-backend-cu128'",
     "python_version < '0'",
     "python_version < '0'",
@@ -387,6 +417,10 @@ resolution-markers = [
     "python_version < '0'",
     "python_version < '0'",
     "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
     "python_full_version >= '3.14' and sys_platform == 'linux' and extra != 'extra-16-surf-new-backend-cpu' and extra == 'extra-16-surf-new-backend-cu126' and extra != 'extra-16-surf-new-backend-cu128'",
     "python_version < '0'",
     "python_version < '0'",
@@ -421,6 +455,9 @@ resolution-markers = [
     "python_version < '0'",
     "python_version < '0'",
     "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
     "python_full_version == '3.13.*' and sys_platform == 'linux' and extra != 'extra-16-surf-new-backend-cpu' and extra == 'extra-16-surf-new-backend-cu126' and extra != 'extra-16-surf-new-backend-cu128'",
     "python_version < '0'",
     "python_version < '0'",
@@ -455,6 +492,9 @@ resolution-markers = [
     "python_version < '0'",
     "python_version < '0'",
     "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
     "python_full_version < '3.13' and sys_platform == 'linux' and extra != 'extra-16-surf-new-backend-cpu' and extra == 'extra-16-surf-new-backend-cu126' and extra != 'extra-16-surf-new-backend-cu128'",
     "python_version < '0'",
     "python_version < '0'",
@@ -489,6 +529,9 @@ resolution-markers = [
     "python_version < '0'",
     "python_version < '0'",
     "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
     "python_full_version >= '3.14' and sys_platform == 'win32' and extra != 'extra-16-surf-new-backend-cpu' and extra == 'extra-16-surf-new-backend-cu126' and extra != 'extra-16-surf-new-backend-cu128'",
     "python_version < '0'",
     "python_version < '0'",
@@ -523,6 +566,9 @@ resolution-markers = [
     "python_version < '0'",
     "python_version < '0'",
     "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
     "python_full_version >= '3.14' and sys_platform == 'emscripten' and extra != 'extra-16-surf-new-backend-cpu' and extra == 'extra-16-surf-new-backend-cu126' and extra != 'extra-16-surf-new-backend-cu128'",
     "python_version < '0'",
     "python_version < '0'",
@@ -557,6 +603,9 @@ resolution-markers = [
     "python_version < '0'",
     "python_version < '0'",
     "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
     "python_full_version >= '3.14' and sys_platform != 'emscripten' and sys_platform != 'linux' and sys_platform != 'win32' and extra != 'extra-16-surf-new-backend-cpu' and extra == 'extra-16-surf-new-backend-cu126' and extra != 'extra-16-surf-new-backend-cu128'",
     "python_version < '0'",
     "python_version < '0'",
@@ -591,6 +640,9 @@ resolution-markers = [
     "python_version < '0'",
     "python_version < '0'",
     "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
     "python_full_version == '3.13.*' and sys_platform == 'win32' and extra != 'extra-16-surf-new-backend-cpu' and extra == 'extra-16-surf-new-backend-cu126' and extra != 'extra-16-surf-new-backend-cu128'",
     "python_version < '0'",
     "python_version < '0'",
@@ -625,6 +677,9 @@ resolution-markers = [
     "python_version < '0'",
     "python_version < '0'",
     "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
     "python_full_version == '3.13.*' and sys_platform == 'emscripten' and extra != 'extra-16-surf-new-backend-cpu' and extra == 'extra-16-surf-new-backend-cu126' and extra != 'extra-16-surf-new-backend-cu128'",
     "python_version < '0'",
     "python_version < '0'",
@@ -659,6 +714,9 @@ resolution-markers = [
     "python_version < '0'",
     "python_version < '0'",
     "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
     "python_full_version == '3.13.*' and sys_platform != 'emscripten' and sys_platform != 'linux' and sys_platform != 'win32' and extra != 'extra-16-surf-new-backend-cpu' and extra == 'extra-16-surf-new-backend-cu126' and extra != 'extra-16-surf-new-backend-cu128'",
     "python_version < '0'",
     "python_version < '0'",
@@ -693,6 +751,9 @@ resolution-markers = [
     "python_version < '0'",
     "python_version < '0'",
     "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
     "python_full_version < '3.13' and sys_platform != 'linux' and sys_platform != 'win32' and extra != 'extra-16-surf-new-backend-cpu' and extra == 'extra-16-surf-new-backend-cu126' and extra != 'extra-16-surf-new-backend-cu128'",
     "python_version < '0'",
     "python_version < '0'",
@@ -727,6 +788,9 @@ resolution-markers = [
     "python_version < '0'",
     "python_version < '0'",
     "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
     "python_full_version < '3.13' and sys_platform == 'win32' and extra != 'extra-16-surf-new-backend-cpu' and extra == 'extra-16-surf-new-backend-cu126' and extra != 'extra-16-surf-new-backend-cu128'",
     "python_version < '0'",
     "python_version < '0'",
@@ -772,6 +836,10 @@ resolution-markers = [
     "python_version < '0'",
     "python_version < '0'",
     "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
     "python_full_version >= '3.14' and sys_platform == 'linux' and extra == 'extra-16-surf-new-backend-cpu' and extra != 'extra-16-surf-new-backend-cu126' and extra != 'extra-16-surf-new-backend-cu128'",
     "python_version < '0'",
     "python_version < '0'",
@@ -806,6 +874,9 @@ resolution-markers = [
     "python_version < '0'",
     "python_version < '0'",
     "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
     "python_full_version == '3.13.*' and sys_platform == 'linux' and extra == 'extra-16-surf-new-backend-cpu' and extra != 'extra-16-surf-new-backend-cu126' and extra != 'extra-16-surf-new-backend-cu128'",
     "python_version < '0'",
     "python_version < '0'",
@@ -840,6 +911,9 @@ resolution-markers = [
     "python_version < '0'",
     "python_version < '0'",
     "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
     "python_full_version < '3.13' and sys_platform == 'linux' and extra == 'extra-16-surf-new-backend-cpu' and extra != 'extra-16-surf-new-backend-cu126' and extra != 'extra-16-surf-new-backend-cu128'",
     "python_version < '0'",
     "python_version < '0'",
@@ -874,6 +948,9 @@ resolution-markers = [
     "python_version < '0'",
     "python_version < '0'",
     "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
     "python_full_version >= '3.14' and sys_platform == 'win32' and extra == 'extra-16-surf-new-backend-cpu' and extra != 'extra-16-surf-new-backend-cu126' and extra != 'extra-16-surf-new-backend-cu128'",
     "python_version < '0'",
     "python_version < '0'",
@@ -908,6 +985,9 @@ resolution-markers = [
     "python_version < '0'",
     "python_version < '0'",
     "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
     "python_full_version >= '3.14' and sys_platform == 'emscripten' and extra == 'extra-16-surf-new-backend-cpu' and extra != 'extra-16-surf-new-backend-cu126' and extra != 'extra-16-surf-new-backend-cu128'",
     "python_version < '0'",
     "python_version < '0'",
@@ -942,6 +1022,9 @@ resolution-markers = [
     "python_version < '0'",
     "python_version < '0'",
     "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
     "python_full_version >= '3.14' and sys_platform != 'emscripten' and sys_platform != 'linux' and sys_platform != 'win32' and extra == 'extra-16-surf-new-backend-cpu' and extra != 'extra-16-surf-new-backend-cu126' and extra != 'extra-16-surf-new-backend-cu128'",
     "python_version < '0'",
     "python_version < '0'",
@@ -976,6 +1059,9 @@ resolution-markers = [
     "python_version < '0'",
     "python_version < '0'",
     "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
     "python_full_version == '3.13.*' and sys_platform == 'win32' and extra == 'extra-16-surf-new-backend-cpu' and extra != 'extra-16-surf-new-backend-cu126' and extra != 'extra-16-surf-new-backend-cu128'",
     "python_version < '0'",
     "python_version < '0'",
@@ -1010,6 +1096,9 @@ resolution-markers = [
     "python_version < '0'",
     "python_version < '0'",
     "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
     "python_full_version == '3.13.*' and sys_platform == 'emscripten' and extra == 'extra-16-surf-new-backend-cpu' and extra != 'extra-16-surf-new-backend-cu126' and extra != 'extra-16-surf-new-backend-cu128'",
     "python_version < '0'",
     "python_version < '0'",
@@ -1044,6 +1133,9 @@ resolution-markers = [
     "python_version < '0'",
     "python_version < '0'",
     "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
     "python_full_version == '3.13.*' and sys_platform != 'emscripten' and sys_platform != 'linux' and sys_platform != 'win32' and extra == 'extra-16-surf-new-backend-cpu' and extra != 'extra-16-surf-new-backend-cu126' and extra != 'extra-16-surf-new-backend-cu128'",
     "python_version < '0'",
     "python_version < '0'",
@@ -1078,6 +1170,9 @@ resolution-markers = [
     "python_version < '0'",
     "python_version < '0'",
     "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
     "python_full_version < '3.13' and sys_platform != 'linux' and sys_platform != 'win32' and extra == 'extra-16-surf-new-backend-cpu' and extra != 'extra-16-surf-new-backend-cu126' and extra != 'extra-16-surf-new-backend-cu128'",
     "python_version < '0'",
     "python_version < '0'",
@@ -1112,6 +1207,9 @@ resolution-markers = [
     "python_version < '0'",
     "python_version < '0'",
     "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
     "python_full_version < '3.13' and sys_platform == 'win32' and extra == 'extra-16-surf-new-backend-cpu' and extra != 'extra-16-surf-new-backend-cu126' and extra != 'extra-16-surf-new-backend-cu128'",
     "python_version < '0'",
     "python_version < '0'",
@@ -1157,6 +1255,10 @@ resolution-markers = [
     "python_version < '0'",
     "python_version < '0'",
     "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
     "python_full_version >= '3.14' and sys_platform == 'win32' and extra != 'extra-16-surf-new-backend-cpu' and extra != 'extra-16-surf-new-backend-cu126' and extra != 'extra-16-surf-new-backend-cu128'",
     "python_version < '0'",
     "python_version < '0'",
@@ -1191,6 +1293,9 @@ resolution-markers = [
     "python_version < '0'",
     "python_version < '0'",
     "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
     "python_full_version >= '3.14' and sys_platform == 'emscripten' and extra != 'extra-16-surf-new-backend-cpu' and extra != 'extra-16-surf-new-backend-cu126' and extra != 'extra-16-surf-new-backend-cu128'",
     "python_version < '0'",
     "python_version < '0'",
@@ -1258,6 +1363,12 @@ resolution-markers = [
     "python_version < '0'",
     "python_version < '0'",
     "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
     "python_full_version >= '3.14' and sys_platform != 'emscripten' and sys_platform != 'win32' and extra != 'extra-16-surf-new-backend-cpu' and extra != 'extra-16-surf-new-backend-cu126' and extra != 'extra-16-surf-new-backend-cu128'",
     "python_version < '0'",
     "python_version < '0'",
@@ -1292,6 +1403,9 @@ resolution-markers = [
     "python_version < '0'",
     "python_version < '0'",
     "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
     "python_full_version == '3.13.*' and sys_platform == 'win32' and extra != 'extra-16-surf-new-backend-cpu' and extra != 'extra-16-surf-new-backend-cu126' and extra != 'extra-16-surf-new-backend-cu128'",
     "python_version < '0'",
     "python_version < '0'",
@@ -1326,6 +1440,9 @@ resolution-markers = [
     "python_version < '0'",
     "python_version < '0'",
     "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
     "python_full_version == '3.13.*' and sys_platform == 'emscripten' and extra != 'extra-16-surf-new-backend-cpu' and extra != 'extra-16-surf-new-backend-cu126' and extra != 'extra-16-surf-new-backend-cu128'",
     "python_version < '0'",
     "python_version < '0'",
@@ -1393,6 +1510,12 @@ resolution-markers = [
     "python_version < '0'",
     "python_version < '0'",
     "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
     "python_full_version == '3.13.*' and sys_platform != 'emscripten' and sys_platform != 'win32' and extra != 'extra-16-surf-new-backend-cpu' and extra != 'extra-16-surf-new-backend-cu126' and extra != 'extra-16-surf-new-backend-cu128'",
     "python_version < '0'",
     "python_version < '0'",
@@ -1460,6 +1583,12 @@ resolution-markers = [
     "python_version < '0'",
     "python_version < '0'",
     "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
     "python_full_version < '3.13' and sys_platform != 'win32' and extra != 'extra-16-surf-new-backend-cpu' and extra != 'extra-16-surf-new-backend-cu126' and extra != 'extra-16-surf-new-backend-cu128'",
     "python_version < '0'",
     "python_version < '0'",
@@ -1494,6 +1623,9 @@ resolution-markers = [
     "python_version < '0'",
     "python_version < '0'",
     "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
+    "python_version < '0'",
     "python_full_version < '3.13' and sys_platform == 'win32' and extra != 'extra-16-surf-new-backend-cpu' and extra != 'extra-16-surf-new-backend-cu126' and extra != 'extra-16-surf-new-backend-cu128'",
 ]
 conflicts = [[
@@ -10353,7 +10485,7 @@ wheels = [
 
 [[package]]
 name = "surf-new-backend"
-version = "0.0.31"
+version = "0.0.32"
 source = { editable = "." }
 dependencies = [
     { name = "alembic" },
diff --git a/surfsense_browser_extension/package.json b/surfsense_browser_extension/package.json
index 8dda0d82f..a2c25a602 100644
--- a/surfsense_browser_extension/package.json
+++ b/surfsense_browser_extension/package.json
@@ -1,7 +1,7 @@
 {
 	"name": "surfsense_browser_extension",
 	"displayName": "Surfsense Browser Extension",
-	"version": "0.0.31",
+	"version": "0.0.32",
 	"description": "Extension to collect Browsing History for SurfSense.",
 	"author": "https://github.com/MODSetter",
 	"engines": {
diff --git a/surfsense_desktop/package.json b/surfsense_desktop/package.json
index f12b9722c..629fe801d 100644
--- a/surfsense_desktop/package.json
+++ b/surfsense_desktop/package.json
@@ -1,7 +1,7 @@
 {
   "name": "surfsense-desktop",
   "productName": "SurfSense",
-  "version": "0.0.31",
+  "version": "0.0.32",
   "description": "SurfSense Desktop App",
   "main": "dist/main.js",
   "scripts": {
diff --git a/surfsense_evals/scripts/analyze_failure_timing.py b/surfsense_evals/scripts/analyze_failure_timing.py
index f4f8aedba..14b76852f 100644
--- a/surfsense_evals/scripts/analyze_failure_timing.py
+++ b/surfsense_evals/scripts/analyze_failure_timing.py
@@ -21,8 +21,7 @@ PDFS = REPO / "data" / "multimodal_doc" / "mmlongbench" / "pdfs"
 
 def main() -> None:
     rows = [
-        json.loads(line) for line in RAW.read_text(encoding="utf-8").splitlines()
-        if line.strip()
+        json.loads(line) for line in RAW.read_text(encoding="utf-8").splitlines() if line.strip()
     ]
 
     # 1) SSL clustering: failures by question index per arm
@@ -35,11 +34,19 @@ def main() -> None:
         arm_seen_count[arm] += 1
         qid_order[f"{arm}::{row['qid']}"] = idx
         err = row.get("error") or ""
-        cluster = "ssl" if "SSLError" in err else (
-            "empty" if not (row.get("raw_text") or "").strip() and not err else (
-                "5xx" if "502" in err or "503" in err else (
-                    "size_limit" if "exceeds" in err.lower() and "limit" in err.lower() else (
-                        "other_err" if err else "ok"
+        cluster = (
+            "ssl"
+            if "SSLError" in err
+            else (
+                "empty"
+                if not (row.get("raw_text") or "").strip() and not err
+                else (
+                    "5xx"
+                    if "502" in err or "503" in err
+                    else (
+                        "size_limit"
+                        if "exceeds" in err.lower() and "limit" in err.lower()
+                        else ("other_err" if err else "ok")
                     )
                 )
             )
@@ -100,19 +107,26 @@ def main() -> None:
         err = row.get("error") or ""
         empty = not (row.get("raw_text") or "").strip()
         if err or empty:
-            by_pdf[row["doc_id"]].append({
-                "arm": row["arm"],
-                "qid": row["qid"],
-                "err_kind": (
-                    "ssl" if "SSLError" in err
-                    else "size_limit" if "exceeds" in err.lower() and "limit" in err.lower()
-                    else "5xx" if "502" in err or "503" in err
-                    else "json_decode" if "JSONDecodeError" in err
-                    else "empty" if empty and not err
-                    else "other"
-                ),
-                "pages": row.get("pages"),
-            })
+            by_pdf[row["doc_id"]].append(
+                {
+                    "arm": row["arm"],
+                    "qid": row["qid"],
+                    "err_kind": (
+                        "ssl"
+                        if "SSLError" in err
+                        else "size_limit"
+                        if "exceeds" in err.lower() and "limit" in err.lower()
+                        else "5xx"
+                        if "502" in err or "503" in err
+                        else "json_decode"
+                        if "JSONDecodeError" in err
+                        else "empty"
+                        if empty and not err
+                        else "other"
+                    ),
+                    "pages": row.get("pages"),
+                }
+            )
     for doc, items in sorted(by_pdf.items(), key=lambda x: (-len(x[1]), x[0])):
         kinds = Counter(i["err_kind"] for i in items)
         arms = sorted({i["arm"] for i in items})
diff --git a/surfsense_evals/scripts/analyze_failures.py b/surfsense_evals/scripts/analyze_failures.py
index e7ace1e1b..f60038c00 100644
--- a/surfsense_evals/scripts/analyze_failures.py
+++ b/surfsense_evals/scripts/analyze_failures.py
@@ -12,12 +12,10 @@ Outputs (printed to stdout + written to `failures_n171.json`):
 from __future__ import annotations
 
 import json
-import re
 from collections import Counter, defaultdict
 from pathlib import Path
 from typing import Any
 
-
 REPO = Path(__file__).resolve().parents[1]
 RUN = REPO / "data" / "multimodal_doc" / "runs" / "2026-05-14T00-53-19Z" / "parser_compare"
 RAW = RUN / "raw.jsonl"
@@ -53,8 +51,7 @@ def _classify(error: str | None, raw_text: str) -> str:
 
 def main() -> None:
     rows = [
-        json.loads(line) for line in RAW.read_text(encoding="utf-8").splitlines()
-        if line.strip()
+        json.loads(line) for line in RAW.read_text(encoding="utf-8").splitlines() if line.strip()
     ]
 
     by_arm_failures: dict[str, list[dict]] = defaultdict(list)
@@ -123,7 +120,9 @@ def main() -> None:
     print("=" * 90)
     for entry in by_arm_failures.get("native_pdf", []):
         err = (entry["error"] or "(no error string)")[:240].replace("\n", " ")
-        print(f"  {entry['qid']}  doc={entry['doc_id']} pages={entry['pages']} cluster={entry['cluster']}")
+        print(
+            f"  {entry['qid']}  doc={entry['doc_id']} pages={entry['pages']} cluster={entry['cluster']}"
+        )
         print(f"    err: {err}")
 
     summary: dict[str, Any] = {
@@ -132,18 +131,13 @@ def main() -> None:
                 "n": n_per_arm[arm],
                 "failures": len(by_arm_failures[arm]),
                 "rate": len(by_arm_failures[arm]) / n_per_arm[arm],
-                "clusters": {
-                    cluster: len(items)
-                    for cluster, items in error_clusters[arm].items()
-                },
+                "clusters": {cluster: len(items) for cluster, items in error_clusters[arm].items()},
                 "rows": by_arm_failures[arm],
             }
             for arm in sorted(n_per_arm)
         },
         "per_pdf": {
-            pdf: [
-                {**r, "arm": r["arm"]} for r in failures
-            ]
+            pdf: [{**r, "arm": r["arm"]} for r in failures]
             for pdf, failures in by_pdf_failures.items()
         },
     }
diff --git a/surfsense_evals/scripts/check_extraction_sizes.py b/surfsense_evals/scripts/check_extraction_sizes.py
index 712e693cb..1755e9b6c 100644
--- a/surfsense_evals/scripts/check_extraction_sizes.py
+++ b/surfsense_evals/scripts/check_extraction_sizes.py
@@ -23,9 +23,7 @@ SAFE_CHARS = (CTX_TOKENS - PROMPT_OVERHEAD_TOKENS - MAX_OUTPUT_TOKENS) * CHARS_P
 
 def main() -> None:
     rows = [
-        json.loads(line)
-        for line in MAP.read_text(encoding="utf-8").splitlines()
-        if line.strip()
+        json.loads(line) for line in MAP.read_text(encoding="utf-8").splitlines() if line.strip()
     ]
 
     total = len(rows)
diff --git a/surfsense_evals/scripts/check_uploaded_status.py b/surfsense_evals/scripts/check_uploaded_status.py
index 7021ba83d..1903502ed 100644
--- a/surfsense_evals/scripts/check_uploaded_status.py
+++ b/surfsense_evals/scripts/check_uploaded_status.py
@@ -15,7 +15,6 @@ from pathlib import Path
 import httpx
 from dotenv import load_dotenv
 
-
 REPO = Path(__file__).resolve().parents[1]
 PDF_DIR = REPO / "data" / "multimodal_doc" / "mmlongbench" / "pdfs"
 
diff --git a/surfsense_evals/scripts/compute_adjusted_accuracy.py b/surfsense_evals/scripts/compute_adjusted_accuracy.py
index 13693c055..0cd4b3073 100644
--- a/surfsense_evals/scripts/compute_adjusted_accuracy.py
+++ b/surfsense_evals/scripts/compute_adjusted_accuracy.py
@@ -67,14 +67,18 @@ def classify(error: str | None, raw_text: str) -> str:
 
 def main() -> None:
     rows = [
-        json.loads(line) for line in RAW.read_text(encoding="utf-8").splitlines()
-        if line.strip()
+        json.loads(line) for line in RAW.read_text(encoding="utf-8").splitlines() if line.strip()
     ]
-    by_arm: dict[str, dict] = defaultdict(lambda: {
-        "n": 0, "correct": 0,
-        "transient_ssl_or_5xx": 0, "transient_empty": 0,
-        "intrinsic_limit": 0, "other_error": 0,
-    })
+    by_arm: dict[str, dict] = defaultdict(
+        lambda: {
+            "n": 0,
+            "correct": 0,
+            "transient_ssl_or_5xx": 0,
+            "transient_empty": 0,
+            "intrinsic_limit": 0,
+            "other_error": 0,
+        }
+    )
     for row in rows:
         arm = row["arm"]
         m = by_arm[arm]
@@ -86,7 +90,9 @@ def main() -> None:
         if kind != "ok":
             m[kind] += 1
 
-    print(f"{'arm':<25} {'raw acc%':>8} {'transient':>10} {'intrinsic':>10} {'other':>6} {'adj acc% (no transient)':>22}")
+    print(
+        f"{'arm':<25} {'raw acc%':>8} {'transient':>10} {'intrinsic':>10} {'other':>6} {'adj acc% (no transient)':>22}"
+    )
     print("-" * 88)
     for arm in sorted(by_arm):
         m = by_arm[arm]
@@ -96,9 +102,7 @@ def main() -> None:
         other = m["other_error"]
         usable = m["n"] - transient
         adj = m["correct"] / usable * 100 if usable else 0
-        print(
-            f"{arm:<25} {raw:>7.1f}% {transient:>10} {intrinsic:>10} {other:>6} {adj:>21.1f}%"
-        )
+        print(f"{arm:<25} {raw:>7.1f}% {transient:>10} {intrinsic:>10} {other:>6} {adj:>21.1f}%")
 
     print()
     print("transient   = SSLError / 502 / 503 / empty stream / mid-stream JSON decode (would")
diff --git a/surfsense_evals/scripts/compute_blog_extras.py b/surfsense_evals/scripts/compute_blog_extras.py
index abe88d08b..29922f54c 100644
--- a/surfsense_evals/scripts/compute_blog_extras.py
+++ b/surfsense_evals/scripts/compute_blog_extras.py
@@ -95,7 +95,7 @@ def _mcnemar_exact_pvalue(b: int, c: int) -> float:
     k = min(b, c)
     # Two-sided exact: 2 * P(X <= k) clipped at 1.0
     cdf = sum(_binom_coef(n, i) for i in range(k + 1))
-    p = 2.0 * cdf / (2 ** n)
+    p = 2.0 * cdf / (2**n)
     return min(1.0, p)
 
 
@@ -116,7 +116,7 @@ def _mcnemar_table(rows: list[dict]) -> dict:
     qids = sorted(by_qid)
     out: dict[str, dict] = {"arms": arms, "n_qids": len(qids), "pairs": []}
     for i, ai in enumerate(arms):
-        for aj in arms[i + 1:]:
+        for aj in arms[i + 1 :]:
             b = c = both = neither = 0
             for q in qids:
                 row = by_qid[q]
@@ -132,12 +132,17 @@ def _mcnemar_table(rows: list[dict]) -> dict:
                 else:
                     neither += 1
             p = _mcnemar_exact_pvalue(b, c)
-            out["pairs"].append({
-                "arm_i": ai, "arm_j": aj,
-                "b_i_only": b, "c_j_only": c,
-                "both_correct": both, "both_wrong": neither,
-                "p_value": p,
-            })
+            out["pairs"].append(
+                {
+                    "arm_i": ai,
+                    "arm_j": aj,
+                    "b_i_only": b,
+                    "c_j_only": c,
+                    "both_correct": both,
+                    "both_wrong": neither,
+                    "p_value": p,
+                }
+            )
     return out
 
 
@@ -154,9 +159,7 @@ def _per_pdf_stats(rows: list[dict]) -> dict[str, dict]:
         arm = r["arm"]
         pdf = r["doc_id"]
         graded = r.get("graded") or {}
-        bucket.setdefault(arm, {}).setdefault(pdf, []).append(
-            bool(graded.get("correct"))
-        )
+        bucket.setdefault(arm, {}).setdefault(pdf, []).append(bool(graded.get("correct")))
 
     out: dict[str, dict] = {}
     for arm, pdfs in bucket.items():
@@ -207,7 +210,8 @@ def _per_arm_latency(rows: list[dict]) -> dict[str, dict]:
             # Coefficient of variation: std / mean (unitless tail-fatness).
             "cv": (
                 statistics.stdev(lats) / statistics.mean(lats)
-                if len(lats) > 1 and statistics.mean(lats) > 0 else 0.0
+                if len(lats) > 1 and statistics.mean(lats) > 0
+                else 0.0
             ),
         }
     return out
@@ -259,24 +263,30 @@ def _print_latency(title: str, lat: dict[str, dict]) -> None:
     print()
     print(title)
     print("-" * len(title))
-    header = (f"{'arm':<25} {'n':>4} {'mean':>7} {'std':>7} "
-              f"{'p50':>7} {'p90':>7} {'p95':>7} {'p99':>7} {'max':>7} {'CV':>5}")
+    header = (
+        f"{'arm':<25} {'n':>4} {'mean':>7} {'std':>7} "
+        f"{'p50':>7} {'p90':>7} {'p95':>7} {'p99':>7} {'max':>7} {'CV':>5}"
+    )
     print(header)
     print("-" * len(header))
     for arm in sorted(lat, key=lambda a: lat[a]["mean_s"]):
         s = lat[arm]
-        print(f"{arm:<25} {s['n']:>4} "
-              f"{s['mean_s']:>6.1f}s {s['std_s']:>6.1f}s "
-              f"{s['p50_s']:>6.1f}s {s['p90_s']:>6.1f}s {s['p95_s']:>6.1f}s "
-              f"{s['p99_s']:>6.1f}s {s['max_s']:>6.1f}s {s['cv']:>5.2f}")
+        print(
+            f"{arm:<25} {s['n']:>4} "
+            f"{s['mean_s']:>6.1f}s {s['std_s']:>6.1f}s "
+            f"{s['p50_s']:>6.1f}s {s['p90_s']:>6.1f}s {s['p95_s']:>6.1f}s "
+            f"{s['p99_s']:>6.1f}s {s['max_s']:>6.1f}s {s['cv']:>5.2f}"
+        )
 
 
 def _print_tokens(title: str, toks: dict[str, dict]) -> None:
     print()
     print(title)
     print("-" * len(title))
-    header = (f"{'arm':<25} {'in mean':>9} {'in p50':>9} {'in p95':>9} {'in max':>9}"
-              f"  {'out mean':>9} {'out p95':>9}")
+    header = (
+        f"{'arm':<25} {'in mean':>9} {'in p50':>9} {'in p95':>9} {'in max':>9}"
+        f"  {'out mean':>9} {'out p95':>9}"
+    )
     print(header)
     print("-" * len(header))
     for arm in sorted(toks):
@@ -285,25 +295,31 @@ def _print_tokens(title: str, toks: dict[str, dict]) -> None:
         eout = e.get("output")
         if not ein:
             continue
-        print(f"{arm:<25} "
-              f"{ein['mean']:>9,.0f} {ein['p50']:>9,.0f} {ein['p95']:>9,.0f} {ein['max']:>9,.0f}  "
-              f"{(eout or {}).get('mean', 0):>9,.0f} {(eout or {}).get('p95', 0):>9,.0f}")
+        print(
+            f"{arm:<25} "
+            f"{ein['mean']:>9,.0f} {ein['p50']:>9,.0f} {ein['p95']:>9,.0f} {ein['max']:>9,.0f}  "
+            f"{(eout or {}).get('mean', 0):>9,.0f} {(eout or {}).get('p95', 0):>9,.0f}"
+        )
 
 
 def _print_pdf_var(title: str, var: dict[str, dict]) -> None:
     print()
     print(title)
     print("-" * len(title))
-    header = (f"{'arm':<25} {'n_pdfs':>7} {'mean':>7} {'std':>7} {'min':>7} "
-              f"{'p25':>7} {'p50':>7} {'p75':>7} {'max':>7} {'#0%':>5} {'#100%':>6}")
+    header = (
+        f"{'arm':<25} {'n_pdfs':>7} {'mean':>7} {'std':>7} {'min':>7} "
+        f"{'p25':>7} {'p50':>7} {'p75':>7} {'max':>7} {'#0%':>5} {'#100%':>6}"
+    )
     print(header)
     print("-" * len(header))
     for arm in sorted(var, key=lambda a: -var[a]["mean"]):
         s = var[arm]
-        print(f"{arm:<25} {s['n_pdfs']:>7} "
-              f"{s['mean']*100:>6.1f}% {s['std']*100:>6.1f}% {s['min']*100:>6.1f}% "
-              f"{s['p25']*100:>6.1f}% {s['p50']*100:>6.1f}% {s['p75']*100:>6.1f}% "
-              f"{s['max']*100:>6.1f}% {s['n_pdfs_zero']:>5} {s['n_pdfs_perfect']:>6}")
+        print(
+            f"{arm:<25} {s['n_pdfs']:>7} "
+            f"{s['mean'] * 100:>6.1f}% {s['std'] * 100:>6.1f}% {s['min'] * 100:>6.1f}% "
+            f"{s['p25'] * 100:>6.1f}% {s['p50'] * 100:>6.1f}% {s['p75'] * 100:>6.1f}% "
+            f"{s['max'] * 100:>6.1f}% {s['n_pdfs_zero']:>5} {s['n_pdfs_perfect']:>6}"
+        )
 
 
 def _print_mcnemar(title: str, table: dict) -> None:
@@ -311,8 +327,10 @@ def _print_mcnemar(title: str, table: dict) -> None:
     print(title)
     print("-" * len(title))
     print(f"n_qids on which all arms have a graded row: {table['n_qids']}")
-    header = (f"{'arm_i':<25} {'arm_j':<25} {'b':>4} {'c':>4} "
-              f"{'both ok':>8} {'both wr':>8} {'p (2-sided)':>13} {'sig':>4}")
+    header = (
+        f"{'arm_i':<25} {'arm_j':<25} {'b':>4} {'c':>4} "
+        f"{'both ok':>8} {'both wr':>8} {'p (2-sided)':>13} {'sig':>4}"
+    )
     print(header)
     print("-" * len(header))
     for pair in sorted(table["pairs"], key=lambda p: p["p_value"]):
@@ -323,10 +341,12 @@ def _print_mcnemar(title: str, table: dict) -> None:
             sig = "**"
         elif pair["p_value"] < 0.05:
             sig = "*"
-        print(f"{pair['arm_i']:<25} {pair['arm_j']:<25} "
-              f"{pair['b_i_only']:>4} {pair['c_j_only']:>4} "
-              f"{pair['both_correct']:>8} {pair['both_wrong']:>8} "
-              f"{pair['p_value']:>13.4f} {sig:>4}")
+        print(
+            f"{pair['arm_i']:<25} {pair['arm_j']:<25} "
+            f"{pair['b_i_only']:>4} {pair['c_j_only']:>4} "
+            f"{pair['both_correct']:>8} {pair['both_wrong']:>8} "
+            f"{pair['p_value']:>13.4f} {sig:>4}"
+        )
 
 
 # ---------------------------------------------------------------------------
diff --git a/surfsense_evals/scripts/compute_post_retry_accuracy.py b/surfsense_evals/scripts/compute_post_retry_accuracy.py
index 4c8c47672..29007ed41 100644
--- a/surfsense_evals/scripts/compute_post_retry_accuracy.py
+++ b/surfsense_evals/scripts/compute_post_retry_accuracy.py
@@ -47,9 +47,7 @@ def _row_key(row: dict) -> tuple[str, str]:
 def _is_failure(row: dict) -> bool:
     if row.get("error"):
         return True
-    if not (row.get("raw_text") or "").strip():
-        return True
-    return False
+    return bool(not (row.get("raw_text") or "").strip())
 
 
 def _summarise(rows_by_arm: dict[str, list[dict]]) -> dict[str, dict]:
@@ -80,9 +78,11 @@ def _print_table(title: str, summary: dict[str, dict]) -> None:
     # stable order: highest accuracy first
     arms_sorted = sorted(summary.items(), key=lambda kv: -kv[1]["accuracy"])
     for arm, s in arms_sorted:
-        print(f"{arm:<25} {s['n']:>4} {s['n_correct']:>7} "
-              f"{s['accuracy']*100:>6.1f}% {s['f1_mean']*100:>6.1f}% "
-              f"{s['n_failures']:>6} {s['failure_rate']*100:>6.1f}%")
+        print(
+            f"{arm:<25} {s['n']:>4} {s['n_correct']:>7} "
+            f"{s['accuracy'] * 100:>6.1f}% {s['f1_mean'] * 100:>6.1f}% "
+            f"{s['n_failures']:>6} {s['failure_rate'] * 100:>6.1f}%"
+        )
 
 
 def main() -> int:
@@ -105,9 +105,7 @@ def main() -> int:
     raw_rows = _read_jsonl(raw_path)
     retry_rows = _read_jsonl(retry_path)
 
-    retry_by_key: dict[tuple[str, str], dict] = {
-        _row_key(r): r for r in retry_rows
-    }
+    retry_by_key: dict[tuple[str, str], dict] = {_row_key(r): r for r in retry_rows}
 
     merged_rows: list[dict] = []
     n_replaced_recovered = 0
diff --git a/surfsense_evals/scripts/inspect_first30.py b/surfsense_evals/scripts/inspect_first30.py
index e06c6c029..b3caedca6 100644
--- a/surfsense_evals/scripts/inspect_first30.py
+++ b/surfsense_evals/scripts/inspect_first30.py
@@ -44,10 +44,7 @@ def main() -> None:
         f"questions covering first 30 docs: total={len(qs_in_30)}  "
         f"answerable={answerable}  unanswerable={unanswerable}"
     )
-    print(
-        f"avg Qs/PDF: {len(qs_in_30) / 30:.1f}  "
-        f"answerable/PDF: {answerable / 30:.1f}"
-    )
+    print(f"avg Qs/PDF: {len(qs_in_30) / 30:.1f}  answerable/PDF: {answerable / 30:.1f}")
     print(f"format mix in scope: {dict(fmts)}")
     print()
     print("25 new PDFs to ingest:")
diff --git a/surfsense_evals/scripts/patch_manifest_for_parallel_ingest.py b/surfsense_evals/scripts/patch_manifest_for_parallel_ingest.py
index e1a2edc65..8cfb13eb7 100644
--- a/surfsense_evals/scripts/patch_manifest_for_parallel_ingest.py
+++ b/surfsense_evals/scripts/patch_manifest_for_parallel_ingest.py
@@ -27,7 +27,6 @@ from __future__ import annotations
 import json
 from pathlib import Path
 
-
 REPO = Path(__file__).resolve().parents[1]
 MAP_PATH = REPO / "data" / "multimodal_doc" / "maps" / "mmlongbench_doc_map.jsonl"
 PDF_DIR = REPO / "data" / "multimodal_doc" / "mmlongbench" / "pdfs"
diff --git a/surfsense_evals/scripts/peek_crag_run.py b/surfsense_evals/scripts/peek_crag_run.py
index 225e5ec98..0720e24cf 100644
--- a/surfsense_evals/scripts/peek_crag_run.py
+++ b/surfsense_evals/scripts/peek_crag_run.py
@@ -10,26 +10,24 @@ from collections import defaultdict
 def main() -> None:
     raw_path = sorted(glob.glob("data/research/runs/*/crag/raw.jsonl"))[-1]
     print(f"Reading: {raw_path}")
-    rows = [json.loads(line) for line in open(raw_path, encoding="utf-8") if line.strip()]
+    with open(raw_path, encoding="utf-8") as fh:
+        rows = [json.loads(line) for line in fh if line.strip()]
     by_q: dict[str, dict[str, dict]] = defaultdict(dict)
     for r in rows:
         by_q[r["qid"]][r["arm"]] = r
 
     for qid, arms in list(by_q.items()):
         b = arms.get("bare_llm", {})
-        l = arms.get("long_context", {})
+        lc = arms.get("long_context", {})
         s = arms.get("surfsense", {})
         print(f"\n=== {qid} ({b.get('domain')}/{b.get('question_type')}) ===")
         print(f"  question: {b.get('extra', {}).get('question', '?')!r}")
         print(f"  gold: {b.get('gold')!r}")
-        for arm_name, a in (("bare_llm", b), ("long_context", l), ("surfsense", s)):
+        for arm_name, a in (("bare_llm", b), ("long_context", lc), ("surfsense", s)):
             grade = a.get("graded", {})
             text = (a.get("raw_text") or "").strip()
             tail = text[-200:] if text else ""
-            print(
-                f"  [{arm_name}] grade={grade.get('grade')} "
-                f"method={grade.get('method')}"
-            )
+            print(f"  [{arm_name}] grade={grade.get('grade')} method={grade.get('method')}")
             print(f"    -> {tail!r}")
 
 
diff --git a/surfsense_evals/scripts/peek_disagreements.py b/surfsense_evals/scripts/peek_disagreements.py
index c0fe0acd9..b6497570e 100644
--- a/surfsense_evals/scripts/peek_disagreements.py
+++ b/surfsense_evals/scripts/peek_disagreements.py
@@ -10,7 +10,8 @@ from collections import defaultdict
 def main() -> None:
     raw_path = sorted(glob.glob("data/research/runs/*/crag/raw.jsonl"))[-1]
     print(f"Reading: {raw_path}")
-    rows = [json.loads(line) for line in open(raw_path, encoding="utf-8") if line.strip()]
+    with open(raw_path, encoding="utf-8") as fh:
+        rows = [json.loads(line) for line in fh if line.strip()]
     by_q: dict[str, dict[str, dict]] = defaultdict(dict)
     for r in rows:
         by_q[r["qid"]][r["arm"]] = r
diff --git a/surfsense_evals/scripts/retry_failed_questions.py b/surfsense_evals/scripts/retry_failed_questions.py
index 7cc9478e0..d65f9f0fb 100644
--- a/surfsense_evals/scripts/retry_failed_questions.py
+++ b/surfsense_evals/scripts/retry_failed_questions.py
@@ -106,9 +106,7 @@ def _is_failure_row(row: dict[str, Any]) -> bool:
 
     if row.get("error"):
         return True
-    if not (row.get("raw_text") or "").strip():
-        return True
-    return False
+    return bool(not (row.get("raw_text") or "").strip())
 
 
 @dataclass
@@ -134,17 +132,19 @@ def _load_failed_rows(raw_path: Path) -> list[FailedRow]:
             row = json.loads(line)
             if not _is_failure_row(row):
                 continue
-            out.append(FailedRow(
-                arm=str(row["arm"]),
-                qid=str(row["qid"]),
-                doc_id=str(row["doc_id"]),
-                answer_format=str(row.get("answer_format") or ""),
-                gold=str(row.get("gold") or ""),
-                pages=int(row.get("pages") or 0),
-                document_id=row.get("document_id"),
-                original_error=row.get("error"),
-                original_row=row,
-            ))
+            out.append(
+                FailedRow(
+                    arm=str(row["arm"]),
+                    qid=str(row["qid"]),
+                    doc_id=str(row["doc_id"]),
+                    answer_format=str(row.get("answer_format") or ""),
+                    gold=str(row.get("gold") or ""),
+                    pages=int(row.get("pages") or 0),
+                    document_id=row.get("document_id"),
+                    original_error=row.get("error"),
+                    original_row=row,
+                )
+            )
     return out
 
 
@@ -204,8 +204,12 @@ def _qid_index(qid: str) -> int:
 
 
 def _build_native_request(
-    qid: str, question: str, answer_format: str, pdf_path: Path,
-    *, max_output_tokens: int,
+    qid: str,
+    question: str,
+    answer_format: str,
+    pdf_path: Path,
+    *,
+    max_output_tokens: int,
 ) -> ArmRequest:
     return ArmRequest(
         question_id=qid,
@@ -216,12 +220,14 @@ def _build_native_request(
 
 
 def _build_lc_request(
-    qid: str, question: str, answer_format: str, doc_id: str, md_path: Path,
+    qid: str,
+    question: str,
+    answer_format: str,
+    doc_id: str,
+    md_path: Path,
 ) -> ArmRequest:
     if not md_path.exists():
-        raise FileNotFoundError(
-            f"Missing parser extraction at {md_path}; cannot retry LC arm."
-        )
+        raise FileNotFoundError(f"Missing parser extraction at {md_path}; cannot retry LC arm.")
     markdown = md_path.read_text(encoding="utf-8")
     return ArmRequest(
         question_id=qid,
@@ -258,7 +264,9 @@ class RetryOutcome:
 
 
 async def _retry_one(
-    arm_obj: Any, request: ArmRequest, *,
+    arm_obj: Any,
+    request: ArmRequest,
+    *,
     arm_name: str,
     qid: str,
     max_attempts: int,
@@ -276,31 +284,44 @@ async def _retry_one(
         attempt_error = result.error
         if not attempt_error and not raw_text:
             attempt_error = "EmptyResponse: stream ended with no text"
-        attempts.append(AttemptLog(
-            attempt=attempt,
-            started_iso=started_iso,
-            latency_ms=latency_ms,
-            error=attempt_error,
-            raw_text_chars=len(raw_text),
-        ))
+        attempts.append(
+            AttemptLog(
+                attempt=attempt,
+                started_iso=started_iso,
+                latency_ms=latency_ms,
+                error=attempt_error,
+                raw_text_chars=len(raw_text),
+            )
+        )
         final = result
         if not attempt_error and raw_text:
             return RetryOutcome(
-                arm=arm_name, qid=qid, attempts=attempts,
-                final_result=result, recovered=True,
+                arm=arm_name,
+                qid=qid,
+                attempts=attempts,
+                final_result=result,
+                recovered=True,
             )
         if attempt < max_attempts:
             delay = min(max_delay, base_delay * (2 ** (attempt - 1)))
             delay = delay * (0.5 + random.random())
             logger.info(
                 "[%s::%s] attempt %d/%d failed (%s); sleeping %.1fs",
-                arm_name, qid, attempt, max_attempts, attempt_error, delay,
+                arm_name,
+                qid,
+                attempt,
+                max_attempts,
+                attempt_error,
+                delay,
             )
             await asyncio.sleep(delay)
     assert final is not None
     return RetryOutcome(
-        arm=arm_name, qid=qid, attempts=attempts,
-        final_result=final, recovered=False,
+        arm=arm_name,
+        qid=qid,
+        attempts=attempts,
+        final_result=final,
+        recovered=False,
     )
 
 
@@ -367,7 +388,8 @@ async def _run(args: argparse.Namespace) -> int:
         by_arm_count[f.arm] = by_arm_count.get(f.arm, 0) + 1
     logger.info(
         "Loaded %d failed rows across %d arms: %s",
-        len(failed), len(by_arm_count),
+        len(failed),
+        len(by_arm_count),
         ", ".join(f"{a}={n}" for a, n in sorted(by_arm_count.items())),
     )
 
@@ -385,7 +407,8 @@ async def _run(args: argparse.Namespace) -> int:
         engine=PdfEngine(args.pdf_engine),
     )
     native_arm = NativePdfArm(
-        provider=native_provider, max_output_tokens=args.max_output_tokens,
+        provider=native_provider,
+        max_output_tokens=args.max_output_tokens,
     )
 
     lc_arms: dict[str, BareLlmArm] = {}
@@ -415,7 +438,8 @@ async def _run(args: argparse.Namespace) -> int:
         if qrow is None:
             logger.error(
                 "Could not find question text for %s (idx %d) — skipping",
-                f.doc_id, q_idx,
+                f.doc_id,
+                q_idx,
             )
             continue
         question_text = str(qrow.get("question") or "").strip()
@@ -428,11 +452,14 @@ async def _run(args: argparse.Namespace) -> int:
 
         if f.arm == "native_pdf":
             pdf_path = Path(map_row["pdf_path"])
-            if not pdf_path.exists():
+            if not await asyncio.to_thread(pdf_path.exists):
                 logger.error("PDF missing on disk: %s — skipping", pdf_path)
                 continue
             request = _build_native_request(
-                f.qid, question_text, answer_format, pdf_path,
+                f.qid,
+                question_text,
+                answer_format,
+                pdf_path,
                 max_output_tokens=args.max_output_tokens,
             )
             arm_obj = native_arm
@@ -442,11 +469,16 @@ async def _run(args: argparse.Namespace) -> int:
             if not md_path_str or ext_blob.get("status") != "ok":
                 logger.error(
                     "Missing extraction for %s on %s — cannot retry; skipping",
-                    f.arm, f.doc_id,
+                    f.arm,
+                    f.doc_id,
                 )
                 continue
             request = _build_lc_request(
-                f.qid, question_text, answer_format, f.doc_id, Path(md_path_str),
+                f.qid,
+                question_text,
+                answer_format,
+                f.doc_id,
+                Path(md_path_str),
             )
             arm_obj = lc_arms[f.arm]
         else:
@@ -454,13 +486,17 @@ async def _run(args: argparse.Namespace) -> int:
             continue
 
         plan.append((f, request, arm_obj))
-        coros.append(_retry_one(
-            arm_obj, request,
-            arm_name=f.arm, qid=f.qid,
-            max_attempts=args.max_attempts,
-            base_delay=args.base_delay,
-            max_delay=args.max_delay,
-        ))
+        coros.append(
+            _retry_one(
+                arm_obj,
+                request,
+                arm_name=f.arm,
+                qid=f.qid,
+                max_attempts=args.max_attempts,
+                base_delay=args.base_delay,
+                max_delay=args.max_delay,
+            )
+        )
 
     if not coros:
         logger.warning("Nothing to retry after request building.")
@@ -469,13 +505,17 @@ async def _run(args: argparse.Namespace) -> int:
     logger.info(
         "Retrying %d failed rows with up to %d attempts each "
         "(base_delay=%.1fs, max_delay=%.1fs, concurrency=%d).",
-        len(coros), args.max_attempts, args.base_delay, args.max_delay,
+        len(coros),
+        args.max_attempts,
+        args.base_delay,
+        args.max_delay,
         args.concurrency,
     )
 
     started = time.monotonic()
     outcomes: list[RetryOutcome] = await _gather_with_limit(
-        coros, concurrency=args.concurrency,
+        coros,
+        concurrency=args.concurrency,
     )
     elapsed = time.monotonic() - started
     logger.info("Retry pass finished in %.1fs.", elapsed)
@@ -491,12 +531,8 @@ async def _run(args: argparse.Namespace) -> int:
         for (f, _req, _arm_obj), outcome in zip(plan, outcomes, strict=True):
             per_arm_total[outcome.arm] = per_arm_total.get(outcome.arm, 0) + 1
             if outcome.recovered:
-                per_arm_recovered[outcome.arm] = (
-                    per_arm_recovered.get(outcome.arm, 0) + 1
-                )
-            per_arm_attempts_dist.setdefault(outcome.arm, []).append(
-                len(outcome.attempts)
-            )
+                per_arm_recovered[outcome.arm] = per_arm_recovered.get(outcome.arm, 0) + 1
+            per_arm_attempts_dist.setdefault(outcome.arm, []).append(len(outcome.attempts))
 
             g = grade(
                 pred=extract_freeform_answer(outcome.final_result.raw_text or ""),
@@ -557,12 +593,11 @@ async def _run(args: argparse.Namespace) -> int:
             arm: {
                 "tried": per_arm_total.get(arm, 0),
                 "recovered": per_arm_recovered.get(arm, 0),
-                "still_failed": (
-                    per_arm_total.get(arm, 0) - per_arm_recovered.get(arm, 0)
-                ),
+                "still_failed": (per_arm_total.get(arm, 0) - per_arm_recovered.get(arm, 0)),
                 "recovery_rate": (
                     per_arm_recovered.get(arm, 0) / per_arm_total[arm]
-                    if per_arm_total.get(arm) else 0.0
+                    if per_arm_total.get(arm)
+                    else 0.0
                 ),
                 "attempts_distribution": sorted(per_arm_attempts_dist.get(arm, [])),
             }
@@ -595,8 +630,7 @@ async def _run(args: argparse.Namespace) -> int:
     rec_total = sum(per_arm_recovered.values())
     rate_total = (rec_total / total * 100) if total else 0.0
     print("-" * len(header))
-    print(f"{'TOTAL':<25} {total:>6} {rec_total:>10} {total - rec_total:>11} "
-          f"{rate_total:>6.1f}%")
+    print(f"{'TOTAL':<25} {total:>6} {rec_total:>10} {total - rec_total:>11} {rate_total:>6.1f}%")
     print()
     print(f"Wrote {out_path.relative_to(REPO)}")
     print(f"Wrote {summary_path.relative_to(REPO)}")
@@ -606,27 +640,37 @@ async def _run(args: argparse.Namespace) -> int:
 def main() -> None:
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument(
-        "--run-id", default="2026-05-14T00-53-19Z",
+        "--run-id",
+        default="2026-05-14T00-53-19Z",
         help="Run timestamp under data/multimodal_doc/runs/. Default is the "
-             "n=171 production run we wrote up in the blog.",
+        "n=171 production run we wrote up in the blog.",
     )
     parser.add_argument("--max-attempts", type=int, default=5)
-    parser.add_argument("--base-delay", type=float, default=1.0,
-                        help="Base seconds for exponential backoff (default 1s).")
-    parser.add_argument("--max-delay", type=float, default=30.0,
-                        help="Cap on per-retry sleep (default 30s).")
-    parser.add_argument("--concurrency", type=int, default=2,
-                        help="Parallel retries in flight (default 2 — keep low "
-                             "to avoid the same transport stress that caused "
-                             "the original failures).")
+    parser.add_argument(
+        "--base-delay",
+        type=float,
+        default=1.0,
+        help="Base seconds for exponential backoff (default 1s).",
+    )
+    parser.add_argument(
+        "--max-delay", type=float, default=30.0, help="Cap on per-retry sleep (default 30s)."
+    )
+    parser.add_argument(
+        "--concurrency",
+        type=int,
+        default=2,
+        help="Parallel retries in flight (default 2 — keep low "
+        "to avoid the same transport stress that caused "
+        "the original failures).",
+    )
     parser.add_argument("--llm-model", default="anthropic/claude-sonnet-4.5")
-    parser.add_argument("--pdf-engine", default="native",
-                        choices=[e.value for e in PdfEngine])
+    parser.add_argument("--pdf-engine", default="native", choices=[e.value for e in PdfEngine])
     parser.add_argument("--max-output-tokens", type=int, default=512)
     parser.add_argument(
-        "--include-surfsense", action="store_true",
+        "--include-surfsense",
+        action="store_true",
         help="Also retry surfsense_agentic failures (requires backend + celery up). "
-             "Default is to skip them since the n=171 run had 0 SurfSense failures.",
+        "Default is to skip them since the n=171 run had 0 SurfSense failures.",
     )
     args = parser.parse_args()
     raise SystemExit(asyncio.run(_run(args)))
diff --git a/surfsense_evals/scripts/summarise_crag_run.py b/surfsense_evals/scripts/summarise_crag_run.py
index 646fb6a97..d15c4996f 100644
--- a/surfsense_evals/scripts/summarise_crag_run.py
+++ b/surfsense_evals/scripts/summarise_crag_run.py
@@ -11,7 +11,8 @@ def main() -> None:
     if not runs:
         print("(no CRAG runs found)")
         return
-    m = json.load(open(runs[-1], encoding="utf-8"))
+    with open(runs[-1], encoding="utf-8") as fh:
+        m = json.load(fh)
     metrics = m["metrics"]
 
     print(f"Reading: {runs[-1]}")
@@ -22,12 +23,12 @@ def main() -> None:
         d = metrics[arm]
         print(
             f"{arm:14s}: "
-            f"acc={d['accuracy']*100:5.1f}% (Wilson 95% CI "
-            f"{d['ci_low']*100:.1f}-{d['ci_high']*100:.1f}) | "
-            f"correct={d['correct_rate']*100:5.1f}% "
-            f"missing={d['missing_rate']*100:5.1f}% "
-            f"incorrect={d['incorrect_rate']*100:5.1f}% | "
-            f"truth={d['truthfulness_score']*100:+5.1f}%"
+            f"acc={d['accuracy'] * 100:5.1f}% (Wilson 95% CI "
+            f"{d['ci_low'] * 100:.1f}-{d['ci_high'] * 100:.1f}) | "
+            f"correct={d['correct_rate'] * 100:5.1f}% "
+            f"missing={d['missing_rate'] * 100:5.1f}% "
+            f"incorrect={d['incorrect_rate'] * 100:5.1f}% | "
+            f"truth={d['truthfulness_score'] * 100:+5.1f}%"
         )
 
     print()
@@ -47,7 +48,7 @@ def main() -> None:
         pieces = [f"{qt:20s} (n={n:3d}):"]
         for arm in ("bare_llm", "long_context", "surfsense"):
             if arm in row:
-                pieces.append(f"{arm}={row[arm]['truthfulness_score']*100:+7.1f}%")
+                pieces.append(f"{arm}={row[arm]['truthfulness_score'] * 100:+7.1f}%")
         print(" ".join(pieces))
 
     print()
@@ -57,7 +58,7 @@ def main() -> None:
         pieces = [f"{dom:10s} (n={n:3d}):"]
         for arm in ("bare_llm", "long_context", "surfsense"):
             if arm in row:
-                pieces.append(f"{arm}={row[arm]['truthfulness_score']*100:+7.1f}%")
+                pieces.append(f"{arm}={row[arm]['truthfulness_score'] * 100:+7.1f}%")
         print(" ".join(pieces))
 
 
diff --git a/surfsense_evals/scripts/summarise_parser_compare_run.py b/surfsense_evals/scripts/summarise_parser_compare_run.py
index c54d82784..7801a1318 100644
--- a/surfsense_evals/scripts/summarise_parser_compare_run.py
+++ b/surfsense_evals/scripts/summarise_parser_compare_run.py
@@ -16,7 +16,6 @@ import statistics
 from collections import defaultdict
 from pathlib import Path
 
-
 REPO = Path(__file__).resolve().parents[1]
 RUN_DIR = REPO / "data" / "multimodal_doc" / "runs" / "2026-05-14T00-53-19Z" / "parser_compare"
 RAW = RUN_DIR / "raw.jsonl"
@@ -24,7 +23,9 @@ ARTIFACT = RUN_DIR / "run_artifact.json"
 
 
 def main() -> None:
-    rows = [json.loads(line) for line in RAW.read_text(encoding="utf-8").splitlines() if line.strip()]
+    rows = [
+        json.loads(line) for line in RAW.read_text(encoding="utf-8").splitlines() if line.strip()
+    ]
     print(f"raw rows: {len(rows)}")
 
     by_qid: dict[str, list[dict]] = defaultdict(list)
@@ -32,11 +33,19 @@ def main() -> None:
         by_qid[row["qid"]].append(row)
     print(f"unique questions: {len(by_qid)}")
 
-    arm_metrics: dict[str, dict] = defaultdict(lambda: {
-        "n": 0, "n_correct": 0, "n_failed": 0, "n_empty": 0,
-        "costs": [], "in_tokens": [], "out_tokens": [], "latency_ms": [],
-        "by_format": defaultdict(lambda: {"n": 0, "correct": 0}),
-    })
+    arm_metrics: dict[str, dict] = defaultdict(
+        lambda: {
+            "n": 0,
+            "n_correct": 0,
+            "n_failed": 0,
+            "n_empty": 0,
+            "costs": [],
+            "in_tokens": [],
+            "out_tokens": [],
+            "latency_ms": [],
+            "by_format": defaultdict(lambda: {"n": 0, "correct": 0}),
+        }
+    )
 
     for row in rows:
         arm = row["arm"]
@@ -71,7 +80,9 @@ def main() -> None:
 
     print()
     print("=" * 100)
-    print(f"{'arm':<25} {'n':>4} {'acc%':>6} {'F1%':>6} {'fail':>5} {'$ mean':>10} {'$ median':>10} {'in tok mean':>12} {'out tok mean':>12} {'p50 ms':>8}")
+    print(
+        f"{'arm':<25} {'n':>4} {'acc%':>6} {'F1%':>6} {'fail':>5} {'$ mean':>10} {'$ median':>10} {'in tok mean':>12} {'out tok mean':>12} {'p50 ms':>8}"
+    )
     print("=" * 100)
     art = json.loads(ARTIFACT.read_text(encoding="utf-8"))
     per_arm_art = art["metrics"]["per_arm"]
@@ -91,7 +102,7 @@ def main() -> None:
 
     print()
     print("by answer_format (accuracy):")
-    formats = sorted({f for m in arm_metrics.values() for f in m["by_format"].keys()})
+    formats = sorted({f for m in arm_metrics.values() for f in m["by_format"]})
     header = f"{'arm':<25} " + " ".join(f"{f:>10}" for f in formats)
     print(header)
     print("-" * len(header))
@@ -111,7 +122,7 @@ def main() -> None:
     print("Aggregated cost (from run_artifact.json):")
     for arm, row in per_arm_art.items():
         print(
-            f"  {arm:<25}  acc={row['accuracy']*100:5.1f}% "
+            f"  {arm:<25}  acc={row['accuracy'] * 100:5.1f}% "
             f"  $/Q LLM={row['llm_cost_per_q']:.4f}  "
             f"  preprocess total=${row['preprocess_cost_total']:.2f}  "
             f"  $/Q total={row['total_cost_per_q']:.4f}"
diff --git a/surfsense_evals/scripts/test_context_overflow_hypothesis.py b/surfsense_evals/scripts/test_context_overflow_hypothesis.py
index 89bd6cb3d..8ccccba45 100644
--- a/surfsense_evals/scripts/test_context_overflow_hypothesis.py
+++ b/surfsense_evals/scripts/test_context_overflow_hypothesis.py
@@ -40,8 +40,7 @@ CONTEXT_HINTS = (
 
 def main() -> None:
     rows = [
-        json.loads(line) for line in RAW.read_text(encoding="utf-8").splitlines()
-        if line.strip()
+        json.loads(line) for line in RAW.read_text(encoding="utf-8").splitlines() if line.strip()
     ]
 
     extraction_size: dict[tuple[str, str], int] = {}
@@ -73,12 +72,12 @@ def main() -> None:
     print("=" * 80)
     print("(b) Extraction size for OK vs FAILED rows per arm")
     print("=" * 80)
-    arm_buckets: dict[str, dict[str, list[int]]] = defaultdict(
-        lambda: {"ok": [], "fail": []}
-    )
+    arm_buckets: dict[str, dict[str, list[int]]] = defaultdict(lambda: {"ok": [], "fail": []})
     parser_arms = (
-        "azure_basic_lc", "azure_premium_lc",
-        "llamacloud_basic_lc", "llamacloud_premium_lc",
+        "azure_basic_lc",
+        "azure_premium_lc",
+        "llamacloud_basic_lc",
+        "llamacloud_premium_lc",
     )
     for row in rows:
         arm = row["arm"]
@@ -133,10 +132,13 @@ def main() -> None:
         "  3M_2018_10K x llamacloud_premium = 908,733 chars (~227k tokens) "
         "-- this is above Sonnet 4.5's 200k window."
     )
-    print("  If transport hypothesis is correct, this should still fail with a "
-          "real overflow error.")
-    print("  If transport hypothesis is correct AND the model truncates silently, "
-          "it might 'succeed' but be wrong.")
+    print(
+        "  If transport hypothesis is correct, this should still fail with a real overflow error."
+    )
+    print(
+        "  If transport hypothesis is correct AND the model truncates silently, "
+        "it might 'succeed' but be wrong."
+    )
     print()
     for row in rows:
         if row["doc_id"] != "3M_2018_10K.pdf":
@@ -145,10 +147,7 @@ def main() -> None:
             continue
         err = row.get("error") or "(none)"
         graded = row.get("graded") or {}
-        print(
-            f"  {row['qid']:<40} correct={graded.get('correct')!s:<5}  "
-            f"err={err[:100]}"
-        )
+        print(f"  {row['qid']:<40} correct={graded.get('correct')!s:<5}  err={err[:100]}")
 
 
 if __name__ == "__main__":
diff --git a/surfsense_evals/src/surfsense_evals/core/arms/surfsense.py b/surfsense_evals/src/surfsense_evals/core/arms/surfsense.py
index a84350dfd..f63b5cbe6 100644
--- a/surfsense_evals/src/surfsense_evals/core/arms/surfsense.py
+++ b/surfsense_evals/src/surfsense_evals/core/arms/surfsense.py
@@ -72,9 +72,7 @@ class SurfSenseArm(Arm):
                 try:
                     await self._client.delete_thread(thread_id)
                 except Exception as exc:  # noqa: BLE001
-                    logger.debug(
-                        "Failed to delete thread %s: %s", thread_id, exc
-                    )
+                    logger.debug("Failed to delete thread %s: %s", thread_id, exc)
 
         letter = extract_answer_letter(answer.text)
         return ArmResult(
diff --git a/surfsense_evals/src/surfsense_evals/core/auth.py b/surfsense_evals/src/surfsense_evals/core/auth.py
index a87e757c2..cf348e3ff 100644
--- a/surfsense_evals/src/surfsense_evals/core/auth.py
+++ b/surfsense_evals/src/surfsense_evals/core/auth.py
@@ -83,6 +83,7 @@ async def acquire_token(config: Config, *, http: httpx.AsyncClient | None = None
         )
 
     if config.has_local_mode():
+
         async def _login(client: httpx.AsyncClient) -> TokenBundle:
             response = await client.post(
                 f"{config.surfsense_api_base}/auth/desktop/login",
@@ -94,15 +95,12 @@ async def acquire_token(config: Config, *, http: httpx.AsyncClient | None = None
             )
             if response.status_code != 200:
                 raise CredentialError(
-                    f"LOCAL login failed (HTTP {response.status_code}): "
-                    f"{_safe_text(response)}"
+                    f"LOCAL login failed (HTTP {response.status_code}): {_safe_text(response)}"
                 )
             payload = response.json()
             access = payload.get("access_token")
             if not access:
-                raise CredentialError(
-                    f"LOCAL login response missing access_token: {payload!r}"
-                )
+                raise CredentialError(f"LOCAL login response missing access_token: {payload!r}")
             return TokenBundle(
                 access_token=access,
                 refresh_token=payload.get("refresh_token") or None,
diff --git a/surfsense_evals/src/surfsense_evals/core/cli.py b/surfsense_evals/src/surfsense_evals/core/cli.py
index 17979fba0..21e706c49 100644
--- a/surfsense_evals/src/surfsense_evals/core/cli.py
+++ b/surfsense_evals/src/surfsense_evals/core/cli.py
@@ -32,14 +32,13 @@ from __future__ import annotations
 
 import argparse
 import asyncio
+import contextlib
 import json
 import logging
 import sys
 from dataclasses import dataclass
 from typing import Any
 
-import sys
-
 import httpx
 from rich.console import Console
 from rich.table import Table
@@ -51,10 +50,8 @@ from rich.table import Table
 # Terminal, PowerShell, cmd) all interpret ANSI escapes natively.
 if sys.platform == "win32":
     for _stream in (sys.stdout, sys.stderr):
-        try:
+        with contextlib.suppress(AttributeError, ValueError):
             _stream.reconfigure(encoding="utf-8", errors="replace")
-        except (AttributeError, ValueError):
-            pass
 
 from . import registry
 from .auth import CredentialError, acquire_token, client_with_auth
@@ -207,8 +204,7 @@ async def _cmd_setup(args: argparse.Namespace) -> int:
 
     if scenario not in SCENARIOS:
         console.print(
-            f"[red]Unknown scenario {scenario!r}. Pick one of: "
-            f"{', '.join(SCENARIOS)}[/red]"
+            f"[red]Unknown scenario {scenario!r}. Pick one of: {', '.join(SCENARIOS)}[/red]"
         )
         return 2
 
@@ -295,9 +291,7 @@ async def _cmd_setup(args: argparse.Namespace) -> int:
         if not skip_vision_setup and (vision_required or vision_llm_slug is not None):
             try:
                 vision_candidates = await ss_client.list_global_vision_models()
-                resolved = resolve_vision_llm(
-                    vision_candidates, explicit_slug=vision_llm_slug
-                )
+                resolved = resolve_vision_llm(vision_candidates, explicit_slug=vision_llm_slug)
             except VisionConfigError as exc:
                 console.print(f"[red]{exc}[/red]")
                 return 2
@@ -527,10 +521,7 @@ async def _cmd_run(args: argparse.Namespace) -> int:
         )
         artifact = await benchmark.run(ctx, **extra_kwargs)
 
-    console.print(
-        f"[green]run OK[/green] {args.suite}/{args.benchmark} → "
-        f"{artifact.raw_path}"
-    )
+    console.print(f"[green]run OK[/green] {args.suite}/{args.benchmark} → {artifact.raw_path}")
     return 0
 
 
@@ -700,15 +691,21 @@ def _build_parser() -> argparse.ArgumentParser:
     )
     p_setup.set_defaults(_func=_cmd_setup, _async=True)
 
-    p_teardown = sub.add_parser("teardown", help="Soft-delete the suite SearchSpace + clear state slot.")
+    p_teardown = sub.add_parser(
+        "teardown", help="Soft-delete the suite SearchSpace + clear state slot."
+    )
     p_teardown.add_argument("--suite", required=True)
     p_teardown.set_defaults(_func=_cmd_teardown, _async=True)
 
     p_models = sub.add_parser("models", help="LLM-config discovery helpers.")
     models_sub = p_models.add_subparsers(dest="subcommand", required=True)
     p_models_list = models_sub.add_parser("list", help="List global LLM configs.")
-    p_models_list.add_argument("--provider", default=None, help="Filter by provider, e.g. openrouter")
-    p_models_list.add_argument("--grep", default=None, help="Substring filter on name / model_name.")
+    p_models_list.add_argument(
+        "--provider", default=None, help="Filter by provider, e.g. openrouter"
+    )
+    p_models_list.add_argument(
+        "--grep", default=None, help="Substring filter on name / model_name."
+    )
     p_models_list.set_defaults(_func=_cmd_models_list, _async=True)
 
     p_suites = sub.add_parser("suites", help="List registered suites.")
@@ -732,7 +729,9 @@ def _build_parser() -> argparse.ArgumentParser:
         suite_parser = ingest_sub.add_parser(suite, help=f"Ingest a {suite} benchmark.")
         suite_bench = suite_parser.add_subparsers(dest="benchmark", required=True)
         for benchmark in registry.list_benchmarks(suite):
-            bp = suite_bench.add_parser(benchmark.name, help=getattr(benchmark, "description", benchmark.name))
+            bp = suite_bench.add_parser(
+                benchmark.name, help=getattr(benchmark, "description", benchmark.name)
+            )
             if hasattr(benchmark, "add_run_args"):
                 benchmark.add_run_args(bp)
             bp.set_defaults(_func=_cmd_ingest, _async=True)
@@ -743,7 +742,9 @@ def _build_parser() -> argparse.ArgumentParser:
         suite_parser = run_sub.add_parser(suite, help=f"Run a {suite} benchmark.")
         suite_bench = suite_parser.add_subparsers(dest="benchmark", required=True)
         for benchmark in registry.list_benchmarks(suite):
-            bp = suite_bench.add_parser(benchmark.name, help=getattr(benchmark, "description", benchmark.name))
+            bp = suite_bench.add_parser(
+                benchmark.name, help=getattr(benchmark, "description", benchmark.name)
+            )
             if hasattr(benchmark, "add_run_args"):
                 benchmark.add_run_args(bp)
             bp.set_defaults(_func=_cmd_run, _async=True)
diff --git a/surfsense_evals/src/surfsense_evals/core/clients/documents.py b/surfsense_evals/src/surfsense_evals/core/clients/documents.py
index 362aae53b..2fd9b2766 100644
--- a/surfsense_evals/src/surfsense_evals/core/clients/documents.py
+++ b/surfsense_evals/src/surfsense_evals/core/clients/documents.py
@@ -18,6 +18,7 @@ Document processing is asynchronous:
 from __future__ import annotations
 
 import asyncio
+import contextlib
 import logging
 import mimetypes
 from collections.abc import Iterable, Sequence
@@ -83,8 +84,7 @@ class DocumentProcessingFailed(RuntimeError):
 
     def __init__(self, statuses: Sequence[DocumentStatus]) -> None:
         details = ", ".join(
-            f"id={s.document_id} ({s.title!r}): {s.reason or 'unknown'}"
-            for s in statuses
+            f"id={s.document_id} ({s.title!r}): {s.reason or 'unknown'}" for s in statuses
         )
         super().__init__(f"Document(s) failed to process: {details}")
         self.statuses = list(statuses)
@@ -157,10 +157,8 @@ class DocumentsClient:
             )
         finally:
             for _, (_, file_obj, _) in opened:
-                try:
+                with contextlib.suppress(Exception):
                     file_obj.close()
-                except Exception:  # noqa: BLE001
-                    pass
 
         response.raise_for_status()
         return FileUploadResult.from_payload(response.json())
@@ -241,9 +239,7 @@ class DocumentsClient:
     # chunks (chunk_id -> document_id map)
     # ------------------------------------------------------------------
 
-    async def list_chunks(
-        self, document_id: int, *, page_size: int = 100
-    ) -> list[ChunkRow]:
+    async def list_chunks(self, document_id: int, *, page_size: int = 100) -> list[ChunkRow]:
         """Walk ``GET /documents/{id}/chunks`` until ``has_more=False``.
 
         Used by ingestion to materialise the ``chunk_id -> document_id``
diff --git a/surfsense_evals/src/surfsense_evals/core/clients/new_chat.py b/surfsense_evals/src/surfsense_evals/core/clients/new_chat.py
index a4c23d010..397193bba 100644
--- a/surfsense_evals/src/surfsense_evals/core/clients/new_chat.py
+++ b/surfsense_evals/src/surfsense_evals/core/clients/new_chat.py
@@ -145,7 +145,7 @@ class NewChatClient:
                 if attempt > max_busy_retries:
                     raise
                 # Cap wait at 30s; backend retry hint is exponential anyway.
-                wait = min(30.0, 0.5 * (2 ** attempt))
+                wait = min(30.0, 0.5 * (2**attempt))
                 logger.info(
                     "thread_id=%s busy (%s); retry %d/%d after %.1fs",
                     thread_id,
diff --git a/surfsense_evals/src/surfsense_evals/core/clients/search_space.py b/surfsense_evals/src/surfsense_evals/core/clients/search_space.py
index efd4a571d..19486aca1 100644
--- a/surfsense_evals/src/surfsense_evals/core/clients/search_space.py
+++ b/surfsense_evals/src/surfsense_evals/core/clients/search_space.py
@@ -177,16 +177,12 @@ class SearchSpaceClient:
         response.raise_for_status()
         payload = response.json()
         if not isinstance(payload, list):
-            raise RuntimeError(
-                f"Unexpected /model-connections/global payload: {payload!r}"
-            )
+            raise RuntimeError(f"Unexpected /model-connections/global payload: {payload!r}")
         entries: list[VisionModelEntry] = []
         for connection in payload:
             provider = str(connection.get("provider", ""))
             for model in connection.get("models") or []:
                 if not model.get("enabled", True) or not model.get("supports_image_input"):
                     continue
-                entries.append(
-                    VisionModelEntry.from_payload({**model, "provider": provider})
-                )
+                entries.append(VisionModelEntry.from_payload({**model, "provider": provider}))
         return entries
diff --git a/surfsense_evals/src/surfsense_evals/core/config.py b/surfsense_evals/src/surfsense_evals/core/config.py
index 9a5a71e89..80002157e 100644
--- a/surfsense_evals/src/surfsense_evals/core/config.py
+++ b/surfsense_evals/src/surfsense_evals/core/config.py
@@ -104,7 +104,9 @@ def load_config() -> Config:
     data_dir = Path(os.environ.get("EVAL_DATA_DIR") or (project_root / "data")).resolve()
     reports_dir = Path(os.environ.get("EVAL_REPORTS_DIR") or (project_root / "reports")).resolve()
     return Config(
-        surfsense_api_base=os.environ.get("SURFSENSE_API_BASE", "http://localhost:8000").rstrip("/"),
+        surfsense_api_base=os.environ.get("SURFSENSE_API_BASE", "http://localhost:8000").rstrip(
+            "/"
+        ),
         openrouter_api_key=os.environ.get("OPENROUTER_API_KEY") or None,
         openrouter_base_url=os.environ.get(
             "OPENROUTER_BASE_URL", "https://openrouter.ai/api/v1"
@@ -203,9 +205,7 @@ class SuiteState:
                 else None
             ),
             native_arm_model=(
-                str(payload["native_arm_model"])
-                if payload.get("native_arm_model")
-                else None
+                str(payload["native_arm_model"]) if payload.get("native_arm_model") else None
             ),
         )
 
diff --git a/surfsense_evals/src/surfsense_evals/core/ingest_settings.py b/surfsense_evals/src/surfsense_evals/core/ingest_settings.py
index 8328e0d46..216ae36a4 100644
--- a/surfsense_evals/src/surfsense_evals/core/ingest_settings.py
+++ b/surfsense_evals/src/surfsense_evals/core/ingest_settings.py
@@ -95,10 +95,7 @@ class IngestSettings:
     def render_label(self) -> str:
         """Human-readable single-line label for reports / log lines."""
 
-        return (
-            f"vision={'on' if self.use_vision_llm else 'off'}, "
-            f"mode={self.processing_mode}"
-        )
+        return f"vision={'on' if self.use_vision_llm else 'off'}, mode={self.processing_mode}"
 
 
 def _coerce_bool(value: Any, default: bool) -> bool:
@@ -122,9 +119,7 @@ def _coerce_mode(value: Any, default: str) -> str:
         return default
     val = str(value).strip().lower()
     if val not in PROCESSING_MODES:
-        raise ValueError(
-            f"Invalid processing_mode {val!r}; must be one of {PROCESSING_MODES}"
-        )
+        raise ValueError(f"Invalid processing_mode {val!r}; must be one of {PROCESSING_MODES}")
     return val
 
 
@@ -274,10 +269,7 @@ def format_ingest_settings_md(settings: Any) -> str:
         return "- SurfSense ingest settings: (not recorded — re-ingest to capture)"
     vision = "on" if settings.get("use_vision_llm") else "off"
     mode = settings.get("processing_mode") or "basic"
-    return (
-        f"- SurfSense ingest settings: vision_llm=`{vision}`, "
-        f"processing_mode=`{mode}`"
-    )
+    return f"- SurfSense ingest settings: vision_llm=`{vision}`, processing_mode=`{mode}`"
 
 
 __all__ = [
diff --git a/surfsense_evals/src/surfsense_evals/core/metrics/comparison.py b/surfsense_evals/src/surfsense_evals/core/metrics/comparison.py
index 579576f4f..332535871 100644
--- a/surfsense_evals/src/surfsense_evals/core/metrics/comparison.py
+++ b/surfsense_evals/src/surfsense_evals/core/metrics/comparison.py
@@ -67,17 +67,13 @@ def mcnemar_test(
     """
 
     if len(arm_a_correct) != len(arm_b_correct):
-        raise ValueError(
-            f"Length mismatch: arm_a={len(arm_a_correct)}, arm_b={len(arm_b_correct)}"
-        )
+        raise ValueError(f"Length mismatch: arm_a={len(arm_a_correct)}, arm_b={len(arm_b_correct)}")
     n = len(arm_a_correct)
-    b = sum(1 for a, c in zip(arm_a_correct, arm_b_correct) if a and not c)
-    c = sum(1 for a, cc in zip(arm_a_correct, arm_b_correct) if (not a) and cc)
+    b = sum(1 for a, c in zip(arm_a_correct, arm_b_correct, strict=False) if a and not c)
+    c = sum(1 for a, cc in zip(arm_a_correct, arm_b_correct, strict=False) if (not a) and cc)
     discordant = b + c
     if discordant == 0:
-        return McnemarResult(
-            n_total=n, b=b, c=c, statistic=0.0, p_value=1.0, method="degenerate"
-        )
+        return McnemarResult(n_total=n, b=b, c=c, statistic=0.0, p_value=1.0, method="degenerate")
 
     if discordant < use_exact_below:
         # Exact binomial: under H0 each discordant pair is a Bernoulli(0.5).
@@ -92,13 +88,11 @@ def mcnemar_test(
     # Chi-square with continuity correction (McNemar-Edwards).
     chi = ((abs(b - c) - 1) ** 2) / discordant
     p_value = _chi2_sf(chi, df=1)
-    return McnemarResult(
-        n_total=n, b=b, c=c, statistic=chi, p_value=p_value, method="chi2_cc"
-    )
+    return McnemarResult(n_total=n, b=b, c=c, statistic=chi, p_value=p_value, method="chi2_cc")
 
 
 def _binom_pmf(n: int, k: int) -> float:
-    return math.comb(n, k) * (0.5 ** n)
+    return math.comb(n, k) * (0.5**n)
 
 
 def _chi2_sf(x: float, *, df: int) -> float:
diff --git a/surfsense_evals/src/surfsense_evals/core/metrics/mc_accuracy.py b/surfsense_evals/src/surfsense_evals/core/metrics/mc_accuracy.py
index 8b0188ca4..958f62600 100644
--- a/surfsense_evals/src/surfsense_evals/core/metrics/mc_accuracy.py
+++ b/surfsense_evals/src/surfsense_evals/core/metrics/mc_accuracy.py
@@ -46,9 +46,7 @@ _Z_FOR_LEVEL: dict[float, float] = {
 }
 
 
-def wilson_ci(
-    n_correct: int, n_total: int, *, level: float = 0.95
-) -> tuple[float, float]:
+def wilson_ci(n_correct: int, n_total: int, *, level: float = 0.95) -> tuple[float, float]:
     """Two-sided Wilson score confidence interval for a proportion.
 
     Returns ``(low, high)``. ``n_total == 0`` returns ``(0.0, 1.0)`` —
@@ -70,9 +68,7 @@ def wilson_ci(
     return low, high
 
 
-def accuracy_with_wilson_ci(
-    n_correct: int, n_total: int, *, level: float = 0.95
-) -> AccuracyResult:
+def accuracy_with_wilson_ci(n_correct: int, n_total: int, *, level: float = 0.95) -> AccuracyResult:
     if n_total < 0:
         raise ValueError(f"n_total must be >= 0, got {n_total}")
     if n_correct < 0 or n_correct > n_total:
@@ -109,10 +105,7 @@ def per_task_accuracy(
         bucket[1] += 1
         if row.get(correct_key):
             bucket[0] += 1
-    return {
-        task: accuracy_with_wilson_ci(c[0], c[1], level=level)
-        for task, c in counts.items()
-    }
+    return {task: accuracy_with_wilson_ci(c[0], c[1], level=level) for task, c in counts.items()}
 
 
 def macro_accuracy(per_task: Mapping[str, AccuracyResult]) -> float:
diff --git a/surfsense_evals/src/surfsense_evals/core/metrics/retrieval.py b/surfsense_evals/src/surfsense_evals/core/metrics/retrieval.py
index d4cfe10ae..3fd25f634 100644
--- a/surfsense_evals/src/surfsense_evals/core/metrics/retrieval.py
+++ b/surfsense_evals/src/surfsense_evals/core/metrics/retrieval.py
@@ -61,7 +61,7 @@ def _dcg_at_k(grades: Sequence[float], k: int) -> float:
     s = 0.0
     for i, grade in enumerate(grades[:k], start=1):
         # Standard log-base-2 discount; gain = 2^grade - 1 for graded relevance.
-        s += (2.0 ** grade - 1.0) / math.log2(i + 1)
+        s += (2.0**grade - 1.0) / math.log2(i + 1)
     return s
 
 
@@ -106,7 +106,9 @@ def score_run(
 
     qids = set(per_query_qrels.keys()) & set(per_query_retrieved.keys())
     if not qids:
-        return RetrievalScores(recall_at_k={k: 0.0 for k in ks}, mrr=0.0, ndcg_at_10=0.0, n_queries=0)
+        return RetrievalScores(
+            recall_at_k={k: 0.0 for k in ks}, mrr=0.0, ndcg_at_10=0.0, n_queries=0
+        )
 
     recall_totals = {k: 0.0 for k in ks}
     mrr_total = 0.0
diff --git a/surfsense_evals/src/surfsense_evals/core/parse/__init__.py b/surfsense_evals/src/surfsense_evals/core/parse/__init__.py
index 208c2d374..8b90de78b 100644
--- a/surfsense_evals/src/surfsense_evals/core/parse/__init__.py
+++ b/surfsense_evals/src/surfsense_evals/core/parse/__init__.py
@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from .answer_letter import AnswerLetterResult, extract_answer_letter
-from .citations import CITATION_REGEX, CitationToken, ChunkCitation, UrlCitation, parse_citations
+from .citations import CITATION_REGEX, ChunkCitation, CitationToken, UrlCitation, parse_citations
 from .freeform_answer import extract_freeform_answer
 from .sse import SseEvent, iter_sse_events
 
diff --git a/surfsense_evals/src/surfsense_evals/core/parse/citations.py b/surfsense_evals/src/surfsense_evals/core/parse/citations.py
index 1fcd35434..38bd16d31 100644
--- a/surfsense_evals/src/surfsense_evals/core/parse/citations.py
+++ b/surfsense_evals/src/surfsense_evals/core/parse/citations.py
@@ -15,7 +15,7 @@ from __future__ import annotations
 
 import re
 from dataclasses import dataclass
-from typing import Any, Union
+from typing import Any
 
 # Pattern preserves the TS source verbatim:
 #   /[\[【]\u200B?citation:\s*(https?:\/\/[^\]】\u200B]+|urlcite\d+|(?:doc-)?-?\d+(?:\s*,\s*(?:doc-)?-?\d+)*)\s*\u200B?[\]】]/g
@@ -35,7 +35,7 @@ from typing import Any, Union
 # the pattern source, so we splice the literal character in via an
 # f-string. This keeps our pattern functionally identical to the TS
 # reference and lets ``"\u200B" in CITATION_REGEX.pattern`` succeed.
-_ZWSP = "\u200B"
+_ZWSP = "\u200b"
 CITATION_REGEX = re.compile(
     rf"[\[【]{_ZWSP}?citation:\s*("
     rf"https?://[^\]】{_ZWSP}]+|urlcite\d+|(?:doc-)?-?\d+(?:\s*,\s*(?:doc-)?-?\d+)*"
@@ -64,7 +64,7 @@ class UrlCitation:
         return {"kind": "url", "url": self.url}
 
 
-CitationToken = Union[ChunkCitation, UrlCitation]
+CitationToken = ChunkCitation | UrlCitation
 
 
 def parse_citations(text: str, *, url_map: dict[str, str] | None = None) -> list[CitationToken]:
diff --git a/surfsense_evals/src/surfsense_evals/core/parse/freeform_answer.py b/surfsense_evals/src/surfsense_evals/core/parse/freeform_answer.py
index 959b045a5..104176d09 100644
--- a/surfsense_evals/src/surfsense_evals/core/parse/freeform_answer.py
+++ b/surfsense_evals/src/surfsense_evals/core/parse/freeform_answer.py
@@ -56,7 +56,7 @@ def extract_freeform_answer(text: str) -> str:
         marker_matches = list(_ANSWER_MARKER.finditer(text))
         if marker_matches:
             last = marker_matches[-1]
-            tail = text[last.end():]
+            tail = text[last.end() :]
             nl = tail.find("\n")
             if nl >= 0:
                 tail = tail[:nl]
@@ -77,7 +77,7 @@ def extract_freeform_answer(text: str) -> str:
     # 2. Strip wrapping quotes / parens / trailing punctuation that
     #    confuse the grader without changing meaning.
     candidate = candidate.strip().strip("`").strip()
-    if candidate.startswith(("\"", "'")) and candidate.endswith(("\"", "'")):
+    if candidate.startswith(('"', "'")) and candidate.endswith(('"', "'")):
         candidate = candidate[1:-1].strip()
     return candidate
 
diff --git a/surfsense_evals/src/surfsense_evals/core/parsers/azure_di.py b/surfsense_evals/src/surfsense_evals/core/parsers/azure_di.py
index eebad906a..16e618db4 100644
--- a/surfsense_evals/src/surfsense_evals/core/parsers/azure_di.py
+++ b/surfsense_evals/src/surfsense_evals/core/parsers/azure_di.py
@@ -25,6 +25,7 @@ import asyncio
 import logging
 import os
 import random
+from pathlib import Path
 
 logger = logging.getLogger(__name__)
 
@@ -63,8 +64,7 @@ async def parse_with_azure_di(
     api_key = api_key or os.environ.get("AZURE_DI_KEY")
     if not endpoint or not api_key:
         raise ValueError(
-            "AZURE_DI_ENDPOINT and AZURE_DI_KEY must be set "
-            "(see surfsense_evals/.env)."
+            "AZURE_DI_ENDPOINT and AZURE_DI_KEY must be set (see surfsense_evals/.env)."
         )
 
     model_id = _AZURE_MODEL_BY_MODE.get(processing_mode, "prebuilt-read")
@@ -82,10 +82,13 @@ async def parse_with_azure_di(
         ServiceResponseError,
     )
 
-    file_size_mb = os.path.getsize(file_path) / (1024 * 1024)
+    file_size_mb = await asyncio.to_thread(os.path.getsize, file_path) / (1024 * 1024)
     logger.info(
         "Azure DI parsing %s (mode=%s, model=%s, size=%.1fMB)",
-        file_path, processing_mode, model_id, file_size_mb,
+        file_path,
+        processing_mode,
+        model_id,
+        file_size_mb,
     )
 
     last_exc: Exception | None = None
@@ -96,21 +99,21 @@ async def parse_with_azure_di(
                 credential=AzureKeyCredential(api_key),
             )
             async with client:
-                with open(file_path, "rb") as fh:
-                    poller = await client.begin_analyze_document(
-                        model_id,
-                        body=fh,
-                        output_content_format=DocumentContentFormat.MARKDOWN,
-                    )
+                body = await asyncio.to_thread(Path(file_path).read_bytes)
+                poller = await client.begin_analyze_document(
+                    model_id,
+                    body=body,
+                    output_content_format=DocumentContentFormat.MARKDOWN,
+                )
                 result = await poller.result()
             content = (result.content or "").strip()
             if not content:
-                raise AzureDIError(
-                    f"Azure DI returned empty content for {file_path}"
-                )
+                raise AzureDIError(f"Azure DI returned empty content for {file_path}")
             logger.info(
                 "Azure DI OK: %s (%s) -> %d chars",
-                file_path, model_id, len(content),
+                file_path,
+                model_id,
+                len(content),
             )
             return content
 
@@ -119,9 +122,7 @@ async def parse_with_azure_di(
         except HttpResponseError as exc:
             # 4xx that's not auth: don't retry, the request itself is broken.
             if exc.status_code and 400 <= exc.status_code < 500:
-                raise AzureDIError(
-                    f"Azure DI {exc.status_code} on {file_path}: {exc}"
-                ) from exc
+                raise AzureDIError(f"Azure DI {exc.status_code} on {file_path}: {exc}") from exc
             last_exc = exc
         except (ServiceRequestError, ServiceResponseError) as exc:
             last_exc = exc
@@ -132,7 +133,10 @@ async def parse_with_azure_di(
             sleep_for = delay + jitter
             logger.warning(
                 "Azure DI attempt %d/%d failed (%s); retrying in %.1fs",
-                attempt, _MAX_RETRIES, type(last_exc).__name__, sleep_for,
+                attempt,
+                _MAX_RETRIES,
+                type(last_exc).__name__,
+                sleep_for,
             )
             await asyncio.sleep(sleep_for)
 
diff --git a/surfsense_evals/src/surfsense_evals/core/parsers/llamacloud.py b/surfsense_evals/src/surfsense_evals/core/parsers/llamacloud.py
index ba3d787ef..32fd97e47 100644
--- a/surfsense_evals/src/surfsense_evals/core/parsers/llamacloud.py
+++ b/surfsense_evals/src/surfsense_evals/core/parsers/llamacloud.py
@@ -61,8 +61,7 @@ def _extract_markdown(result) -> str:
         if result and hasattr(result[0], "text"):
             return result[0].text
         return "\n\n".join(
-            doc.page_content if hasattr(doc, "page_content") else str(doc)
-            for doc in result
+            doc.page_content if hasattr(doc, "page_content") else str(doc) for doc in result
         )
 
     return str(result)
@@ -86,9 +85,7 @@ async def parse_with_llamacloud(
 
     api_key = api_key or os.environ.get("LLAMA_CLOUD_API_KEY")
     if not api_key:
-        raise ValueError(
-            "LLAMA_CLOUD_API_KEY must be set (see surfsense_evals/.env)."
-        )
+        raise ValueError("LLAMA_CLOUD_API_KEY must be set (see surfsense_evals/.env).")
 
     parse_mode = _LLAMA_PARSE_MODE_MAP.get(processing_mode, "parse_page_with_llm")
 
@@ -98,7 +95,7 @@ async def parse_with_llamacloud(
     from llama_cloud_services.parse.base import JobFailedException
     from llama_cloud_services.parse.utils import ResultType
 
-    file_size_mb = os.path.getsize(file_path) / (1024 * 1024)
+    file_size_mb = await asyncio.to_thread(os.path.getsize, file_path) / (1024 * 1024)
     # Match backend's per-page timeout heuristic so big PDFs don't drop
     # mid-job: 60s baseline + 30s/page (premium agent runs longer than
     # basic; both fit comfortably here).
@@ -106,13 +103,19 @@ async def parse_with_llamacloud(
     upload_timeout = max(120.0, 30.0 * file_size_mb)
 
     logger.info(
-        "LlamaCloud parsing %s (mode=%s, parse_mode=%s, %.1fMB, "
-        "job_timeout=%.0fs)",
-        file_path, processing_mode, parse_mode, file_size_mb, job_timeout,
+        "LlamaCloud parsing %s (mode=%s, parse_mode=%s, %.1fMB, job_timeout=%.0fs)",
+        file_path,
+        processing_mode,
+        parse_mode,
+        file_size_mb,
+        job_timeout,
     )
 
     custom_timeout = httpx.Timeout(
-        connect=120.0, read=upload_timeout, write=upload_timeout, pool=120.0,
+        connect=120.0,
+        read=upload_timeout,
+        write=upload_timeout,
+        pool=120.0,
     )
 
     last_exc: Exception | None = None
@@ -135,12 +138,12 @@ async def parse_with_llamacloud(
                 result = await parser.aparse(str(file_path))
             content = _extract_markdown(result).strip()
             if not content:
-                raise LlamaCloudError(
-                    f"LlamaCloud returned empty content for {file_path}"
-                )
+                raise LlamaCloudError(f"LlamaCloud returned empty content for {file_path}")
             logger.info(
                 "LlamaCloud OK: %s (%s) -> %d chars",
-                file_path, parse_mode, len(content),
+                file_path,
+                parse_mode,
+                len(content),
             )
             return content
 
@@ -156,7 +159,10 @@ async def parse_with_llamacloud(
                 sleep_for = delay + jitter
                 logger.warning(
                     "LlamaCloud attempt %d/%d failed (%s); retrying in %.1fs",
-                    attempt, _MAX_RETRIES, type(last_exc).__name__, sleep_for,
+                    attempt,
+                    _MAX_RETRIES,
+                    type(last_exc).__name__,
+                    sleep_for,
                 )
                 await asyncio.sleep(sleep_for)
 
diff --git a/surfsense_evals/src/surfsense_evals/core/pdf/render.py b/surfsense_evals/src/surfsense_evals/core/pdf/render.py
index 624136d7c..21866f3e5 100644
--- a/surfsense_evals/src/surfsense_evals/core/pdf/render.py
+++ b/surfsense_evals/src/surfsense_evals/core/pdf/render.py
@@ -116,11 +116,7 @@ def _normalise_paragraphs(text: str) -> list[str]:
 
 
 def _escape_html(text: str) -> str:
-    return (
-        text.replace("&", "&amp;")
-        .replace("<", "&lt;")
-        .replace(">", "&gt;")
-    )
+    return text.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
 
 
 def render_pdf(
diff --git a/surfsense_evals/src/surfsense_evals/core/providers/openrouter_chat.py b/surfsense_evals/src/surfsense_evals/core/providers/openrouter_chat.py
index 2494434be..208fbb865 100644
--- a/surfsense_evals/src/surfsense_evals/core/providers/openrouter_chat.py
+++ b/surfsense_evals/src/surfsense_evals/core/providers/openrouter_chat.py
@@ -29,8 +29,8 @@ from typing import Any
 import httpx
 
 from .openrouter_pdf import (
-    OpenRouterResponse,
     _DEFAULT_HEADERS,
+    OpenRouterResponse,
     _parse_chat_completion,
 )
 
diff --git a/surfsense_evals/src/surfsense_evals/core/providers/openrouter_pdf.py b/surfsense_evals/src/surfsense_evals/core/providers/openrouter_pdf.py
index e98590cbf..5cd47b04e 100644
--- a/surfsense_evals/src/surfsense_evals/core/providers/openrouter_pdf.py
+++ b/surfsense_evals/src/surfsense_evals/core/providers/openrouter_pdf.py
@@ -34,7 +34,7 @@ import base64
 import logging
 import time
 from dataclasses import dataclass
-from enum import Enum
+from enum import StrEnum
 from pathlib import Path
 from typing import Any
 
@@ -43,7 +43,7 @@ import httpx
 logger = logging.getLogger(__name__)
 
 
-class PdfEngine(str, Enum):
+class PdfEngine(StrEnum):
     NATIVE = "native"
     MISTRAL_OCR = "mistral-ocr"
     CLOUDFLARE_AI = "cloudflare-ai"
@@ -121,9 +121,7 @@ class OpenRouterPdfProvider:
         body: dict[str, Any] = {
             "model": self._model,
             "messages": messages,
-            "plugins": [
-                {"id": "file-parser", "pdf": {"engine": self._engine.value}}
-            ],
+            "plugins": [{"id": "file-parser", "pdf": {"engine": self._engine.value}}],
         }
         if max_tokens:
             body["max_tokens"] = max_tokens
diff --git a/surfsense_evals/src/surfsense_evals/core/registry.py b/surfsense_evals/src/surfsense_evals/core/registry.py
index 65f64c39a..7fb64c36f 100644
--- a/surfsense_evals/src/surfsense_evals/core/registry.py
+++ b/surfsense_evals/src/surfsense_evals/core/registry.py
@@ -177,7 +177,9 @@ class Benchmark(Protocol):
     def add_run_args(self, parser: argparse.ArgumentParser) -> None:  # pragma: no cover - protocol
         """Add benchmark-specific flags to ``run <suite> <benchmark>``."""
 
-    def report_section(self, artifacts: list[RunArtifact]) -> ReportSection:  # pragma: no cover - protocol
+    def report_section(
+        self, artifacts: list[RunArtifact]
+    ) -> ReportSection:  # pragma: no cover - protocol
         ...
 
 
@@ -224,9 +226,7 @@ def get(suite: str, name: str) -> Benchmark:
         return _REGISTRY[(suite, name)]
     except KeyError as exc:
         available = ", ".join(f"{s}/{n}" for s, n in sorted(_REGISTRY)) or "<none>"
-        raise KeyError(
-            f"Unknown benchmark '{suite}/{name}'. Registered: {available}"
-        ) from exc
+        raise KeyError(f"Unknown benchmark '{suite}/{name}'. Registered: {available}") from exc
 
 
 def list_suites() -> list[str]:
diff --git a/surfsense_evals/src/surfsense_evals/core/scenarios.py b/surfsense_evals/src/surfsense_evals/core/scenarios.py
index 16874a069..fefdc6865 100644
--- a/surfsense_evals/src/surfsense_evals/core/scenarios.py
+++ b/surfsense_evals/src/surfsense_evals/core/scenarios.py
@@ -45,10 +45,7 @@ def format_scenario_md(extra: Mapping[str, Any] | None) -> str:
             "(text-only model can't see images) — that's the point."
         )
     else:
-        body = (
-            f"- Scenario: head-to-head — both arms answer with `{surf_slug}` "
-            "via OpenRouter."
-        )
+        body = f"- Scenario: head-to-head — both arms answer with `{surf_slug}` via OpenRouter."
         if vision_slug:
             body += f" SurfSense ingest VLM: `{vision_slug}`."
 
diff --git a/surfsense_evals/src/surfsense_evals/suites/__init__.py b/surfsense_evals/src/surfsense_evals/suites/__init__.py
index 95ed958ca..f3d26f865 100644
--- a/surfsense_evals/src/surfsense_evals/suites/__init__.py
+++ b/surfsense_evals/src/surfsense_evals/suites/__init__.py
@@ -20,7 +20,7 @@ from __future__ import annotations
 import importlib
 import logging
 import pkgutil
-from typing import Iterable
+from collections.abc import Iterable
 
 logger = logging.getLogger(__name__)
 
@@ -60,7 +60,5 @@ def discover_suites() -> list[str]:
                 importlib.import_module(benchmark_name)
                 imported.append(benchmark_name)
             except Exception as exc:  # noqa: BLE001
-                logger.warning(
-                    "Failed to import benchmark %s: %s", benchmark_name, exc
-                )
+                logger.warning("Failed to import benchmark %s: %s", benchmark_name, exc)
     return imported
diff --git a/surfsense_evals/src/surfsense_evals/suites/_demo/hello/__init__.py b/surfsense_evals/src/surfsense_evals/suites/_demo/hello/__init__.py
index 1da33926c..43dc51ac5 100644
--- a/surfsense_evals/src/surfsense_evals/suites/_demo/hello/__init__.py
+++ b/surfsense_evals/src/surfsense_evals/suites/_demo/hello/__init__.py
@@ -6,7 +6,6 @@ import argparse
 from typing import Any
 
 from ....core.registry import (
-    Benchmark,
     ReportSection,
     RunArtifact,
     RunContext,
diff --git a/surfsense_evals/src/surfsense_evals/suites/medical/cure/__init__.py b/surfsense_evals/src/surfsense_evals/suites/medical/cure/__init__.py
index e13224be7..7e9d9a07b 100644
--- a/surfsense_evals/src/surfsense_evals/suites/medical/cure/__init__.py
+++ b/surfsense_evals/src/surfsense_evals/suites/medical/cure/__init__.py
@@ -12,7 +12,7 @@ Recall@k / MRR / nDCG@10 against qrels.
 
 from __future__ import annotations
 
-from .runner import CureBenchmark
 from ....core import registry as _registry
+from .runner import CureBenchmark
 
 _registry.register(CureBenchmark())
diff --git a/surfsense_evals/src/surfsense_evals/suites/medical/cure/ingest.py b/surfsense_evals/src/surfsense_evals/suites/medical/cure/ingest.py
index 275e28ce5..84108b4df 100644
--- a/surfsense_evals/src/surfsense_evals/suites/medical/cure/ingest.py
+++ b/surfsense_evals/src/surfsense_evals/suites/medical/cure/ingest.py
@@ -154,13 +154,11 @@ async def run_ingest(
             if not batches:
                 logger.warning("Discipline %s produced 0 batches; skipping upload", discipline)
                 continue
-            logger.info(
-                "Uploading %d batches for discipline %s", len(batches), discipline
-            )
+            logger.info("Uploading %d batches for discipline %s", len(batches), discipline)
             upload_result = await docs_client.upload(
                 files=[b.path for b in batches],
                 search_space_id=ctx.search_space_id,
-                    use_vision_llm=settings.use_vision_llm,
+                use_vision_llm=settings.use_vision_llm,
                 processing_mode=settings.processing_mode,
             )
             new_doc_ids = list(upload_result.document_ids)
@@ -177,9 +175,7 @@ async def run_ingest(
             )
             title_to_doc = {s.title: s.document_id for s in statuses}
 
-            per_discipline_path = (
-                ctx.maps_dir() / f"cure_corpus_map_{discipline}.jsonl"
-            )
+            per_discipline_path = ctx.maps_dir() / f"cure_corpus_map_{discipline}.jsonl"
             with per_discipline_path.open("w", encoding="utf-8") as fh:
                 fh.write(settings_header_line(settings) + "\n")
                 for batch in batches:
@@ -202,9 +198,7 @@ async def run_ingest(
                     try:
                         chunks = await docs_client.list_chunks(int(doc_id))
                     except Exception as exc:  # noqa: BLE001
-                        logger.warning(
-                            "Failed to list chunks for doc_id=%s: %s", doc_id, exc
-                        )
+                        logger.warning("Failed to list chunks for doc_id=%s: %s", doc_id, exc)
                         continue
                     for chunk in chunks:
                         fh.write(
@@ -227,12 +221,10 @@ async def run_ingest(
 
 
 def _take(it: Iterable, n: int) -> Iterable:
-    yielded = 0
-    for x in it:
-        if yielded >= n:
+    for i, x in enumerate(it):
+        if i >= n:
             return
         yield x
-        yielded += 1
 
 
 __all__ = ["DISCIPLINES", "CorpusPassage", "PassageBatch", "run_ingest"]
diff --git a/surfsense_evals/src/surfsense_evals/suites/medical/cure/runner.py b/surfsense_evals/src/surfsense_evals/suites/medical/cure/runner.py
index 041e0e8b5..d2735c8d5 100644
--- a/surfsense_evals/src/surfsense_evals/suites/medical/cure/runner.py
+++ b/surfsense_evals/src/surfsense_evals/suites/medical/cure/runner.py
@@ -34,7 +34,6 @@ from ....core.ingest_settings import (
 )
 from ....core.metrics.retrieval import score_run
 from ....core.registry import (
-    Benchmark,
     ReportSection,
     RunArtifact,
     RunContext,
@@ -192,12 +191,15 @@ class CureBenchmark:
 
     def add_run_args(self, parser: argparse.ArgumentParser) -> None:
         parser.add_argument("--lang", default="en", choices=("en", "es", "fr"))
-        parser.add_argument("--discipline", default=None,
-                            help="Restrict to one discipline (default: all ingested).")
+        parser.add_argument(
+            "--discipline", default=None, help="Restrict to one discipline (default: all ingested)."
+        )
         parser.add_argument("--n", dest="sample_n", type=int, default=None)
         parser.add_argument("--concurrency", type=int, default=4)
         parser.add_argument(
-            "--max-passages-per-discipline", type=int, default=None,
+            "--max-passages-per-discipline",
+            type=int,
+            default=None,
             help="(ingest only) cap corpus rows per discipline for smoke testing.",
         )
         # Per-upload knobs forwarded to /documents/fileupload at ingest;
@@ -234,11 +236,13 @@ class CureBenchmark:
 
         # Disciplines to query are determined by the per-discipline maps
         # actually present (either user-filtered or whatever was ingested).
-        ingested_disciplines = sorted({
-            row_disc
-            for path in maps_dir.glob("cure_corpus_map_*.jsonl")
-            for row_disc in [path.stem[len("cure_corpus_map_"):]]
-        })
+        ingested_disciplines = sorted(
+            {
+                row_disc
+                for path in maps_dir.glob("cure_corpus_map_*.jsonl")
+                for row_disc in [path.stem[len("cure_corpus_map_") :]]
+            }
+        )
         if discipline_filter:
             disciplines = [discipline_filter]
         else:
@@ -276,7 +280,7 @@ class CureBenchmark:
         )
 
         per_query_retrieved: dict[str, list[str]] = {}
-        for q, res in zip(queries, results):
+        for q, res in zip(queries, results, strict=False):
             chunk_ids: list[int] = []
             seen: set[int] = set()
             for citation in res.citations:
@@ -311,7 +315,7 @@ class CureBenchmark:
         run_dir = ctx.runs_dir(run_timestamp=run_timestamp)
         raw_path = run_dir / "raw.jsonl"
         with raw_path.open("w", encoding="utf-8") as fh:
-            for q, res in zip(queries, results):
+            for q, res in zip(queries, results, strict=False):
                 fh.write(
                     json.dumps(
                         {
diff --git a/surfsense_evals/src/surfsense_evals/suites/medical/medxpertqa/ingest.py b/surfsense_evals/src/surfsense_evals/suites/medical/medxpertqa/ingest.py
index ff43c7049..f50247acb 100644
--- a/surfsense_evals/src/surfsense_evals/suites/medical/medxpertqa/ingest.py
+++ b/surfsense_evals/src/surfsense_evals/suites/medical/medxpertqa/ingest.py
@@ -55,15 +55,15 @@ def _hf_hub_download(*args, **kwargs):
 
 @dataclass
 class MedXpertQuestion:
-    qid: str                         # e.g. "MM-26"
-    question: str                    # full question text (case + ask)
-    options: dict[str, str]          # A-E
-    label: str                       # "A".."E"
-    image_files: list[str]           # filenames inside images.zip
+    qid: str  # e.g. "MM-26"
+    question: str  # full question text (case + ask)
+    options: dict[str, str]  # A-E
+    label: str  # "A".."E"
+    image_files: list[str]  # filenames inside images.zip
     medical_task: str
     body_system: str
     question_type: str
-    split: str                       # "test" or "dev"
+    split: str  # "test" or "dev"
 
 
 def _load_jsonl(path: Path, *, split: str) -> list[MedXpertQuestion]:
@@ -84,17 +84,19 @@ def _load_jsonl(path: Path, *, split: str) -> list[MedXpertQuestion]:
             images = row.get("images") or []
             if not isinstance(images, list):
                 images = []
-            out.append(MedXpertQuestion(
-                qid=qid,
-                question=question,
-                options=opts,
-                label=label,
-                image_files=[str(x).strip() for x in images if str(x).strip()],
-                medical_task=str(row.get("medical_task") or "").strip(),
-                body_system=str(row.get("body_system") or "").strip(),
-                question_type=str(row.get("question_type") or "").strip(),
-                split=split,
-            ))
+            out.append(
+                MedXpertQuestion(
+                    qid=qid,
+                    question=question,
+                    options=opts,
+                    label=label,
+                    image_files=[str(x).strip() for x in images if str(x).strip()],
+                    medical_task=str(row.get("medical_task") or "").strip(),
+                    body_system=str(row.get("body_system") or "").strip(),
+                    question_type=str(row.get("question_type") or "").strip(),
+                    split=split,
+                )
+            )
     return out
 
 
@@ -204,7 +206,7 @@ async def _upload_pdfs(
     name_to_id: dict[str, int] = {}
     pdf_list = list(pdf_paths)
     for batch_start in range(0, len(pdf_list), batch_size):
-        batch = pdf_list[batch_start:batch_start + batch_size]
+        batch = pdf_list[batch_start : batch_start + batch_size]
         result = await docs_client.upload(
             files=batch,
             search_space_id=ctx.search_space_id,
@@ -226,8 +228,10 @@ async def _upload_pdfs(
                 name_to_id[s.title] = s.document_id
         logger.info(
             "Uploaded MedXpertQA batch %d-%d: %d new, %d duplicate",
-            batch_start, batch_start + len(batch),
-            len(result.document_ids), len(result.duplicate_document_ids),
+            batch_start,
+            batch_start + len(batch),
+            len(result.document_ids),
+            len(result.duplicate_document_ids),
         )
     return name_to_id
 
@@ -310,9 +314,11 @@ async def run_ingest(
         # Materialise into bench_dir so the path is stable.
         try:
             from os import link as _link
+
             _link(local_zip, images_zip_local)
         except OSError:
             from shutil import copy2
+
             copy2(local_zip, images_zip_local)
     _ensure_images_extracted(images_zip_local, images_dir)
 
@@ -354,17 +360,22 @@ async def run_ingest(
     questions_jsonl = bench_dir / "questions.jsonl"
     with questions_jsonl.open("w", encoding="utf-8") as fh:
         for q in questions:
-            fh.write(json.dumps({
-                "qid": q.qid,
-                "question": q.question,
-                "options": q.options,
-                "label": q.label,
-                "image_files": q.image_files,
-                "medical_task": q.medical_task,
-                "body_system": q.body_system,
-                "question_type": q.question_type,
-                "split": q.split,
-            }) + "\n")
+            fh.write(
+                json.dumps(
+                    {
+                        "qid": q.qid,
+                        "question": q.question,
+                        "options": q.options,
+                        "label": q.label,
+                        "image_files": q.image_files,
+                        "medical_task": q.medical_task,
+                        "body_system": q.body_system,
+                        "question_type": q.question_type,
+                        "split": q.split,
+                    }
+                )
+                + "\n"
+            )
     logger.info("Wrote %d MedXpertQA questions to %s", len(questions), questions_jsonl)
 
     map_path = ctx.maps_dir() / "medxpertqa_doc_map.jsonl"
@@ -376,13 +387,18 @@ async def run_ingest(
             local = pdf_paths.get(q.qid)
             if local is None:
                 continue
-            fh.write(json.dumps({
-                "qid": q.qid,
-                "document_id": name_to_id.get(local.name),
-                "pdf_path": str(local),
-                "n_images": len(q.image_files),
-                "split": q.split,
-            }) + "\n")
+            fh.write(
+                json.dumps(
+                    {
+                        "qid": q.qid,
+                        "document_id": name_to_id.get(local.name),
+                        "pdf_path": str(local),
+                        "n_images": len(q.image_files),
+                        "split": q.split,
+                    }
+                )
+                + "\n"
+            )
     logger.info("Wrote MedXpertQA doc map to %s", map_path)
 
     new_state = ctx.suite_state
diff --git a/surfsense_evals/src/surfsense_evals/suites/medical/medxpertqa/runner.py b/surfsense_evals/src/surfsense_evals/suites/medical/medxpertqa/runner.py
index ac0651996..f7a3331a9 100644
--- a/surfsense_evals/src/surfsense_evals/suites/medical/medxpertqa/runner.py
+++ b/surfsense_evals/src/surfsense_evals/suites/medical/medxpertqa/runner.py
@@ -129,19 +129,21 @@ def _load_questions(
             n_images = int(map_row.get("n_images", 0))
             if require_images and n_images <= 0:
                 continue
-            out.append(MXQuestion(
-                qid=qid,
-                question=str(row.get("question") or ""),
-                options={str(k).upper(): str(v) for k, v in (row.get("options") or {}).items()},
-                label=str(row.get("label") or "").strip().upper(),
-                medical_task=str(row.get("medical_task") or "").strip(),
-                body_system=str(row.get("body_system") or "").strip(),
-                question_type=str(row.get("question_type") or "").strip(),
-                split=str(row.get("split") or ""),
-                n_images=n_images,
-                pdf_path=Path(map_row["pdf_path"]),
-                document_id=map_row.get("document_id"),
-            ))
+            out.append(
+                MXQuestion(
+                    qid=qid,
+                    question=str(row.get("question") or ""),
+                    options={str(k).upper(): str(v) for k, v in (row.get("options") or {}).items()},
+                    label=str(row.get("label") or "").strip().upper(),
+                    medical_task=str(row.get("medical_task") or "").strip(),
+                    body_system=str(row.get("body_system") or "").strip(),
+                    question_type=str(row.get("question_type") or "").strip(),
+                    split=str(row.get("split") or ""),
+                    n_images=n_images,
+                    pdf_path=Path(map_row["pdf_path"]),
+                    document_id=map_row.get("document_id"),
+                )
+            )
     out.sort(key=lambda q: (q.split, q.qid))
     if sample_n is not None and sample_n > 0:
         out = out[:sample_n]
@@ -182,51 +184,81 @@ class MedXpertQAMMBenchmark:
 
     def add_run_args(self, parser: argparse.ArgumentParser) -> None:
         parser.add_argument(
-            "--split", default="test", choices=["test", "dev", "all"],
+            "--split",
+            default="test",
+            choices=["test", "dev", "all"],
             help="Which MedXpertQA-MM split to run (default: test).",
         )
         parser.add_argument(
-            "--task", default="all",
+            "--task",
+            default="all",
             help="Filter by medical_task value (e.g. Diagnosis, Treatment, Basic Medicine).",
         )
         parser.add_argument(
-            "--body-system", dest="body_filter", default="all",
+            "--body-system",
+            dest="body_filter",
+            default="all",
             help="Filter by body_system value (e.g. Cardiovascular, Lymphatic).",
         )
         parser.add_argument(
-            "--require-images", dest="require_images", action="store_true",
+            "--require-images",
+            dest="require_images",
+            action="store_true",
             help="Skip rare MM rows that ended up with zero resolvable images.",
         )
-        parser.add_argument("--n", dest="sample_n", type=int, default=None,
-                            help="Run only the first N questions after filters apply.")
-        parser.add_argument("--concurrency", type=int, default=4,
-                            help="Parallel question workers per arm.")
-        parser.add_argument("--no-mentions", dest="no_mentions", action="store_true",
-                            help="SurfSense arm: skip mentioned_document_ids (unscoped retrieval).")
         parser.add_argument(
-            "--pdf-engine", default="native",
+            "--n",
+            dest="sample_n",
+            type=int,
+            default=None,
+            help="Run only the first N questions after filters apply.",
+        )
+        parser.add_argument(
+            "--concurrency", type=int, default=4, help="Parallel question workers per arm."
+        )
+        parser.add_argument(
+            "--no-mentions",
+            dest="no_mentions",
+            action="store_true",
+            help="SurfSense arm: skip mentioned_document_ids (unscoped retrieval).",
+        )
+        parser.add_argument(
+            "--pdf-engine",
+            default="native",
             choices=[e.value for e in PdfEngine],
             help="OpenRouter file-parser engine for the native arm.",
         )
         parser.add_argument(
-            "--max-output-tokens", type=int, default=512,
+            "--max-output-tokens",
+            type=int,
+            default=512,
             help="Cap on completion length for both arms.",
         )
         # Ingest-only knobs (forwarded by the CLI to ingest.run_ingest).
         parser.add_argument(
-            "--max-questions", dest="max_questions", type=int, default=None,
+            "--max-questions",
+            dest="max_questions",
+            type=int,
+            default=None,
             help="(ingest only) cap on number of MM questions to render + upload.",
         )
         parser.add_argument(
-            "--upload-batch-size", dest="upload_batch_size", type=int, default=8,
+            "--upload-batch-size",
+            dest="upload_batch_size",
+            type=int,
+            default=8,
             help="(ingest only) PDFs per fileupload call.",
         )
         parser.add_argument(
-            "--skip-upload", dest="skip_upload", action="store_true",
+            "--skip-upload",
+            dest="skip_upload",
+            action="store_true",
             help="(ingest only) render PDFs locally but don't push to SurfSense.",
         )
         parser.add_argument(
-            "--include-dev", dest="include_dev", action="store_true",
+            "--include-dev",
+            dest="include_dev",
+            action="store_true",
             help="(ingest only) shorthand for --split all.",
         )
         # Per-upload knobs forwarded to /documents/fileupload at ingest;
@@ -270,7 +302,8 @@ class MedXpertQAMMBenchmark:
 
         doc_map, ingest_settings = _load_doc_map(map_path)
         questions = _load_questions(
-            questions_jsonl, doc_map,
+            questions_jsonl,
+            doc_map,
             split_filter=split_filter,
             task_filter=task_filter if task_filter != "all" else None,
             body_filter=body_filter if body_filter != "all" else None,
@@ -378,13 +411,18 @@ class MedXpertQAMMBenchmark:
 
         manifest_path = run_dir / "run_artifact.json"
         manifest_path.write_text(
-            json.dumps({
-                "suite": self.suite,
-                "benchmark": self.name,
-                "raw_path": "raw.jsonl",
-                "metrics": metrics,
-                "extra": artifact.extra,
-            }, indent=2, sort_keys=True) + "\n",
+            json.dumps(
+                {
+                    "suite": self.suite,
+                    "benchmark": self.name,
+                    "raw_path": "raw.jsonl",
+                    "metrics": metrics,
+                    "extra": artifact.extra,
+                },
+                indent=2,
+                sort_keys=True,
+            )
+            + "\n",
             encoding="utf-8",
         )
         return artifact
@@ -536,8 +574,12 @@ def _compute_metrics(
     cost_pct = _safe_pct(surf_cost_agg.mean, native_cost_agg.mean)
     lat_pct = _safe_pct(surf_lat_agg.median, native_lat_agg.median)
 
-    per_task = _per_field(questions, native_correct, surf_correct, key=lambda q: q.medical_task or "unknown")
-    per_body = _per_field(questions, native_correct, surf_correct, key=lambda q: q.body_system or "unknown")
+    per_task = _per_field(
+        questions, native_correct, surf_correct, key=lambda q: q.medical_task or "unknown"
+    )
+    per_body = _per_field(
+        questions, native_correct, surf_correct, key=lambda q: q.body_system or "unknown"
+    )
 
     return {
         "native": {
@@ -593,8 +635,7 @@ def _per_field(
             "native_accuracy": (sum(n_correct) / len(pairs)) if pairs else 0.0,
             "surfsense_accuracy": (sum(s_correct) / len(pairs)) if pairs else 0.0,
             "delta_accuracy_pp": (
-                100.0 * (sum(s_correct) - sum(n_correct)) / len(pairs)
-                if pairs else 0.0
+                100.0 * (sum(s_correct) - sum(n_correct)) / len(pairs) if pairs else 0.0
             ),
         }
     return out
diff --git a/surfsense_evals/src/surfsense_evals/suites/medical/mirage/__init__.py b/surfsense_evals/src/surfsense_evals/suites/medical/mirage/__init__.py
index e527b37f4..265dd62f7 100644
--- a/surfsense_evals/src/surfsense_evals/suites/medical/mirage/__init__.py
+++ b/surfsense_evals/src/surfsense_evals/suites/medical/mirage/__init__.py
@@ -11,7 +11,7 @@ document — the corpus is millions of biomedical snippets.
 
 from __future__ import annotations
 
-from .runner import MirageBenchmark
 from ....core import registry as _registry
+from .runner import MirageBenchmark
 
 _registry.register(MirageBenchmark())
diff --git a/surfsense_evals/src/surfsense_evals/suites/medical/mirage/ingest.py b/surfsense_evals/src/surfsense_evals/suites/medical/mirage/ingest.py
index 59006b6c0..c4aa53fe2 100644
--- a/surfsense_evals/src/surfsense_evals/suites/medical/mirage/ingest.py
+++ b/surfsense_evals/src/surfsense_evals/suites/medical/mirage/ingest.py
@@ -48,9 +48,7 @@ from ....core.registry import RunContext
 logger = logging.getLogger(__name__)
 
 
-MIRAGE_BENCHMARK_URL = (
-    "https://raw.githubusercontent.com/Teddy-XiongGZ/MIRAGE/main/benchmark.json"
-)
+MIRAGE_BENCHMARK_URL = "https://raw.githubusercontent.com/Teddy-XiongGZ/MIRAGE/main/benchmark.json"
 # Upstream only ships ONE zip — top-10k retrievals across 5 retrievers,
 # ~16 GB. We default to skipping it (see `--skip-snippet-filter`) and
 # ingesting the chosen corpus in full; this URL is only fetched when
@@ -93,6 +91,24 @@ class SnippetRow:
 # ---------------------------------------------------------------------------
 
 
+def _reuse_cached_dest(dest: Path, *, expect_zip: bool, label: str) -> Path | None:
+    """Return ``dest`` if a usable cache hit, else ``None`` (and delete corrupt zips)."""
+
+    if not dest.exists():
+        return None
+    if expect_zip and not _is_valid_zip(dest):
+        logger.warning(
+            "Cached %s at %s failed ZIP validation (size=%d B); deleting and re-downloading.",
+            label,
+            dest,
+            dest.stat().st_size,
+        )
+        dest.unlink(missing_ok=True)
+        return None
+    logger.info("Using cached %s at %s", label, dest)
+    return dest
+
+
 async def _fetch_to_path(
     url: str,
     *,
@@ -127,19 +143,9 @@ async def _fetch_to_path(
       surprise-grabbing 16 GB on a slow link.
     """
 
-    if dest.exists():
-        if expect_zip and not _is_valid_zip(dest):
-            logger.warning(
-                "Cached %s at %s failed ZIP validation (size=%d B); deleting "
-                "and re-downloading.",
-                label,
-                dest,
-                dest.stat().st_size,
-            )
-            dest.unlink(missing_ok=True)
-        else:
-            logger.info("Using cached %s at %s", label, dest)
-            return dest
+    cached = _reuse_cached_dest(dest, expect_zip=expect_zip, label=label)
+    if cached is not None:
+        return cached
 
     dest.parent.mkdir(parents=True, exist_ok=True)
     partial = dest.with_suffix(dest.suffix + ".partial")
@@ -167,42 +173,44 @@ async def _fetch_to_path(
             )
 
         try:
-            async with httpx.AsyncClient(
-                timeout=httpx.Timeout(timeout_s, connect=20.0),
-                follow_redirects=True,
-            ) as client:
-                async with client.stream("GET", url, headers=headers) as response:
-                    if existing_bytes and response.status_code == 200:
-                        logger.warning(
-                            "Server ignored Range header for %s; restarting from 0.",
-                            label,
-                        )
-                        partial.unlink(missing_ok=True)
-                        existing_bytes = 0
-                    elif response.status_code == 416:
-                        # Range not satisfiable — the .partial is at or
-                        # past the end. Treat as "already downloaded";
-                        # validate by closing and re-opening for atomic
-                        # rename below.
-                        logger.info(
-                            "Server reports %s already complete (HTTP 416).",
-                            label,
-                        )
-                    elif response.status_code not in (200, 206):
-                        response.raise_for_status()
+            async with (
+                httpx.AsyncClient(
+                    timeout=httpx.Timeout(timeout_s, connect=20.0),
+                    follow_redirects=True,
+                ) as client,
+                client.stream("GET", url, headers=headers) as response,
+            ):
+                if existing_bytes and response.status_code == 200:
+                    logger.warning(
+                        "Server ignored Range header for %s; restarting from 0.",
+                        label,
+                    )
+                    partial.unlink(missing_ok=True)
+                    existing_bytes = 0
+                elif response.status_code == 416:
+                    # Range not satisfiable — the .partial is at or
+                    # past the end. Treat as "already downloaded";
+                    # validate by closing and re-opening for atomic
+                    # rename below.
+                    logger.info(
+                        "Server reports %s already complete (HTTP 416).",
+                        label,
+                    )
+                elif response.status_code not in (200, 206):
+                    response.raise_for_status()
 
-                    total_size = _planned_total_size(response, existing_bytes)
-                    if (
-                        total_size is not None
-                        and total_size > _LARGE_DOWNLOAD_BYTES
-                        and not allow_large_download
-                    ):
-                        raise _LargeDownloadAbort(label, total_size)
+                total_size = _planned_total_size(response, existing_bytes)
+                if (
+                    total_size is not None
+                    and total_size > _LARGE_DOWNLOAD_BYTES
+                    and not allow_large_download
+                ):
+                    raise _LargeDownloadAbort(label, total_size)
 
-                    mode = "ab" if existing_bytes else "wb"
-                    with partial.open(mode) as fh:
-                        async for chunk in response.aiter_bytes(chunk_size=1 << 18):
-                            fh.write(chunk)
+                mode = "ab" if existing_bytes else "wb"
+                with partial.open(mode) as fh:
+                    async for chunk in response.aiter_bytes(chunk_size=1 << 18):
+                        fh.write(chunk)
             # Optional content sanity check before promoting to dest.
             if expect_zip and not _is_valid_zip(partial):
                 raise zipfile.BadZipFile(
@@ -215,7 +223,7 @@ async def _fetch_to_path(
             raise
         except _RETRYABLE_NET_EXC as exc:
             last_exc = exc
-            wait = min(60.0, 2.0 ** attempt)
+            wait = min(60.0, 2.0**attempt)
             logger.warning(
                 "Network error fetching %s (%s: %s); retrying in %.0fs.",
                 label,
@@ -228,7 +236,7 @@ async def _fetch_to_path(
             last_exc = exc
             # Truncated body — drop the partial and retry from scratch.
             partial.unlink(missing_ok=True)
-            wait = min(60.0, 2.0 ** attempt)
+            wait = min(60.0, 2.0**attempt)
             logger.warning(
                 "Truncated ZIP for %s; restarting from byte 0 in %.0fs.",
                 label,
@@ -270,9 +278,9 @@ class _LargeDownloadAbort(RuntimeError):
     """Raised when a download exceeds the safety threshold without opt-in."""
 
     def __init__(self, label: str, size_bytes: int) -> None:
-        gb = size_bytes / (1024 ** 3)
+        gb = size_bytes / (1024**3)
         super().__init__(
-            f"{label} would download ~{gb:.1f} GB, above the {_LARGE_DOWNLOAD_BYTES / (1024 ** 3):.0f} GB safety cap. "
+            f"{label} would download ~{gb:.1f} GB, above the {_LARGE_DOWNLOAD_BYTES / (1024**3):.0f} GB safety cap. "
             "Re-run with `--allow-large-download` to acknowledge, or use "
             "`--skip-snippet-filter` to bypass this download entirely and "
             "ingest the full corpus instead."
@@ -312,9 +320,7 @@ def _read_snippet_ids(zip_path: Path, *, tasks: list[str]) -> dict[str, set[str]
     return out
 
 
-def _load_corpus(
-    corpus_name: str, snippet_ids: set[str] | None
-) -> Iterable[SnippetRow]:
+def _load_corpus(corpus_name: str, snippet_ids: set[str] | None) -> Iterable[SnippetRow]:
     """Stream rows from a MedRAG HF corpus.
 
     * ``snippet_ids=None`` → yield every row (full-corpus ingestion path).
@@ -533,10 +539,7 @@ async def run_ingest(
                 logger.warning("Failed to list chunks for doc_id=%s: %s", doc_id, exc)
                 continue
             for chunk in chunks:
-                fh.write(
-                    json.dumps({"chunk_id": chunk.id, "document_id": doc_id})
-                    + "\n"
-                )
+                fh.write(json.dumps({"chunk_id": chunk.id, "document_id": doc_id}) + "\n")
 
     new_state = ctx.suite_state
     new_state.ingestion_maps["mirage"] = str(snippet_map_path)
diff --git a/surfsense_evals/src/surfsense_evals/suites/medical/mirage/prompt.py b/surfsense_evals/src/surfsense_evals/suites/medical/mirage/prompt.py
index 9e5b1c618..3e5192aaa 100644
--- a/surfsense_evals/src/surfsense_evals/suites/medical/mirage/prompt.py
+++ b/surfsense_evals/src/surfsense_evals/suites/medical/mirage/prompt.py
@@ -8,7 +8,6 @@ from __future__ import annotations
 
 from collections.abc import Mapping
 
-
 _PROMPT_TEMPLATE = """\
 You are a helpful medical expert. Answer the following multiple-choice
 question using the relevant medical knowledge available to you (and any
diff --git a/surfsense_evals/src/surfsense_evals/suites/medical/mirage/runner.py b/surfsense_evals/src/surfsense_evals/suites/medical/mirage/runner.py
index b01b645a9..76e719f1f 100644
--- a/surfsense_evals/src/surfsense_evals/suites/medical/mirage/runner.py
+++ b/surfsense_evals/src/surfsense_evals/suites/medical/mirage/runner.py
@@ -29,7 +29,6 @@ from ....core.ingest_settings import (
 )
 from ....core.metrics.mc_accuracy import accuracy_with_wilson_ci, macro_accuracy
 from ....core.registry import (
-    Benchmark,
     ReportSection,
     RunArtifact,
     RunContext,
@@ -135,15 +134,23 @@ class MirageBenchmark:
             choices=("all", *_TASKS),
             help="Run a single task or all (default: all).",
         )
-        parser.add_argument("--n", dest="sample_n", type=int, default=None,
-                            help="Stratified sample size across tasks.")
+        parser.add_argument(
+            "--n",
+            dest="sample_n",
+            type=int,
+            default=None,
+            help="Stratified sample size across tasks.",
+        )
         parser.add_argument("--concurrency", type=int, default=4)
         parser.add_argument(
-            "--corpus", default="MedRAG/textbooks",
+            "--corpus",
+            default="MedRAG/textbooks",
             help="HF MedRAG corpus to ingest from (default: MedRAG/textbooks).",
         )
         parser.add_argument(
-            "--max-snippets-per-task", type=int, default=None,
+            "--max-snippets-per-task",
+            type=int,
+            default=None,
             help="Cap the per-task ingestion to N snippets (smoke).",
         )
         # Mutually exclusive: by default we skip the upstream 16 GB
@@ -153,18 +160,24 @@ class MirageBenchmark:
         # --allow-large-download).
         snippet_group = parser.add_mutually_exclusive_group()
         snippet_group.add_argument(
-            "--use-snippet-filter", dest="use_snippet_filter", action="store_true",
+            "--use-snippet-filter",
+            dest="use_snippet_filter",
+            action="store_true",
             default=False,
             help="Download retrieved_snippets_10k.zip (~16 GB) and "
-                 "filter the corpus to those ids before ingest. "
-                 "Default: skip and ingest entire corpus.",
+            "filter the corpus to those ids before ingest. "
+            "Default: skip and ingest entire corpus.",
         )
         snippet_group.add_argument(
-            "--skip-snippet-filter", dest="use_snippet_filter", action="store_false",
+            "--skip-snippet-filter",
+            dest="use_snippet_filter",
+            action="store_false",
             help="(Default) Skip the 16 GB upstream zip; ingest entire corpus.",
         )
         parser.add_argument(
-            "--allow-large-download", action="store_true", default=False,
+            "--allow-large-download",
+            action="store_true",
+            default=False,
             help="Permit downloads larger than 2 GB (e.g. retrieved_snippets_10k.zip).",
         )
         # Per-upload knobs; ignored at run-time (runner reads the
@@ -197,16 +210,13 @@ class MirageBenchmark:
                 "`python -m surfsense_evals ingest medical mirage` first."
             )
         benchmark = json.loads(bench_path.read_text(encoding="utf-8"))
-        ingest_settings = read_settings_header(
-            ctx.maps_dir() / "mirage_snippet_map.jsonl"
-        )
+        ingest_settings = read_settings_header(ctx.maps_dir() / "mirage_snippet_map.jsonl")
         questions = _load_questions(benchmark, tasks=tasks, sample_n=sample_n)
         if not questions:
             raise RuntimeError(
                 f"No MIRAGE questions matched task={task_filter!r} sample_n={sample_n!r}."
             )
-        logger.info("MIRAGE: scheduled %d questions across tasks %s",
-                    len(questions), tasks)
+        logger.info("MIRAGE: scheduled %d questions across tasks %s", len(questions), tasks)
 
         arm = SurfSenseArm(
             client=ctx.new_chat_client(),
@@ -229,7 +239,7 @@ class MirageBenchmark:
         run_dir = ctx.runs_dir(run_timestamp=run_timestamp)
         raw_path = run_dir / "raw.jsonl"
         with raw_path.open("w", encoding="utf-8") as fh:
-            for q, res in zip(questions, results):
+            for q, res in zip(questions, results, strict=False):
                 fh.write(
                     json.dumps(
                         {
@@ -246,7 +256,7 @@ class MirageBenchmark:
         for task in tasks:
             n_correct = 0
             n_total = 0
-            for q, res in zip(questions, results):
+            for q, res in zip(questions, results, strict=False):
                 if q.task != task:
                     continue
                 n_total += 1
@@ -256,7 +266,10 @@ class MirageBenchmark:
             per_task_acc[task] = acc.to_dict()
 
         macro = macro_accuracy(
-            {t: accuracy_with_wilson_ci(d["n_correct"], d["n_total"]) for t, d in per_task_acc.items()}
+            {
+                t: accuracy_with_wilson_ci(d["n_correct"], d["n_total"])
+                for t, d in per_task_acc.items()
+            }
         )
         metrics = {"per_task": per_task_acc, "macro_accuracy": macro}
 
diff --git a/surfsense_evals/src/surfsense_evals/suites/multimodal_doc/mmlongbench/grader.py b/surfsense_evals/src/surfsense_evals/suites/multimodal_doc/mmlongbench/grader.py
index 7edad73eb..ecb5144e8 100644
--- a/surfsense_evals/src/surfsense_evals/suites/multimodal_doc/mmlongbench/grader.py
+++ b/surfsense_evals/src/surfsense_evals/suites/multimodal_doc/mmlongbench/grader.py
@@ -112,8 +112,9 @@ def _grade_int(pred: str, gold: str) -> GradeResult:
     if p_match is None:
         return GradeResult(False, 0.0, "int_eq", str(p_match), str(g_val))
     p_val = int(p_match.group(0).replace(",", ""))
-    return GradeResult(p_val == g_val, 1.0 if p_val == g_val else 0.0,
-                       "int_eq", str(p_val), str(g_val))
+    return GradeResult(
+        p_val == g_val, 1.0 if p_val == g_val else 0.0, "int_eq", str(p_val), str(g_val)
+    )
 
 
 _FLOAT_RE = re.compile(r"-?\d+(?:[.,]\d+)?")
@@ -145,15 +146,15 @@ def _grade_list(pred: str, gold: str) -> GradeResult:
         return _grade_str(pred, gold)
     inter = g_items & p_items
     if not inter:
-        return GradeResult(False, 0.0, "list_set",
-                           ", ".join(sorted(p_items)),
-                           ", ".join(sorted(g_items)))
+        return GradeResult(
+            False, 0.0, "list_set", ", ".join(sorted(p_items)), ", ".join(sorted(g_items))
+        )
     precision = len(inter) / len(p_items) if p_items else 0.0
     recall = len(inter) / len(g_items)
     f1 = (2 * precision * recall / (precision + recall)) if (precision + recall) else 0.0
-    return GradeResult(f1 >= 0.999, f1, "list_set",
-                       ", ".join(sorted(p_items)),
-                       ", ".join(sorted(g_items)))
+    return GradeResult(
+        f1 >= 0.999, f1, "list_set", ", ".join(sorted(p_items)), ", ".join(sorted(g_items))
+    )
 
 
 def _grade_none(pred: str, gold: str) -> GradeResult:
@@ -188,8 +189,11 @@ def _grade_none(pred: str, gold: str) -> GradeResult:
                 expressed_unknown = True
                 break
     return GradeResult(
-        expressed_unknown, 1.0 if expressed_unknown else 0.0,
-        "none_match", p, _normalise_text(gold),
+        expressed_unknown,
+        1.0 if expressed_unknown else 0.0,
+        "none_match",
+        p,
+        _normalise_text(gold),
     )
 
 
diff --git a/surfsense_evals/src/surfsense_evals/suites/multimodal_doc/mmlongbench/ingest.py b/surfsense_evals/src/surfsense_evals/suites/multimodal_doc/mmlongbench/ingest.py
index 15cdbeb77..3c736756a 100644
--- a/surfsense_evals/src/surfsense_evals/suites/multimodal_doc/mmlongbench/ingest.py
+++ b/surfsense_evals/src/surfsense_evals/suites/multimodal_doc/mmlongbench/ingest.py
@@ -41,6 +41,7 @@ logger = logging.getLogger(__name__)
 HF_REPO_ID = "yubo2333/MMLongBench-Doc"
 HF_REPO_TYPE = "dataset"
 
+
 # Lazy import: huggingface_hub + pyarrow are heavyweight; keep the
 # benchmark module importable on machines that have only the core
 # install (e.g. CI lint jobs).
@@ -63,11 +64,11 @@ def _list_repo_files() -> list[str]:
 
 @dataclass
 class MMLongBenchQuestion:
-    doc_id: str          # filename inside the documents/ folder
+    doc_id: str  # filename inside the documents/ folder
     doc_type: str
     question: str
     answer: str
-    answer_format: str   # Str / Int / Float / List / None
+    answer_format: str  # Str / Int / Float / List / None
     evidence_pages: list[int]
     evidence_sources: list[str]
 
@@ -161,7 +162,9 @@ def _download_questions_parquet(cache_dir: Path) -> Path:
         )
         parquet_paths.append(Path(local))
         logger.info("Cached MMLongBench parquet shard %s -> %s", rel, local)
-    return parquet_paths[0] if len(parquet_paths) == 1 else _merge_parquets(parquet_paths, cache_dir)
+    return (
+        parquet_paths[0] if len(parquet_paths) == 1 else _merge_parquets(parquet_paths, cache_dir)
+    )
 
 
 def _merge_parquets(paths: list[Path], cache_dir: Path) -> Path:
@@ -221,7 +224,7 @@ async def _upload_pdfs(
     name_to_id: dict[str, int] = {}
     pdf_list = list(pdf_paths)
     for batch_start in range(0, len(pdf_list), batch_size):
-        batch = pdf_list[batch_start:batch_start + batch_size]
+        batch = pdf_list[batch_start : batch_start + batch_size]
         result = await docs_client.upload(
             files=batch,
             search_space_id=ctx.search_space_id,
@@ -243,8 +246,10 @@ async def _upload_pdfs(
                 name_to_id[s.title] = s.document_id
         logger.info(
             "Uploaded MMLongBench batch %d-%d: %d new, %d duplicate",
-            batch_start, batch_start + len(batch),
-            len(result.document_ids), len(result.duplicate_document_ids),
+            batch_start,
+            batch_start + len(batch),
+            len(result.document_ids),
+            len(result.duplicate_document_ids),
         )
     return name_to_id
 
@@ -299,15 +304,20 @@ async def run_ingest(
     questions_jsonl = bench_dir / "questions.jsonl"
     with questions_jsonl.open("w", encoding="utf-8") as fh:
         for q in questions:
-            fh.write(json.dumps({
-                "doc_id": q.doc_id,
-                "doc_type": q.doc_type,
-                "question": q.question,
-                "answer": q.answer,
-                "answer_format": q.answer_format,
-                "evidence_pages": q.evidence_pages,
-                "evidence_sources": q.evidence_sources,
-            }) + "\n")
+            fh.write(
+                json.dumps(
+                    {
+                        "doc_id": q.doc_id,
+                        "doc_type": q.doc_type,
+                        "question": q.question,
+                        "answer": q.answer,
+                        "answer_format": q.answer_format,
+                        "evidence_pages": q.evidence_pages,
+                        "evidence_sources": q.evidence_sources,
+                    }
+                )
+                + "\n"
+            )
     logger.info("Wrote %d MMLongBench questions to %s", len(questions), questions_jsonl)
 
     # Step 2: download unique PDFs
@@ -348,12 +358,17 @@ async def run_ingest(
             local = pdf_paths.get(doc_id)
             if local is None:
                 continue
-            fh.write(json.dumps({
-                "doc_id": doc_id,
-                "document_id": name_to_id.get(local.name),
-                "pdf_path": str(local),
-                "n_questions": sum(1 for q in questions if q.doc_id == doc_id),
-            }) + "\n")
+            fh.write(
+                json.dumps(
+                    {
+                        "doc_id": doc_id,
+                        "document_id": name_to_id.get(local.name),
+                        "pdf_path": str(local),
+                        "n_questions": sum(1 for q in questions if q.doc_id == doc_id),
+                    }
+                )
+                + "\n"
+            )
     logger.info("Wrote MMLongBench doc map to %s", map_path)
 
     new_state = ctx.suite_state
diff --git a/surfsense_evals/src/surfsense_evals/suites/multimodal_doc/mmlongbench/prompt.py b/surfsense_evals/src/surfsense_evals/suites/multimodal_doc/mmlongbench/prompt.py
index 27d6a0d00..70229dc15 100644
--- a/surfsense_evals/src/surfsense_evals/suites/multimodal_doc/mmlongbench/prompt.py
+++ b/surfsense_evals/src/surfsense_evals/suites/multimodal_doc/mmlongbench/prompt.py
@@ -18,10 +18,7 @@ _FORMAT_HINTS: dict[str, str] = {
         "Respond with the answer as a short phrase, no full sentence. "
         "Format your final line as `Answer: <text>`."
     ),
-    "int": (
-        "Respond with a single integer only. "
-        "Format your final line as `Answer: <integer>`."
-    ),
+    "int": ("Respond with a single integer only. Format your final line as `Answer: <integer>`."),
     "float": (
         "Respond with a single decimal number only (no units). "
         "Format your final line as `Answer: <number>`."
diff --git a/surfsense_evals/src/surfsense_evals/suites/multimodal_doc/mmlongbench/runner.py b/surfsense_evals/src/surfsense_evals/suites/multimodal_doc/mmlongbench/runner.py
index b7685766e..782ba5d9a 100644
--- a/surfsense_evals/src/surfsense_evals/suites/multimodal_doc/mmlongbench/runner.py
+++ b/surfsense_evals/src/surfsense_evals/suites/multimodal_doc/mmlongbench/runner.py
@@ -58,8 +58,8 @@ logger = logging.getLogger(__name__)
 
 @dataclass
 class MMLBQuestion:
-    qid: str               # synthesised from doc_id + index
-    doc_id: str            # filename inside the documents/ folder
+    qid: str  # synthesised from doc_id + index
+    doc_id: str  # filename inside the documents/ folder
     doc_type: str
     question: str
     gold_answer: str
@@ -126,18 +126,20 @@ def _load_questions(
                 continue
             idx = per_doc_counter.get(doc_id, 0)
             per_doc_counter[doc_id] = idx + 1
-            out.append(MMLBQuestion(
-                qid=f"{doc_id}::Q{idx:03d}",
-                doc_id=doc_id,
-                doc_type=str(row.get("doc_type") or "").strip(),
-                question=str(row.get("question") or "").strip(),
-                gold_answer=gold,
-                answer_format=answer_format,
-                evidence_pages=list(row.get("evidence_pages") or []),
-                evidence_sources=list(row.get("evidence_sources") or []),
-                pdf_path=Path(map_row["pdf_path"]),
-                document_id=map_row.get("document_id"),
-            ))
+            out.append(
+                MMLBQuestion(
+                    qid=f"{doc_id}::Q{idx:03d}",
+                    doc_id=doc_id,
+                    doc_type=str(row.get("doc_type") or "").strip(),
+                    question=str(row.get("question") or "").strip(),
+                    gold_answer=gold,
+                    answer_format=answer_format,
+                    evidence_pages=list(row.get("evidence_pages") or []),
+                    evidence_sources=list(row.get("evidence_sources") or []),
+                    pdf_path=Path(map_row["pdf_path"]),
+                    document_id=map_row.get("document_id"),
+                )
+            )
     out.sort(key=lambda q: (q.doc_id, q.qid))
     if sample_n is not None and sample_n > 0:
         out = out[:sample_n]
@@ -202,41 +204,61 @@ class MMLongBenchDocBenchmark:
             help="Filter to one answer format. 'none' = unanswerable probes only.",
         )
         parser.add_argument(
-            "--n", dest="sample_n", type=int, default=None,
+            "--n",
+            dest="sample_n",
+            type=int,
+            default=None,
             help="Run only the first N questions after filters apply.",
         )
         parser.add_argument(
-            "--skip-unanswerable", dest="skip_unanswerable", action="store_true",
+            "--skip-unanswerable",
+            dest="skip_unanswerable",
+            action="store_true",
             help="Drop ~22%% unanswerable questions (use to compare against baselines that don't include them).",
         )
         parser.add_argument(
-            "--concurrency", type=int, default=4,
+            "--concurrency",
+            type=int,
+            default=4,
             help="Parallel question workers per arm.",
         )
         parser.add_argument(
-            "--no-mentions", dest="no_mentions", action="store_true",
+            "--no-mentions",
+            dest="no_mentions",
+            action="store_true",
             help="SurfSense arm: skip mentioned_document_ids (unscoped retrieval).",
         )
         parser.add_argument(
-            "--pdf-engine", default="native",
+            "--pdf-engine",
+            default="native",
             choices=[e.value for e in PdfEngine],
             help="OpenRouter file-parser engine for the native arm.",
         )
         parser.add_argument(
-            "--max-output-tokens", type=int, default=512,
+            "--max-output-tokens",
+            type=int,
+            default=512,
             help="Cap on completion length for both arms.",
         )
         # Ingest-only knobs (forwarded by the CLI to ingest.run_ingest).
         parser.add_argument(
-            "--max-docs", dest="max_docs", type=int, default=None,
+            "--max-docs",
+            dest="max_docs",
+            type=int,
+            default=None,
             help="(ingest only) cap on number of unique PDFs to download + upload.",
         )
         parser.add_argument(
-            "--upload-batch-size", dest="upload_batch_size", type=int, default=8,
+            "--upload-batch-size",
+            dest="upload_batch_size",
+            type=int,
+            default=8,
             help="(ingest only) PDFs per fileupload call.",
         )
         parser.add_argument(
-            "--skip-upload", dest="skip_upload", action="store_true",
+            "--skip-upload",
+            dest="skip_upload",
+            action="store_true",
             help="(ingest only) cache PDFs locally but don't push to SurfSense.",
         )
         # Per-upload knobs forwarded to /documents/fileupload at ingest;
@@ -278,7 +300,8 @@ class MMLongBenchDocBenchmark:
 
         doc_map, ingest_settings = _load_doc_map(map_path)
         questions = _load_questions(
-            questions_jsonl, doc_map,
+            questions_jsonl,
+            doc_map,
             doc_filter=doc_filter,
             format_filter=None if format_filter == "all" else format_filter,
             sample_n=sample_n,
@@ -292,9 +315,7 @@ class MMLongBenchDocBenchmark:
 
         api_key = os.environ.get("OPENROUTER_API_KEY")
         if not api_key:
-            raise RuntimeError(
-                "OPENROUTER_API_KEY env var is required for the native arm."
-            )
+            raise RuntimeError("OPENROUTER_API_KEY env var is required for the native arm.")
 
         # Native arm slug differs from SurfSense slug only in cost-arbitrage
         # scenario; otherwise both arms answer with provider_model.
@@ -362,18 +383,30 @@ class MMLongBenchDocBenchmark:
                     "evidence_sources": q.evidence_sources,
                     "document_id": q.document_id,
                 }
-                fh.write(json.dumps({
-                    **meta,
-                    **n_res.to_jsonl(),
-                    "graded": _grade_to_jsonl(n_g),
-                }) + "\n")
-                fh.write(json.dumps({
-                    **meta,
-                    **s_res.to_jsonl(),
-                    "graded": _grade_to_jsonl(s_g),
-                }) + "\n")
+                fh.write(
+                    json.dumps(
+                        {
+                            **meta,
+                            **n_res.to_jsonl(),
+                            "graded": _grade_to_jsonl(n_g),
+                        }
+                    )
+                    + "\n"
+                )
+                fh.write(
+                    json.dumps(
+                        {
+                            **meta,
+                            **s_res.to_jsonl(),
+                            "graded": _grade_to_jsonl(s_g),
+                        }
+                    )
+                    + "\n"
+                )
 
-        metrics = _compute_metrics(questions, native_results, surf_results, native_grades, surf_grades)
+        metrics = _compute_metrics(
+            questions, native_results, surf_results, native_grades, surf_grades
+        )
         artifact = RunArtifact(
             suite=self.suite,
             benchmark=self.name,
@@ -398,13 +431,18 @@ class MMLongBenchDocBenchmark:
 
         manifest_path = run_dir / "run_artifact.json"
         manifest_path.write_text(
-            json.dumps({
-                "suite": self.suite,
-                "benchmark": self.name,
-                "raw_path": "raw.jsonl",
-                "metrics": metrics,
-                "extra": artifact.extra,
-            }, indent=2, sort_keys=True) + "\n",
+            json.dumps(
+                {
+                    "suite": self.suite,
+                    "benchmark": self.name,
+                    "raw_path": "raw.jsonl",
+                    "metrics": metrics,
+                    "extra": artifact.extra,
+                },
+                indent=2,
+                sort_keys=True,
+            )
+            + "\n",
             encoding="utf-8",
         )
         return artifact
@@ -450,9 +488,7 @@ class MMLongBenchDocBenchmark:
             f"(McNemar p={_fmt(delta.get('mcnemar_p_value'), 4)}, "
             f"method={delta.get('mcnemar_method')})"
         )
-        body_lines.append(
-            f"  - F1 (mean): SurfSense {_pp(delta.get('f1_pp'))} pp"
-        )
+        body_lines.append(f"  - F1 (mean): SurfSense {_pp(delta.get('f1_pp'))} pp")
         body_lines.append(
             f"  - Bootstrap 95% CI on accuracy delta: "
             f"[{_pp(delta.get('bootstrap_ci_low'))}pp, {_pp(delta.get('bootstrap_ci_high'))}pp]"
@@ -472,8 +508,8 @@ class MMLongBenchDocBenchmark:
             for fmt, vals in sorted(per_format.items()):
                 body_lines.append(
                     f"  - {fmt}: SurfSense {_pp(vals.get('delta_accuracy_pp'))} pp "
-                    f"(n={vals.get('n')}, native acc={vals.get('native_accuracy', 0)*100:.1f}%, "
-                    f"surf acc={vals.get('surfsense_accuracy', 0)*100:.1f}%)"
+                    f"(n={vals.get('n')}, native acc={vals.get('native_accuracy', 0) * 100:.1f}%, "
+                    f"surf acc={vals.get('surfsense_accuracy', 0) * 100:.1f}%)"
                 )
 
         return ReportSection(
@@ -576,8 +612,7 @@ def _compute_metrics(
             "native_accuracy": (sum(n_correct) / len(pairs)) if pairs else 0.0,
             "surfsense_accuracy": (sum(s_correct) / len(pairs)) if pairs else 0.0,
             "delta_accuracy_pp": (
-                100.0 * (sum(s_correct) - sum(n_correct)) / len(pairs)
-                if pairs else 0.0
+                100.0 * (sum(s_correct) - sum(n_correct)) / len(pairs) if pairs else 0.0
             ),
         }
 
@@ -593,8 +628,12 @@ def _compute_metrics(
             "latency_ms_mean": native_latency_agg.mean,
             "latency_ms_median": native_latency_agg.median,
             "latency_ms_p95": native_latency_agg.p95,
-            "input_tokens_mean": (sum(native_in_tokens) / len(native_in_tokens)) if native_in_tokens else 0.0,
-            "output_tokens_mean": (sum(native_out_tokens) / len(native_out_tokens)) if native_out_tokens else 0.0,
+            "input_tokens_mean": (sum(native_in_tokens) / len(native_in_tokens))
+            if native_in_tokens
+            else 0.0,
+            "output_tokens_mean": (sum(native_out_tokens) / len(native_out_tokens))
+            if native_out_tokens
+            else 0.0,
         },
         "surfsense": {
             **surf_acc.to_dict(),
diff --git a/surfsense_evals/src/surfsense_evals/suites/multimodal_doc/parser_compare/ingest.py b/surfsense_evals/src/surfsense_evals/suites/multimodal_doc/parser_compare/ingest.py
index 93c8db4ab..a7fce60d1 100644
--- a/surfsense_evals/src/surfsense_evals/suites/multimodal_doc/parser_compare/ingest.py
+++ b/surfsense_evals/src/surfsense_evals/suites/multimodal_doc/parser_compare/ingest.py
@@ -41,8 +41,6 @@ from typing import Any
 
 from ....core.config import set_suite_state
 from ....core.parsers import (
-    AzureDIError,
-    LlamaCloudError,
     count_pdf_pages,
     parse_with_azure_di,
     parse_with_llamacloud,
@@ -55,9 +53,9 @@ logger = logging.getLogger(__name__)
 # Order matters for the manifest only (deterministic JSONL diffs);
 # the runner doesn't rely on it.
 PARSER_ARMS: tuple[tuple[str, str, str], ...] = (
-    ("azure_basic_lc",       "azure",      "basic"),
-    ("azure_premium_lc",     "azure",      "premium"),
-    ("llamacloud_basic_lc",  "llamacloud", "basic"),
+    ("azure_basic_lc", "azure", "basic"),
+    ("azure_premium_lc", "azure", "premium"),
+    ("llamacloud_basic_lc", "llamacloud", "basic"),
     ("llamacloud_premium_lc", "llamacloud", "premium"),
 )
 
@@ -100,9 +98,7 @@ class PdfManifestRow:
             "pdf_path": str(self.pdf_path),
             "document_id": self.document_id,
             "pages": self.pages,
-            "extractions": {
-                arm: ext.to_jsonl() for arm, ext in self.extractions.items()
-            },
+            "extractions": {arm: ext.to_jsonl() for arm, ext in self.extractions.items()},
         }
 
 
@@ -126,12 +122,14 @@ async def _run_one_extraction(
         markdown = await parse_with_azure_di(pdf_path, processing_mode=mode)
     elif parser == "llamacloud":
         markdown = await parse_with_llamacloud(
-            pdf_path, processing_mode=mode, estimated_pages=estimated_pages,
+            pdf_path,
+            processing_mode=mode,
+            estimated_pages=estimated_pages,
         )
     else:
         raise ValueError(f"Unknown parser {parser!r}")
     out_path.parent.mkdir(parents=True, exist_ok=True)
-    out_path.write_text(markdown, encoding="utf-8")
+    await asyncio.to_thread(out_path.write_text, markdown, encoding="utf-8")
     return markdown, time.monotonic() - started
 
 
@@ -170,14 +168,17 @@ async def _extract_one_pdf(
                 error="(cached)",
             )
             logger.info(
-                "Cached extraction reused: %s (%d chars)", out_path.name, len(cached),
+                "Cached extraction reused: %s (%d chars)",
+                out_path.name,
+                len(cached),
             )
             coros.append(_noop())
         else:
             coros.append(
                 _run_one_extraction(
                     pdf_path,
-                    parser=parser, mode=mode,
+                    parser=parser,
+                    mode=mode,
                     out_path=out_path,
                     estimated_pages=estimated_pages,
                 )
@@ -192,16 +193,24 @@ async def _extract_one_pdf(
             err_msg = f"{type(err).__name__}: {err}"
             logger.warning(
                 "Extraction FAILED for %s [%s/%s]: %s",
-                pdf_path.name, parser, mode, err_msg,
+                pdf_path.name,
+                parser,
+                mode,
+                err_msg,
             )
             out[arm_name] = ExtractionResult(
-                arm=arm_name, parser=parser, mode=mode,
-                status="failed", error=err_msg,
+                arm=arm_name,
+                parser=parser,
+                mode=mode,
+                status="failed",
+                error=err_msg,
             )
         else:
             markdown, elapsed = result
             out[arm_name] = ExtractionResult(
-                arm=arm_name, parser=parser, mode=mode,
+                arm=arm_name,
+                parser=parser,
+                mode=mode,
                 markdown_path=out_path,
                 chars=len(markdown),
                 elapsed_s=elapsed,
@@ -290,9 +299,7 @@ async def run_ingest(
         rows_in_scope = rows_in_scope[:max_docs]
 
     if not rows_in_scope:
-        raise RuntimeError(
-            "No PDFs in scope for parser_compare. Check --docs / --max-docs."
-        )
+        raise RuntimeError("No PDFs in scope for parser_compare. Check --docs / --max-docs.")
 
     bench_dir = ctx.benchmark_data_dir()
     extractions_dir = bench_dir / "extractions"
@@ -319,7 +326,8 @@ async def run_ingest(
 
     logger.info(
         "parser_compare: extracting %d PDFs x 4 parsers (concurrency=%d)",
-        len(rows_in_scope), pdf_concurrency,
+        len(rows_in_scope),
+        pdf_concurrency,
     )
     manifest_rows = await asyncio.gather(*(_process(r) for r in rows_in_scope))
 
@@ -339,12 +347,13 @@ async def run_ingest(
     # Quick summary log
     total_extractions = sum(len(mr.extractions) for mr in manifest_rows)
     failures = sum(
-        1 for mr in manifest_rows for ext in mr.extractions.values()
-        if ext.status != "ok"
+        1 for mr in manifest_rows for ext in mr.extractions.values() if ext.status != "ok"
     )
     logger.info(
         "parser_compare ingest done: %d PDFs, %d extractions, %d failures",
-        len(manifest_rows), total_extractions, failures,
+        len(manifest_rows),
+        total_extractions,
+        failures,
     )
 
 
diff --git a/surfsense_evals/src/surfsense_evals/suites/multimodal_doc/parser_compare/prompt.py b/surfsense_evals/src/surfsense_evals/suites/multimodal_doc/parser_compare/prompt.py
index 7119bbd29..ccde69e71 100644
--- a/surfsense_evals/src/surfsense_evals/suites/multimodal_doc/parser_compare/prompt.py
+++ b/surfsense_evals/src/surfsense_evals/suites/multimodal_doc/parser_compare/prompt.py
@@ -34,10 +34,7 @@ _FORMAT_HINTS: dict[str, str] = {
         "Respond with the answer as a short phrase, no full sentence. "
         "Format your final line as `Answer: <text>`."
     ),
-    "int": (
-        "Respond with a single integer only. "
-        "Format your final line as `Answer: <integer>`."
-    ),
+    "int": ("Respond with a single integer only. Format your final line as `Answer: <integer>`."),
     "float": (
         "Respond with a single decimal number only (no units). "
         "Format your final line as `Answer: <number>`."
@@ -69,11 +66,7 @@ _BASE_INSTRUCTION = (
 def build_native_pdf_prompt(question: str, *, answer_format: str) -> str:
     """Prompt for ``NativePdfArm`` — PDF attached separately as a file part."""
 
-    return (
-        f"{_BASE_INSTRUCTION}\n\n"
-        f"Question: {question.strip()}\n\n"
-        f"{_format_hint(answer_format)}\n"
-    )
+    return f"{_BASE_INSTRUCTION}\n\nQuestion: {question.strip()}\n\n{_format_hint(answer_format)}\n"
 
 
 def build_surfsense_prompt(question: str, *, answer_format: str) -> str:
@@ -82,11 +75,7 @@ def build_surfsense_prompt(question: str, *, answer_format: str) -> str:
     # SurfSense's agent already injects retrieved chunks via its tool
     # loop; the prompt only carries the user-visible question + format
     # hint, mirroring how a human asks the SurfSense UI.
-    return (
-        f"{_BASE_INSTRUCTION}\n\n"
-        f"Question: {question.strip()}\n\n"
-        f"{_format_hint(answer_format)}\n"
-    )
+    return f"{_BASE_INSTRUCTION}\n\nQuestion: {question.strip()}\n\n{_format_hint(answer_format)}\n"
 
 
 def build_long_context_prompt(
@@ -105,7 +94,7 @@ def build_long_context_prompt(
 
     return (
         f"{_BASE_INSTRUCTION}\n\n"
-        f"<document name=\"{document_label}\">\n"
+        f'<document name="{document_label}">\n'
         f"{document_markdown.strip()}\n"
         f"</document>\n\n"
         f"Question: {question.strip()}\n\n"
diff --git a/surfsense_evals/src/surfsense_evals/suites/multimodal_doc/parser_compare/runner.py b/surfsense_evals/src/surfsense_evals/suites/multimodal_doc/parser_compare/runner.py
index 2c4a0ffe4..6c009995f 100644
--- a/surfsense_evals/src/surfsense_evals/suites/multimodal_doc/parser_compare/runner.py
+++ b/surfsense_evals/src/surfsense_evals/suites/multimodal_doc/parser_compare/runner.py
@@ -72,7 +72,7 @@ logger = logging.getLogger(__name__)
 # Cost tariff (per the user's spec: $1 / 1k pages basic, $10 / 1k pages premium).
 # Held as dollars-per-page so per-PDF math is a pure multiply.
 PREPROCESS_USD_PER_PAGE = {
-    "basic":   1.0  / 1000.0,
+    "basic": 1.0 / 1000.0,
     "premium": 10.0 / 1000.0,
 }
 
@@ -183,17 +183,19 @@ def _select_questions(
                 if ext_blob.get("status") == "ok" and ext_blob.get("markdown_path"):
                     extractions[arm_name] = Path(ext_blob["markdown_path"])
 
-            out.append(PCQuestion(
-                qid=f"{doc_id}::Q{idx:03d}",
-                doc_id=doc_id,
-                question=str(row.get("question") or "").strip(),
-                gold_answer=str(row.get("answer") or "").strip(),
-                answer_format=answer_format,
-                pdf_path=Path(map_row["pdf_path"]),
-                document_id=map_row.get("document_id"),
-                pages=int(map_row.get("pages", 0)),
-                extractions=extractions,
-            ))
+            out.append(
+                PCQuestion(
+                    qid=f"{doc_id}::Q{idx:03d}",
+                    doc_id=doc_id,
+                    question=str(row.get("question") or "").strip(),
+                    gold_answer=str(row.get("answer") or "").strip(),
+                    answer_format=answer_format,
+                    pdf_path=Path(map_row["pdf_path"]),
+                    document_id=map_row.get("document_id"),
+                    pages=int(map_row.get("pages", 0)),
+                    extractions=extractions,
+                )
+            )
             per_doc_taken[doc_id] = per_doc_taken.get(doc_id, 0) + 1
 
     out.sort(key=lambda q: (q.doc_id, q.qid))
@@ -242,65 +244,86 @@ class ParserCompareBenchmark:
 
     def add_run_args(self, parser: argparse.ArgumentParser) -> None:
         parser.add_argument(
-            "--docs", default=None,
+            "--docs",
+            default=None,
             help="Comma-separated doc_ids to include (default: all in manifest).",
         )
         parser.add_argument(
-            "--sample-per-doc", type=int, default=1,
+            "--sample-per-doc",
+            type=int,
+            default=1,
             help="Take the first N answerable questions per PDF (default 1).",
         )
         parser.add_argument(
-            "--skip-unanswerable", dest="skip_unanswerable",
-            action="store_true", default=True,
+            "--skip-unanswerable",
+            dest="skip_unanswerable",
+            action="store_true",
+            default=True,
             help="Drop 'None' format probes (default true; we want signal not "
-                 "hallucination probes for n=5).",
+            "hallucination probes for n=5).",
         )
         parser.add_argument(
-            "--include-unanswerable", dest="skip_unanswerable",
+            "--include-unanswerable",
+            dest="skip_unanswerable",
             action="store_false",
             help="Override --skip-unanswerable; include unanswerable probes too.",
         )
         parser.add_argument(
-            "--skip-format", default=None,
+            "--skip-format",
+            default=None,
             help="Comma-separated answer_format values to skip (e.g. 'none,float').",
         )
         parser.add_argument(
-            "--concurrency", type=int, default=2,
+            "--concurrency",
+            type=int,
+            default=2,
             help="Parallel question workers per arm (default 2).",
         )
         parser.add_argument(
-            "--no-mentions", dest="no_mentions", action="store_true",
+            "--no-mentions",
+            dest="no_mentions",
+            action="store_true",
             help="SurfSense arm: skip mentioned_document_ids (full-corpus retrieval).",
         )
         parser.add_argument(
-            "--pdf-engine", default="native",
+            "--pdf-engine",
+            default="native",
             choices=[e.value for e in PdfEngine],
             help="OpenRouter file-parser engine for native_pdf arm.",
         )
         parser.add_argument(
-            "--max-output-tokens", type=int, default=512,
+            "--max-output-tokens",
+            type=int,
+            default=512,
             help="Cap on completion length for every arm.",
         )
         parser.add_argument(
-            "--llm-model", default="anthropic/claude-sonnet-4.5",
+            "--llm-model",
+            default="anthropic/claude-sonnet-4.5",
             help="OpenRouter slug used by the 5 OpenRouter-driven arms. "
-                 "SurfSense arm uses whatever provider_model is pinned on the suite.",
+            "SurfSense arm uses whatever provider_model is pinned on the suite.",
         )
         parser.add_argument(
-            "--skip-arms", default=None,
+            "--skip-arms",
+            default=None,
             help="Comma-separated arm names to skip (e.g. 'llamacloud_premium_lc').",
         )
         # Ingest-only flags (forwarded by the CLI to ingest.run_ingest).
         parser.add_argument(
-            "--max-docs", type=int, default=None,
+            "--max-docs",
+            type=int,
+            default=None,
             help="(ingest only) cap number of unique PDFs to process.",
         )
         parser.add_argument(
-            "--force-reextract", action="store_true",
+            "--force-reextract",
+            action="store_true",
             help="(ingest only) re-call parsers even if cached .md exists.",
         )
         parser.add_argument(
-            "--pdf-concurrency", type=int, default=2,
+            "--pdf-concurrency",
+            type=int,
+            default=2,
             help="(ingest only) parallel PDFs (each fans out to 4 parsers).",
         )
 
@@ -312,9 +335,7 @@ class ParserCompareBenchmark:
         from .ingest import run_ingest
 
         docs_raw: str | None = opts.get("docs")
-        docs_filter = (
-            [d.strip() for d in docs_raw.split(",") if d.strip()] if docs_raw else None
-        )
+        docs_filter = [d.strip() for d in docs_raw.split(",") if d.strip()] if docs_raw else None
         await run_ingest(
             ctx,
             docs_filter=docs_filter,
@@ -329,15 +350,14 @@ class ParserCompareBenchmark:
 
     async def run(self, ctx: RunContext, **opts: Any) -> RunArtifact:
         docs_raw: str | None = opts.get("docs")
-        docs_filter = (
-            [d.strip() for d in docs_raw.split(",") if d.strip()] if docs_raw else None
-        )
+        docs_filter = [d.strip() for d in docs_raw.split(",") if d.strip()] if docs_raw else None
         sample_per_doc = int(opts.get("sample_per_doc") or 1)
         skip_unanswerable = bool(opts.get("skip_unanswerable", True))
         skip_format_raw: str | None = opts.get("skip_format")
         skip_format = (
             [f.strip() for f in skip_format_raw.split(",") if f.strip()]
-            if skip_format_raw else None
+            if skip_format_raw
+            else None
         )
         concurrency = int(opts.get("concurrency") or 2)
         no_mentions = bool(opts.get("no_mentions"))
@@ -346,8 +366,7 @@ class ParserCompareBenchmark:
         llm_model = str(opts.get("llm_model") or "anthropic/claude-sonnet-4.5")
         skip_arms_raw: str | None = opts.get("skip_arms")
         skip_arms = (
-            {a.strip() for a in skip_arms_raw.split(",") if a.strip()}
-            if skip_arms_raw else set()
+            {a.strip() for a in skip_arms_raw.split(",") if a.strip()} if skip_arms_raw else set()
         )
 
         active_arms = [a for a in ARM_NAMES if a not in skip_arms]
@@ -373,19 +392,20 @@ class ParserCompareBenchmark:
 
         doc_map = _read_doc_map(map_path)
         questions = _select_questions(
-            questions_jsonl, doc_map,
+            questions_jsonl,
+            doc_map,
             docs_filter=docs_filter,
             sample_per_doc=sample_per_doc,
             skip_unanswerable=skip_unanswerable,
             skip_format=skip_format,
         )
         if not questions:
-            raise RuntimeError(
-                "No questions matched filters; broaden --docs / --skip-format."
-            )
+            raise RuntimeError("No questions matched filters; broaden --docs / --skip-format.")
         logger.info(
             "parser_compare: scheduled %d questions across %d arms (%s)",
-            len(questions), len(active_arms), ",".join(active_arms),
+            len(questions),
+            len(active_arms),
+            ",".join(active_arms),
         )
 
         api_key = os.environ.get("OPENROUTER_API_KEY")
@@ -396,16 +416,20 @@ class ParserCompareBenchmark:
         arms: dict[str, Any] = {}
         if "native_pdf" in active_arms:
             native_provider = OpenRouterPdfProvider(
-                api_key=api_key, base_url=ctx.config.openrouter_base_url,
-                model=llm_model, engine=PdfEngine(pdf_engine_name),
+                api_key=api_key,
+                base_url=ctx.config.openrouter_base_url,
+                model=llm_model,
+                engine=PdfEngine(pdf_engine_name),
             )
             arms["native_pdf"] = NativePdfArm(
-                provider=native_provider, max_output_tokens=max_output_tokens,
+                provider=native_provider,
+                max_output_tokens=max_output_tokens,
             )
         for arm_name, _, _ in PARSER_ARMS:
             if arm_name in active_arms:
                 lc_provider = OpenRouterChatProvider(
-                    api_key=api_key, base_url=ctx.config.openrouter_base_url,
+                    api_key=api_key,
+                    base_url=ctx.config.openrouter_base_url,
                     model=llm_model,
                 )
                 arms[arm_name] = BareLlmArm(
@@ -441,9 +465,7 @@ class ParserCompareBenchmark:
         def _lc_req(q: PCQuestion, arm_name: str) -> ArmRequest:
             md_path = q.extractions.get(arm_name)
             if md_path is None or not md_path.exists():
-                raise FileNotFoundError(
-                    f"Missing extraction for {arm_name} on {q.doc_id}"
-                )
+                raise FileNotFoundError(f"Missing extraction for {arm_name} on {q.doc_id}")
             markdown = md_path.read_text(encoding="utf-8")
             return ArmRequest(
                 question_id=q.qid,
@@ -483,14 +505,15 @@ class ParserCompareBenchmark:
 
         # Run all arms in parallel (each arm bounded by `concurrency`).
         per_arm_tasks: dict[str, list] = {
-            arm_name: [_answer_one(arm_name, q) for q in questions]
-            for arm_name in active_arms
+            arm_name: [_answer_one(arm_name, q) for q in questions] for arm_name in active_arms
         }
         per_arm_results: dict[str, list[ArmResult]] = {}
-        gathered = await asyncio.gather(*[
-            _gather_with_limit(per_arm_tasks[arm_name], concurrency=concurrency)
-            for arm_name in active_arms
-        ])
+        gathered = await asyncio.gather(
+            *[
+                _gather_with_limit(per_arm_tasks[arm_name], concurrency=concurrency)
+                for arm_name in active_arms
+            ]
+        )
         for arm_name, results in zip(active_arms, gathered, strict=True):
             per_arm_results[arm_name] = results
 
@@ -520,21 +543,29 @@ class ParserCompareBenchmark:
                 for arm_name in active_arms:
                     res = per_arm_results[arm_name][i]
                     g = per_arm_grades[arm_name][i]
-                    fh.write(json.dumps({
-                        **base,
-                        **res.to_jsonl(),
-                        "graded": {
-                            "correct": g.correct,
-                            "f1": g.f1,
-                            "method": g.method,
-                            "normalised_pred": g.normalised_pred,
-                            "normalised_gold": g.normalised_gold,
-                        },
-                    }) + "\n")
+                    fh.write(
+                        json.dumps(
+                            {
+                                **base,
+                                **res.to_jsonl(),
+                                "graded": {
+                                    "correct": g.correct,
+                                    "f1": g.f1,
+                                    "method": g.method,
+                                    "normalised_pred": g.normalised_pred,
+                                    "normalised_gold": g.normalised_gold,
+                                },
+                            }
+                        )
+                        + "\n"
+                    )
 
         # Aggregate per-arm metrics + cost
         metrics = _compute_metrics(
-            questions, per_arm_results, per_arm_grades, active_arms,
+            questions,
+            per_arm_results,
+            per_arm_grades,
+            active_arms,
         )
 
         artifact = RunArtifact(
@@ -564,13 +595,18 @@ class ParserCompareBenchmark:
 
         manifest_path = run_dir / "run_artifact.json"
         manifest_path.write_text(
-            json.dumps({
-                "suite": self.suite,
-                "benchmark": self.name,
-                "raw_path": "raw.jsonl",
-                "metrics": metrics,
-                "extra": artifact.extra,
-            }, indent=2, sort_keys=True) + "\n",
+            json.dumps(
+                {
+                    "suite": self.suite,
+                    "benchmark": self.name,
+                    "raw_path": "raw.jsonl",
+                    "metrics": metrics,
+                    "extra": artifact.extra,
+                },
+                indent=2,
+                sort_keys=True,
+            )
+            + "\n",
             encoding="utf-8",
         )
         return artifact
@@ -602,10 +638,7 @@ class ParserCompareBenchmark:
             f"(LLM: `{extra.get('llm_model', '?')}`, "
             f"engine: `{extra.get('pdf_engine', 'native')}`)."
         )
-        body.append(
-            f"- Preprocess tariff: basic = $1 / 1k pages, "
-            f"premium = $10 / 1k pages."
-        )
+        body.append("- Preprocess tariff: basic = $1 / 1k pages, premium = $10 / 1k pages.")
         body.append("")
         body.append("### Per-arm summary")
         body.append("")
@@ -620,13 +653,13 @@ class ParserCompareBenchmark:
                 continue
             body.append(
                 f"| `{arm_name}` "
-                f"| {row['accuracy']*100:.1f}% "
+                f"| {row['accuracy'] * 100:.1f}% "
                 f"({row['n_correct']}/{row['n']}) "
-                f"| {row['f1_mean']*100:.1f}% "
+                f"| {row['f1_mean'] * 100:.1f}% "
                 f"| ${row['llm_cost_per_q']:.4f} "
                 f"| ${row['preprocess_cost_total']:.4f} "
                 f"| ${row['total_cost_per_q']:.4f} "
-                f"| {row['latency_ms_median']/1000:.1f}s |"
+                f"| {row['latency_ms_median'] / 1000:.1f}s |"
             )
         body.append("")
 
@@ -679,8 +712,7 @@ class ParserCompareBenchmark:
                     else:
                         row_cells.append("✓" if g.get("correct") else "✗")
                 body.append(
-                    f"| `{doc_id}` | {info.get('pages', '?')} | "
-                    + " | ".join(row_cells) + " |"
+                    f"| `{doc_id}` | {info.get('pages', '?')} | " + " | ".join(row_cells) + " |"
                 )
 
         return ReportSection(
@@ -740,16 +772,16 @@ def _compute_metrics(
             preprocess_per_page = 0.0
             preprocess_label = "unknown"
 
-        preprocess_cost_total = sum(
-            pages * preprocess_per_page for pages in pdf_pages.values()
-        )
+        preprocess_cost_total = sum(pages * preprocess_per_page for pages in pdf_pages.values())
         preprocess_cost_per_q = preprocess_cost_total / n if n else 0.0
         total_cost_per_q = llm_cost_per_q + preprocess_cost_per_q
 
         latencies = sorted(int(r.latency_ms or 0) for r in results)
         latency_median = latencies[len(latencies) // 2] if latencies else 0
-        latency_p95 = latencies[int(len(latencies) * 0.95)] if len(latencies) >= 20 else (
-            latencies[-1] if latencies else 0
+        latency_p95 = (
+            latencies[int(len(latencies) * 0.95)]
+            if len(latencies) >= 20
+            else (latencies[-1] if latencies else 0)
         )
 
         in_tokens = [int(r.input_tokens or 0) for r in results]
@@ -775,15 +807,21 @@ def _compute_metrics(
     # Per-PDF breakdown (correct / not for each arm)
     per_pdf: dict[str, dict[str, Any]] = {}
     for i, q in enumerate(questions):
-        slot = per_pdf.setdefault(q.doc_id, {
-            "pages": q.pages,
-            "arms": {},
-        })
+        slot = per_pdf.setdefault(
+            q.doc_id,
+            {
+                "pages": q.pages,
+                "arms": {},
+            },
+        )
         for arm_name in active_arms:
-            slot["arms"].setdefault(arm_name, {
-                "correct": per_arm_grades[arm_name][i].correct,
-                "f1": per_arm_grades[arm_name][i].f1,
-            })
+            slot["arms"].setdefault(
+                arm_name,
+                {
+                    "correct": per_arm_grades[arm_name][i].correct,
+                    "f1": per_arm_grades[arm_name][i].f1,
+                },
+            )
 
     return {
         "per_arm": per_arm,
diff --git a/surfsense_evals/src/surfsense_evals/suites/research/crag/dataset.py b/surfsense_evals/src/surfsense_evals/suites/research/crag/dataset.py
index 224dcae5c..7154e6d14 100644
--- a/surfsense_evals/src/surfsense_evals/suites/research/crag/dataset.py
+++ b/surfsense_evals/src/surfsense_evals/suites/research/crag/dataset.py
@@ -80,7 +80,7 @@ class CragPage:
 class CragQuestion:
     """One row of CRAG (Tasks 1 & 2)."""
 
-    qid: str                          # synthesised "C00000".."C02705"
+    qid: str  # synthesised "C00000".."C02705"
     interaction_id: str
     query_time: str
     query: str
@@ -89,9 +89,9 @@ class CragQuestion:
     domain: str
     question_type: str
     static_or_dynamic: str
-    popularity: str                   # may be "" for web-sourced questions
-    split: int                        # 0=validation, 1=public_test
-    raw_index: int                    # row index in the source JSONL
+    popularity: str  # may be "" for web-sourced questions
+    split: int  # 0=validation, 1=public_test
+    raw_index: int  # row index in the source JSONL
     pages: list[CragPage] = field(default_factory=list)
 
     def to_dict(self) -> dict[str, Any]:
@@ -166,16 +166,19 @@ def _parse_pages(raw_search_results: Any) -> list[CragPage]:
         if not url or not html.strip():
             # No URL or empty HTML => useless for retrieval.
             continue
-        pages.append(CragPage(
-            page_name=str(entry.get("page_name") or "").strip(),
-            page_url=url,
-            page_snippet=str(entry.get("page_snippet") or "").strip(),
-            page_html=html,
-            page_last_modified=(
-                str(entry.get("page_last_modified")).strip()
-                if entry.get("page_last_modified") else None
-            ),
-        ))
+        pages.append(
+            CragPage(
+                page_name=str(entry.get("page_name") or "").strip(),
+                page_url=url,
+                page_snippet=str(entry.get("page_snippet") or "").strip(),
+                page_html=html,
+                page_last_modified=(
+                    str(entry.get("page_last_modified")).strip()
+                    if entry.get("page_last_modified")
+                    else None
+                ),
+            )
+        )
     return pages
 
 
@@ -217,21 +220,23 @@ def iter_questions(jsonl_bz2_path: Path) -> list[CragQuestion]:
                 continue
             interaction_id = str(row.get("interaction_id") or "").strip()
             pages = _parse_pages(row.get("search_results"))
-            out.append(CragQuestion(
-                qid=f"C{raw_idx:05d}",
-                interaction_id=interaction_id,
-                query_time=str(row.get("query_time") or "").strip(),
-                query=query,
-                gold_answer=answer,
-                alt_answers=_parse_alt_answers(row.get("alt_ans")),
-                domain=str(row.get("domain") or "").strip().lower(),
-                question_type=str(row.get("question_type") or "").strip().lower(),
-                static_or_dynamic=str(row.get("static_or_dynamic") or "").strip().lower(),
-                popularity=str(row.get("popularity") or "").strip().lower(),
-                split=int(row.get("split") or 0),
-                raw_index=raw_idx,
-                pages=pages,
-            ))
+            out.append(
+                CragQuestion(
+                    qid=f"C{raw_idx:05d}",
+                    interaction_id=interaction_id,
+                    query_time=str(row.get("query_time") or "").strip(),
+                    query=query,
+                    gold_answer=answer,
+                    alt_answers=_parse_alt_answers(row.get("alt_ans")),
+                    domain=str(row.get("domain") or "").strip().lower(),
+                    question_type=str(row.get("question_type") or "").strip().lower(),
+                    static_or_dynamic=str(row.get("static_or_dynamic") or "").strip().lower(),
+                    popularity=str(row.get("popularity") or "").strip().lower(),
+                    split=int(row.get("split") or 0),
+                    raw_index=raw_idx,
+                    pages=pages,
+                )
+            )
     return out
 
 
diff --git a/surfsense_evals/src/surfsense_evals/suites/research/crag/grader.py b/surfsense_evals/src/surfsense_evals/suites/research/crag/grader.py
index 63f66702b..e49660a6f 100644
--- a/surfsense_evals/src/surfsense_evals/suites/research/crag/grader.py
+++ b/surfsense_evals/src/surfsense_evals/suites/research/crag/grader.py
@@ -58,10 +58,10 @@ class CragGradeResult:
     """One graded (pred, gold) pair under CRAG's 3-class rubric."""
 
     grade: GradeClass
-    score: int                     # +1 / 0 / -1
-    method: str                    # exact, numeric, substring, refusal,
-                                   # false_premise_correct, false_premise_miss,
-                                   # llm_judge, lexical_miss, ...
+    score: int  # +1 / 0 / -1
+    method: str  # exact, numeric, substring, refusal,
+    # false_premise_correct, false_premise_miss,
+    # llm_judge, lexical_miss, ...
     normalised_pred: str = ""
     normalised_gold: str = ""
     judge_rationale: str = ""
@@ -112,10 +112,27 @@ def _normalise(s: str) -> str:
 
 
 _WORD_NUMBERS = {
-    "zero": 0, "one": 1, "two": 2, "three": 3, "four": 4, "five": 5,
-    "six": 6, "seven": 7, "eight": 8, "nine": 9, "ten": 10, "eleven": 11,
-    "twelve": 12, "thirteen": 13, "fourteen": 14, "fifteen": 15, "sixteen": 16,
-    "seventeen": 17, "eighteen": 18, "nineteen": 19, "twenty": 20,
+    "zero": 0,
+    "one": 1,
+    "two": 2,
+    "three": 3,
+    "four": 4,
+    "five": 5,
+    "six": 6,
+    "seven": 7,
+    "eight": 8,
+    "nine": 9,
+    "ten": 10,
+    "eleven": 11,
+    "twelve": 12,
+    "thirteen": 13,
+    "fourteen": 14,
+    "fifteen": 15,
+    "sixteen": 16,
+    "seventeen": 17,
+    "eighteen": 18,
+    "nineteen": 19,
+    "twenty": 20,
 }
 
 _NUMERIC_RE = re.compile(r"-?\d+(?:[.,]\d+)?")
@@ -274,8 +291,11 @@ def grade_deterministic(
             continue
         if n_pred == cand_norm:
             return CragGradeResult(
-                grade="correct", score=1, method="exact",
-                normalised_pred=n_pred, normalised_gold=cand_norm,
+                grade="correct",
+                score=1,
+                method="exact",
+                normalised_pred=n_pred,
+                normalised_gold=cand_norm,
             )
         p_num = _maybe_number(pred)
         c_num = _maybe_number(candidate)
@@ -289,21 +309,30 @@ def grade_deterministic(
             tol = abs(c_num) * 0.01
             if abs(p_num - c_num) <= tol:
                 return CragGradeResult(
-                    grade="correct", score=1, method="numeric",
-                    normalised_pred=n_pred, normalised_gold=cand_norm,
+                    grade="correct",
+                    score=1,
+                    method="numeric",
+                    normalised_pred=n_pred,
+                    normalised_gold=cand_norm,
                 )
             # Numeric question with different numbers — keep looking
             # at other candidates rather than declaring miss now;
             # alt answers may include word forms that pass.
         if _whole_word_substring(n_pred, cand_norm):
             return CragGradeResult(
-                grade="correct", score=1, method="substring",
-                normalised_pred=n_pred, normalised_gold=cand_norm,
+                grade="correct",
+                score=1,
+                method="substring",
+                normalised_pred=n_pred,
+                normalised_gold=cand_norm,
             )
         if _whole_word_substring(cand_norm, n_pred) and len(n_pred) >= 3:
             return CragGradeResult(
-                grade="correct", score=1, method="substring_reverse",
-                normalised_pred=n_pred, normalised_gold=cand_norm,
+                grade="correct",
+                score=1,
+                method="substring_reverse",
+                normalised_pred=n_pred,
+                normalised_gold=cand_norm,
             )
 
     return CragGradeResult(
@@ -326,21 +355,21 @@ _JUDGE_SYSTEM = (
     "answer (and any alternative valid answers), and a model's "
     "prediction, classify the prediction into exactly one of three "
     "categories:\n\n"
-    "* \"correct\"   — the prediction expresses the same factual "
+    '* "correct"   — the prediction expresses the same factual '
     "content as the gold answer (paraphrasing OK; numbers as words "
     "OK; partial-but-correct names OK; non-contradictory extra "
     "detail OK).\n"
-    "* \"missing\"   — the prediction explicitly refuses, says \"I "
+    '* "missing"   — the prediction explicitly refuses, says "I '
     "don't know\", says there is insufficient information, or hedges "
     "without committing.\n"
-    "* \"incorrect\" — the prediction commits to a fact that is "
+    '* "incorrect" — the prediction commits to a fact that is '
     "different from the gold answer, or fails to flag a false "
     "premise when the question contains one.\n\n"
     "Special case: if the question contains a false premise and the "
     "gold answer says so, then a prediction that flags the false "
-    "premise is \"correct\".\n\n"
+    'premise is "correct".\n\n'
     "Respond with ONLY a JSON object on a single line:\n"
-    '{\"grade\": \"correct\"|\"missing\"|\"incorrect\", \"rationale\": \"<one short sentence>\"}'
+    '{"grade": "correct"|"missing"|"incorrect", "rationale": "<one short sentence>"}'
 )
 
 
@@ -444,15 +473,17 @@ def _parse_judge_response(text: str) -> tuple[GradeClass, str]:
 
 # Methods that should *not* trigger the LLM judge — the deterministic
 # verdict is conclusive (refusal, exact match, numeric mismatch, etc.).
-_TERMINAL_METHODS = frozenset({
-    "refusal",
-    "exact",
-    "numeric",
-    "substring",
-    "substring_reverse",
-    "false_premise_flagged",
-    "empty_gold",
-})
+_TERMINAL_METHODS = frozenset(
+    {
+        "refusal",
+        "exact",
+        "numeric",
+        "substring",
+        "substring_reverse",
+        "false_premise_flagged",
+        "empty_gold",
+    }
+)
 
 
 async def grade_with_judge(
diff --git a/surfsense_evals/src/surfsense_evals/suites/research/crag/html_extract.py b/surfsense_evals/src/surfsense_evals/suites/research/crag/html_extract.py
index 1b00aedc2..271d43d56 100644
--- a/surfsense_evals/src/surfsense_evals/suites/research/crag/html_extract.py
+++ b/surfsense_evals/src/surfsense_evals/suites/research/crag/html_extract.py
@@ -42,7 +42,7 @@ class ExtractionResult:
     """Outcome of converting one HTML blob to plain markdown."""
 
     text: str
-    method: str          # "trafilatura" | "fallback_strip" | "empty"
+    method: str  # "trafilatura" | "fallback_strip" | "empty"
     n_chars: int
 
     @property
@@ -94,11 +94,30 @@ class _StripHTMLParser(HTMLParser):
     """
 
     _SKIP_TAGS = frozenset({"script", "style", "nav", "header", "footer", "aside", "svg"})
-    _BLOCK_TAGS = frozenset({
-        "p", "div", "section", "article", "li", "ul", "ol",
-        "h1", "h2", "h3", "h4", "h5", "h6", "br", "tr",
-        "td", "th", "table", "blockquote", "pre",
-    })
+    _BLOCK_TAGS = frozenset(
+        {
+            "p",
+            "div",
+            "section",
+            "article",
+            "li",
+            "ul",
+            "ol",
+            "h1",
+            "h2",
+            "h3",
+            "h4",
+            "h5",
+            "h6",
+            "br",
+            "tr",
+            "td",
+            "th",
+            "table",
+            "blockquote",
+            "pre",
+        }
+    )
 
     def __init__(self) -> None:
         super().__init__(convert_charrefs=True)
@@ -177,10 +196,7 @@ def extract_main_content(
             # Prefer trafilatura output even if short, but only if it
             # contained any prose at all — empty trafilatura fall-through
             # to the stripped form.
-            if body and stripped and len(stripped) > len(body) * 1.5:
-                body = stripped
-                method = "fallback_strip"
-            elif not body and stripped:
+            if body and stripped and len(stripped) > len(body) * 1.5 or not body and stripped:
                 body = stripped
                 method = "fallback_strip"
             elif body:
diff --git a/surfsense_evals/src/surfsense_evals/suites/research/crag/ingest.py b/surfsense_evals/src/surfsense_evals/suites/research/crag/ingest.py
index 4e0c2bdc5..1b66f45f9 100644
--- a/surfsense_evals/src/surfsense_evals/suites/research/crag/ingest.py
+++ b/surfsense_evals/src/surfsense_evals/suites/research/crag/ingest.py
@@ -158,7 +158,10 @@ def _materialise_pages(
 
     logger.info(
         "CRAG page extraction: %s; empty=%d, total_files=%d across %d questions",
-        method_counts, n_empty, len(file_to_url), len(qid_to_files),
+        method_counts,
+        n_empty,
+        len(file_to_url),
+        len(qid_to_files),
     )
     return qid_to_files, file_to_url
 
@@ -215,8 +218,10 @@ async def _upload_pages(
                     name_to_id[f"{s.title}.md"] = s.document_id
         logger.info(
             "CRAG upload batch %d-%d: %d new, %d duplicate",
-            batch_start, batch_start + len(batch),
-            len(result.document_ids), len(result.duplicate_document_ids),
+            batch_start,
+            batch_start + len(batch),
+            len(result.document_ids),
+            len(result.duplicate_document_ids),
         )
     return name_to_id
 
@@ -243,24 +248,26 @@ def _resolve_question_doc_ids(
                 doc_ids.append(doc_id)
             else:
                 missing.append(fn)
-        rows.append({
-            "qid": q.qid,
-            "interaction_id": q.interaction_id,
-            "raw_index": q.raw_index,
-            "question": q.query,
-            "gold_answer": q.gold_answer,
-            "alt_answers": list(q.alt_answers),
-            "domain": q.domain,
-            "question_type": q.question_type,
-            "static_or_dynamic": q.static_or_dynamic,
-            "popularity": q.popularity,
-            "query_time": q.query_time,
-            "split": q.split,
-            "page_filenames": filenames,
-            "document_ids": doc_ids,
-            "missing_pages": missing,
-            "n_pages": len(filenames),
-        })
+        rows.append(
+            {
+                "qid": q.qid,
+                "interaction_id": q.interaction_id,
+                "raw_index": q.raw_index,
+                "question": q.query,
+                "gold_answer": q.gold_answer,
+                "alt_answers": list(q.alt_answers),
+                "domain": q.domain,
+                "question_type": q.question_type,
+                "static_or_dynamic": q.static_or_dynamic,
+                "popularity": q.popularity,
+                "query_time": q.query_time,
+                "split": q.split,
+                "page_filenames": filenames,
+                "document_ids": doc_ids,
+                "missing_pages": missing,
+                "n_pages": len(filenames),
+            }
+        )
     return rows
 
 
@@ -305,7 +312,7 @@ async def run_ingest(
     settings = settings or IngestSettings(
         use_vision_llm=False,
         processing_mode="basic",
-        )
+    )
     bench_dir = ctx.benchmark_data_dir()
     pages_dir = bench_dir / "pages"
     raw_cache = bench_dir / ".raw_cache"
@@ -336,10 +343,13 @@ async def run_ingest(
     n_pages_total = sum(len(q.pages) for q in questions)
     logger.info(
         "CRAG: extracting up to %d pages across %d questions ...",
-        n_pages_total, len(questions),
+        n_pages_total,
+        len(questions),
     )
     qid_to_files, file_to_url = _materialise_pages(
-        questions, pages_dir=pages_dir, overwrite=overwrite_extract,
+        questions,
+        pages_dir=pages_dir,
+        overwrite=overwrite_extract,
     )
     n_pages_extracted = sum(len(v) for v in qid_to_files.values())
 
diff --git a/surfsense_evals/src/surfsense_evals/suites/research/crag/prompt.py b/surfsense_evals/src/surfsense_evals/suites/research/crag/prompt.py
index 626834505..5b29fb90b 100644
--- a/surfsense_evals/src/surfsense_evals/suites/research/crag/prompt.py
+++ b/surfsense_evals/src/surfsense_evals/suites/research/crag/prompt.py
@@ -28,7 +28,6 @@ in the runner, so the format is mandatory.
 
 from __future__ import annotations
 
-
 _BASE_INSTRUCTIONS = (
     "You are a careful question-answering assistant. The question is a "
     "real-world factual question that may be about finance, music, "
@@ -38,7 +37,7 @@ _BASE_INSTRUCTIONS = (
     "is factually wrong), say so explicitly in your final answer "
     "rather than answering as if the premise were true.\n"
     "2. If you are not confident in an answer, prefer saying \"I don't "
-    "know\" over guessing. A wrong commit is penalised more than a "
+    'know" over guessing. A wrong commit is penalised more than a '
     "refusal.\n"
     "3. Keep the final answer short — a name, a number, a date, a "
     "phrase. Do not repeat the question.\n\n"
@@ -126,9 +125,7 @@ def build_long_context_prompt(
         if len(body) > per_page_char_cap:
             body = body[:per_page_char_cap].rstrip() + "\n[...truncated...]"
         title_clean = (title or f"page_{idx}").strip().replace("\n", " ")
-        blocks.append(
-            f"--- PAGE {idx}: {title_clean} ---\n{body}\n"
-        )
+        blocks.append(f"--- PAGE {idx}: {title_clean} ---\n{body}\n")
     contexts_block = "\n".join(blocks) if blocks else "(no pages retrieved)"
     return _LONG_CONTEXT_TEMPLATE.format(
         instructions=_BASE_INSTRUCTIONS,
diff --git a/surfsense_evals/src/surfsense_evals/suites/research/crag/runner.py b/surfsense_evals/src/surfsense_evals/suites/research/crag/runner.py
index 654c261a2..801e00220 100644
--- a/surfsense_evals/src/surfsense_evals/suites/research/crag/runner.py
+++ b/surfsense_evals/src/surfsense_evals/suites/research/crag/runner.py
@@ -125,21 +125,23 @@ def _filter_questions(
             continue
         if qtype_filter and qtype_filter not in qtype:
             continue
-        out.append(CragRunnerQuestion(
-            qid=str(row.get("qid") or "").strip(),
-            raw_index=int(row.get("raw_index") or 0),
-            question=str(row.get("question") or "").strip(),
-            gold_answer=str(row.get("gold_answer") or "").strip(),
-            alt_answers=list(row.get("alt_answers") or []),
-            domain=domain,
-            question_type=qtype,
-            static_or_dynamic=str(row.get("static_or_dynamic") or "").lower(),
-            popularity=str(row.get("popularity") or "").lower(),
-            query_time=str(row.get("query_time") or "").strip(),
-            page_filenames=list(row.get("page_filenames") or []),
-            document_ids=list(row.get("document_ids") or []),
-            missing_pages=list(row.get("missing_pages") or []),
-        ))
+        out.append(
+            CragRunnerQuestion(
+                qid=str(row.get("qid") or "").strip(),
+                raw_index=int(row.get("raw_index") or 0),
+                question=str(row.get("question") or "").strip(),
+                gold_answer=str(row.get("gold_answer") or "").strip(),
+                alt_answers=list(row.get("alt_answers") or []),
+                domain=domain,
+                question_type=qtype,
+                static_or_dynamic=str(row.get("static_or_dynamic") or "").lower(),
+                popularity=str(row.get("popularity") or "").lower(),
+                query_time=str(row.get("query_time") or "").strip(),
+                page_filenames=list(row.get("page_filenames") or []),
+                document_ids=list(row.get("document_ids") or []),
+                missing_pages=list(row.get("missing_pages") or []),
+            )
+        )
     out.sort(key=lambda q: q.raw_index)
     if sample_n is not None and sample_n > 0:
         out = out[:sample_n]
@@ -190,15 +192,22 @@ class CragBenchmark:
 
     def add_run_args(self, parser: argparse.ArgumentParser) -> None:
         parser.add_argument(
-            "--n", dest="sample_n", type=int, default=None,
+            "--n",
+            dest="sample_n",
+            type=int,
+            default=None,
             help="Run only the first N questions after filters.",
         )
         parser.add_argument(
-            "--domain", dest="domain_filter", default=None,
+            "--domain",
+            dest="domain_filter",
+            default=None,
             help="Filter to a single CRAG domain (finance|music|movie|sports|open).",
         )
         parser.add_argument(
-            "--qtype", dest="qtype_filter", default=None,
+            "--qtype",
+            dest="qtype_filter",
+            default=None,
             help=(
                 "Filter to questions whose question_type contains this "
                 "substring (case-insensitive). Examples: 'multi-hop', "
@@ -206,31 +215,46 @@ class CragBenchmark:
             ),
         )
         parser.add_argument(
-            "--concurrency", type=int, default=4,
+            "--concurrency",
+            type=int,
+            default=4,
             help="Parallel question workers per arm.",
         )
         parser.add_argument(
-            "--max-output-tokens", type=int, default=512,
+            "--max-output-tokens",
+            type=int,
+            default=512,
             help="Cap on completion length for the chat-completion arms.",
         )
         parser.add_argument(
-            "--per-page-char-cap", dest="per_page_char_cap", type=int, default=12_000,
+            "--per-page-char-cap",
+            dest="per_page_char_cap",
+            type=int,
+            default=12_000,
             help="Long-context arm: max chars per page before truncation (default 12k).",
         )
         parser.add_argument(
-            "--skip-bare", dest="skip_bare", action="store_true",
+            "--skip-bare",
+            dest="skip_bare",
+            action="store_true",
             help="Skip the bare-LLM arm (saves cost on re-runs).",
         )
         parser.add_argument(
-            "--skip-long-context", dest="skip_long_context", action="store_true",
+            "--skip-long-context",
+            dest="skip_long_context",
+            action="store_true",
             help="Skip the long-context arm.",
         )
         parser.add_argument(
-            "--skip-surfsense", dest="skip_surfsense", action="store_true",
+            "--skip-surfsense",
+            dest="skip_surfsense",
+            action="store_true",
             help="Skip the SurfSense arm (useful when iterating on the LLM arms only).",
         )
         parser.add_argument(
-            "--no-mention-scope", dest="no_mention_scope", action="store_true",
+            "--no-mention-scope",
+            dest="no_mention_scope",
+            action="store_true",
             help=(
                 "SurfSense arm: don't pass mentioned_document_ids; let "
                 "the agent retrieve over the entire SearchSpace. Default "
@@ -239,37 +263,56 @@ class CragBenchmark:
             ),
         )
         parser.add_argument(
-            "--no-judge", dest="no_judge", action="store_true",
+            "--no-judge",
+            dest="no_judge",
+            action="store_true",
             help="Disable the LLM-as-judge fallback grader.",
         )
         parser.add_argument(
-            "--judge-model", dest="judge_model",
+            "--judge-model",
+            dest="judge_model",
             default="anthropic/claude-sonnet-4.5",
             help="OpenRouter slug for the LLM judge.",
         )
         parser.add_argument(
-            "--judge-concurrency", dest="judge_concurrency", type=int, default=4,
+            "--judge-concurrency",
+            dest="judge_concurrency",
+            type=int,
+            default=4,
             help="Parallel judge calls.",
         )
         # Ingest knobs
         parser.add_argument(
-            "--n-questions", dest="n_questions", type=int, default=None,
+            "--n-questions",
+            dest="n_questions",
+            type=int,
+            default=None,
             help="(ingest only) cap on number of questions to materialise + ingest.",
         )
         parser.add_argument(
-            "--upload-batch-size", dest="upload_batch_size", type=int, default=16,
+            "--upload-batch-size",
+            dest="upload_batch_size",
+            type=int,
+            default=16,
             help="(ingest only) markdown files per fileupload call.",
         )
         parser.add_argument(
-            "--skip-upload", dest="skip_upload", action="store_true",
+            "--skip-upload",
+            dest="skip_upload",
+            action="store_true",
             help="(ingest only) extract pages locally but don't push to SurfSense.",
         )
         parser.add_argument(
-            "--overwrite-extract", dest="overwrite_extract", action="store_true",
+            "--overwrite-extract",
+            dest="overwrite_extract",
+            action="store_true",
             help="(ingest only) re-run trafilatura even when cached markdown exists.",
         )
         parser.add_argument(
-            "--sample-seed", dest="sample_seed", type=int, default=17,
+            "--sample-seed",
+            dest="sample_seed",
+            type=int,
+            default=17,
             help="(ingest only) RNG seed for the stratified sample.",
         )
         add_ingest_settings_args(parser, defaults=_DEFAULT_INGEST_SETTINGS)
@@ -362,12 +405,14 @@ class CragBenchmark:
             if not api_key:
                 logger.warning("CRAG: --no-judge implied (no OPENROUTER_API_KEY for judge)")
             else:
-                judge = CragLlmJudge(config=CragJudgeConfig(
-                    api_key=api_key,
-                    model=judge_model,
-                    base_url=ctx.config.openrouter_base_url,
-                    concurrency=judge_concurrency,
-                ))
+                judge = CragLlmJudge(
+                    config=CragJudgeConfig(
+                        api_key=api_key,
+                        model=judge_model,
+                        base_url=ctx.config.openrouter_base_url,
+                        concurrency=judge_concurrency,
+                    )
+                )
 
         run_timestamp = utc_iso_timestamp()
         run_dir = ctx.runs_dir(run_timestamp=run_timestamp)
@@ -393,29 +438,53 @@ class CragBenchmark:
         # internally concurrency-bounded.
         tasks: list[Any] = []
         if bare_arm is not None:
-            tasks.append(_gather_with_limit((_bare_one(q) for q in questions), concurrency=concurrency))
+            tasks.append(
+                _gather_with_limit((_bare_one(q) for q in questions), concurrency=concurrency)
+            )
         else:
             tasks.append(_make_skipped_results(questions, "bare_llm"))
         if long_context_arm is not None:
-            tasks.append(_gather_with_limit((_long_context_one(q) for q in questions), concurrency=concurrency))
+            tasks.append(
+                _gather_with_limit(
+                    (_long_context_one(q) for q in questions), concurrency=concurrency
+                )
+            )
         else:
             tasks.append(_make_skipped_results(questions, "long_context"))
         if surf_arm is not None:
-            tasks.append(_gather_with_limit((_surf_one(q) for q in questions), concurrency=concurrency))
+            tasks.append(
+                _gather_with_limit((_surf_one(q) for q in questions), concurrency=concurrency)
+            )
         else:
             tasks.append(_make_skipped_results(questions, "surfsense"))
 
         bare_results, long_context_results, surf_results = await asyncio.gather(*tasks)
 
-        bare_grades = await _grade_results(questions, bare_results, judge=judge) if bare_arm else _empty_grades(questions)
-        lc_grades = await _grade_results(questions, long_context_results, judge=judge) if long_context_arm else _empty_grades(questions)
-        surf_grades = await _grade_results(questions, surf_results, judge=judge) if surf_arm else _empty_grades(questions)
+        bare_grades = (
+            await _grade_results(questions, bare_results, judge=judge)
+            if bare_arm
+            else _empty_grades(questions)
+        )
+        lc_grades = (
+            await _grade_results(questions, long_context_results, judge=judge)
+            if long_context_arm
+            else _empty_grades(questions)
+        )
+        surf_grades = (
+            await _grade_results(questions, surf_results, judge=judge)
+            if surf_arm
+            else _empty_grades(questions)
+        )
 
         with raw_path.open("w", encoding="utf-8") as fh:
             for q, b_res, l_res, s_res, b_g, l_g, s_g in zip(
                 questions,
-                bare_results, long_context_results, surf_results,
-                bare_grades, lc_grades, surf_grades,
+                bare_results,
+                long_context_results,
+                surf_results,
+                bare_grades,
+                lc_grades,
+                surf_grades,
                 strict=False,
             ):
                 meta = {
@@ -431,18 +500,29 @@ class CragBenchmark:
                     "alt_answers": q.alt_answers,
                 }
                 for res, grade in (
-                    (b_res, b_g), (l_res, l_g), (s_res, s_g),
+                    (b_res, b_g),
+                    (l_res, l_g),
+                    (s_res, s_g),
                 ):
-                    fh.write(json.dumps({
-                        **meta,
-                        **res.to_jsonl(),
-                        "graded": grade.to_dict(),
-                    }) + "\n")
+                    fh.write(
+                        json.dumps(
+                            {
+                                **meta,
+                                **res.to_jsonl(),
+                                "graded": grade.to_dict(),
+                            }
+                        )
+                        + "\n"
+                    )
 
         metrics = _compute_metrics(
             questions=questions,
-            bare_results=bare_results, long_context_results=long_context_results, surf_results=surf_results,
-            bare_grades=bare_grades, lc_grades=lc_grades, surf_grades=surf_grades,
+            bare_results=bare_results,
+            long_context_results=long_context_results,
+            surf_results=surf_results,
+            bare_grades=bare_grades,
+            lc_grades=lc_grades,
+            surf_grades=surf_grades,
             arms_active={
                 "bare_llm": bare_arm is not None,
                 "long_context": long_context_arm is not None,
@@ -481,13 +561,18 @@ class CragBenchmark:
 
         manifest_path = run_dir / "run_artifact.json"
         manifest_path.write_text(
-            json.dumps({
-                "suite": self.suite,
-                "benchmark": self.name,
-                "raw_path": "raw.jsonl",
-                "metrics": metrics,
-                "extra": artifact.extra,
-            }, indent=2, sort_keys=True) + "\n",
+            json.dumps(
+                {
+                    "suite": self.suite,
+                    "benchmark": self.name,
+                    "raw_path": "raw.jsonl",
+                    "metrics": metrics,
+                    "extra": artifact.extra,
+                },
+                indent=2,
+                sort_keys=True,
+            )
+            + "\n",
             encoding="utf-8",
         )
         return artifact
@@ -547,7 +632,9 @@ class CragBenchmark:
 
         body_lines.append("- Headline truthfulness scores (CRAG paper rubric):")
         for label, key in (
-            ("Bare LLM", "bare_llm"), ("Long-Context", "long_context"), ("SurfSense", "surfsense"),
+            ("Bare LLM", "bare_llm"),
+            ("Long-Context", "long_context"),
+            ("SurfSense", "surfsense"),
         ):
             d = m.get(key, {})
             body_lines.append(
@@ -583,9 +670,7 @@ class CragBenchmark:
                 for arm in ("bare_llm", "long_context", "surfsense"):
                     if arm not in row:
                         continue
-                    pieces.append(
-                        f"{arm}={_signed_pct(row[arm].get('truthfulness_score'))}"
-                    )
+                    pieces.append(f"{arm}={_signed_pct(row[arm].get('truthfulness_score'))}")
                 body_lines.append(" ".join(pieces))
 
         if per_qtype:
@@ -596,9 +681,7 @@ class CragBenchmark:
                 for arm in ("bare_llm", "long_context", "surfsense"):
                     if arm not in row:
                         continue
-                    pieces.append(
-                        f"{arm}={_signed_pct(row[arm].get('truthfulness_score'))}"
-                    )
+                    pieces.append(f"{arm}={_signed_pct(row[arm].get('truthfulness_score'))}")
                 body_lines.append(" ".join(pieces))
 
         return ReportSection(
@@ -669,32 +752,31 @@ async def _grade_results(
     rows: list[CragGradeRow] = []
     for q, r in zip(questions, results, strict=False):
         pred = extract_freeform_answer(r.raw_text or "")
-        rows.append(CragGradeRow(
-            qid=q.qid,
-            question=q.question,
-            gold=q.gold_answer,
-            alt_answers=q.alt_answers,
-            pred=pred,
-            question_type=q.question_type,
-        ))
+        rows.append(
+            CragGradeRow(
+                qid=q.qid,
+                question=q.question,
+                gold=q.gold_answer,
+                alt_answers=q.alt_answers,
+                pred=pred,
+                question_type=q.question_type,
+            )
+        )
     return await grade_many(rows=rows, judge=judge)
 
 
 def _empty_grades(questions: list[CragRunnerQuestion]) -> list[CragGradeResult]:
-    return [
-        CragGradeResult(grade="missing", score=0, method="skipped_arm")
-        for _ in questions
-    ]
+    return [CragGradeResult(grade="missing", score=0, method="skipped_arm") for _ in questions]
 
 
 async def _make_skipped_results(
-    questions: list[CragRunnerQuestion], arm_name: str,
+    questions: list[CragRunnerQuestion],
+    arm_name: str,
 ) -> list[ArmResult]:
     """Stand-in results so downstream code can assume parallel lists."""
 
     return [
-        ArmResult(arm=arm_name, question_id=q.qid, raw_text="", error="skipped")
-        for q in questions
+        ArmResult(arm=arm_name, question_id=q.qid, raw_text="", error="skipped") for q in questions
     ]
 
 
@@ -776,20 +858,41 @@ def _compute_metrics(
 
     deltas: dict[str, Any] = {}
     for label, ref_correct, ref_t, chal_correct, chal_t, both_active in (
-        ("surfsense_vs_bare", bare_correct, bare_t, surf_correct, surf_t,
-         arms_active.get("bare_llm") and arms_active.get("surfsense")),
-        ("surfsense_vs_long_context", lc_correct, lc_t, surf_correct, surf_t,
-         arms_active.get("long_context") and arms_active.get("surfsense")),
-        ("long_context_vs_bare", bare_correct, bare_t, lc_correct, lc_t,
-         arms_active.get("bare_llm") and arms_active.get("long_context")),
+        (
+            "surfsense_vs_bare",
+            bare_correct,
+            bare_t,
+            surf_correct,
+            surf_t,
+            arms_active.get("bare_llm") and arms_active.get("surfsense"),
+        ),
+        (
+            "surfsense_vs_long_context",
+            lc_correct,
+            lc_t,
+            surf_correct,
+            surf_t,
+            arms_active.get("long_context") and arms_active.get("surfsense"),
+        ),
+        (
+            "long_context_vs_bare",
+            bare_correct,
+            bare_t,
+            lc_correct,
+            lc_t,
+            arms_active.get("bare_llm") and arms_active.get("long_context"),
+        ),
     ):
         if not both_active:
             continue
         mc = mcnemar_test(ref_correct, chal_correct)
         boot = bootstrap_delta_ci(ref_correct, chal_correct, n_resamples=2000)
         deltas[label] = {
-            "accuracy_pp": 100.0 * (sum(chal_correct) - sum(ref_correct)) / max(1, len(chal_correct)),
-            "truthfulness_score_pp": 100.0 * (chal_t["truthfulness_score"] - ref_t["truthfulness_score"]),
+            "accuracy_pp": 100.0
+            * (sum(chal_correct) - sum(ref_correct))
+            / max(1, len(chal_correct)),
+            "truthfulness_score_pp": 100.0
+            * (chal_t["truthfulness_score"] - ref_t["truthfulness_score"]),
             "mcnemar_p_value": mc.p_value,
             "mcnemar_method": mc.method,
             "mcnemar_b_ref_only": mc.b,
@@ -800,12 +903,18 @@ def _compute_metrics(
     out["deltas"] = deltas
 
     out["per_domain"] = _per_facet_truthfulness(
-        questions, bare_grades, lc_grades, surf_grades,
+        questions,
+        bare_grades,
+        lc_grades,
+        surf_grades,
         arms_active=arms_active,
         key_fn=lambda q: q.domain or "(unspecified)",
     )
     out["per_question_type"] = _per_facet_truthfulness(
-        questions, bare_grades, lc_grades, surf_grades,
+        questions,
+        bare_grades,
+        lc_grades,
+        surf_grades,
         arms_active=arms_active,
         key_fn=lambda q: q.question_type or "(unspecified)",
     )
@@ -830,11 +939,11 @@ def _per_facet_truthfulness(
     """Bucket truthfulness scores by ``key_fn(q)``."""
 
     buckets: dict[str, dict[str, list[CragGradeResult]]] = {}
-    for q, b, l, s in zip(questions, bare_grades, lc_grades, surf_grades, strict=False):
+    for q, b, lc, s in zip(questions, bare_grades, lc_grades, surf_grades, strict=False):
         key = key_fn(q)
         bucket = buckets.setdefault(key, {"bare_llm": [], "long_context": [], "surfsense": []})
         bucket["bare_llm"].append(b)
-        bucket["long_context"].append(l)
+        bucket["long_context"].append(lc)
         bucket["surfsense"].append(s)
     out: dict[str, Any] = {}
     for key, arms in buckets.items():
@@ -867,11 +976,11 @@ def _arm_summary_lines(d: dict[str, Any], *, indent: str) -> str:
     high = d.get("ci_high", 0.0)
     lines = [
         f"{indent}- Accuracy: {acc * 100:.1f}% (Wilson 95% CI: {low * 100:.1f}% – {high * 100:.1f}%)",
-        f"{indent}- 3-class: correct={d.get('correct_rate', 0)*100:.1f}%, "
-        f"missing={d.get('missing_rate', 0)*100:.1f}%, "
-        f"incorrect={d.get('incorrect_rate', 0)*100:.1f}%",
+        f"{indent}- 3-class: correct={d.get('correct_rate', 0) * 100:.1f}%, "
+        f"missing={d.get('missing_rate', 0) * 100:.1f}%, "
+        f"incorrect={d.get('incorrect_rate', 0) * 100:.1f}%",
         f"{indent}- Truthfulness score (correct - incorrect)/total: "
-        f"{d.get('truthfulness_score', 0)*100:+.1f}%",
+        f"{d.get('truthfulness_score', 0) * 100:+.1f}%",
         f"{indent}- Cost / question: ${_dollars(d.get('cost_micros_mean'))} (mean), "
         f"${_dollars(d.get('cost_micros_median'))} (median)",
         f"{indent}- Latency: p50 {_ms_to_s(d.get('latency_ms_median'))}, "
@@ -916,7 +1025,7 @@ def _pct(value: Any) -> str:
     if value is None:
         return "?"
     try:
-        return f"{float(value)*100:.1f}%"
+        return f"{float(value) * 100:.1f}%"
     except (TypeError, ValueError):
         return "?"
 
@@ -925,7 +1034,7 @@ def _signed_pct(value: Any) -> str:
     if value is None:
         return "?"
     try:
-        return f"{float(value)*100:+.1f}%"
+        return f"{float(value) * 100:+.1f}%"
     except (TypeError, ValueError):
         return "?"
 
diff --git a/surfsense_evals/src/surfsense_evals/suites/research/frames/dataset.py b/surfsense_evals/src/surfsense_evals/suites/research/frames/dataset.py
index c3b6b878e..80c7075f8 100644
--- a/surfsense_evals/src/surfsense_evals/suites/research/frames/dataset.py
+++ b/surfsense_evals/src/surfsense_evals/suites/research/frames/dataset.py
@@ -51,12 +51,12 @@ def _hf_hub_download(*args: Any, **kwargs: Any) -> str:
 class FramesQuestion:
     """One row of FRAMES (post-parse)."""
 
-    qid: str                   # synthesised "Q000" .. "Q823"
+    qid: str  # synthesised "Q000" .. "Q823"
     question: str
     gold_answer: str
-    wiki_urls: list[str]       # deduped, in original order
-    reasoning_types: list[str] # split on "|"
-    raw_index: int             # row index from the TSV (for debugging)
+    wiki_urls: list[str]  # deduped, in original order
+    reasoning_types: list[str]  # split on "|"
+    raw_index: int  # row index from the TSV (for debugging)
 
     def to_dict(self) -> dict[str, Any]:
         return {
@@ -102,7 +102,7 @@ def _parse_wiki_links(raw: Any) -> list[str]:
     except (SyntaxError, ValueError):
         # Fall back: maybe it's a comma-separated string with no quotes.
         return [tok.strip() for tok in text.strip("[]").split(",") if tok.strip()]
-    if isinstance(parsed, (list, tuple)):
+    if isinstance(parsed, list | tuple):
         return [str(x).strip() for x in parsed if str(x).strip()]
     return [str(parsed).strip()]
 
@@ -146,14 +146,16 @@ def load_questions(tsv_path: Path) -> list[FramesQuestion]:
                     if val and val not in urls:
                         urls.append(val)
         reasoning = _parse_reasoning_types(row.get("reasoning_types"))
-        out.append(FramesQuestion(
-            qid=f"Q{int(raw_idx):03d}",
-            question=prompt,
-            gold_answer=answer,
-            wiki_urls=urls,
-            reasoning_types=reasoning,
-            raw_index=int(raw_idx),
-        ))
+        out.append(
+            FramesQuestion(
+                qid=f"Q{int(raw_idx):03d}",
+                question=prompt,
+                gold_answer=answer,
+                wiki_urls=urls,
+                reasoning_types=reasoning,
+                raw_index=int(raw_idx),
+            )
+        )
     return out
 
 
diff --git a/surfsense_evals/src/surfsense_evals/suites/research/frames/grader.py b/surfsense_evals/src/surfsense_evals/suites/research/frames/grader.py
index d280e3eaf..32343de42 100644
--- a/surfsense_evals/src/surfsense_evals/suites/research/frames/grader.py
+++ b/surfsense_evals/src/surfsense_evals/suites/research/frames/grader.py
@@ -90,10 +90,27 @@ def _normalise(s: str) -> str:
 
 
 _WORD_NUMBERS = {
-    "zero": 0, "one": 1, "two": 2, "three": 3, "four": 4, "five": 5,
-    "six": 6, "seven": 7, "eight": 8, "nine": 9, "ten": 10, "eleven": 11,
-    "twelve": 12, "thirteen": 13, "fourteen": 14, "fifteen": 15, "sixteen": 16,
-    "seventeen": 17, "eighteen": 18, "nineteen": 19, "twenty": 20,
+    "zero": 0,
+    "one": 1,
+    "two": 2,
+    "three": 3,
+    "four": 4,
+    "five": 5,
+    "six": 6,
+    "seven": 7,
+    "eight": 8,
+    "nine": 9,
+    "ten": 10,
+    "eleven": 11,
+    "twelve": 12,
+    "thirteen": 13,
+    "fourteen": 14,
+    "fifteen": 15,
+    "sixteen": 16,
+    "seventeen": 17,
+    "eighteen": 18,
+    "nineteen": 19,
+    "twenty": 20,
 }
 
 _NUMERIC_RE = re.compile(r"-?\d+(?:[.,]\d+)?")
@@ -194,7 +211,7 @@ _JUDGE_SYSTEM = (
     "expresses a different fact, omits the central answer, or hedges "
     "without committing.\n\n"
     "Respond with ONLY a JSON object on a single line:\n"
-    '{\"correct\": true|false, \"rationale\": \"<one short sentence>\"}'
+    '{"correct": true|false, "rationale": "<one short sentence>"}'
 )
 
 
@@ -324,10 +341,7 @@ async def grade_many(
 
     if not rows:
         return []
-    coros = [
-        grade_with_judge(pred=p, gold=g, question=q, judge=judge)
-        for _qid, q, g, p in rows
-    ]
+    coros = [grade_with_judge(pred=p, gold=g, question=q, judge=judge) for _qid, q, g, p in rows]
     return list(await asyncio.gather(*coros))
 
 
diff --git a/surfsense_evals/src/surfsense_evals/suites/research/frames/ingest.py b/surfsense_evals/src/surfsense_evals/suites/research/frames/ingest.py
index 98e035f28..3ea7246a6 100644
--- a/surfsense_evals/src/surfsense_evals/suites/research/frames/ingest.py
+++ b/surfsense_evals/src/surfsense_evals/suites/research/frames/ingest.py
@@ -34,7 +34,6 @@ filename (without extension), so we round-trip via
 
 from __future__ import annotations
 
-import asyncio
 import json
 import logging
 from dataclasses import dataclass
@@ -161,8 +160,10 @@ async def _upload_markdowns(
                 name_to_id[s.title] = s.document_id
         logger.info(
             "FRAMES upload batch %d-%d: %d new, %d duplicate",
-            batch_start, batch_start + len(batch),
-            len(result.document_ids), len(result.duplicate_document_ids),
+            batch_start,
+            batch_start + len(batch),
+            len(result.document_ids),
+            len(result.duplicate_document_ids),
         )
     return name_to_id
 
@@ -189,14 +190,16 @@ def _resolve_question_doc_ids(
             doc_id = name_to_id.get(stem) or name_to_id.get(article.markdown_path.name)
             if doc_id is not None and doc_id not in doc_ids:
                 doc_ids.append(doc_id)
-        rows.append({
-            "qid": q.qid,
-            "raw_index": q.raw_index,
-            "n_wiki_urls": len(q.wiki_urls),
-            "wiki_titles": titles,
-            "document_ids": doc_ids,
-            "missing_urls": missing,
-        })
+        rows.append(
+            {
+                "qid": q.qid,
+                "raw_index": q.raw_index,
+                "n_wiki_urls": len(q.wiki_urls),
+                "wiki_titles": titles,
+                "document_ids": doc_ids,
+                "missing_urls": missing,
+            }
+        )
     return rows
 
 
@@ -239,7 +242,7 @@ async def run_ingest(
     settings = settings or IngestSettings(
         use_vision_llm=False,
         processing_mode="basic",
-        )
+    )
     bench_dir = ctx.benchmark_data_dir()
     wiki_cache = bench_dir / "wiki"
     wiki_cache.mkdir(parents=True, exist_ok=True)
@@ -251,8 +254,7 @@ async def run_ingest(
     questions = load_questions(tsv_path)
     if not questions:
         raise RuntimeError(
-            "FRAMES test.tsv contained no parseable rows; upstream may "
-            "have changed schema."
+            "FRAMES test.tsv contained no parseable rows; upstream may have changed schema."
         )
     logger.info("FRAMES: parsed %d questions from %s", len(questions), tsv_path.name)
     if max_questions is not None and max_questions > 0:
@@ -270,19 +272,23 @@ async def run_ingest(
     unique_urls = list(seen_urls.keys())
     logger.info(
         "FRAMES: %d unique Wikipedia URLs across %d questions",
-        len(unique_urls), len(questions),
+        len(unique_urls),
+        len(questions),
     )
 
     # 3. Fetch (with cache).
     fetcher = WikiFetcher(cache_dir=wiki_cache, rate_limit_rps=fetch_rate_limit_rps)
     n_cached = sum(
-        1 for url in unique_urls
+        1
+        for url in unique_urls
         if (wiki_cache / cache_filename_for_title(_safe_title(url))).exists()
     )
     fetched, missing_urls = await _fetch_articles(fetcher, unique_urls)
     logger.info(
         "FRAMES: fetched=%d, cache_hits=%d, missing=%d",
-        len(fetched), n_cached, len(missing_urls),
+        len(fetched),
+        n_cached,
+        len(missing_urls),
     )
 
     # 4. Upload to SurfSense (deduped by filename).
diff --git a/surfsense_evals/src/surfsense_evals/suites/research/frames/prompt.py b/surfsense_evals/src/surfsense_evals/suites/research/frames/prompt.py
index 16bb06da4..8f8b6e3b6 100644
--- a/surfsense_evals/src/surfsense_evals/suites/research/frames/prompt.py
+++ b/surfsense_evals/src/surfsense_evals/suites/research/frames/prompt.py
@@ -17,7 +17,6 @@ Format expectations (mirrors the FRAMES paper, section 4):
 
 from __future__ import annotations
 
-
 _BASE_INSTRUCTIONS = (
     "You are a careful question-answering assistant. The question may "
     "require combining facts from multiple sources, doing arithmetic, "
diff --git a/surfsense_evals/src/surfsense_evals/suites/research/frames/runner.py b/surfsense_evals/src/surfsense_evals/suites/research/frames/runner.py
index 450c7ddd6..c703ab23e 100644
--- a/surfsense_evals/src/surfsense_evals/suites/research/frames/runner.py
+++ b/surfsense_evals/src/surfsense_evals/suites/research/frames/runner.py
@@ -65,7 +65,7 @@ class FramesRunnerQuestion:
     question: str
     gold_answer: str
     reasoning_types: list[str]
-    document_ids: list[int]   # subset of corpus relevant to this Q (may be empty)
+    document_ids: list[int]  # subset of corpus relevant to this Q (may be empty)
     n_wiki_urls: int
     missing_urls: list[str]
 
@@ -107,16 +107,18 @@ def _load_questions(
             reasoning = list(row.get("reasoning_types") or [])
             if reasoning_filter and reasoning_filter not in [r.lower() for r in reasoning]:
                 continue
-            out.append(FramesRunnerQuestion(
-                qid=qid,
-                raw_index=int(row.get("raw_index") or 0),
-                question=str(row.get("question") or "").strip(),
-                gold_answer=str(row.get("gold_answer") or "").strip(),
-                reasoning_types=reasoning,
-                document_ids=list(map_row.get("document_ids") or []),
-                n_wiki_urls=int(map_row.get("n_wiki_urls") or 0),
-                missing_urls=list(map_row.get("missing_urls") or []),
-            ))
+            out.append(
+                FramesRunnerQuestion(
+                    qid=qid,
+                    raw_index=int(row.get("raw_index") or 0),
+                    question=str(row.get("question") or "").strip(),
+                    gold_answer=str(row.get("gold_answer") or "").strip(),
+                    reasoning_types=reasoning,
+                    document_ids=list(map_row.get("document_ids") or []),
+                    n_wiki_urls=int(map_row.get("n_wiki_urls") or 0),
+                    missing_urls=list(map_row.get("missing_urls") or []),
+                )
+            )
     out.sort(key=lambda q: q.raw_index)
     if sample_n is not None and sample_n > 0:
         out = out[:sample_n]
@@ -166,7 +168,10 @@ class FramesBenchmark:
 
     def add_run_args(self, parser: argparse.ArgumentParser) -> None:
         parser.add_argument(
-            "--n", dest="sample_n", type=int, default=None,
+            "--n",
+            dest="sample_n",
+            type=int,
+            default=None,
             help="Run only the first N questions after filters (default: all 824).",
         )
         parser.add_argument(
@@ -180,11 +185,15 @@ class FramesBenchmark:
             ),
         )
         parser.add_argument(
-            "--concurrency", type=int, default=4,
+            "--concurrency",
+            type=int,
+            default=4,
             help="Parallel question workers per arm.",
         )
         parser.add_argument(
-            "--scope-mentions", dest="scope_mentions", action="store_true",
+            "--scope-mentions",
+            dest="scope_mentions",
+            action="store_true",
             help=(
                 "SurfSense arm: scope retrieval to the per-question "
                 "document_ids (oracle-retrieval upper bound). Default "
@@ -192,11 +201,15 @@ class FramesBenchmark:
             ),
         )
         parser.add_argument(
-            "--max-output-tokens", type=int, default=512,
+            "--max-output-tokens",
+            type=int,
+            default=512,
             help="Cap on completion length for both arms.",
         )
         parser.add_argument(
-            "--no-judge", dest="no_judge", action="store_true",
+            "--no-judge",
+            dest="no_judge",
+            action="store_true",
             help=(
                 "Disable LLM-as-judge fallback grading; use only the "
                 "deterministic grader (faster but more pessimistic)."
@@ -217,19 +230,30 @@ class FramesBenchmark:
         )
         # Ingest-only knobs.
         parser.add_argument(
-            "--max-questions", dest="max_questions", type=int, default=None,
+            "--max-questions",
+            dest="max_questions",
+            type=int,
+            default=None,
             help="(ingest only) cap on number of questions to materialise + ingest.",
         )
         parser.add_argument(
-            "--upload-batch-size", dest="upload_batch_size", type=int, default=16,
+            "--upload-batch-size",
+            dest="upload_batch_size",
+            type=int,
+            default=16,
             help="(ingest only) markdown files per fileupload call.",
         )
         parser.add_argument(
-            "--skip-upload", dest="skip_upload", action="store_true",
+            "--skip-upload",
+            dest="skip_upload",
+            action="store_true",
             help="(ingest only) cache wiki articles locally but don't push to SurfSense.",
         )
         parser.add_argument(
-            "--fetch-rps", dest="fetch_rate_limit_rps", type=float, default=2.0,
+            "--fetch-rps",
+            dest="fetch_rate_limit_rps",
+            type=float,
+            default=2.0,
             help="(ingest only) max requests/second to the Wikipedia API.",
         )
         add_ingest_settings_args(parser, defaults=_DEFAULT_INGEST_SETTINGS)
@@ -270,21 +294,18 @@ class FramesBenchmark:
 
         doc_map, ingest_settings = _load_doc_map(map_path)
         questions = _load_questions(
-            questions_jsonl, doc_map,
+            questions_jsonl,
+            doc_map,
             sample_n=sample_n,
             reasoning_filter=reasoning_filter,
         )
         if not questions:
-            raise RuntimeError(
-                "No FRAMES questions matched the filters; broaden --reasoning/--n."
-            )
+            raise RuntimeError("No FRAMES questions matched the filters; broaden --reasoning/--n.")
         logger.info("FRAMES: scheduled %d questions", len(questions))
 
         api_key = os.environ.get("OPENROUTER_API_KEY")
         if not api_key:
-            raise RuntimeError(
-                "OPENROUTER_API_KEY env var is required for the bare-LLM arm."
-            )
+            raise RuntimeError("OPENROUTER_API_KEY env var is required for the bare-LLM arm.")
 
         bare_provider = OpenRouterChatProvider(
             api_key=api_key,
@@ -303,12 +324,14 @@ class FramesBenchmark:
 
         judge: LlmJudge | None = None
         if not no_judge:
-            judge = LlmJudge(config=JudgeConfig(
-                api_key=api_key,
-                model=judge_model,
-                base_url=ctx.config.openrouter_base_url,
-                concurrency=judge_concurrency,
-            ))
+            judge = LlmJudge(
+                config=JudgeConfig(
+                    api_key=api_key,
+                    model=judge_model,
+                    base_url=ctx.config.openrouter_base_url,
+                    concurrency=judge_concurrency,
+                )
+            )
 
         run_timestamp = utc_iso_timestamp()
         run_dir = ctx.runs_dir(run_timestamp=run_timestamp)
@@ -318,9 +341,7 @@ class FramesBenchmark:
             return await bare_arm.answer(_make_bare_request(q, max_output_tokens))
 
         async def _surf_one(q: FramesRunnerQuestion) -> ArmResult:
-            return await surf_arm.answer(
-                _make_surfsense_request(q, scope_mentions=scope_mentions)
-            )
+            return await surf_arm.answer(_make_surfsense_request(q, scope_mentions=scope_mentions))
 
         bare_results, surf_results = await asyncio.gather(
             _gather_with_limit((_bare_one(q) for q in questions), concurrency=concurrency),
@@ -343,16 +364,26 @@ class FramesBenchmark:
                     "n_missing_urls": len(q.missing_urls),
                     "gold": q.gold_answer,
                 }
-                fh.write(json.dumps({
-                    **meta,
-                    **b_res.to_jsonl(),
-                    "graded": b_g.to_dict(),
-                }) + "\n")
-                fh.write(json.dumps({
-                    **meta,
-                    **s_res.to_jsonl(),
-                    "graded": s_g.to_dict(),
-                }) + "\n")
+                fh.write(
+                    json.dumps(
+                        {
+                            **meta,
+                            **b_res.to_jsonl(),
+                            "graded": b_g.to_dict(),
+                        }
+                    )
+                    + "\n"
+                )
+                fh.write(
+                    json.dumps(
+                        {
+                            **meta,
+                            **s_res.to_jsonl(),
+                            "graded": s_g.to_dict(),
+                        }
+                    )
+                    + "\n"
+                )
 
         metrics = _compute_metrics(questions, bare_results, surf_results, bare_grades, surf_grades)
         artifact = RunArtifact(
@@ -380,13 +411,18 @@ class FramesBenchmark:
 
         manifest_path = run_dir / "run_artifact.json"
         manifest_path.write_text(
-            json.dumps({
-                "suite": self.suite,
-                "benchmark": self.name,
-                "raw_path": "raw.jsonl",
-                "metrics": metrics,
-                "extra": artifact.extra,
-            }, indent=2, sort_keys=True) + "\n",
+            json.dumps(
+                {
+                    "suite": self.suite,
+                    "benchmark": self.name,
+                    "raw_path": "raw.jsonl",
+                    "metrics": metrics,
+                    "extra": artifact.extra,
+                },
+                indent=2,
+                sort_keys=True,
+            )
+            + "\n",
             encoding="utf-8",
         )
         return artifact
@@ -451,8 +487,8 @@ class FramesBenchmark:
             for tag, vals in sorted(per_reasoning.items()):
                 body_lines.append(
                     f"  - {tag}: SurfSense {_pp(vals.get('delta_accuracy_pp'))} pp "
-                    f"(n={vals.get('n')}, bare acc={vals.get('bare_accuracy', 0)*100:.1f}%, "
-                    f"surf acc={vals.get('surfsense_accuracy', 0)*100:.1f}%)"
+                    f"(n={vals.get('n')}, bare acc={vals.get('bare_accuracy', 0) * 100:.1f}%, "
+                    f"surf acc={vals.get('surfsense_accuracy', 0) * 100:.1f}%)"
                 )
 
         return ReportSection(
@@ -553,8 +589,7 @@ def _compute_metrics(
             "bare_accuracy": (sum(b_correct) / len(pairs)) if pairs else 0.0,
             "surfsense_accuracy": (sum(s_correct) / len(pairs)) if pairs else 0.0,
             "delta_accuracy_pp": (
-                100.0 * (sum(s_correct) - sum(b_correct)) / len(pairs)
-                if pairs else 0.0
+                100.0 * (sum(s_correct) - sum(b_correct)) / len(pairs) if pairs else 0.0
             ),
         }
 
@@ -571,8 +606,12 @@ def _compute_metrics(
             "latency_ms_mean": bare_latency_agg.mean,
             "latency_ms_median": bare_latency_agg.median,
             "latency_ms_p95": bare_latency_agg.p95,
-            "input_tokens_mean": (sum(bare_in_tokens) / len(bare_in_tokens)) if bare_in_tokens else 0.0,
-            "output_tokens_mean": (sum(bare_out_tokens) / len(bare_out_tokens)) if bare_out_tokens else 0.0,
+            "input_tokens_mean": (sum(bare_in_tokens) / len(bare_in_tokens))
+            if bare_in_tokens
+            else 0.0,
+            "output_tokens_mean": (sum(bare_out_tokens) / len(bare_out_tokens))
+            if bare_out_tokens
+            else 0.0,
         },
         "surfsense": {
             **surf_acc.to_dict(),
diff --git a/surfsense_evals/src/surfsense_evals/suites/research/frames/wiki_fetch.py b/surfsense_evals/src/surfsense_evals/suites/research/frames/wiki_fetch.py
index 7f6b63e50..2bc96ad3a 100644
--- a/surfsense_evals/src/surfsense_evals/suites/research/frames/wiki_fetch.py
+++ b/surfsense_evals/src/surfsense_evals/suites/research/frames/wiki_fetch.py
@@ -49,10 +49,10 @@ USER_AGENT = (
 class WikiArticle:
     """One fetched article + metadata."""
 
-    title: str            # canonical title returned by MW (post-redirect)
-    source_url: str       # the URL we were asked to fetch
-    markdown_path: Path   # where the cached body lives on disk
-    n_chars: int          # length of the body (post-prepend H1)
+    title: str  # canonical title returned by MW (post-redirect)
+    source_url: str  # the URL we were asked to fetch
+    markdown_path: Path  # where the cached body lives on disk
+    n_chars: int  # length of the body (post-prepend H1)
     redirected_from: str | None = None
 
 
@@ -168,10 +168,13 @@ class WikiFetcher:
                 break
             except (httpx.HTTPError, RuntimeError) as exc:
                 last_exc = exc
-                wait = 1.0 * (2 ** attempt)
+                wait = 1.0 * (2**attempt)
                 logger.warning(
                     "wiki fetch %r attempt %d failed: %s; retry in %.1fs",
-                    title, attempt + 1, exc, wait,
+                    title,
+                    attempt + 1,
+                    exc,
+                    wait,
                 )
                 await asyncio.sleep(wait)
         else:
@@ -217,10 +220,14 @@ class WikiFetcher:
         }
         headers = {"User-Agent": USER_AGENT, "Accept": "application/json"}
         if http is not None:
-            response = await http.get(WIKI_API, params=params, headers=headers, timeout=self._timeout)
+            response = await http.get(
+                WIKI_API, params=params, headers=headers, timeout=self._timeout
+            )
         else:
             async with httpx.AsyncClient(timeout=self._timeout) as client:
-                response = await client.get(WIKI_API, params=params, headers=headers, timeout=self._timeout)
+                response = await client.get(
+                    WIKI_API, params=params, headers=headers, timeout=self._timeout
+                )
         response.raise_for_status()
         data = response.json()
         if "error" in data:
diff --git a/surfsense_evals/tests/core/test_auth.py b/surfsense_evals/tests/core/test_auth.py
index 181d8e632..ad291b295 100644
--- a/surfsense_evals/tests/core/test_auth.py
+++ b/surfsense_evals/tests/core/test_auth.py
@@ -52,9 +52,7 @@ async def test_acquire_token_local_mode_posts_desktop_login_json():
             200, json={"access_token": "T", "refresh_token": "R", "token_type": "bearer"}
         )
     )
-    config = _make_config(
-        surfsense_user_email="u@example.com", surfsense_user_password="pw"
-    )
+    config = _make_config(surfsense_user_email="u@example.com", surfsense_user_password="pw")
     bundle = await acquire_token(config)
     assert bundle.access_token == "T"
     assert bundle.refresh_token == "R"
diff --git a/surfsense_evals/tests/core/test_clients.py b/surfsense_evals/tests/core/test_clients.py
index aa98f0ad4..44b78e3ba 100644
--- a/surfsense_evals/tests/core/test_clients.py
+++ b/surfsense_evals/tests/core/test_clients.py
@@ -94,10 +94,18 @@ async def test_documents_status_parses_state(respx_mock, http):
             200,
             json={
                 "items": [
-                    {"id": 1, "title": "a.pdf", "document_type": "FILE",
-                     "status": {"state": "ready", "reason": None}},
-                    {"id": 2, "title": "b.pdf", "document_type": "FILE",
-                     "status": {"state": "failed", "reason": "ETL boom"}},
+                    {
+                        "id": 1,
+                        "title": "a.pdf",
+                        "document_type": "FILE",
+                        "status": {"state": "ready", "reason": None},
+                    },
+                    {
+                        "id": 2,
+                        "title": "b.pdf",
+                        "document_type": "FILE",
+                        "status": {"state": "failed", "reason": "ETL boom"},
+                    },
                 ]
             },
         )
@@ -137,14 +145,26 @@ async def test_documents_upload_returns_payload(respx_mock, http, tmp_path: Path
 async def test_documents_list_chunks_paginated(respx_mock, http):
     respx_mock.get("/api/v1/documents/5/chunks").mock(
         side_effect=[
-            httpx.Response(200, json={
-                "items": [{"id": 1, "content": "a"}, {"id": 2, "content": "b"}],
-                "total": 3, "page": 0, "page_size": 2, "has_more": True,
-            }),
-            httpx.Response(200, json={
-                "items": [{"id": 3, "content": "c"}],
-                "total": 3, "page": 1, "page_size": 2, "has_more": False,
-            }),
+            httpx.Response(
+                200,
+                json={
+                    "items": [{"id": 1, "content": "a"}, {"id": 2, "content": "b"}],
+                    "total": 3,
+                    "page": 0,
+                    "page_size": 2,
+                    "has_more": True,
+                },
+            ),
+            httpx.Response(
+                200,
+                json={
+                    "items": [{"id": 3, "content": "c"}],
+                    "total": 3,
+                    "page": 1,
+                    "page_size": 2,
+                    "has_more": False,
+                },
+            ),
         ]
     )
     client = DocumentsClient(http, _BASE)
@@ -191,15 +211,17 @@ def _sse_body(events: list[dict]) -> bytes:
 @pytest.mark.asyncio
 @respx.mock(base_url=_BASE)
 async def test_ask_accumulates_text_deltas(respx_mock, http):
-    body = _sse_body([
-        {"type": "start", "messageId": "m1"},
-        {"type": "text-start", "id": "t1"},
-        {"type": "text-delta", "id": "t1", "delta": "Answer "},
-        {"type": "text-delta", "id": "t1", "delta": "is "},
-        {"type": "text-delta", "id": "t1", "delta": "B [citation:42]."},
-        {"type": "text-end", "id": "t1"},
-        {"type": "finish"},
-    ])
+    body = _sse_body(
+        [
+            {"type": "start", "messageId": "m1"},
+            {"type": "text-start", "id": "t1"},
+            {"type": "text-delta", "id": "t1", "delta": "Answer "},
+            {"type": "text-delta", "id": "t1", "delta": "is "},
+            {"type": "text-delta", "id": "t1", "delta": "B [citation:42]."},
+            {"type": "text-end", "id": "t1"},
+            {"type": "finish"},
+        ]
+    )
     respx_mock.post("/api/v1/new_chat").mock(
         return_value=httpx.Response(
             200,
@@ -208,9 +230,7 @@ async def test_ask_accumulates_text_deltas(respx_mock, http):
         )
     )
     client = NewChatClient(http, _BASE)
-    answer = await client.ask(
-        thread_id=1, search_space_id=2, user_query="What is the answer?"
-    )
+    answer = await client.ask(thread_id=1, search_space_id=2, user_query="What is the answer?")
     assert answer.text == "Answer is B [citation:42]."
     assert answer.finished_normally is True
     assert any(c["chunk_id"] == 42 for c in answer.citations)
@@ -219,23 +239,21 @@ async def test_ask_accumulates_text_deltas(respx_mock, http):
 @pytest.mark.asyncio
 @respx.mock(base_url=_BASE)
 async def test_ask_409_thread_busy_retries(respx_mock, http):
-    body = _sse_body([
-        {"type": "text-delta", "id": "t1", "delta": "ok"},
-        {"type": "finish"},
-    ])
+    body = _sse_body(
+        [
+            {"type": "text-delta", "id": "t1", "delta": "ok"},
+            {"type": "finish"},
+        ]
+    )
     busy = httpx.Response(
         409,
         json={"detail": {"errorCode": "THREAD_BUSY", "message": "busy"}},
         headers={"Retry-After": "1"},
     )
-    success = httpx.Response(
-        200, content=body, headers={"Content-Type": "text/event-stream"}
-    )
+    success = httpx.Response(200, content=body, headers={"Content-Type": "text/event-stream"})
     respx_mock.post("/api/v1/new_chat").mock(side_effect=[busy, success])
     client = NewChatClient(http, _BASE)
-    answer = await client.ask(
-        thread_id=1, search_space_id=2, user_query="hi", max_busy_retries=2
-    )
+    answer = await client.ask(thread_id=1, search_space_id=2, user_query="hi", max_busy_retries=2)
     assert answer.text == "ok"
 
 
@@ -250,6 +268,4 @@ async def test_ask_409_exhausts_retries(respx_mock, http):
     respx_mock.post("/api/v1/new_chat").mock(return_value=busy)
     client = NewChatClient(http, _BASE)
     with pytest.raises(ThreadBusyError):
-        await client.ask(
-            thread_id=1, search_space_id=2, user_query="hi", max_busy_retries=1
-        )
+        await client.ask(thread_id=1, search_space_id=2, user_query="hi", max_busy_retries=1)
diff --git a/surfsense_evals/tests/core/test_ingest_settings.py b/surfsense_evals/tests/core/test_ingest_settings.py
index fd7e7818a..cd1d1f827 100644
--- a/surfsense_evals/tests/core/test_ingest_settings.py
+++ b/surfsense_evals/tests/core/test_ingest_settings.py
@@ -46,32 +46,24 @@ class TestMerge:
 
     def test_explicit_false_overrides_default_true(self) -> None:
         defaults = IngestSettings(use_vision_llm=True)
-        merged = IngestSettings.merge(
-            defaults, {"use_vision_llm": False}
-        )
+        merged = IngestSettings.merge(defaults, {"use_vision_llm": False})
         assert merged.use_vision_llm is False
 
     def test_explicit_true_overrides_default_false(self) -> None:
         defaults = IngestSettings(use_vision_llm=False)
-        merged = IngestSettings.merge(
-            defaults, {"use_vision_llm": True}
-        )
+        merged = IngestSettings.merge(defaults, {"use_vision_llm": True})
         assert merged.use_vision_llm is True
 
     def test_none_means_silent(self) -> None:
         # Argparse with BooleanOptionalAction yields None when the
         # operator passed neither --use-vision-llm nor --no-vision-llm.
         defaults = IngestSettings(use_vision_llm=True)
-        merged = IngestSettings.merge(
-            defaults, {"use_vision_llm": None}
-        )
+        merged = IngestSettings.merge(defaults, {"use_vision_llm": None})
         assert merged.use_vision_llm is True
 
     def test_processing_mode_override(self) -> None:
         defaults = IngestSettings(processing_mode="basic")
-        merged = IngestSettings.merge(
-            defaults, {"processing_mode": "premium"}
-        )
+        merged = IngestSettings.merge(defaults, {"processing_mode": "premium"})
         assert merged.processing_mode == "premium"
 
     def test_processing_mode_invalid_raises(self) -> None:
@@ -134,9 +126,7 @@ class TestAddArgs:
         p = argparse.ArgumentParser()
         add_ingest_settings_args(
             p,
-            defaults=IngestSettings(
-                use_vision_llm=False, processing_mode="basic"
-            ),
+            defaults=IngestSettings(use_vision_llm=False, processing_mode="basic"),
         )
         return p
 
@@ -158,31 +148,21 @@ class TestAddArgs:
             args = parser.parse_args(["--processing-mode", mode])
             assert args.processing_mode == mode
 
-    def test_processing_mode_rejects_unknown(
-        self, parser: argparse.ArgumentParser
-    ) -> None:
+    def test_processing_mode_rejects_unknown(self, parser: argparse.ArgumentParser) -> None:
         with pytest.raises(SystemExit):
             parser.parse_args(["--processing-mode", "exotic"])
 
-    def test_vision_flags_mutually_exclusive(
-        self, parser: argparse.ArgumentParser
-    ) -> None:
+    def test_vision_flags_mutually_exclusive(self, parser: argparse.ArgumentParser) -> None:
         with pytest.raises(SystemExit):
             parser.parse_args(["--use-vision-llm", "--no-vision-llm"])
 
     def test_full_pipeline(self, parser: argparse.ArgumentParser) -> None:
         # Operator passes flags + defaults are reasonable. Merge
         # should yield exactly what they asked for.
-        args = parser.parse_args(
-            ["--use-vision-llm", "--processing-mode", "premium"]
-        )
-        defaults = IngestSettings(
-            use_vision_llm=False, processing_mode="basic"
-        )
+        args = parser.parse_args(["--use-vision-llm", "--processing-mode", "premium"])
+        defaults = IngestSettings(use_vision_llm=False, processing_mode="basic")
         merged = IngestSettings.merge(defaults, vars(args))
-        assert merged == IngestSettings(
-            use_vision_llm=True, processing_mode="premium"
-        )
+        assert merged == IngestSettings(use_vision_llm=True, processing_mode="premium")
 
 
 # ---------------------------------------------------------------------------
@@ -240,16 +220,12 @@ class TestHeader:
 
 class TestFormatMd:
     def test_full_settings(self) -> None:
-        out = format_ingest_settings_md(
-            {"use_vision_llm": True, "processing_mode": "premium"}
-        )
+        out = format_ingest_settings_md({"use_vision_llm": True, "processing_mode": "premium"})
         assert "vision_llm=`on`" in out
         assert "processing_mode=`premium`" in out
 
     def test_default_off(self) -> None:
-        out = format_ingest_settings_md(
-            {"use_vision_llm": False, "processing_mode": "basic"}
-        )
+        out = format_ingest_settings_md({"use_vision_llm": False, "processing_mode": "basic"})
         assert "vision_llm=`off`" in out
         assert "processing_mode=`basic`" in out
 
diff --git a/surfsense_evals/tests/core/test_metrics.py b/surfsense_evals/tests/core/test_metrics.py
index cde1bb957..73c85c371 100644
--- a/surfsense_evals/tests/core/test_metrics.py
+++ b/surfsense_evals/tests/core/test_metrics.py
@@ -25,7 +25,12 @@ from surfsense_evals.core.metrics import (
 @pytest.mark.parametrize(
     "k,n,low,high",
     [
-        (80, 100, 0.7111, 0.8666),  # cross-checked vs statsmodels.proportion_confint(method='wilson')
+        (
+            80,
+            100,
+            0.7111,
+            0.8666,
+        ),  # cross-checked vs statsmodels.proportion_confint(method='wilson')
         (50, 100, 0.4038, 0.5962),
         (0, 0, 0.0, 1.0),
         (0, 10, 0.0, 0.2775),
@@ -74,7 +79,7 @@ def test_mcnemar_exact_branch_strong_signal():
     assert res.b == 0
     assert res.c == 10
     assert res.method == "exact"
-    expected = 2 * (0.5 ** 10)
+    expected = 2 * (0.5**10)
     assert math.isclose(res.p_value, expected, rel_tol=1e-9)
 
 
diff --git a/surfsense_evals/tests/core/test_parse_answer_letter.py b/surfsense_evals/tests/core/test_parse_answer_letter.py
index 5adbf4bc3..0662adba3 100644
--- a/surfsense_evals/tests/core/test_parse_answer_letter.py
+++ b/surfsense_evals/tests/core/test_parse_answer_letter.py
@@ -11,7 +11,11 @@ from surfsense_evals.core.parse.answer_letter import AnswerLetterResult
 @pytest.mark.parametrize(
     "text,expected_letter,expected_strategy",
     [
-        ('```json\n{"step_by_step_thinking": "...", "answer_choice": "B"}\n```', "B", "json_envelope"),
+        (
+            '```json\n{"step_by_step_thinking": "...", "answer_choice": "B"}\n```',
+            "B",
+            "json_envelope",
+        ),
         ('Reasoning... {"step_by_step_thinking": "x", "answer_choice": "C"}', "C", "json_envelope"),
         ("Long reasoning.\nAnswer: D", "D", "answer_line"),
         ("The correct answer is (A).", "A", "answer_line"),
diff --git a/surfsense_evals/tests/core/test_parse_citations.py b/surfsense_evals/tests/core/test_parse_citations.py
index eb444dab2..488af590d 100644
--- a/surfsense_evals/tests/core/test_parse_citations.py
+++ b/surfsense_evals/tests/core/test_parse_citations.py
@@ -91,7 +91,7 @@ def test_regex_pattern_matches_ts_source():
     assert "https?://" in pattern
     assert "urlcite" in pattern
     assert "doc-" in pattern
-    assert "\u200B" in pattern
+    assert "\u200b" in pattern
     assert "【" in pattern and "】" in pattern
 
 
diff --git a/surfsense_evals/tests/core/test_parse_freeform_answer.py b/surfsense_evals/tests/core/test_parse_freeform_answer.py
index bdc7d74fc..a39aad2e5 100644
--- a/surfsense_evals/tests/core/test_parse_freeform_answer.py
+++ b/surfsense_evals/tests/core/test_parse_freeform_answer.py
@@ -44,11 +44,14 @@ class TestExtractFreeformAnswer:
         assert extract_freeform_answer("ANSWER: yes") == "yes"
         assert extract_freeform_answer("answer: no") == "no"
 
-    @pytest.mark.parametrize("text,expected", [
-        ("Answer: 1, 2, 3", "1, 2, 3"),
-        ("Answer: 3.14", "3.14"),
-        ("Answer:    spaced   ", "spaced"),
-    ])
+    @pytest.mark.parametrize(
+        "text,expected",
+        [
+            ("Answer: 1, 2, 3", "1, 2, 3"),
+            ("Answer: 3.14", "3.14"),
+            ("Answer:    spaced   ", "spaced"),
+        ],
+    )
     def test_various_payloads(self, text: str, expected: str) -> None:
         assert extract_freeform_answer(text) == expected
 
diff --git a/surfsense_evals/tests/core/test_parse_sse.py b/surfsense_evals/tests/core/test_parse_sse.py
index 362717288..10998a881 100644
--- a/surfsense_evals/tests/core/test_parse_sse.py
+++ b/surfsense_evals/tests/core/test_parse_sse.py
@@ -22,12 +22,16 @@ async def _astream(lines):
 @pytest.mark.asyncio
 async def test_basic_data_frame():
     events = await _alist(
-        iter_sse_events(_astream([
-            'data: {"type": "text-delta", "delta": "hi"}',
-            "",
-            'data: {"type": "finish"}',
-            "",
-        ]))
+        iter_sse_events(
+            _astream(
+                [
+                    'data: {"type": "text-delta", "delta": "hi"}',
+                    "",
+                    'data: {"type": "finish"}',
+                    "",
+                ]
+            )
+        )
     )
     assert [e.data for e in events] == [
         '{"type": "text-delta", "delta": "hi"}',
@@ -38,10 +42,14 @@ async def test_basic_data_frame():
 @pytest.mark.asyncio
 async def test_done_sentinel_passes_through():
     events = await _alist(
-        iter_sse_events(_astream([
-            "data: [DONE]",
-            "",
-        ]))
+        iter_sse_events(
+            _astream(
+                [
+                    "data: [DONE]",
+                    "",
+                ]
+            )
+        )
     )
     assert [e.data for e in events] == ["[DONE]"]
 
@@ -49,11 +57,15 @@ async def test_done_sentinel_passes_through():
 @pytest.mark.asyncio
 async def test_multiline_data_joins_with_newline():
     events = await _alist(
-        iter_sse_events(_astream([
-            "data: line1",
-            "data: line2",
-            "",
-        ]))
+        iter_sse_events(
+            _astream(
+                [
+                    "data: line1",
+                    "data: line2",
+                    "",
+                ]
+            )
+        )
     )
     assert events[0].data == "line1\nline2"
 
@@ -61,13 +73,17 @@ async def test_multiline_data_joins_with_newline():
 @pytest.mark.asyncio
 async def test_comments_and_other_fields_ignored():
     events = await _alist(
-        iter_sse_events(_astream([
-            ": heartbeat",
-            "event: foo",
-            "id: 123",
-            "data: payload",
-            "",
-        ]))
+        iter_sse_events(
+            _astream(
+                [
+                    ": heartbeat",
+                    "event: foo",
+                    "id: 123",
+                    "data: payload",
+                    "",
+                ]
+            )
+        )
     )
     assert [e.data for e in events] == ["payload"]
 
@@ -77,8 +93,12 @@ async def test_handles_missing_trailing_blank():
     """Some servers omit the final blank line; the consumer should still emit."""
 
     events = await _alist(
-        iter_sse_events(_astream([
-            "data: only-one",
-        ]))
+        iter_sse_events(
+            _astream(
+                [
+                    "data: only-one",
+                ]
+            )
+        )
     )
     assert [e.data for e in events] == ["only-one"]
diff --git a/surfsense_evals/tests/core/test_provider_openrouter.py b/surfsense_evals/tests/core/test_provider_openrouter.py
index eb78aa053..aeed6eae5 100644
--- a/surfsense_evals/tests/core/test_provider_openrouter.py
+++ b/surfsense_evals/tests/core/test_provider_openrouter.py
@@ -36,11 +36,18 @@ async def test_payload_shape_matches_openrouter_docs(respx_mock, tiny_pdf: Path)
         return httpx.Response(
             200,
             json={
-                "choices": [{
-                    "message": {"content": "Answer: B"},
-                    "finish_reason": "stop",
-                }],
-                "usage": {"prompt_tokens": 10, "completion_tokens": 5, "total_tokens": 15, "cost": 0.0001},
+                "choices": [
+                    {
+                        "message": {"content": "Answer: B"},
+                        "finish_reason": "stop",
+                    }
+                ],
+                "usage": {
+                    "prompt_tokens": 10,
+                    "completion_tokens": 5,
+                    "total_tokens": 15,
+                    "cost": 0.0001,
+                },
             },
         )
 
@@ -63,8 +70,7 @@ async def test_payload_shape_matches_openrouter_docs(respx_mock, tiny_pdf: Path)
     assert file_part["file"]["filename"] == tiny_pdf.name
     assert file_part["file"]["file_data"].startswith("data:application/pdf;base64,")
     assert (
-        base64.b64decode(file_part["file"]["file_data"].split(",", 1)[1])
-        == tiny_pdf.read_bytes()  # noqa: ASYNC240 — test fixture, sync read is fine
+        base64.b64decode(file_part["file"]["file_data"].split(",", 1)[1]) == tiny_pdf.read_bytes()  # noqa: ASYNC240 — test fixture, sync read is fine
     )
     assert user["content"][1] == {"type": "text", "text": "What is the diagnosis?"}
     assert captured["headers"]["authorization"] == "Bearer sk-or-test"
@@ -85,22 +91,22 @@ async def test_chat_array_content_concatenates(respx_mock, tiny_pdf: Path):
         return_value=httpx.Response(
             200,
             json={
-                "choices": [{
-                    "message": {
-                        "content": [
-                            {"type": "text", "text": "Hello "},
-                            {"type": "text", "text": "world"},
-                            {"type": "image_url", "image_url": "ignored"},
-                        ]
+                "choices": [
+                    {
+                        "message": {
+                            "content": [
+                                {"type": "text", "text": "Hello "},
+                                {"type": "text", "text": "world"},
+                                {"type": "image_url", "image_url": "ignored"},
+                            ]
+                        }
                     }
-                }],
+                ],
                 "usage": {"prompt_tokens": 1, "completion_tokens": 1},
             },
         )
     )
-    provider = OpenRouterPdfProvider(
-        api_key="sk-or-test", base_url=_BASE, model="x/y"
-    )
+    provider = OpenRouterPdfProvider(api_key="sk-or-test", base_url=_BASE, model="x/y")
     response = await provider.complete(prompt="hi", pdf_path=tiny_pdf)
     assert response.text == "Hello world"
 
diff --git a/surfsense_evals/tests/suites/test_crag_dataset.py b/surfsense_evals/tests/suites/test_crag_dataset.py
index 36114b52e..c52e0f56b 100644
--- a/surfsense_evals/tests/suites/test_crag_dataset.py
+++ b/surfsense_evals/tests/suites/test_crag_dataset.py
@@ -11,8 +11,6 @@ import bz2
 import json
 from pathlib import Path
 
-import pytest
-
 from surfsense_evals.suites.research.crag.dataset import (
     CragPage,
     CragQuestion,
@@ -67,13 +65,15 @@ class TestParser:
                 interaction_id="abc",
                 query="Who directed Inception?",
                 answer="Christopher Nolan",
-                pages=[{
-                    "page_name": "Inception (film)",
-                    "page_url": "https://en.wikipedia.org/wiki/Inception",
-                    "page_snippet": "snippet",
-                    "page_result": "<html>full html</html>",
-                    "page_last_modified": "2024-01-01",
-                }],
+                pages=[
+                    {
+                        "page_name": "Inception (film)",
+                        "page_url": "https://en.wikipedia.org/wiki/Inception",
+                        "page_snippet": "snippet",
+                        "page_result": "<html>full html</html>",
+                        "page_last_modified": "2024-01-01",
+                    }
+                ],
             ),
         ]
         path = _make_jsonl_bz2(rows, tmp_path)
@@ -122,8 +122,7 @@ class TestParser:
 
     def test_alt_answers_parsed(self, tmp_path: Path) -> None:
         rows = [
-            _row(interaction_id="z", query="q?", answer="42",
-                 alt_ans=["forty-two", "42.0"]),
+            _row(interaction_id="z", query="q?", answer="42", alt_ans=["forty-two", "42.0"]),
         ]
         path = _make_jsonl_bz2(rows, tmp_path)
         parsed = iter_questions(path)
@@ -145,22 +144,32 @@ class TestParser:
 class TestPageHash:
     def test_url_hash_stable(self) -> None:
         a = CragPage(
-            page_name="A", page_url="https://x.test/p?q=1",
-            page_snippet="", page_html="<html/>",
+            page_name="A",
+            page_url="https://x.test/p?q=1",
+            page_snippet="",
+            page_html="<html/>",
         )
         b = CragPage(
-            page_name="B", page_url="https://x.test/p?q=1",
-            page_snippet="", page_html="<html/>",
+            page_name="B",
+            page_url="https://x.test/p?q=1",
+            page_snippet="",
+            page_html="<html/>",
         )
         assert a.url_hash == b.url_hash
         assert len(a.url_hash) == 12
 
     def test_url_hash_unique(self) -> None:
         a = CragPage(
-            page_name="A", page_url="https://x.test/a", page_snippet="", page_html="<html/>",
+            page_name="A",
+            page_url="https://x.test/a",
+            page_snippet="",
+            page_html="<html/>",
         )
         b = CragPage(
-            page_name="B", page_url="https://x.test/b", page_snippet="", page_html="<html/>",
+            page_name="B",
+            page_url="https://x.test/b",
+            page_snippet="",
+            page_html="<html/>",
         )
         assert a.url_hash != b.url_hash
 
@@ -176,21 +185,23 @@ class TestStratifiedSample:
             (5, "sports", "multi-hop"),
         ):
             for _ in range(n):
-                out.append(CragQuestion(
-                    qid=f"C{idx:05d}",
-                    interaction_id=f"i{idx}",
-                    query_time="2024-01-01",
-                    query=f"q{idx}?",
-                    gold_answer="a",
-                    alt_answers=[],
-                    domain=domain,
-                    question_type=qtype,
-                    static_or_dynamic="static",
-                    popularity="head",
-                    split=0,
-                    raw_index=idx,
-                    pages=[],
-                ))
+                out.append(
+                    CragQuestion(
+                        qid=f"C{idx:05d}",
+                        interaction_id=f"i{idx}",
+                        query_time="2024-01-01",
+                        query=f"q{idx}?",
+                        gold_answer="a",
+                        alt_answers=[],
+                        domain=domain,
+                        question_type=qtype,
+                        static_or_dynamic="static",
+                        popularity="head",
+                        split=0,
+                        raw_index=idx,
+                        pages=[],
+                    )
+                )
                 idx += 1
         return out
 
diff --git a/surfsense_evals/tests/suites/test_crag_grader.py b/surfsense_evals/tests/suites/test_crag_grader.py
index 93bf6f478..e0599c8b6 100644
--- a/surfsense_evals/tests/suites/test_crag_grader.py
+++ b/surfsense_evals/tests/suites/test_crag_grader.py
@@ -7,8 +7,6 @@ exercise the deterministic shortcut + the special-case routing for
 
 from __future__ import annotations
 
-import pytest
-
 from surfsense_evals.suites.research.crag.grader import (
     CragGradeResult,
     _flags_false_premise,
@@ -154,7 +152,9 @@ class TestGradeDeterministicHappyPath:
 class TestGradeDeterministicRefusal:
     def test_idk_maps_to_missing(self) -> None:
         result = grade_deterministic(
-            pred="I don't know.", gold="Tim Cook", question_type="simple",
+            pred="I don't know.",
+            gold="Tim Cook",
+            question_type="simple",
         )
         assert result.grade == "missing"
         assert result.score == 0
@@ -227,8 +227,11 @@ class TestGradeDeterministicLexicalMiss:
 class TestGradeResultShape:
     def test_to_dict_round_trip(self) -> None:
         result = CragGradeResult(
-            grade="correct", score=1, method="exact",
-            normalised_pred="x", normalised_gold="x",
+            grade="correct",
+            score=1,
+            method="exact",
+            normalised_pred="x",
+            normalised_gold="x",
         )
         d = result.to_dict()
         assert d["grade"] == "correct"
diff --git a/surfsense_evals/tests/suites/test_crag_html_extract.py b/surfsense_evals/tests/suites/test_crag_html_extract.py
index a2b47aa45..368692177 100644
--- a/surfsense_evals/tests/suites/test_crag_html_extract.py
+++ b/surfsense_evals/tests/suites/test_crag_html_extract.py
@@ -11,13 +11,10 @@ We don't network-fetch trafilatura; we just verify the wrapper:
 
 from __future__ import annotations
 
-import pytest
-
 from surfsense_evals.suites.research.crag.html_extract import (
     extract_main_content,
 )
 
-
 _RICH_HTML = """\
 <!DOCTYPE html>
 <html>
@@ -115,7 +112,9 @@ class TestFallbackStripper:
         </body></html>
         """
         result = extract_main_content(
-            html, url="https://x.test/", page_name="Title",
+            html,
+            url="https://x.test/",
+            page_name="Title",
         )
         assert result.ok
         assert "content one" in result.text
diff --git a/surfsense_evals/tests/suites/test_frames_dataset.py b/surfsense_evals/tests/suites/test_frames_dataset.py
index e79e7db89..f76dc0b6f 100644
--- a/surfsense_evals/tests/suites/test_frames_dataset.py
+++ b/surfsense_evals/tests/suites/test_frames_dataset.py
@@ -16,8 +16,6 @@ from __future__ import annotations
 import textwrap
 from pathlib import Path
 
-import pytest
-
 from surfsense_evals.suites.research.frames.dataset import (
     FramesQuestion,
     _parse_reasoning_types,
@@ -25,7 +23,6 @@ from surfsense_evals.suites.research.frames.dataset import (
     load_questions,
 )
 
-
 # ---------------------------------------------------------------------------
 # Pure-function tests
 # ---------------------------------------------------------------------------
diff --git a/surfsense_evals/tests/suites/test_frames_grader.py b/surfsense_evals/tests/suites/test_frames_grader.py
index e6e38ff8a..d4bbad79a 100644
--- a/surfsense_evals/tests/suites/test_frames_grader.py
+++ b/surfsense_evals/tests/suites/test_frames_grader.py
@@ -8,10 +8,7 @@ runner knows to consult the judge.
 
 from __future__ import annotations
 
-import pytest
-
 from surfsense_evals.suites.research.frames.grader import (
-    GradeResult,
     _maybe_number,
     _normalise,
     _whole_word_substring,
diff --git a/surfsense_evals/tests/suites/test_frames_wiki_fetch.py b/surfsense_evals/tests/suites/test_frames_wiki_fetch.py
index 4941756f4..483c7aa58 100644
--- a/surfsense_evals/tests/suites/test_frames_wiki_fetch.py
+++ b/surfsense_evals/tests/suites/test_frames_wiki_fetch.py
@@ -63,14 +63,22 @@ class TestCacheFilename:
 @pytest.mark.asyncio
 @respx.mock
 async def test_fetch_success_writes_markdown(tmp_path: Path) -> None:
-    respx.get(WIKI_API).mock(return_value=httpx.Response(
-        200,
-        json={"query": {"pages": [{
-            "pageid": 1,
-            "title": "James Buchanan",
-            "extract": "James Buchanan was the 15th president of the United States.",
-        }]}},
-    ))
+    respx.get(WIKI_API).mock(
+        return_value=httpx.Response(
+            200,
+            json={
+                "query": {
+                    "pages": [
+                        {
+                            "pageid": 1,
+                            "title": "James Buchanan",
+                            "extract": "James Buchanan was the 15th president of the United States.",
+                        }
+                    ]
+                }
+            },
+        )
+    )
     fetcher = WikiFetcher(cache_dir=tmp_path, rate_limit_rps=100)  # disable throttle
     article = await fetcher.fetch("https://en.wikipedia.org/wiki/James_Buchanan")
     assert article is not None
@@ -83,13 +91,21 @@ async def test_fetch_success_writes_markdown(tmp_path: Path) -> None:
 @pytest.mark.asyncio
 @respx.mock
 async def test_fetch_missing_page_returns_none(tmp_path: Path) -> None:
-    respx.get(WIKI_API).mock(return_value=httpx.Response(
-        200,
-        json={"query": {"pages": [{
-            "title": "DoesNotExist",
-            "missing": True,
-        }]}},
-    ))
+    respx.get(WIKI_API).mock(
+        return_value=httpx.Response(
+            200,
+            json={
+                "query": {
+                    "pages": [
+                        {
+                            "title": "DoesNotExist",
+                            "missing": True,
+                        }
+                    ]
+                }
+            },
+        )
+    )
     fetcher = WikiFetcher(cache_dir=tmp_path, rate_limit_rps=100)
     article = await fetcher.fetch("https://en.wikipedia.org/wiki/DoesNotExist")
     assert article is None
diff --git a/surfsense_evals/tests/suites/test_mmlongbench_grader.py b/surfsense_evals/tests/suites/test_mmlongbench_grader.py
index 92cd5f0cb..89005b3cd 100644
--- a/surfsense_evals/tests/suites/test_mmlongbench_grader.py
+++ b/surfsense_evals/tests/suites/test_mmlongbench_grader.py
@@ -99,7 +99,9 @@ class TestListFormat:
         assert 0.0 < r.f1 < 1.0
 
     def test_extra_items_lower_precision(self) -> None:
-        r = grade(pred="apple, banana, cherry, date", gold="apple, banana, cherry", answer_format="List")
+        r = grade(
+            pred="apple, banana, cherry, date", gold="apple, banana, cherry", answer_format="List"
+        )
         assert 0.0 < r.f1 < 1.0
         # Recall=1, precision=3/4 → F1 ~= 0.857
         assert r.f1 == pytest.approx(2 * (3 / 4) * 1 / (3 / 4 + 1), rel=1e-3)
diff --git a/surfsense_mcp/mcp_server/features/knowledge_base/__init__.py b/surfsense_mcp/mcp_server/features/knowledge_base/__init__.py
index 1a971bfe4..323fb4e48 100644
--- a/surfsense_mcp/mcp_server/features/knowledge_base/__init__.py
+++ b/surfsense_mcp/mcp_server/features/knowledge_base/__init__.py
@@ -14,9 +14,7 @@ from ...core.workspace_context import WorkspaceContext
 from . import document_tools, search_tools
 
 
-def register(
-    mcp: FastMCP, client: SurfSenseClient, context: WorkspaceContext
-) -> None:
+def register(mcp: FastMCP, client: SurfSenseClient, context: WorkspaceContext) -> None:
     """Register every knowledge-base tool on the server."""
     search_tools.register(mcp, client, context)
     document_tools.register(mcp, client, context)
diff --git a/surfsense_mcp/mcp_server/features/knowledge_base/document_tools.py b/surfsense_mcp/mcp_server/features/knowledge_base/document_tools.py
index 497a2526c..f2cc20f9e 100644
--- a/surfsense_mcp/mcp_server/features/knowledge_base/document_tools.py
+++ b/surfsense_mcp/mcp_server/features/knowledge_base/document_tools.py
@@ -20,9 +20,7 @@ from .annotations import DELETE, WRITE, DocumentId
 from .note_ingestion import build_note_document
 
 
-def register(
-    mcp: FastMCP, client: SurfSenseClient, context: WorkspaceContext
-) -> None:
+def register(mcp: FastMCP, client: SurfSenseClient, context: WorkspaceContext) -> None:
     """Register the knowledge-base write and delete tools."""
 
     @mcp.tool(
@@ -136,8 +134,7 @@ def register(
             str,
             Field(
                 min_length=1,
-                description="New full text; replaces the existing content "
-                "entirely.",
+                description="New full text; replaces the existing content entirely.",
             ),
         ],
     ) -> str:
diff --git a/surfsense_mcp/mcp_server/features/knowledge_base/search_tools.py b/surfsense_mcp/mcp_server/features/knowledge_base/search_tools.py
index a9e60810d..c0f7f83a9 100644
--- a/surfsense_mcp/mcp_server/features/knowledge_base/search_tools.py
+++ b/surfsense_mcp/mcp_server/features/knowledge_base/search_tools.py
@@ -17,9 +17,7 @@ from ...core.workspace_context import WorkspaceContext, WorkspaceParam
 from .annotations import READ, DocumentId, DocumentTypes
 
 
-def register(
-    mcp: FastMCP, client: SurfSenseClient, context: WorkspaceContext
-) -> None:
+def register(mcp: FastMCP, client: SurfSenseClient, context: WorkspaceContext) -> None:
     """Register the knowledge-base read tools."""
 
     @mcp.tool(
@@ -81,12 +79,8 @@ def register(
             int | None,
             Field(description="Only documents in this folder. Omit for all."),
         ] = None,
-        page: Annotated[
-            int, Field(ge=0, description="Zero-based page number.")
-        ] = 0,
-        page_size: Annotated[
-            int, Field(ge=1, description="Documents per page.")
-        ] = 20,
+        page: Annotated[int, Field(ge=0, description="Zero-based page number.")] = 0,
+        page_size: Annotated[int, Field(ge=1, description="Documents per page.")] = 20,
         workspace: WorkspaceParam = None,
         response_format: ResponseFormatParam = "markdown",
     ) -> str:
diff --git a/surfsense_mcp/mcp_server/features/scrapers/__init__.py b/surfsense_mcp/mcp_server/features/scrapers/__init__.py
index eb5f72ba5..9aabbe0e5 100644
--- a/surfsense_mcp/mcp_server/features/scrapers/__init__.py
+++ b/surfsense_mcp/mcp_server/features/scrapers/__init__.py
@@ -35,9 +35,7 @@ _REGISTRARS = (
 )
 
 
-def register(
-    mcp: FastMCP, client: SurfSenseClient, context: WorkspaceContext
-) -> None:
+def register(mcp: FastMCP, client: SurfSenseClient, context: WorkspaceContext) -> None:
     """Register every scraper and run-history tool on the server."""
     for module in _REGISTRARS:
         module.register(mcp, client, context)
diff --git a/surfsense_mcp/mcp_server/features/scrapers/capability.py b/surfsense_mcp/mcp_server/features/scrapers/capability.py
index 7245c9f84..82f24c6e7 100644
--- a/surfsense_mcp/mcp_server/features/scrapers/capability.py
+++ b/surfsense_mcp/mcp_server/features/scrapers/capability.py
@@ -38,9 +38,7 @@ async def run_scraper(
     return _render_markdown(platform, verb, resolved.name, result)
 
 
-def _render_markdown(
-    platform: str, verb: str, workspace_name: str, result: Any
-) -> str:
+def _render_markdown(platform: str, verb: str, workspace_name: str, result: Any) -> str:
     """A readable header plus the structured payload, clipped to a safe size."""
     header = f'# {platform}.{verb} — {_describe_size(result)} from "{workspace_name}"'
     body = clip(to_json(result))
diff --git a/surfsense_mcp/mcp_server/features/scrapers/platforms/google_maps.py b/surfsense_mcp/mcp_server/features/scrapers/platforms/google_maps.py
index e1613ca4e..daa27cef2 100644
--- a/surfsense_mcp/mcp_server/features/scrapers/platforms/google_maps.py
+++ b/surfsense_mcp/mcp_server/features/scrapers/platforms/google_maps.py
@@ -16,9 +16,7 @@ from ..capability import run_scraper
 ReviewSort = Literal["newest", "mostRelevant", "highestRanking", "lowestRanking"]
 
 
-def register(
-    mcp: FastMCP, client: SurfSenseClient, context: WorkspaceContext
-) -> None:
+def register(mcp: FastMCP, client: SurfSenseClient, context: WorkspaceContext) -> None:
     """Register the Google Maps place and review tools."""
 
     @mcp.tool(
@@ -45,10 +43,7 @@ def register(
         ] = None,
         location: Annotated[
             str | None,
-            Field(
-                description="Geographic scope for a search, e.g. "
-                "'Seattle, USA'."
-            ),
+            Field(description="Geographic scope for a search, e.g. 'Seattle, USA'."),
         ] = None,
         max_places: Annotated[
             int, Field(ge=1, description="Maximum places to return.")
@@ -56,8 +51,7 @@ def register(
         include_details: Annotated[
             bool,
             Field(
-                description="True adds opening hours and extra contact info "
-                "(slower)."
+                description="True adds opening hours and extra contact info (slower)."
             ),
         ] = False,
         workspace: WorkspaceParam = None,
@@ -96,16 +90,11 @@ def register(
     async def google_maps_reviews(
         urls: Annotated[
             list[str] | None,
-            Field(
-                description="Google Maps URLs of places. Provide urls OR "
-                "place_ids."
-            ),
+            Field(description="Google Maps URLs of places. Provide urls OR place_ids."),
         ] = None,
         place_ids: Annotated[
             list[str] | None,
-            Field(
-                description="Google place ids from surfsense_google_maps_scrape."
-            ),
+            Field(description="Google place ids from surfsense_google_maps_scrape."),
         ] = None,
         max_reviews: Annotated[
             int, Field(ge=1, description="Maximum reviews per place.")
diff --git a/surfsense_mcp/mcp_server/features/scrapers/platforms/google_search.py b/surfsense_mcp/mcp_server/features/scrapers/platforms/google_search.py
index cc1a1f8ed..acabef1d1 100644
--- a/surfsense_mcp/mcp_server/features/scrapers/platforms/google_search.py
+++ b/surfsense_mcp/mcp_server/features/scrapers/platforms/google_search.py
@@ -14,9 +14,7 @@ from ..annotations import SCRAPE
 from ..capability import run_scraper
 
 
-def register(
-    mcp: FastMCP, client: SurfSenseClient, context: WorkspaceContext
-) -> None:
+def register(mcp: FastMCP, client: SurfSenseClient, context: WorkspaceContext) -> None:
     """Register the Google Search tool."""
 
     @mcp.tool(
@@ -46,9 +44,7 @@ def register(
         ] = "",
         site: Annotated[
             str | None,
-            Field(
-                description="Restrict results to one domain, e.g. 'example.com'."
-            ),
+            Field(description="Restrict results to one domain, e.g. 'example.com'."),
         ] = None,
         workspace: WorkspaceParam = None,
         response_format: ResponseFormatParam = "markdown",
diff --git a/surfsense_mcp/mcp_server/features/scrapers/platforms/instagram.py b/surfsense_mcp/mcp_server/features/scrapers/platforms/instagram.py
index 28ad34e66..62e7552d6 100644
--- a/surfsense_mcp/mcp_server/features/scrapers/platforms/instagram.py
+++ b/surfsense_mcp/mcp_server/features/scrapers/platforms/instagram.py
@@ -17,9 +17,7 @@ ResultType = Literal["posts", "reels"]
 SearchType = Literal["profile", "user"]
 
 
-def register(
-    mcp: FastMCP, client: SurfSenseClient, context: WorkspaceContext
-) -> None:
+def register(mcp: FastMCP, client: SurfSenseClient, context: WorkspaceContext) -> None:
     """Register the Instagram scrape and details tools (anonymous-only)."""
 
     @mcp.tool(
@@ -41,7 +39,9 @@ def register(
             list[str] | None,
             Field(
                 description="Terms to discover public profiles for (resolved via "
-                "Google). Provide search_queries OR urls."
+                "Google). Google-backed discovery is slow (~30-60s per query), so "
+                "start with at most 3 queries and expand only if nothing "
+                "significant is found. Provide search_queries OR urls."
             ),
         ] = None,
         search_type: Annotated[
@@ -100,7 +100,9 @@ def register(
         search_queries: Annotated[
             list[str] | None,
             Field(
-                description="Terms to discover public profiles for. Provide "
+                description="Terms to discover public profiles for. Google-backed "
+                "discovery is slow (~30-60s per query), so start with at most 3 "
+                "queries and expand only if nothing significant is found. Provide "
                 "search_queries OR urls."
             ),
         ] = None,
diff --git a/surfsense_mcp/mcp_server/features/scrapers/platforms/reddit.py b/surfsense_mcp/mcp_server/features/scrapers/platforms/reddit.py
index 035193ebc..1bc2d851e 100644
--- a/surfsense_mcp/mcp_server/features/scrapers/platforms/reddit.py
+++ b/surfsense_mcp/mcp_server/features/scrapers/platforms/reddit.py
@@ -17,9 +17,7 @@ RedditSort = Literal["relevance", "hot", "top", "new", "rising", "comments"]
 RedditTime = Literal["hour", "day", "week", "month", "year", "all"]
 
 
-def register(
-    mcp: FastMCP, client: SurfSenseClient, context: WorkspaceContext
-) -> None:
+def register(mcp: FastMCP, client: SurfSenseClient, context: WorkspaceContext) -> None:
     """Register the Reddit tool."""
 
     @mcp.tool(
diff --git a/surfsense_mcp/mcp_server/features/scrapers/platforms/tiktok.py b/surfsense_mcp/mcp_server/features/scrapers/platforms/tiktok.py
index c295ec3b6..620936063 100644
--- a/surfsense_mcp/mcp_server/features/scrapers/platforms/tiktok.py
+++ b/surfsense_mcp/mcp_server/features/scrapers/platforms/tiktok.py
@@ -14,9 +14,7 @@ from ..annotations import SCRAPE
 from ..capability import run_scraper
 
 
-def register(
-    mcp: FastMCP, client: SurfSenseClient, context: WorkspaceContext
-) -> None:
+def register(mcp: FastMCP, client: SurfSenseClient, context: WorkspaceContext) -> None:
     """Register the TikTok tools."""
 
     @mcp.tool(
@@ -32,7 +30,7 @@ def register(
                 description="TikTok URLs: a video, a profile "
                 "('https://www.tiktok.com/@nasa'), a hashtag "
                 "('https://www.tiktok.com/tag/food'), or a search URL. Provide "
-                "urls OR profiles/hashtags/search_queries."
+                "urls OR profiles/hashtags."
             ),
         ] = None,
         profiles: Annotated[
@@ -45,21 +43,12 @@ def register(
         hashtags: Annotated[
             list[str] | None,
             Field(
-                description="Hashtag names to scrape, without the '#', e.g. "
-                "['food']."
-            ),
-        ] = None,
-        search_queries: Annotated[
-            list[str] | None,
-            Field(
-                description="Keyword search terms. Returns no videos — use "
-                "hashtags/profiles/urls for videos, or the user-search tool for "
-                "accounts."
+                description="Hashtag names to scrape, without the '#', e.g. ['food']."
             ),
         ] = None,
         results_per_page: Annotated[
             int,
-            Field(ge=1, description="Max videos per profile/hashtag/search target."),
+            Field(ge=1, description="Max videos per profile/hashtag target."),
         ] = 10,
         max_items: Annotated[
             int, Field(ge=1, description="Maximum videos to return in total.")
@@ -71,9 +60,9 @@ def register(
 
         Use for TikTok video research — a creator's videos, a hashtag feed, or a
         specific video/profile/hashtag URL — instead of a generic web search.
-        Returns videos with text, author, stats, music, and the web URL. For
-        accounts by keyword use the user-search tool; keyword search returns no
-        videos. Example: hashtags=['food'], max_items=20.
+        Returns videos with text, author, stats, music, and the web URL. There is
+        no keyword-video search; for accounts by keyword use
+        surfsense_tiktok_user_search. Example: hashtags=['food'], max_items=20.
         """
         return await run_scraper(
             client,
@@ -84,7 +73,6 @@ def register(
                 "urls": urls,
                 "profiles": profiles,
                 "hashtags": hashtags,
-                "search_queries": search_queries,
                 "results_per_page": results_per_page,
                 "max_items": max_items,
             },
diff --git a/surfsense_mcp/mcp_server/features/scrapers/platforms/web.py b/surfsense_mcp/mcp_server/features/scrapers/platforms/web.py
index 9c24a4352..8c6faaaf3 100644
--- a/surfsense_mcp/mcp_server/features/scrapers/platforms/web.py
+++ b/surfsense_mcp/mcp_server/features/scrapers/platforms/web.py
@@ -14,9 +14,7 @@ from ..annotations import SCRAPE
 from ..capability import run_scraper
 
 
-def register(
-    mcp: FastMCP, client: SurfSenseClient, context: WorkspaceContext
-) -> None:
+def register(mcp: FastMCP, client: SurfSenseClient, context: WorkspaceContext) -> None:
     """Register the web crawl tool."""
 
     @mcp.tool(
diff --git a/surfsense_mcp/mcp_server/features/scrapers/platforms/youtube.py b/surfsense_mcp/mcp_server/features/scrapers/platforms/youtube.py
index 5582c82bb..1871fe711 100644
--- a/surfsense_mcp/mcp_server/features/scrapers/platforms/youtube.py
+++ b/surfsense_mcp/mcp_server/features/scrapers/platforms/youtube.py
@@ -16,9 +16,7 @@ from ..capability import run_scraper
 CommentSort = Literal["TOP_COMMENTS", "NEWEST_FIRST"]
 
 
-def register(
-    mcp: FastMCP, client: SurfSenseClient, context: WorkspaceContext
-) -> None:
+def register(mcp: FastMCP, client: SurfSenseClient, context: WorkspaceContext) -> None:
     """Register the YouTube video and comment tools."""
 
     @mcp.tool(
diff --git a/surfsense_mcp/mcp_server/features/scrapers/run_history.py b/surfsense_mcp/mcp_server/features/scrapers/run_history.py
index 9274a1a69..ed36cfca6 100644
--- a/surfsense_mcp/mcp_server/features/scrapers/run_history.py
+++ b/surfsense_mcp/mcp_server/features/scrapers/run_history.py
@@ -17,9 +17,7 @@ from ...core.workspace_context import WorkspaceContext, WorkspaceParam
 from .annotations import READ_RUNS
 
 
-def register(
-    mcp: FastMCP, client: SurfSenseClient, context: WorkspaceContext
-) -> None:
+def register(mcp: FastMCP, client: SurfSenseClient, context: WorkspaceContext) -> None:
     """Register the run-history tools."""
 
     @mcp.tool(
@@ -29,9 +27,7 @@ def register(
         structured_output=False,
     )
     async def list_scraper_runs(
-        limit: Annotated[
-            int, Field(ge=1, description="Maximum runs to list.")
-        ] = 20,
+        limit: Annotated[int, Field(ge=1, description="Maximum runs to list.")] = 20,
         capability: Annotated[
             str | None,
             Field(
diff --git a/surfsense_web/app/dashboard/[workspace_id]/new-chat/[[...chat_id]]/page.tsx b/surfsense_web/app/dashboard/[workspace_id]/new-chat/[[...chat_id]]/page.tsx
index 4bb355049..f5b857ce1 100644
--- a/surfsense_web/app/dashboard/[workspace_id]/new-chat/[[...chat_id]]/page.tsx
+++ b/surfsense_web/app/dashboard/[workspace_id]/new-chat/[[...chat_id]]/page.tsx
@@ -7,14 +7,11 @@ import {
 	useExternalStoreRuntime,
 } from "@assistant-ui/react";
 import { useQueryClient } from "@tanstack/react-query";
-import { useAtomValue, useSetAtom, useStore } from "jotai";
+import { useAtomValue, useSetAtom } from "jotai";
 import dynamic from "next/dynamic";
 import { useParams } from "next/navigation";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { toast } from "sonner";
-import { z } from "zod";
-import { agentFlagsAtom } from "@/atoms/agent/agent-flags-query.atom";
-import { disabledToolsAtom } from "@/atoms/agent-tools/agent-tools.atoms";
 import {
 	clearTargetCommentIdAtom,
 	currentThreadAtom,
@@ -22,24 +19,15 @@ import {
 	setTargetCommentIdAtom,
 } from "@/atoms/chat/current-thread.atom";
 import {
-	deriveMentionedPayload,
 	type MentionedDocumentInfo,
 	mentionedDocumentsAtom,
 	messageDocumentsMapAtom,
-	submittedMentionsAtom,
 } from "@/atoms/chat/mentioned-documents.atom";
-import { pendingUserImageDataUrlsAtom } from "@/atoms/chat/pending-user-images.atom";
-import {
-	clearPlanOwnerRegistry,
-	// extractWriteTodosFromContent,
-} from "@/atoms/chat/plan-state.atom";
-import { setPremiumAlertForThreadAtom } from "@/atoms/chat/premium-alert.atom";
+import { clearPlanOwnerRegistry } from "@/atoms/chat/plan-state.atom";
 import { closeReportPanelAtom } from "@/atoms/chat/report-panel.atom";
-import { type AgentCreatedDocument, agentCreatedDocumentsAtom } from "@/atoms/documents/ui.atoms";
 import { closeEditorPanelAtom } from "@/atoms/editor/editor-panel.atom";
 import { membersAtom } from "@/atoms/members/members-query.atoms";
-import { removeChatTabAtom, syncChatTabAtom, updateChatTabTitleAtom } from "@/atoms/tabs/tabs.atom";
-import { currentUserAtom } from "@/atoms/user/user-query.atoms";
+import { removeChatTabAtom, syncChatTabAtom } from "@/atoms/tabs/tabs.atom";
 import {
 	EditMessageDialog,
 	type EditMessageDialogChoice,
@@ -47,7 +35,6 @@ import {
 import { StepSeparatorDataUI } from "@/components/assistant-ui/step-separator";
 import { Thread } from "@/components/assistant-ui/thread";
 import {
-	createTokenUsageStore,
 	type TokenUsageData,
 	TokenUsageProvider,
 } from "@/components/assistant-ui/token-usage-context";
@@ -60,64 +47,31 @@ import {
 	type PendingInterruptState,
 } from "@/features/chat-messages/hitl";
 import { TimelineDataUI } from "@/features/chat-messages/timeline";
-import {
-	applyActionLogSse,
-	applyActionLogUpdatedSse,
-	markActionRevertedInCache,
-	useAgentActionsQuery,
-} from "@/hooks/use-agent-actions-query";
+import { useAgentActionsQuery } from "@/hooks/use-agent-actions-query";
 import { useChatSessionStateSync } from "@/hooks/use-chat-session-state";
 import { useMessagesSync } from "@/hooks/use-messages-sync";
 import { useThreadDetail, useThreadMessages } from "@/hooks/use-thread-queries";
-import { getAgentFilesystemSelection } from "@/lib/agent-filesystem";
 import { documentsApiService } from "@/lib/apis/documents-api.service";
-import { authenticatedFetch } from "@/lib/auth-fetch";
-import { type ChatFlow, classifyChatError } from "@/lib/chat/chat-error-classifier";
-import { tagPreAcceptSendFailure, toHttpResponseError } from "@/lib/chat/chat-request-errors";
-import { getMentionDocKey } from "@/lib/chat/mention-doc-key";
 import {
 	convertToThreadMessage,
 	reconcileInterruptedAssistantMessages,
 } from "@/lib/chat/message-utils";
-import { createStreamFlushHelpers } from "@/lib/chat/stream-flush";
-import { consumeSseEvents, processSharedStreamEvent } from "@/lib/chat/stream-pipeline";
 import {
-	applyTurnIdToAssistantMessageList,
-	mergeChatTurnIdIntoMessage,
-	readStreamedChatTurnId,
-	readStreamedMessageId,
-} from "@/lib/chat/stream-side-effects";
-import {
-	addToolCall,
-	buildContentForUI,
-	type ContentPartsState,
-	type FrameBatchedUpdater,
-	type ThinkingStepData,
-	type ToolUIGate,
-	updateToolCall,
-} from "@/lib/chat/streaming-state";
-import {
-	appendMessage,
-	createThread,
-	getRegenerateUrl,
-	type ThreadListItem,
-	type ThreadListResponse,
-	type ThreadRecord,
-} from "@/lib/chat/thread-persistence";
+	cancelActiveTurn,
+	type EngineContext,
+	regenerateChat,
+	resumeChat,
+	startNewChat,
+} from "@/lib/chat/stream-engine/engine";
+import { extractMentionedDocuments } from "@/lib/chat/stream-engine/helpers";
+import { chatStreamStore } from "@/lib/chat/stream-engine/store";
+import { useChatStream } from "@/lib/chat/stream-engine/use-chat-stream";
+import type { ThreadRecord } from "@/lib/chat/thread-persistence";
 import {
 	extractUserTurnForNewChatApi,
 	type NewChatUserImagePayload,
 } from "@/lib/chat/user-turn-api-parts";
-import { buildBackendUrl } from "@/lib/env-config";
 import { NotFoundError } from "@/lib/error";
-import {
-	trackChatBlocked,
-	trackChatCreated,
-	trackChatErrorDetailed,
-	trackChatMessageSent,
-	trackChatResponseReceived,
-} from "@/lib/posthog/events";
-import { cacheKeys } from "@/lib/query-client/cache-keys";
 
 const MobileEditorPanel = dynamic(
 	() =>
@@ -148,156 +102,8 @@ const MobileArtifactsPanel = dynamic(
 	{ ssr: false }
 );
 
-/**
- * Generate a synthetic ``toolCallId`` for an action_request that has no
- * matching streamed tool-call card (HITL-blocked subagent calls don't surface
- * as tool-call events). Suffixes a counter when the base id is already taken
- * — sequential interrupts for the same tool name otherwise collide on
- * ``interrupt-${name}-${i}`` and crash assistant-ui with a duplicate-key error.
- */
-function freshSynthToolCallId(
-	toolCallIndices: Map<string, number>,
-	toolName: string,
-	index: number
-): string {
-	const base = `interrupt-${toolName}-${index}`;
-	if (!toolCallIndices.has(base)) return base;
-	let n = 1;
-	while (toolCallIndices.has(`${base}-${n}`)) n++;
-	return `${base}-${n}`;
-}
-
-/**
- * Pair each ``action_request`` to a unique pending tool-call card, preserving
- * order so ``decisions[i]`` lines up with ``action_requests[i]`` on the wire.
- *
- * Same-name bundles (e.g. three ``create_jira_issue``) used to collapse onto
- * one card because the matcher keyed by name; this consumes each card via the
- * ``claimed`` set and walks forward in DOM order.
- */
-function pairBundleToolCallIds(
-	toolCallIndices: Map<string, number>,
-	contentParts: Array<{
-		type: string;
-		toolName?: string;
-		result?: unknown;
-	}>,
-	actionRequests: ReadonlyArray<{ name: string }>
-): Array<string | null> {
-	const claimed = new Set<string>();
-	const paired: Array<string | null> = [];
-	for (const action of actionRequests) {
-		let matched: string | null = null;
-		for (const [tcId, idx] of toolCallIndices) {
-			if (claimed.has(tcId)) continue;
-			const part = contentParts[idx];
-			if (!part || part.type !== "tool-call" || part.toolName !== action.name) continue;
-			const result = part.result as Record<string, unknown> | undefined | null;
-			if (result == null || (result.__interrupt__ === true && !result.__decided__)) {
-				matched = tcId;
-				claimed.add(tcId);
-				break;
-			}
-		}
-		paired.push(matched);
-	}
-	return paired;
-}
-
-/**
- * Zod schema for mentioned document info (for type-safe parsing).
- *
- * ``kind`` defaults to ``"doc"`` so messages persisted before folder
- * mentions existed deserialise unchanged.
- */
-const MentionedDocumentInfoSchema = z.object({
-	id: z.number(),
-	title: z.string(),
-	document_type: z.string().optional(),
-	kind: z
-		.union([z.literal("doc"), z.literal("folder"), z.literal("connector"), z.literal("thread")])
-		.optional()
-		.default("doc"),
-	connector_type: z.string().optional(),
-	account_name: z.string().optional(),
-});
-
-const MentionedDocumentsPartSchema = z.object({
-	type: z.literal("mentioned-documents"),
-	documents: z.array(MentionedDocumentInfoSchema),
-});
-
-/**
- * Extract mentioned documents from message content (type-safe with Zod)
- */
-function extractMentionedDocuments(content: unknown): MentionedDocumentInfo[] {
-	if (!Array.isArray(content)) return [];
-
-	for (const part of content) {
-		const result = MentionedDocumentsPartSchema.safeParse(part);
-		if (result.success) {
-			return result.data.documents.map<MentionedDocumentInfo>((doc) => {
-				if (doc.kind === "connector") {
-					return {
-						id: doc.id,
-						title: doc.title,
-						kind: "connector",
-						connector_type: doc.connector_type ?? doc.document_type ?? "UNKNOWN",
-						account_name: doc.account_name ?? doc.title,
-					};
-				}
-				if (doc.kind === "folder") {
-					return {
-						id: doc.id,
-						title: doc.title,
-						kind: "folder",
-					};
-				}
-				if (doc.kind === "thread") {
-					return {
-						id: doc.id,
-						title: doc.title,
-						kind: "thread",
-					};
-				}
-				return {
-					id: doc.id,
-					title: doc.title,
-					document_type: doc.document_type ?? "UNKNOWN",
-					kind: "doc",
-				};
-			});
-		}
-	}
-
-	return [];
-}
-
-/**
- * Every tool call renders a card. The legacy
- * ``BASE_TOOLS_WITH_UI`` allowlist used to drop unknown tool calls on the
- * floor; we now route everything through ``ToolFallback``. Persisted
- * payload size stays bounded because the backend's
- * ``format_thinking_step`` summarisation and the
- * ``result_length``-only default for unknown tools (see
- * ``stream_new_chat.py``) keep the JSON from ballooning.
- */
-const TOOLS_WITH_UI_ALL: ToolUIGate = "all";
-const TURN_CANCELLING_INITIAL_DELAY_MS = 200;
-const TURN_CANCELLING_BACKOFF_FACTOR = 2;
-const TURN_CANCELLING_MAX_DELAY_MS = 1500;
-const RECENT_CANCEL_WINDOW_MS = 5_000;
-
-function sleep(ms: number): Promise<void> {
-	return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-function computeFallbackTurnCancellingRetryDelay(attempt: number): number {
-	const safeAttempt = Math.max(1, attempt);
-	const raw =
-		TURN_CANCELLING_INITIAL_DELAY_MS * TURN_CANCELLING_BACKOFF_FACTOR ** (safeAttempt - 1);
-	return Math.min(raw, TURN_CANCELLING_MAX_DELAY_MS);
-}
+/** Stable empty reference so idle threads don't re-render the interrupt provider. */
+const EMPTY_PENDING_INTERRUPTS: PendingInterruptState[] = [];
 
 function parseUrlChatId(id: string | string[] | undefined): number {
 	let parsed = 0;
@@ -372,103 +178,37 @@ export default function NewChatPage() {
 	const activeThreadId = urlChatId > 0 ? urlChatId : threadId;
 	const handledLoadErrorThreadRef = useRef<number | null>(null);
 	const [currentThread, setCurrentThread] = useState<ThreadRecord | null>(null);
+	// DB-hydrated messages for the viewed thread (idle display). While a turn
+	// is streaming, the live overlay in ``chatStreamStore`` takes precedence
+	// (see ``displayMessages``) so it survives this page unmounting on nav.
 	const [messages, setMessages] = useState<ThreadMessageLike[]>([]);
-	const [isRunning, setIsRunning] = useState(false);
-	const [tokenUsageStore] = useState(() => createTokenUsageStore());
-	const abortControllerRef = useRef<AbortController | null>(null);
-	const recentCancelRequestedAtRef = useRef(0);
-	// One entry per paused subagent, in receipt order (which matches the
-	// backend's ``state.interrupts`` traversal — and therefore the order
-	// ``slice_decisions_by_tool_call`` consumes on resume). Cleared on submit
-	// or on a fresh user turn.
-	const [pendingInterrupts, setPendingInterrupts] = useState<PendingInterruptState[]>([]);
-	// Per-card staged decisions held until every pending card has submitted,
-	// at which point we batch them into one ``hitl-decision`` event in the
-	// same order as ``pendingInterrupts``. Using a ref because partial
-	// progress should not re-render the page.
-	const stagedDecisionsByInterruptIdRef = useRef<Map<string, HitlDecision[]>>(new Map());
-	const toolsWithUI = TOOLS_WITH_UI_ALL;
+
+	// Durable, cross-navigation streaming state for the viewed thread.
+	const streamState = useChatStream(activeThreadId);
+	const isRunning = streamState?.isRunning ?? false;
+	const pendingInterrupts = streamState?.pendingInterrupts ?? EMPTY_PENDING_INTERRUPTS;
+	// Live overlay while a turn is streaming / awaiting HITL; DB-hydrated
+	// messages once the overlay is cleared (the hydration effect drops it only
+	// after the DB catches up, so there is no finish->refetch gap).
+	const displayMessages = streamState ? streamState.messages : messages;
+
+	// One shared token-usage store, alive across navigation.
+	const tokenUsageStore = chatStreamStore.tokenUsage;
+
 	const setMessageDocumentsMap = useSetAtom(messageDocumentsMapAtom);
-
-	const persistAssistantErrorMessage = useCallback(
-		async ({
-			threadId,
-			assistantMsgId,
-			text,
-		}: {
-			threadId: number | null;
-			assistantMsgId: string;
-			text: string;
-		}) => {
-			setMessages((prev) =>
-				prev.map((m) =>
-					m.id === assistantMsgId
-						? {
-								...m,
-								content: [{ type: "text", text }],
-							}
-						: m
-				)
-			);
-
-			if (!threadId) return;
-
-			// Persist only temporary assistant placeholders to avoid duplicate rows
-			// when the message already has a database-backed ID.
-			if (!assistantMsgId.startsWith("msg-assistant-")) return;
-
-			try {
-				const savedMessage = await appendMessage(threadId, {
-					role: "assistant",
-					content: [{ type: "text", text }],
-				});
-				const newMsgId = `msg-${savedMessage.id}`;
-				tokenUsageStore.rename(assistantMsgId, newMsgId);
-				setMessages((prev) =>
-					prev.map((m) => (m.id === assistantMsgId ? { ...m, id: newMsgId } : m))
-				);
-			} catch (persistErr) {
-				console.error("Failed to persist assistant error message:", persistErr);
-			}
-		},
-		[tokenUsageStore]
-	);
-
-	// NOTE: ``persistUserTurn`` / ``persistAssistantTurn`` callbacks
-	// were removed in the SSE-based message ID handshake refactor.
-	// ``stream_new_chat`` and ``stream_resume_chat`` now persist both
-	// the user and assistant rows server-side via
-	// ``persist_user_turn`` / ``persist_assistant_shell`` and emit
-	// ``data-user-message-id`` / ``data-assistant-message-id`` SSE
-	// events; the consumers below rename the optimistic ids in real
-	// time. ``persistAssistantErrorMessage`` (above) is intentionally
-	// kept — it is the pre-stream-error fallback fired when the
-	// server NEVER accepted the request, and the BE has nothing to
-	// persist in that case.
-
-	// Get disabled tools from the tool toggle UI
-	const disabledTools = useAtomValue(disabledToolsAtom);
-
-	const jotaiStore = useStore();
-	const mentionedDocuments = useAtomValue(mentionedDocumentsAtom);
-	const messageDocumentsMap = useAtomValue(messageDocumentsMapAtom);
 	const setMentionedDocuments = useSetAtom(mentionedDocumentsAtom);
 	const currentThreadState = useAtomValue(currentThreadAtom);
 	const setCurrentThreadMetadata = useSetAtom(setCurrentThreadMetadataAtom);
-	const setPremiumAlertForThread = useSetAtom(setPremiumAlertForThreadAtom);
 	const setTargetCommentId = useSetAtom(setTargetCommentIdAtom);
 	const clearTargetCommentId = useSetAtom(clearTargetCommentIdAtom);
 	const closeReportPanel = useSetAtom(closeReportPanelAtom);
 	const closeEditorPanel = useSetAtom(closeEditorPanelAtom);
 	const syncChatTab = useSetAtom(syncChatTabAtom);
-	const updateChatTabTitle = useSetAtom(updateChatTabTitleAtom);
 	const removeChatTab = useSetAtom(removeChatTabAtom);
-	const setAgentCreatedDocuments = useSetAtom(agentCreatedDocumentsAtom);
-	const pendingUserImageUrls = useAtomValue(pendingUserImageDataUrlsAtom);
-	const setPendingUserImageUrls = useSetAtom(pendingUserImageDataUrlsAtom);
-	// Edit dialog state. Holds the message id being edited and
-	// the (already extracted) regenerate args so we can resume the edit
-	// after the user picks "revert all" / "continue" / "cancel".
+
+	// Edit dialog state. Holds the message id being edited and the (already
+	// extracted) regenerate args so we can resume the edit after the user picks
+	// "revert all" / "continue" / "cancel".
 	const [editDialogState, setEditDialogState] = useState<{
 		fromMessageId: number;
 		userQuery: string | null;
@@ -478,14 +218,17 @@ export default function NewChatPage() {
 		downstreamTotalCount: number;
 	} | null>(null);
 
-	// Get current user for author info in shared chats
-	const { data: currentUser } = useAtomValue(currentUserAtom);
-	const { data: agentFlags } = useAtomValue(agentFlagsAtom);
-	const localFilesystemEnabled = agentFlags?.enable_desktop_local_filesystem === true;
+	// Per-card staged decisions held until every pending card has submitted, at
+	// which point we batch them into one ``hitl-decision`` event in the same
+	// order as ``pendingInterrupts``. A ref because partial progress should not
+	// re-render the page.
+	const stagedDecisionsByInterruptIdRef = useRef<Map<string, HitlDecision[]>>(new Map());
+
 	const threadDetailQuery = useThreadDetail(activeThreadId);
 	const threadMessagesQuery = useThreadMessages(activeThreadId);
 
-	// Live collaboration: sync session state and messages via Zero
+	// Live collaboration: sync session state and messages via Zero. Kept on the
+	// page because "AI responding" reflects the currently-viewed thread.
 	useChatSessionStateSync(activeThreadId);
 	const { data: membersData } = useAtomValue(membersAtom);
 
@@ -498,10 +241,6 @@ export default function NewChatPage() {
 				content: unknown;
 				author_id: string | null;
 				created_at: string;
-				// Forwarded so ``convertToThreadMessage`` can rebuild the
-				// ``metadata.custom.chatTurnId`` on the
-				// ``ThreadMessageLike``. Required by the inline Revert
-				// button's per-turn fallback.
 				turn_id?: string | null;
 			}[]
 		) => {
@@ -520,7 +259,6 @@ export default function NewChatPage() {
 				return reconcileInterruptedAssistantMessages(syncedMessages).map((msg) => {
 					const member = msg.author_id ? (memberById.get(msg.author_id) ?? null) : null;
 
-					// Preserve existing author info if member lookup fails (e.g., cloned chats)
 					const existingMsg = prevById.get(`msg-${msg.id}`);
 					const existingAuthor = existingMsg?.metadata?.custom?.author as
 						| { displayName?: string | null; avatarUrl?: string | null }
@@ -535,10 +273,6 @@ export default function NewChatPage() {
 						created_at: msg.created_at,
 						author_display_name: member?.user_display_name ?? existingAuthor?.displayName ?? null,
 						author_avatar_url: member?.user_avatar_url ?? existingAuthor?.avatarUrl ?? null,
-						// Forward the per-turn correlation id so the
-						// inline Revert button's ``(chat_turn_id,
-						// tool_name, position)`` fallback survives the
-						// post-stream Zero re-sync.
 						turn_id: msg.turn_id ?? null,
 					});
 				});
@@ -556,169 +290,33 @@ export default function NewChatPage() {
 		return Number.isNaN(parsed) ? 0 : parsed;
 	}, [params.workspace_id]);
 
-	// Unified store for agent-action rows (the same react-query cache
-	// the agent-actions dialog, the inline Revert button, and the
-	// per-turn Revert button all read). Hydrates from
-	// ``GET /threads/{id}/actions`` and is updated incrementally by the
-	// SSE handlers + revert-batch results below — no atom side-channel.
+	// Unified store for agent-action rows (react-query cache). Used by the
+	// edit pre-flight to count reversible downstream actions.
 	const { items: agentActionItems } = useAgentActionsQuery(activeThreadId);
 
-	const handleChatFailure = useCallback(
-		async ({
-			error,
-			flow,
-			threadId,
-			assistantMsgId,
-		}: {
-			error: unknown;
-			flow: ChatFlow;
-			threadId: number | null;
-			assistantMsgId: string;
-		}) => {
-			const normalized = classifyChatError({
-				error,
-				flow,
-				context: {
-					workspaceId: workspaceId,
-					threadId,
-				},
-			});
+	// Latest displayed messages, read by the engine wrappers at call time so
+	// history/slice seeds stay fresh without re-creating the callbacks.
+	const messagesRef = useRef<ThreadMessageLike[]>(displayMessages);
+	messagesRef.current = displayMessages;
 
-			const logger =
-				normalized.severity === "error"
-					? console.error
-					: normalized.severity === "warn"
-						? console.warn
-						: console.info;
-			logger(`[NewChatPage] ${flow} ${normalized.kind}:`, error);
-
-			const telemetryPayload = {
-				flow,
-				kind: normalized.kind,
-				error_code: normalized.errorCode,
-				severity: normalized.severity,
-				is_expected: normalized.isExpected,
-				message: normalized.userMessage,
-			};
-			if (normalized.telemetryEvent === "chat_blocked") {
-				trackChatBlocked(workspaceId, threadId, telemetryPayload);
-			} else {
-				trackChatErrorDetailed(workspaceId, threadId, telemetryPayload);
-			}
-
-			if (normalized.channel === "silent") {
-				return;
-			}
-
-			if (normalized.channel === "pinned_inline") {
-				if (threadId) {
-					setPremiumAlertForThread({
-						threadId,
-						message: normalized.userMessage,
-						userId: currentUser?.id ?? null,
-					});
-				}
-				if (normalized.assistantMessage) {
-					await persistAssistantErrorMessage({
-						threadId,
-						assistantMsgId,
-						text: normalized.assistantMessage,
-					});
-				}
-				return;
-			}
-
-			if (normalized.channel === "inline") {
-				if (normalized.assistantMessage) {
-					await persistAssistantErrorMessage({
-						threadId,
-						assistantMsgId,
-						text: normalized.assistantMessage,
-					});
-				}
-				toast.error(normalized.userMessage);
-				return;
-			}
-
-			toast.error(normalized.userMessage);
-		},
-		[currentUser?.id, persistAssistantErrorMessage, workspaceId, setPremiumAlertForThread]
+	const buildCtx = useCallback(
+		(): EngineContext => ({
+			workspaceId,
+			threadId: activeThreadId,
+			priorMessages: messagesRef.current,
+			view: { setThreadId, setCurrentThread },
+		}),
+		[workspaceId, activeThreadId]
 	);
 
-	const handleStreamTerminalError = useCallback(
-		async ({
-			error,
-			flow,
-			threadId,
-			assistantMsgId,
-			accepted,
-			onAbort,
-			onPreAcceptFailure,
-			onAcceptedStreamError,
-		}: {
-			error: unknown;
-			flow: ChatFlow;
-			threadId: number | null;
-			assistantMsgId: string;
-			accepted: boolean;
-			onAbort?: () => Promise<void>;
-			onPreAcceptFailure?: () => Promise<void>;
-			onAcceptedStreamError?: () => Promise<void>;
-		}) => {
-			if (error instanceof Error && error.name === "AbortError") {
-				await onAbort?.();
-				return;
-			}
-
-			if (!accepted) {
-				await onPreAcceptFailure?.();
-			} else {
-				await onAcceptedStreamError?.();
-			}
-
-			await handleChatFailure({
-				error: !accepted ? tagPreAcceptSendFailure(error) : error,
-				flow,
-				threadId,
-				assistantMsgId: accepted ? assistantMsgId : "no-persist-assistant",
-			});
-		},
-		[handleChatFailure]
-	);
-
-	const fetchWithTurnCancellingRetry = useCallback(async (runFetch: () => Promise<Response>) => {
-		const maxAttempts = 4;
-		for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
-			const response = await runFetch();
-			if (response.ok) {
-				return response;
-			}
-			const error = await toHttpResponseError(response);
-			const withMeta = error as Error & { errorCode?: string; retryAfterMs?: number };
-			const isTurnCancelling = withMeta.errorCode === "TURN_CANCELLING";
-			const isRecentThreadBusyAfterCancel =
-				withMeta.errorCode === "THREAD_BUSY" &&
-				Date.now() - recentCancelRequestedAtRef.current <= RECENT_CANCEL_WINDOW_MS;
-			if ((isTurnCancelling || isRecentThreadBusyAfterCancel) && attempt < maxAttempts) {
-				const waitMs = withMeta.retryAfterMs ?? computeFallbackTurnCancellingRetryDelay(attempt);
-				await sleep(waitMs);
-				continue;
-			}
-			throw error;
-		}
-
-		throw Object.assign(new Error("Turn cancellation retry limit exceeded"), {
-			errorCode: "TURN_CANCELLING",
-		});
-	}, []);
-
 	const hydratedMessagesRef = useRef<{
 		threadId: number | null;
 		data: typeof threadMessagesQuery.data;
 	}>({ threadId: null, data: undefined });
 
-	// Reset thread-local runtime state on route/workspace changes. Data fetching
-	// is handled by React Query below so the chat shell can render immediately.
+	// Reset thread-local runtime state on route/workspace changes. The durable
+	// streaming overlay is preserved for any still-running thread (and the newly
+	// viewed thread) via ``clearInactive`` so an in-flight turn survives nav.
 	useEffect(() => {
 		const nextThreadId = urlChatId > 0 ? urlChatId : null;
 		handledLoadErrorThreadRef.current = null;
@@ -732,13 +330,11 @@ export default function NewChatPage() {
 		clearPlanOwnerRegistry();
 		closeReportPanel();
 		closeEditorPanel();
-		// Note: agent-action data is keyed by threadId in react-query so
-		// switching threads naturally swaps caches; no explicit reset.
+		chatStreamStore.clearInactive(nextThreadId);
 	}, [
 		urlChatId,
 		setMentionedDocuments,
 		setMessageDocumentsMap,
-		tokenUsageStore,
 		closeReportPanel,
 		closeEditorPanel,
 	]);
@@ -773,6 +369,7 @@ export default function NewChatPage() {
 			return;
 		}
 
+		// Per-thread gate: never overwrite the live overlay of a running turn.
 		if (isRunning) {
 			return;
 		}
@@ -800,13 +397,18 @@ export default function NewChatPage() {
 		}
 		setMessageDocumentsMap(restoredDocsMap);
 		hydratedMessagesRef.current = { threadId: activeThreadId, data: messagesResponse };
+
+		// The DB is now authoritative for this thread — drop the streaming
+		// overlay so we render DB messages (no-op while running / HITL-pending).
+		if (loadedMessages.length >= chatStreamStore.getMessages(activeThreadId).length) {
+			chatStreamStore.clear(activeThreadId);
+		}
 	}, [
 		activeThreadId,
 		isRunning,
 		messages.length,
 		setMessageDocumentsMap,
 		threadMessagesQuery.data,
-		tokenUsageStore,
 	]);
 
 	useEffect(() => {
@@ -838,8 +440,7 @@ export default function NewChatPage() {
 		threadMessagesQuery.error,
 	]);
 
-	// Prefetch document titles for @ mention picker
-	// Runs when user lands on page so data is ready when they type @
+	// Prefetch document titles for @ mention picker so data is ready on type.
 	useEffect(() => {
 		if (!workspaceId) return;
 
@@ -856,10 +457,7 @@ export default function NewChatPage() {
 		});
 	}, [workspaceId, queryClient]);
 
-	// Handle scroll to comment from URL query params (e.g., from inbox item click)
-	// Read from window.location.search inside the effect instead of subscribing via
-	// useSearchParams() — avoids re-rendering this heavy component tree on every
-	// unrelated query-string change. (Vercel Best Practice: rerender-defer-reads 5.2)
+	// Handle scroll to comment from URL query params (e.g., from inbox click).
 	useEffect(() => {
 		const readAndApplyCommentId = () => {
 			const params = new URLSearchParams(window.location.search);
@@ -874,10 +472,8 @@ export default function NewChatPage() {
 
 		readAndApplyCommentId();
 
-		// Also respond to SPA navigations (back/forward) that change the query string
 		window.addEventListener("popstate", readAndApplyCommentId);
 
-		// Cleanup on unmount or when navigating away
 		return () => {
 			window.removeEventListener("popstate", readAndApplyCommentId);
 			clearTargetCommentId();
@@ -919,934 +515,158 @@ export default function NewChatPage() {
 		setCurrentThreadMetadata,
 	]);
 
-	// Cleanup on unmount - abort any in-flight requests
-	useEffect(() => {
-		return () => {
-			if (abortControllerRef.current) {
-				abortControllerRef.current.abort();
-				abortControllerRef.current = null;
-			}
-		};
-	}, []);
-
-	// Cancel ongoing request
-	const cancelRun = useCallback(async () => {
-		if (threadId) {
-			try {
-				const response = await authenticatedFetch(
-					buildBackendUrl(`/api/v1/threads/${threadId}/cancel-active-turn`),
-					{
-						method: "POST",
-					}
-				);
-				if (response.ok) {
-					const payload = (await response.json()) as {
-						error_code?: string;
-					};
-					if (payload.error_code === "TURN_CANCELLING") {
-						recentCancelRequestedAtRef.current = Date.now();
-					}
-				}
-			} catch (error) {
-				console.warn("[NewChatPage] Failed to signal cancel-active-turn:", error);
-			}
-		}
-		if (abortControllerRef.current) {
-			abortControllerRef.current.abort();
-			abortControllerRef.current = null;
-		}
-		setIsRunning(false);
-	}, [threadId]);
-
 	// Handle new message from user
 	const onNew = useCallback(
+		(message: AppendMessage) => startNewChat(buildCtx(), message),
+		[buildCtx]
+	);
+
+	// Cancel the in-flight turn (targets the active stream's owner thread).
+	const onCancel = useCallback(async () => {
+		await cancelActiveTurn();
+	}, []);
+
+	// Convert message (pass through since already in correct format)
+	const convertMessage = useCallback(
+		(message: ThreadMessageLike): ThreadMessageLike => message,
+		[]
+	);
+
+	// Handle editing a message - truncates history and regenerates with new
+	// query. When ``message.sourceId`` is set we pin ``from_message_id`` so the
+	// backend rewinds to the right checkpoint, and prompt the user to revert /
+	// continue / cancel before regenerating.
+	const onEdit = useCallback(
 		async (message: AppendMessage) => {
-			// Abort any previous streaming request to prevent race conditions
-			// when user sends a second query while the first is still streaming
-			if (abortControllerRef.current) {
-				abortControllerRef.current.abort();
-				abortControllerRef.current = null;
+			const { userQuery, userImages } = extractUserTurnForNewChatApi(message, []);
+			const queryForApi = userQuery.trim();
+			if (!queryForApi && userImages.length === 0) {
+				toast.error("Cannot edit with empty message");
+				return;
 			}
 
-			// Prefer the submit-time snapshot; fall back to the live atom
-			// for the send-button path.
-			const submittedSnapshot = jotaiStore.get(submittedMentionsAtom);
-			jotaiStore.set(submittedMentionsAtom, null);
-			const activeMentions = submittedSnapshot ?? mentionedDocuments;
-			const mentionPayload = deriveMentionedPayload(activeMentions);
-			if (activeMentions.length > 0) {
-				setMentionedDocuments([]);
+			const userMessageContent = message.content as unknown as ThreadMessageLike["content"];
+
+			const sourceId = (message as { sourceId?: string }).sourceId;
+			const fromMessageId =
+				sourceId && /^msg-\d+$/.test(sourceId)
+					? Number.parseInt(sourceId.replace(/^msg-/, ""), 10)
+					: null;
+
+			if (fromMessageId == null) {
+				await regenerateChat(buildCtx(), queryForApi, {
+					userMessageContent,
+					userImages,
+					sourceUserMessageId: sourceId,
+				});
+				return;
 			}
 
-			const urlsSnapshot = [...pendingUserImageUrls];
-			const { userQuery, userImages } = extractUserTurnForNewChatApi(message, urlsSnapshot);
-
-			if (!userQuery.trim() && userImages.length === 0) return;
-
-			// Lazy thread creation: create thread on first message if it doesn't exist
-			let currentThreadId = threadId;
-			let isNewThread = false;
-			if (!currentThreadId) {
-				try {
-					const newThread = await createThread(workspaceId, "New Chat");
-					currentThreadId = newThread.id;
-					setThreadId(currentThreadId);
-					// Set currentThread so share button in header appears immediately
-					setCurrentThread(newThread);
-					queryClient.setQueryData(cacheKeys.threads.detail(newThread.id), newThread);
-					queryClient.setQueryData(cacheKeys.threads.messages(newThread.id), { messages: [] });
-
-					// Track chat creation
-					trackChatCreated(workspaceId, currentThreadId);
-
-					isNewThread = true;
-					// Update URL silently using browser API (not router.replace) to avoid
-					// interrupting the ongoing fetch/streaming with React navigation
-					window.history.replaceState(
-						null,
-						"",
-						`/dashboard/${workspaceId}/new-chat/${currentThreadId}`
-					);
-				} catch (error) {
-					console.error("[NewChatPage] Failed to create thread:", error);
-					await handleChatFailure({
-						error: tagPreAcceptSendFailure(error),
-						flow: "new",
-						threadId: currentThreadId,
-						assistantMsgId: "no-persist-assistant",
-					});
-					return;
+			const msgs = messagesRef.current;
+			const editedIndex = msgs.findIndex((m) => m.id === `msg-${fromMessageId}`);
+			let downstreamReversibleCount = 0;
+			let downstreamTotalCount = 0;
+			if (editedIndex >= 0) {
+				const downstream = msgs.slice(editedIndex + 1);
+				downstreamTotalCount = downstream.length;
+				const seenTurns = new Set<string>();
+				const downstreamTurnIds = new Set<string>();
+				for (const m of downstream) {
+					const meta = (m.metadata ?? {}) as { custom?: { chatTurnId?: string } };
+					const tid = meta.custom?.chatTurnId;
+					if (!tid || seenTurns.has(tid)) continue;
+					seenTurns.add(tid);
+					downstreamTurnIds.add(tid);
+				}
+				for (const a of agentActionItems) {
+					if (!a.chat_turn_id || !downstreamTurnIds.has(a.chat_turn_id)) continue;
+					if (
+						a.reversible &&
+						(a.reverted_by_action_id === null || a.reverted_by_action_id === undefined) &&
+						!a.is_revert_action &&
+						(a.error === null || a.error === undefined)
+					) {
+						downstreamReversibleCount += 1;
+					}
 				}
 			}
 
-			if (urlsSnapshot.length > 0) {
-				setPendingUserImageUrls((prev) => prev.filter((u) => !urlsSnapshot.includes(u)));
+			if (downstreamReversibleCount === 0) {
+				await regenerateChat(
+					buildCtx(),
+					queryForApi,
+					{ userMessageContent, userImages, sourceUserMessageId: sourceId },
+					{ fromMessageId, revertActions: false }
+				);
+				return;
 			}
 
-			// Add user message to state. Mutable because the SSE
-			// ``data-user-message-id`` handler (below) renames this
-			// optimistic id to the canonical ``msg-{db_id}`` once the
-			// backend's ``persist_user_turn`` resolves the row, and
-			// the in-stream flush / interrupt closures need to see
-			// the post-rename value via this live ``let`` binding.
-			let userMsgId = `msg-user-${Date.now()}`;
-
-			// Always include author metadata so the UI layer can decide visibility
-			const authorMetadata = currentUser
-				? {
-						custom: {
-							author: {
-								displayName: currentUser.display_name ?? null,
-								avatarUrl: currentUser.avatar_url ?? null,
-							},
-						},
-					}
-				: undefined;
-
-			const existingImageUrls = new Set(
-				message.content
-					.filter(
-						(p): p is { type: "image"; image: string } =>
-							typeof p === "object" &&
-							p !== null &&
-							"type" in p &&
-							p.type === "image" &&
-							"image" in p
-					)
-					.map((p) => p.image)
-			);
-			const extraImageParts = urlsSnapshot
-				.filter((u) => !existingImageUrls.has(u))
-				.map((image) => ({ type: "image" as const, image }));
-			const userDisplayContent = [...message.content, ...extraImageParts];
-
-			const userMessage: ThreadMessageLike = {
-				id: userMsgId,
-				role: "user",
-				content: userDisplayContent,
-				createdAt: new Date(),
-				metadata: authorMetadata,
-			};
-			setMessages((prev) => [...prev, userMessage]);
-
-			// Track message sent
-			trackChatMessageSent(workspaceId, currentThreadId, {
-				hasAttachments: userImages.length > 0,
-				hasMentionedDocuments:
-					mentionPayload.document_ids.length > 0 ||
-					mentionPayload.folder_ids.length > 0 ||
-					mentionPayload.connector_ids.length > 0,
-				messageLength: userQuery.length,
+			setEditDialogState({
+				fromMessageId,
+				userQuery: queryForApi,
+				userMessageContent,
+				userImages,
+				downstreamReversibleCount,
+				downstreamTotalCount,
 			});
+		},
+		[buildCtx, agentActionItems]
+	);
 
-			// Collect unique mention chips for display & persistence.
-			// The ``kind`` field is forwarded to the backend
-			// so the persisted ``mentioned-documents`` content part
-			// can render the correct chip type on reload.
-			const allMentionedDocs: MentionedDocumentInfo[] = [];
-			const seenDocKeys = new Set<string>();
-			for (const doc of activeMentions) {
-				const key = getMentionDocKey(doc);
-				if (seenDocKeys.has(key)) continue;
-				seenDocKeys.add(key);
-				allMentionedDocs.push(doc);
+	const handleApprovalSubmit = useCallback(
+		(interruptId: string, decisions: HitlDecision[]) => {
+			// Stage this card's decisions; only fire the resume once every pending
+			// card in the current turn has submitted, so the backend slicer sees a
+			// single concatenated decisions list.
+			stagedDecisionsByInterruptIdRef.current.set(interruptId, decisions);
+			if (stagedDecisionsByInterruptIdRef.current.size < pendingInterrupts.length) {
+				return;
 			}
-
-			if (allMentionedDocs.length > 0) {
-				setMessageDocumentsMap((prev) => ({
-					...prev,
-					[userMsgId]: allMentionedDocs,
-				}));
-			}
-
-			// Start streaming response
-			setIsRunning(true);
-			const controller = new AbortController();
-			abortControllerRef.current = controller;
-
-			// Prepare assistant message. Mutable for the same reason
-			// as ``userMsgId`` above — the ``data-assistant-message-id``
-			// SSE handler reassigns this once
-			// ``persist_assistant_shell`` returns its canonical id.
-			let assistantMsgId = `msg-assistant-${Date.now()}`;
-			const currentThinkingSteps = new Map<string, ThinkingStepData>();
-			const contentPartsState: ContentPartsState = {
-				contentParts: [],
-				currentTextPartIndex: -1,
-				currentReasoningPartIndex: -1,
-				toolCallIndices: new Map(),
-			};
-			const { contentParts } = contentPartsState;
-			let wasInterrupted = false;
-			let newAccepted = false;
-			let streamBatcher: FrameBatchedUpdater | null = null;
-
-			try {
-				const selection = await getAgentFilesystemSelection(workspaceId, {
-					localFilesystemEnabled,
-				});
-				if (
-					selection.filesystem_mode === "desktop_local_folder" &&
-					(!selection.local_filesystem_mounts || selection.local_filesystem_mounts.length === 0)
-				) {
-					toast.error("Select a local folder before using Local Folder mode.");
+			const ordered: HitlDecision[] = [];
+			for (const pi of pendingInterrupts) {
+				const staged = stagedDecisionsByInterruptIdRef.current.get(pi.interruptId);
+				if (!staged) {
 					return;
 				}
-
-				// Build message history for context
-				const messageHistory = messages
-					.filter((m) => m.role === "user" || m.role === "assistant")
-					.map((m) => {
-						let text = "";
-						for (const part of m.content) {
-							if (typeof part === "object" && part.type === "text" && "text" in part) {
-								text += part.text;
-							}
-						}
-						return { role: m.role, content: text };
-					})
-					.filter((m) => m.content.length > 0);
-
-				// Backend expects each mention kind in its own payload bucket.
-				const hasDocumentIds = mentionPayload.document_ids.length > 0;
-				const hasFolderIds = mentionPayload.folder_ids.length > 0;
-				const hasConnectorIds = mentionPayload.connector_ids.length > 0;
-				const hasThreadIds = mentionPayload.thread_ids.length > 0;
-
-				const response = await fetchWithTurnCancellingRetry(() =>
-					authenticatedFetch(buildBackendUrl("/api/v1/new_chat"), {
-						method: "POST",
-						headers: {
-							"Content-Type": "application/json",
-						},
-						body: JSON.stringify({
-							chat_id: currentThreadId,
-							user_query: userQuery.trim(),
-							workspace_id: workspaceId,
-							filesystem_mode: selection.filesystem_mode,
-							client_platform: selection.client_platform,
-							local_filesystem_mounts: selection.local_filesystem_mounts,
-							messages: messageHistory,
-							mentioned_document_ids: hasDocumentIds ? mentionPayload.document_ids : undefined,
-							mentioned_folder_ids: hasFolderIds ? mentionPayload.folder_ids : undefined,
-							mentioned_connector_ids: hasConnectorIds ? mentionPayload.connector_ids : undefined,
-							mentioned_connectors: hasConnectorIds ? mentionPayload.connectors : undefined,
-							mentioned_thread_ids: hasThreadIds ? mentionPayload.thread_ids : undefined,
-							// Full mention metadata so the backend can persist a
-							// ``mentioned-documents`` ContentPart on the user message.
-							mentioned_documents: allMentionedDocs.length > 0 ? allMentionedDocs : undefined,
-							disabled_tools: disabledTools.length > 0 ? disabledTools : undefined,
-							...(userImages.length > 0 ? { user_images: userImages } : {}),
-						}),
-						signal: controller.signal,
-					})
-				);
-
-				if (!response.ok) {
-					throw await toHttpResponseError(response);
-				}
-				newAccepted = true;
-				setMessages((prev) => [
-					...prev,
-					{
-						id: assistantMsgId,
-						role: "assistant",
-						content: [{ type: "text", text: "" }],
-						createdAt: new Date(),
-					},
-				]);
-
-				const flushMessages = () => {
-					setMessages((prev) =>
-						prev.map((m) =>
-							m.id === assistantMsgId
-								? { ...m, content: buildContentForUI(contentPartsState, toolsWithUI) }
-								: m
-						)
-					);
-				};
-				const { batcher, scheduleFlush, forceFlush } = createStreamFlushHelpers(flushMessages);
-				streamBatcher = batcher;
-
-				await consumeSseEvents(response, async (parsed) => {
-					if (
-						processSharedStreamEvent(parsed, {
-							contentPartsState,
-							toolsWithUI,
-							currentThinkingSteps,
-							scheduleFlush,
-							forceFlush,
-							onTokenUsage: (data) => {
-								tokenUsageStore.set(assistantMsgId, data);
-							},
-							onTurnStatus: (data) => {
-								if (data.status === "cancelling") {
-									recentCancelRequestedAtRef.current = Date.now();
-								}
-							},
-						})
-					) {
-						return;
-					}
-					switch (parsed.type) {
-						case "data-thread-title-update": {
-							const titleData = parsed.data as { threadId: number; title: string };
-							if (titleData?.title && titleData?.threadId === currentThreadId) {
-								setCurrentThread((prev) => (prev ? { ...prev, title: titleData.title } : prev));
-								updateChatTabTitle({ chatId: currentThreadId, title: titleData.title });
-								queryClient.setQueriesData<ThreadListResponse>(
-									{ queryKey: ["threads", String(workspaceId)] },
-									(old) => {
-										if (!old) return old;
-										const updateTitle = (list: ThreadListItem[]) =>
-											list.map((t) =>
-												t.id === titleData.threadId ? { ...t, title: titleData.title } : t
-											);
-										return {
-											...old,
-											threads: updateTitle(old.threads),
-											archived_threads: updateTitle(old.archived_threads),
-										};
-									}
-								);
-							}
-							break;
-						}
-
-						case "data-documents-updated": {
-							const docEvent = parsed.data as {
-								action: string;
-								document: AgentCreatedDocument;
-							};
-							if (docEvent?.document?.id) {
-								setAgentCreatedDocuments((prev) => {
-									if (prev.some((d) => d.id === docEvent.document.id)) return prev;
-									return [...prev, docEvent.document];
-								});
-							}
-							break;
-						}
-
-						case "data-interrupt-request": {
-							wasInterrupted = true;
-							const interruptData = parsed.data as Record<string, unknown>;
-							const actionRequests = (interruptData.action_requests ?? []) as Array<{
-								name: string;
-								args: Record<string, unknown>;
-							}>;
-							const paired = pairBundleToolCallIds(
-								contentPartsState.toolCallIndices,
-								contentPartsState.contentParts,
-								actionRequests
-							);
-							const bundleToolCallIds: string[] = [];
-							for (let i = 0; i < actionRequests.length; i++) {
-								const action = actionRequests[i];
-								let targetTcId = paired[i];
-								if (!targetTcId) {
-									targetTcId = freshSynthToolCallId(
-										contentPartsState.toolCallIndices,
-										action.name,
-										i
-									);
-									addToolCall(
-										contentPartsState,
-										toolsWithUI,
-										targetTcId,
-										action.name,
-										action.args,
-										true
-									);
-								}
-								updateToolCall(contentPartsState, targetTcId, {
-									result: { __interrupt__: true, ...interruptData },
-								});
-								bundleToolCallIds.push(targetTcId);
-							}
-							setMessages((prev) =>
-								prev.map((m) =>
-									m.id === assistantMsgId
-										? { ...m, content: buildContentForUI(contentPartsState, toolsWithUI) }
-										: m
-								)
-							);
-							if (currentThreadId) {
-								// ``tool_call_id`` is stamped on the backend by
-								// ``checkpointed_subagent_middleware``. Without it we
-								// can't address the paused subagent on resume — skip
-								// rather than fabricate a synthetic key.
-								const interruptId = String(interruptData.tool_call_id ?? "");
-								if (interruptId) {
-									const incoming: PendingInterruptState = {
-										interruptId,
-										threadId: currentThreadId,
-										assistantMsgId,
-										interruptData,
-										bundleToolCallIds,
-									};
-									setPendingInterrupts((prev) => {
-										const without = prev.filter((p) => p.interruptId !== interruptId);
-										return [...without, incoming];
-									});
-								}
-							}
-							break;
-						}
-
-						case "data-action-log": {
-							applyActionLogSse(queryClient, currentThreadId, workspaceId, parsed.data);
-							break;
-						}
-
-						case "data-action-log-updated": {
-							applyActionLogUpdatedSse(
-								queryClient,
-								currentThreadId,
-								parsed.data.id,
-								parsed.data.reversible
-							);
-							break;
-						}
-
-						case "data-turn-info": {
-							const turnId = readStreamedChatTurnId(parsed.data);
-							if (turnId) {
-								setMessages((prev) =>
-									applyTurnIdToAssistantMessageList(prev, assistantMsgId, turnId)
-								);
-							}
-							break;
-						}
-
-						case "data-user-message-id": {
-							// Server-authoritative user message id resolved by
-							// ``persist_user_turn`` (or recovered via ON CONFLICT).
-							// Rename the optimistic ``msg-user-XXX`` placeholder to
-							// the canonical ``msg-{db_id}`` so DB-id-gated UI
-							// (comments, edit-from-this-message) unlocks immediately,
-							// migrate the local mentioned-documents map, and reassign
-							// the closure variable so all downstream
-							// ``m.id === userMsgId`` checks see the new value.
-							const parsedMsg = readStreamedMessageId(parsed.data);
-							if (!parsedMsg) break;
-							const newUserMsgId = `msg-${parsedMsg.messageId}`;
-							const oldUserMsgId = userMsgId;
-							setMessages((prev) =>
-								prev.map((m) =>
-									m.id === oldUserMsgId
-										? mergeChatTurnIdIntoMessage({ ...m, id: newUserMsgId }, parsedMsg.turnId)
-										: m
-								)
-							);
-							if (allMentionedDocs.length > 0) {
-								setMessageDocumentsMap((prev) => {
-									if (!(oldUserMsgId in prev)) {
-										return { ...prev, [newUserMsgId]: allMentionedDocs };
-									}
-									const { [oldUserMsgId]: _removed, ...rest } = prev;
-									return { ...rest, [newUserMsgId]: allMentionedDocs };
-								});
-							}
-							userMsgId = newUserMsgId;
-							if (isNewThread) {
-								// First user-side row landed in ``new_chat_messages``;
-								// refresh the sidebar so the freshly-bumped
-								// ``thread.updated_at`` reorders this thread.
-								queryClient.invalidateQueries({
-									queryKey: ["threads", String(workspaceId)],
-								});
-							}
-							break;
-						}
-
-						case "data-assistant-message-id": {
-							// Server-authoritative assistant message id resolved
-							// by ``persist_assistant_shell``. Rename the optimistic
-							// id, migrate ``tokenUsageStore`` so any pending
-							// ``data-token-usage`` payload binds to the new id,
-							// remap any in-flight ``pendingInterrupts`` entries,
-							// and reassign the closure variable so the in-stream
-							// flush callback (line ~1074) keeps writing to the
-							// renamed message.
-							const parsedMsg = readStreamedMessageId(parsed.data);
-							if (!parsedMsg) break;
-							const newAssistantMsgId = `msg-${parsedMsg.messageId}`;
-							const oldAssistantMsgId = assistantMsgId;
-							tokenUsageStore.rename(oldAssistantMsgId, newAssistantMsgId);
-							setMessages((prev) =>
-								prev.map((m) =>
-									m.id === oldAssistantMsgId
-										? mergeChatTurnIdIntoMessage({ ...m, id: newAssistantMsgId }, parsedMsg.turnId)
-										: m
-								)
-							);
-							setPendingInterrupts((prev) =>
-								prev.map((p) =>
-									p.assistantMsgId === oldAssistantMsgId
-										? { ...p, assistantMsgId: newAssistantMsgId }
-										: p
-								)
-							);
-							assistantMsgId = newAssistantMsgId;
-							break;
-						}
-					}
-				});
-
-				batcher.flush();
-
-				// Server-authoritative persistence: ``stream_new_chat``
-				// already wrote the user row in ``persist_user_turn``
-				// (the FE renamed the optimistic id mid-stream via
-				// ``data-user-message-id``) and finalises the assistant
-				// row in ``finalize_assistant_turn`` from a shielded
-				// ``finally`` block. Nothing left for the FE to persist
-				// here — track the response and unblock the UI.
-				if (contentParts.length > 0 && !wasInterrupted) {
-					trackChatResponseReceived(workspaceId, currentThreadId);
-				}
-			} catch (error) {
-				streamBatcher?.dispose();
-				await handleStreamTerminalError({
-					error,
-					flow: "new",
-					threadId: currentThreadId,
-					assistantMsgId,
-					accepted: newAccepted,
-					// Server-side ``finalize_assistant_turn`` runs from a
-					// shielded ``anyio.CancelScope(shield=True)`` finally
-					// block, so partial content (incl. abort-mid-stream)
-					// is already persisted by the BE for the assistant
-					// row, and ``persist_user_turn`` ran before any LLM
-					// call. The FE's only remaining responsibility on
-					// abort / accepted-stream-error is to surface the
-					// error toast (handled by ``handleStreamTerminalError``
-					// itself).
-					onPreAcceptFailure: async () => {
-						// Pre-accept failure means the BE never accepted the
-						// request — no server-side persistence ran. Roll
-						// back the optimistic UI insertions we made before
-						// the fetch so the user message and any local
-						// mentioned-docs metadata don't linger.
-						setMessages((prev) => prev.filter((m) => m.id !== userMsgId));
-						setMessageDocumentsMap((prev) => {
-							if (!(userMsgId in prev)) return prev;
-							const { [userMsgId]: _removed, ...rest } = prev;
-							return rest;
-						});
-					},
-				});
-			} finally {
-				setIsRunning(false);
-				abortControllerRef.current = null;
-				if (currentThreadId) {
-					void queryClient.invalidateQueries({
-						queryKey: cacheKeys.threads.messages(currentThreadId),
-					});
-					void queryClient.invalidateQueries({
-						queryKey: cacheKeys.threads.detail(currentThreadId),
-					});
-				}
+				ordered.push(...staged);
 			}
-		},
-		[
-			threadId,
-			workspaceId,
-			messages,
-			jotaiStore,
-			mentionedDocuments,
-			setMentionedDocuments,
-			setMessageDocumentsMap,
-			setAgentCreatedDocuments,
-			queryClient,
-			currentUser,
-			localFilesystemEnabled,
-			disabledTools,
-			updateChatTabTitle,
-			tokenUsageStore,
-			pendingUserImageUrls,
-			setPendingUserImageUrls,
-			fetchWithTurnCancellingRetry,
-			handleStreamTerminalError,
-			handleChatFailure,
-		]
-	);
-
-	const handleResume = useCallback(
-		async (
-			decisions: Array<{
-				type: string;
-				message?: string;
-				edited_action?: { name: string; args: Record<string, unknown> };
-			}>
-		) => {
-			if (pendingInterrupts.length === 0) return;
-			// All cards in this turn share the same threadId/assistantMsgId
-			// (they're siblings of one parent agent step), so reading from
-			// the first entry is safe.
-			const resumeThreadId = pendingInterrupts[0].threadId;
-			// Destructured separately as ``let`` so the SSE
-			// ``data-assistant-message-id`` handler (resume always
-			// allocates a fresh server-side row) can rename it to
-			// the canonical ``msg-{db_id}`` mid-stream.
-			let assistantMsgId = pendingInterrupts[0].assistantMsgId;
-			// Concatenate every card's tool-call ids in pendingInterrupts order;
-			// this matches the ``decisions`` ordering produced by
-			// ``handleApprovalSubmit`` and the backend slicer's traversal of
-			// ``state.interrupts``.
-			const allBundleToolCallIds = pendingInterrupts.flatMap((p) => p.bundleToolCallIds);
-			setPendingInterrupts([]);
 			stagedDecisionsByInterruptIdRef.current.clear();
-			setIsRunning(true);
-
-			const controller = new AbortController();
-			abortControllerRef.current = controller;
-
-			const currentThinkingSteps = new Map<string, ThinkingStepData>();
-
-			const contentPartsState: ContentPartsState = {
-				contentParts: [],
-				currentTextPartIndex: -1,
-				currentReasoningPartIndex: -1,
-				toolCallIndices: new Map(),
-			};
-			const { contentParts, toolCallIndices } = contentPartsState;
-			let resumeAccepted = false;
-			let streamBatcher: FrameBatchedUpdater | null = null;
-
-			const existingMsg = messages.find((m) => m.id === assistantMsgId);
-			if (existingMsg && Array.isArray(existingMsg.content)) {
-				// See ``ContentPartsState.suppressStepSeparators`` doc.
-				contentPartsState.suppressStepSeparators = true;
-				for (const part of existingMsg.content) {
-					if (typeof part === "object" && part !== null) {
-						const p = part as Record<string, unknown>;
-						if (p.type === "text") {
-							contentParts.push({ type: "text", text: String(p.text ?? "") });
-							contentPartsState.currentTextPartIndex = contentParts.length - 1;
-						} else if (p.type === "tool-call") {
-							toolCallIndices.set(String(p.toolCallId), contentParts.length);
-							contentParts.push({
-								type: "tool-call",
-								toolCallId: String(p.toolCallId),
-								toolName: String(p.toolName),
-								args: (p.args as Record<string, unknown>) ?? {},
-								result: p.result as unknown,
-								// argsText: assistant-ui prefers it over
-								// JSON.stringify(args), so restoring it keeps
-								// pretty-printed JSON across reloads.
-								...(typeof p.argsText === "string" ? { argsText: p.argsText } : {}),
-								...(typeof p.langchainToolCallId === "string"
-									? { langchainToolCallId: p.langchainToolCallId }
-									: {}),
-								// metadata: spanId / thinkingStepId drive the
-								// timeline's step↔tool join. Dropping these
-								// here orphans every rehydrated tool-call.
-								...(p.metadata && typeof p.metadata === "object"
-									? { metadata: p.metadata as Record<string, unknown> }
-									: {}),
-							});
-							contentPartsState.currentTextPartIndex = -1;
-						} else if (p.type === "data-thinking-steps") {
-							const stepsData = p.data as { steps: ThinkingStepData[] } | undefined;
-							contentParts.push({
-								type: "data-thinking-steps",
-								data: { steps: stepsData?.steps ?? [] },
-							});
-							for (const step of stepsData?.steps ?? []) {
-								currentThinkingSteps.set(step.id, step);
-							}
-						}
-					}
-				}
-			}
-
-			// Apply each decision to its own card by toolCallId so mixed
-			// bundles (approve/edit/reject) and multi-edit bundles do not
-			// collapse onto ``decisions[0]``. Cards outside the bundle are
-			// untouched. Mirrors the host ``hitl-decision`` handler.
-			const decisionByTcId = new Map<string, (typeof decisions)[number]>();
-			const tcIds = allBundleToolCallIds;
-			if (decisions.length === tcIds.length) {
-				for (let i = 0; i < tcIds.length; i++) decisionByTcId.set(tcIds[i], decisions[i]);
-			}
-			if (decisionByTcId.size > 0) {
-				for (const part of contentParts) {
-					if (part.type !== "tool-call") continue;
-					const tcId = part.toolCallId as string | undefined;
-					const d = tcId ? decisionByTcId.get(tcId) : undefined;
-					if (!d) continue;
-					if (typeof part.result !== "object" || part.result === null) continue;
-					if (!("__interrupt__" in (part.result as Record<string, unknown>))) continue;
-					const decided = d.type;
-					if (decided === "edit" && d.edited_action) {
-						const mergedArgs = { ...part.args, ...d.edited_action.args };
-						part.args = mergedArgs;
-						// Sync argsText so the rendered card shows the
-						// edited inputs (assistant-ui prefers it over
-						// JSON.stringify(args)).
-						part.argsText = JSON.stringify(mergedArgs, null, 2);
-					}
-					part.result = {
-						...(part.result as Record<string, unknown>),
-						__decided__: decided,
-					};
-				}
-			}
-
-			try {
-				const selection = await getAgentFilesystemSelection(workspaceId, {
-					localFilesystemEnabled,
-				});
-				const response = await fetchWithTurnCancellingRetry(() =>
-					authenticatedFetch(buildBackendUrl(`/api/v1/threads/${resumeThreadId}/resume`), {
-						method: "POST",
-						headers: {
-							"Content-Type": "application/json",
-						},
-						body: JSON.stringify({
-							workspace_id: workspaceId,
-							decisions,
-							disabled_tools: disabledTools.length > 0 ? disabledTools : undefined,
-							filesystem_mode: selection.filesystem_mode,
-							client_platform: selection.client_platform,
-							local_filesystem_mounts: selection.local_filesystem_mounts,
-						}),
-						signal: controller.signal,
-					})
-				);
-
-				if (!response.ok) {
-					throw await toHttpResponseError(response);
-				}
-				resumeAccepted = true;
-
-				const flushMessages = () => {
-					setMessages((prev) =>
-						prev.map((m) =>
-							m.id === assistantMsgId
-								? { ...m, content: buildContentForUI(contentPartsState, toolsWithUI) }
-								: m
-						)
-					);
-				};
-				const { batcher, scheduleFlush, forceFlush } = createStreamFlushHelpers(flushMessages);
-				streamBatcher = batcher;
-
-				await consumeSseEvents(response, async (parsed) => {
-					if (
-						processSharedStreamEvent(parsed, {
-							contentPartsState,
-							toolsWithUI,
-							currentThinkingSteps,
-							scheduleFlush,
-							forceFlush,
-							onTokenUsage: (data) => {
-								tokenUsageStore.set(assistantMsgId, data);
-							},
-							onTurnStatus: (data) => {
-								if (data.status === "cancelling") {
-									recentCancelRequestedAtRef.current = Date.now();
-								}
-							},
-						})
-					) {
-						return;
-					}
-					switch (parsed.type) {
-						case "data-interrupt-request": {
-							const interruptData = parsed.data as Record<string, unknown>;
-							const actionRequests = (interruptData.action_requests ?? []) as Array<{
-								name: string;
-								args: Record<string, unknown>;
-							}>;
-							const paired = pairBundleToolCallIds(
-								contentPartsState.toolCallIndices,
-								contentPartsState.contentParts,
-								actionRequests
-							);
-							const bundleToolCallIds: string[] = [];
-							for (let i = 0; i < actionRequests.length; i++) {
-								const action = actionRequests[i];
-								let targetTcId = paired[i];
-								if (!targetTcId) {
-									targetTcId = freshSynthToolCallId(
-										contentPartsState.toolCallIndices,
-										action.name,
-										i
-									);
-									addToolCall(
-										contentPartsState,
-										toolsWithUI,
-										targetTcId,
-										action.name,
-										action.args,
-										true
-									);
-								}
-								updateToolCall(contentPartsState, targetTcId, {
-									result: { __interrupt__: true, ...interruptData },
-								});
-								bundleToolCallIds.push(targetTcId);
-							}
-							setMessages((prev) =>
-								prev.map((m) =>
-									m.id === assistantMsgId
-										? { ...m, content: buildContentForUI(contentPartsState, toolsWithUI) }
-										: m
-								)
-							);
-							{
-								const interruptId = String(interruptData.tool_call_id ?? "");
-								if (interruptId) {
-									const incoming: PendingInterruptState = {
-										interruptId,
-										threadId: resumeThreadId,
-										assistantMsgId,
-										interruptData,
-										bundleToolCallIds,
-									};
-									setPendingInterrupts((prev) => {
-										const without = prev.filter((p) => p.interruptId !== interruptId);
-										return [...without, incoming];
-									});
-								}
-							}
-							break;
-						}
-
-						case "data-action-log": {
-							applyActionLogSse(queryClient, resumeThreadId, workspaceId, parsed.data);
-							break;
-						}
-
-						case "data-action-log-updated": {
-							applyActionLogUpdatedSse(
-								queryClient,
-								resumeThreadId,
-								parsed.data.id,
-								parsed.data.reversible
-							);
-							break;
-						}
-
-						case "data-turn-info": {
-							const turnId = readStreamedChatTurnId(parsed.data);
-							if (turnId) {
-								setMessages((prev) =>
-									applyTurnIdToAssistantMessageList(prev, assistantMsgId, turnId)
-								);
-							}
-							break;
-						}
-
-						case "data-assistant-message-id": {
-							// Resume always allocates a fresh ``new_chat_messages``
-							// row anchored to a new ``turn_id`` (the original
-							// interrupted turn's row stays as-is), so this is a
-							// real id swap. Rename the optimistic placeholder to
-							// ``msg-{db_id}`` and reassign closure state. Resume
-							// does NOT emit ``data-user-message-id`` — the user
-							// row belongs to the original interrupted turn.
-							const parsedMsg = readStreamedMessageId(parsed.data);
-							if (!parsedMsg) break;
-							const newAssistantMsgId = `msg-${parsedMsg.messageId}`;
-							const oldAssistantMsgId = assistantMsgId;
-							tokenUsageStore.rename(oldAssistantMsgId, newAssistantMsgId);
-							setMessages((prev) =>
-								prev.map((m) =>
-									m.id === oldAssistantMsgId
-										? mergeChatTurnIdIntoMessage({ ...m, id: newAssistantMsgId }, parsedMsg.turnId)
-										: m
-								)
-							);
-							assistantMsgId = newAssistantMsgId;
-							break;
-						}
-					}
-				});
-
-				batcher.flush();
-
-				// Server-authoritative persistence: ``stream_resume_chat``
-				// finalises the assistant row in
-				// ``finalize_assistant_turn`` from a shielded
-				// ``finally`` block (covers both happy-path and
-				// abort-mid-stream). FE has no remaining persistence
-				// work here.
-			} catch (error) {
-				streamBatcher?.dispose();
-				await handleStreamTerminalError({
-					error,
-					flow: "resume",
-					threadId: resumeThreadId,
-					assistantMsgId,
-					accepted: resumeAccepted,
-				});
-			} finally {
-				setIsRunning(false);
-				abortControllerRef.current = null;
-				void queryClient.invalidateQueries({
-					queryKey: cacheKeys.threads.messages(resumeThreadId),
-				});
-				void queryClient.invalidateQueries({
-					queryKey: cacheKeys.threads.detail(resumeThreadId),
-				});
-			}
+			window.dispatchEvent(new CustomEvent("hitl-decision", { detail: { decisions: ordered } }));
 		},
-		[
-			pendingInterrupts,
-			messages,
-			workspaceId,
-			localFilesystemEnabled,
-			disabledTools,
-			queryClient,
-			tokenUsageStore,
-			fetchWithTurnCancellingRetry,
-			handleStreamTerminalError,
-		]
+		[pendingInterrupts]
 	);
 
+	const handleEditDialogChoice = useCallback(
+		async (choice: EditMessageDialogChoice) => {
+			const pending = editDialogState;
+			if (!pending) return;
+			setEditDialogState(null);
+			if (choice === "cancel") return;
+			await regenerateChat(
+				buildCtx(),
+				pending.userQuery,
+				{
+					userMessageContent: pending.userMessageContent,
+					userImages: pending.userImages,
+					sourceUserMessageId: `msg-${pending.fromMessageId}`,
+				},
+				{
+					fromMessageId: pending.fromMessageId,
+					revertActions: choice === "revert",
+				}
+			);
+		},
+		[editDialogState, buildCtx]
+	);
+
+	// Handle reloading/refreshing the last AI response
+	const onReload = useCallback(async () => {
+		await regenerateChat(buildCtx(), null);
+	}, [buildCtx]);
+
+	// HITL resume bridge. Submit always happens from this page's approval UI, so
+	// the currently-viewed thread owns the pending interrupts. Applies each
+	// decision to its card, then resumes the (durable) stream.
 	useEffect(() => {
 		const handler = (e: Event) => {
 			const detail = (e as CustomEvent).detail as {
@@ -1859,15 +679,9 @@ export default function NewChatPage() {
 			if (!detail?.decisions || pendingInterrupts.length === 0) return;
 			const incoming = detail.decisions;
 			if (incoming.length === 0) return;
-			// Concatenated tool-call ids across every pending card, in the
-			// order ``handleApprovalSubmit`` produced ``incoming``.
 			const tcIds = pendingInterrupts.flatMap((p) => p.bundleToolCallIds);
 			const N = tcIds.length;
 
-			// Refuse rather than silently broadcast or drop. The orchestrator
-			// only fires ``hitl-decision`` once every pending card has
-			// submitted, so a count mismatch indicates a contract drift
-			// (and would later make the backend slicer raise).
 			if (incoming.length !== N) {
 				toast.error(
 					`Cannot resume: ${incoming.length} decision(s) submitted for ${N} pending actions.`
@@ -1890,631 +704,71 @@ export default function NewChatPage() {
 				submittedDecisions.push(decision);
 			}
 
-			// All pending cards belong to the same assistant message, so a
-			// single content-update pass suffices.
 			const targetAssistantMsgId = pendingInterrupts[0].assistantMsgId;
-			setMessages((prev) =>
-				prev.map((m) => {
-					if (m.id !== targetAssistantMsgId) return m;
-					const parts = m.content as unknown as Array<Record<string, unknown>>;
-					const newContent = parts.map((part) => {
-						const tcId = part.toolCallId as string | undefined;
-						const d = tcId ? byTcId.get(tcId) : undefined;
-						if (!d || part.type !== "tool-call") return part;
-						if (typeof part.result !== "object" || part.result === null) return part;
-						if (!("__interrupt__" in (part.result as Record<string, unknown>))) return part;
-						const decided = d.type;
-						if (decided === "edit" && d.edited_action) {
+			if (activeThreadId != null) {
+				chatStreamStore.setMessages(activeThreadId, (prev) =>
+					prev.map((m) => {
+						if (m.id !== targetAssistantMsgId) return m;
+						const parts = m.content as unknown as Array<Record<string, unknown>>;
+						const newContent = parts.map((part) => {
+							const tcId = part.toolCallId as string | undefined;
+							const d = tcId ? byTcId.get(tcId) : undefined;
+							if (!d || part.type !== "tool-call") return part;
+							if (typeof part.result !== "object" || part.result === null) return part;
+							if (!("__interrupt__" in (part.result as Record<string, unknown>))) return part;
+							const decided = d.type;
+							if (decided === "edit" && d.edited_action) {
+								return {
+									...part,
+									args: d.edited_action.args,
+									argsText: JSON.stringify(d.edited_action.args, null, 2),
+									result: {
+										...(part.result as Record<string, unknown>),
+										__decided__: decided,
+									},
+								};
+							}
 							return {
 								...part,
-								args: d.edited_action.args,
-								// Sync argsText so the card renders the edited
-								// inputs (assistant-ui prefers it over JSON.stringify).
-								argsText: JSON.stringify(d.edited_action.args, null, 2),
 								result: {
 									...(part.result as Record<string, unknown>),
 									__decided__: decided,
 								},
 							};
-						}
-						return {
-							...part,
-							result: {
-								...(part.result as Record<string, unknown>),
-								__decided__: decided,
-							},
-						};
-					});
-					return { ...m, content: newContent as unknown as ThreadMessageLike["content"] };
-				})
-			);
-			handleResume(submittedDecisions);
+						});
+						return { ...m, content: newContent as unknown as ThreadMessageLike["content"] };
+					})
+				);
+			}
+			void resumeChat(buildCtx(), submittedDecisions);
 		};
 		window.addEventListener("hitl-decision", handler);
 		return () => window.removeEventListener("hitl-decision", handler);
-	}, [handleResume, pendingInterrupts]);
-
-	// Convert message (pass through since already in correct format)
-	const convertMessage = useCallback(
-		(message: ThreadMessageLike): ThreadMessageLike => message,
-		[]
-	);
-
-	/**
-	 * Handle regeneration (edit or reload) by calling the regenerate endpoint
-	 * and streaming the response. This rewinds the LangGraph checkpointer state.
-	 *
-	 * @param newUserQuery - `null` = reload with same turn from the server. A string = edit
-	 *   (including an empty string when the edited turn is images-only); pass `editExtras` for images/content.
-	 */
-	const handleRegenerate = useCallback(
-		async (
-			newUserQuery: string | null,
-			editExtras?: {
-				userMessageContent: ThreadMessageLike["content"];
-				userImages: NewChatUserImagePayload[];
-				sourceUserMessageId?: string;
-			},
-			editFromPosition?: {
-				/** Message id (numeric, parsed from ``msg-<n>``) to rewind to. */
-				fromMessageId?: number | null;
-				/** When true, revert reversible downstream actions before stream. */
-				revertActions?: boolean;
-			}
-		) => {
-			if (!threadId) {
-				toast.error("Cannot regenerate: no active chat thread");
-				return;
-			}
-
-			const isEdit = newUserQuery !== null;
-
-			// Abort any previous streaming request
-			if (abortControllerRef.current) {
-				abortControllerRef.current.abort();
-				abortControllerRef.current = null;
-			}
-
-			// Extract the original user query BEFORE removing messages (for reload mode)
-			let userQueryToDisplay: string | undefined;
-			let originalUserMessageContent: ThreadMessageLike["content"] | null = null;
-			let originalUserMessageMetadata: ThreadMessageLike["metadata"] | undefined;
-			let sourceUserMessageId: string | undefined = editExtras?.sourceUserMessageId;
-
-			if (!isEdit) {
-				// Reload mode - find and preserve the last user message content
-				const lastUserMessage = [...messages].reverse().find((m) => m.role === "user");
-				if (lastUserMessage) {
-					sourceUserMessageId = lastUserMessage.id;
-					originalUserMessageContent = lastUserMessage.content;
-					originalUserMessageMetadata = lastUserMessage.metadata;
-					// Extract text for the API request
-					for (const part of lastUserMessage.content) {
-						if (typeof part === "object" && part.type === "text" && "text" in part) {
-							userQueryToDisplay = part.text;
-							break;
-						}
-					}
-				}
-			} else {
-				userQueryToDisplay = newUserQuery;
-			}
-
-			// Start streaming
-			setIsRunning(true);
-			const controller = new AbortController();
-			abortControllerRef.current = controller;
-
-			// Add placeholder user message if we have a new query (edit mode).
-			// Mutable for the same reason as in ``onNew`` — both ids are
-			// renamed mid-stream by the new ``data-user-message-id`` /
-			// ``data-assistant-message-id`` SSE handlers below.
-			let userMsgId = `msg-user-${Date.now()}`;
-			let assistantMsgId = `msg-assistant-${Date.now()}`;
-			const currentThinkingSteps = new Map<string, ThinkingStepData>();
-
-			const contentPartsState: ContentPartsState = {
-				contentParts: [],
-				currentTextPartIndex: -1,
-				currentReasoningPartIndex: -1,
-				toolCallIndices: new Map(),
-			};
-			const { contentParts } = contentPartsState;
-			let regenerateAccepted = false;
-			let streamBatcher: FrameBatchedUpdater | null = null;
-
-			// Add placeholder messages to UI
-			// Always add back the user message (with new query for edit, or original content for reload)
-			const userMessage: ThreadMessageLike = {
-				id: userMsgId,
-				role: "user",
-				content: isEdit
-					? (editExtras?.userMessageContent ?? [{ type: "text", text: newUserQuery ?? "" }])
-					: originalUserMessageContent || [{ type: "text", text: userQueryToDisplay || "" }],
-				createdAt: new Date(),
-				metadata: isEdit ? undefined : originalUserMessageMetadata,
-			};
-			const sourceMentionedDocs =
-				sourceUserMessageId && messageDocumentsMap[sourceUserMessageId]
-					? messageDocumentsMap[sourceUserMessageId]
-					: [];
-			try {
-				const selection = await getAgentFilesystemSelection(workspaceId, {
-					localFilesystemEnabled,
-				});
-				// Partition the source mentions back into doc/folder id buckets
-				// so the regenerate route can pass them to ``stream_new_chat``
-				// and the priority middleware sees the same ``[USER-MENTIONED]``
-				// priority entries the original turn did. Without this partition
-				// the regenerate flow silently dropped the agent's mention
-				// awareness — same architectural bug we fixed on the new-chat path.
-				const regenerateDocIds = sourceMentionedDocs
-					.filter((d) => d.kind === "doc")
-					.map((d) => d.id);
-				const regenerateFolderIds = sourceMentionedDocs
-					.filter((d) => d.kind === "folder")
-					.map((d) => d.id);
-				const regenerateConnectors = sourceMentionedDocs.filter((d) => d.kind === "connector");
-				const regenerateThreadIds = sourceMentionedDocs
-					.filter((d) => d.kind === "thread")
-					.map((d) => d.id);
-
-				const requestBody: Record<string, unknown> = {
-					workspace_id: workspaceId,
-					user_query: newUserQuery,
-					disabled_tools: disabledTools.length > 0 ? disabledTools : undefined,
-					filesystem_mode: selection.filesystem_mode,
-					client_platform: selection.client_platform,
-					local_filesystem_mounts: selection.local_filesystem_mounts,
-					mentioned_document_ids: regenerateDocIds.length > 0 ? regenerateDocIds : undefined,
-					mentioned_folder_ids: regenerateFolderIds.length > 0 ? regenerateFolderIds : undefined,
-					mentioned_connector_ids:
-						regenerateConnectors.length > 0 ? regenerateConnectors.map((d) => d.id) : undefined,
-					mentioned_connectors: regenerateConnectors.length > 0 ? regenerateConnectors : undefined,
-					mentioned_thread_ids: regenerateThreadIds.length > 0 ? regenerateThreadIds : undefined,
-					// Full mention metadata for the regenerate-specific
-					// source list. Only meaningful for edit (the BE only
-					// re-persists a user row when ``user_query`` is set);
-					// reload reuses the original turn's mentioned_documents.
-					mentioned_documents: sourceMentionedDocs.length > 0 ? sourceMentionedDocs : undefined,
-				};
-				if (isEdit) {
-					requestBody.user_images = editExtras?.userImages ?? [];
-				}
-				// Explicit edit-from-arbitrary-position. Only send
-				// ``from_message_id`` / ``revert_actions`` when the
-				// caller asked for them; otherwise the backend keeps the
-				// legacy "last 2 messages" behaviour for back-compat.
-				if (editFromPosition?.fromMessageId != null) {
-					requestBody.from_message_id = editFromPosition.fromMessageId;
-					if (editFromPosition.revertActions) {
-						requestBody.revert_actions = true;
-					}
-				}
-				const response = await fetchWithTurnCancellingRetry(() =>
-					authenticatedFetch(getRegenerateUrl(threadId), {
-						method: "POST",
-						headers: {
-							"Content-Type": "application/json",
-						},
-						body: JSON.stringify(requestBody),
-						signal: controller.signal,
-					})
-				);
-
-				if (!response.ok) {
-					throw await toHttpResponseError(response);
-				}
-				regenerateAccepted = true;
-
-				// Only switch UI to regenerated placeholder messages after the backend accepts
-				// regenerate. This avoids local message loss when regenerate fails early (e.g. 400).
-				//
-				// When an explicit ``editFromPosition.fromMessageId`` is passed, slice from
-				// that message forward so edit-from-arbitrary-position drops every downstream
-				// message; otherwise fall back to the legacy "drop the last 2" behaviour.
-				setMessages((prev) => {
-					let base = prev;
-					if (editFromPosition?.fromMessageId != null) {
-						const targetId = `msg-${editFromPosition.fromMessageId}`;
-						const sliceIndex = prev.findIndex((m) => m.id === targetId);
-						if (sliceIndex >= 0) {
-							base = prev.slice(0, sliceIndex);
-						}
-					} else if (prev.length >= 2) {
-						base = prev.slice(0, -2);
-					}
-					return [
-						...base,
-						userMessage,
-						{
-							id: assistantMsgId,
-							role: "assistant",
-							content: [{ type: "text", text: "" }],
-							createdAt: new Date(),
-						},
-					];
-				});
-				if (sourceMentionedDocs.length > 0) {
-					setMessageDocumentsMap((prev) => ({
-						...prev,
-						[userMsgId]: sourceMentionedDocs,
-					}));
-				}
-
-				const flushMessages = () => {
-					setMessages((prev) =>
-						prev.map((m) =>
-							m.id === assistantMsgId
-								? { ...m, content: buildContentForUI(contentPartsState, toolsWithUI) }
-								: m
-						)
-					);
-				};
-				const { batcher, scheduleFlush, forceFlush } = createStreamFlushHelpers(flushMessages);
-				streamBatcher = batcher;
-
-				await consumeSseEvents(response, async (parsed) => {
-					if (
-						processSharedStreamEvent(parsed, {
-							contentPartsState,
-							toolsWithUI,
-							currentThinkingSteps,
-							scheduleFlush,
-							forceFlush,
-							onTokenUsage: (data) => {
-								tokenUsageStore.set(assistantMsgId, data);
-							},
-							onTurnStatus: (data) => {
-								if (data.status === "cancelling") {
-									recentCancelRequestedAtRef.current = Date.now();
-								}
-							},
-						})
-					) {
-						return;
-					}
-					switch (parsed.type) {
-						case "data-action-log": {
-							if (threadId !== null) {
-								applyActionLogSse(queryClient, threadId, workspaceId, parsed.data);
-							}
-							break;
-						}
-
-						case "data-action-log-updated": {
-							if (threadId !== null) {
-								applyActionLogUpdatedSse(
-									queryClient,
-									threadId,
-									parsed.data.id,
-									parsed.data.reversible
-								);
-							}
-							break;
-						}
-
-						case "data-turn-info": {
-							const turnId = readStreamedChatTurnId(parsed.data);
-							if (turnId) {
-								setMessages((prev) =>
-									applyTurnIdToAssistantMessageList(prev, assistantMsgId, turnId)
-								);
-							}
-							break;
-						}
-
-						case "data-user-message-id": {
-							// Same role as in ``onNew`` but the regenerate-specific
-							// mention metadata (``sourceMentionedDocs``) is the
-							// list to migrate onto the canonical id key.
-							const parsedMsg = readStreamedMessageId(parsed.data);
-							if (!parsedMsg) break;
-							const newUserMsgId = `msg-${parsedMsg.messageId}`;
-							const oldUserMsgId = userMsgId;
-							setMessages((prev) =>
-								prev.map((m) =>
-									m.id === oldUserMsgId
-										? mergeChatTurnIdIntoMessage({ ...m, id: newUserMsgId }, parsedMsg.turnId)
-										: m
-								)
-							);
-							if (sourceMentionedDocs.length > 0) {
-								setMessageDocumentsMap((prev) => {
-									if (!(oldUserMsgId in prev)) {
-										return { ...prev, [newUserMsgId]: sourceMentionedDocs };
-									}
-									const { [oldUserMsgId]: _removed, ...rest } = prev;
-									return { ...rest, [newUserMsgId]: sourceMentionedDocs };
-								});
-							}
-							userMsgId = newUserMsgId;
-							break;
-						}
-
-						case "data-assistant-message-id": {
-							const parsedMsg = readStreamedMessageId(parsed.data);
-							if (!parsedMsg) break;
-							const newAssistantMsgId = `msg-${parsedMsg.messageId}`;
-							const oldAssistantMsgId = assistantMsgId;
-							tokenUsageStore.rename(oldAssistantMsgId, newAssistantMsgId);
-							setMessages((prev) =>
-								prev.map((m) =>
-									m.id === oldAssistantMsgId
-										? mergeChatTurnIdIntoMessage({ ...m, id: newAssistantMsgId }, parsedMsg.turnId)
-										: m
-								)
-							);
-							assistantMsgId = newAssistantMsgId;
-							break;
-						}
-
-						case "data-revert-results": {
-							const summary = parsed.data;
-							// failureCount must include every "not undone" bucket
-							// (not_reversible, permission_denied, failed) so the
-							// toast's "X could not be rolled back" math matches
-							// the response invariant ``total === sum(counters)``.
-							// ``skipped`` rows are batch revert artefacts (revert
-							// rows themselves) and are not user-facing failures.
-							const failureCount =
-								summary.failed + summary.not_reversible + (summary.permission_denied ?? 0);
-							if (failureCount > 0) {
-								toast.warning(
-									`Pre-revert: ${summary.reverted}/${summary.total} undone, ${failureCount} could not be rolled back.`
-								);
-							} else if (summary.reverted > 0) {
-								toast.success(
-									summary.reverted === 1
-										? "Reverted 1 downstream action before regenerating."
-										: `Reverted ${summary.reverted} downstream actions before regenerating.`
-								);
-							}
-							if (threadId !== null) {
-								for (const r of summary.results) {
-									if (r.status === "reverted" || r.status === "already_reverted") {
-										markActionRevertedInCache(
-											queryClient,
-											threadId,
-											r.action_id,
-											r.new_action_id ?? null
-										);
-									}
-								}
-							}
-							break;
-						}
-					}
-				});
-
-				batcher.flush();
-
-				// Server-authoritative persistence: ``stream_new_chat``
-				// (regenerate flow) wrote the user row in
-				// ``persist_user_turn`` and finalises the assistant row
-				// in ``finalize_assistant_turn`` from a shielded
-				// ``finally`` block (covers both happy-path and
-				// abort-mid-stream). FE only needs to track the
-				// successful response here.
-				if (contentParts.length > 0) {
-					trackChatResponseReceived(workspaceId, threadId);
-				}
-			} catch (error) {
-				streamBatcher?.dispose();
-				await handleStreamTerminalError({
-					error,
-					flow: "regenerate",
-					threadId,
-					assistantMsgId,
-					accepted: regenerateAccepted,
-				});
-			} finally {
-				setIsRunning(false);
-				abortControllerRef.current = null;
-				void queryClient.invalidateQueries({
-					queryKey: cacheKeys.threads.messages(threadId),
-				});
-				void queryClient.invalidateQueries({
-					queryKey: cacheKeys.threads.detail(threadId),
-				});
-			}
-		},
-		[
-			threadId,
-			workspaceId,
-			messages,
-			disabledTools,
-			localFilesystemEnabled,
-			messageDocumentsMap,
-			setMessageDocumentsMap,
-			queryClient,
-			tokenUsageStore,
-			fetchWithTurnCancellingRetry,
-			handleStreamTerminalError,
-		]
-	);
-
-	// Handle editing a message - truncates history and regenerates with new query.
-	//
-	// When ``message.sourceId`` is set (the assistant-ui way to say
-	// "this edit replaces an older message"), we pin
-	// ``from_message_id`` so the backend rewinds to the right LangGraph
-	// checkpoint instead of relying on the legacy "last 2 messages"
-	// rewind. We also count downstream reversible actions and prompt the
-	// user to revert / continue / cancel before regenerating.
-	const onEdit = useCallback(
-		async (message: AppendMessage) => {
-			const { userQuery, userImages } = extractUserTurnForNewChatApi(message, []);
-			const queryForApi = userQuery.trim();
-			if (!queryForApi && userImages.length === 0) {
-				toast.error("Cannot edit with empty message");
-				return;
-			}
-
-			const userMessageContent = message.content as unknown as ThreadMessageLike["content"];
-
-			// ``sourceId`` per @assistant-ui/core's ``AppendMessage`` is
-			// "the ID of the message that was edited". Parse the numeric
-			// suffix so we can map it back to a DB row.
-			const sourceId = (message as { sourceId?: string }).sourceId;
-			const fromMessageId =
-				sourceId && /^msg-\d+$/.test(sourceId)
-					? Number.parseInt(sourceId.replace(/^msg-/, ""), 10)
-					: null;
-
-			if (fromMessageId == null) {
-				// No source id (or non-DB id) — fall back to today's
-				// last-2 behaviour. The user gets the legacy edit flow.
-				await handleRegenerate(queryForApi, {
-					userMessageContent,
-					userImages,
-					sourceUserMessageId: sourceId,
-				});
-				return;
-			}
-
-			// Pre-flight: count reversible downstream actions so we can
-			// auto-skip the dialog for harmless edits.
-			//
-			// "Downstream" means messages AFTER the edited one. The
-			// previous slice ``messages.slice(editedIndex)`` included
-			// the edited message itself in both the total
-			// count and the reversibility scan (any actions on the
-			// edited turn would be double-counted). Slice from
-			// ``editedIndex + 1`` so the dialog text matches reality:
-			// "N downstream messages will be dropped".
-			const editedIndex = messages.findIndex((m) => m.id === `msg-${fromMessageId}`);
-			let downstreamReversibleCount = 0;
-			let downstreamTotalCount = 0;
-			if (editedIndex >= 0) {
-				const downstream = messages.slice(editedIndex + 1);
-				downstreamTotalCount = downstream.length;
-				const seenTurns = new Set<string>();
-				const downstreamTurnIds = new Set<string>();
-				for (const m of downstream) {
-					const meta = (m.metadata ?? {}) as { custom?: { chatTurnId?: string } };
-					const tid = meta.custom?.chatTurnId;
-					if (!tid || seenTurns.has(tid)) continue;
-					seenTurns.add(tid);
-					downstreamTurnIds.add(tid);
-				}
-				// Source of truth: the unified react-query cache. Every
-				// action whose ``chat_turn_id`` belongs to the slice we're
-				// about to drop counts toward the prompt.
-				for (const a of agentActionItems) {
-					if (!a.chat_turn_id || !downstreamTurnIds.has(a.chat_turn_id)) continue;
-					if (
-						a.reversible &&
-						(a.reverted_by_action_id === null || a.reverted_by_action_id === undefined) &&
-						!a.is_revert_action &&
-						(a.error === null || a.error === undefined)
-					) {
-						downstreamReversibleCount += 1;
-					}
-				}
-			}
-
-			if (downstreamReversibleCount === 0) {
-				// Nothing to revert — submit silently.
-				await handleRegenerate(
-					queryForApi,
-					{ userMessageContent, userImages, sourceUserMessageId: sourceId },
-					{ fromMessageId, revertActions: false }
-				);
-				return;
-			}
-
-			setEditDialogState({
-				fromMessageId,
-				userQuery: queryForApi,
-				userMessageContent,
-				userImages,
-				downstreamReversibleCount,
-				downstreamTotalCount,
-			});
-		},
-		[handleRegenerate, messages, agentActionItems]
-	);
-
-	const handleApprovalSubmit = useCallback(
-		(interruptId: string, decisions: HitlDecision[]) => {
-			// Stage this card's decisions; only fire the resume once every
-			// pending card in the current turn has submitted, so the
-			// backend slicer sees a single concatenated decisions list
-			// whose total matches the parent state's pending action count.
-			stagedDecisionsByInterruptIdRef.current.set(interruptId, decisions);
-			if (stagedDecisionsByInterruptIdRef.current.size < pendingInterrupts.length) {
-				return;
-			}
-			const ordered: HitlDecision[] = [];
-			for (const pi of pendingInterrupts) {
-				const staged = stagedDecisionsByInterruptIdRef.current.get(pi.interruptId);
-				if (!staged) {
-					// Defensive: a missing entry means the staging map and
-					// the pending list disagreed for one cycle. Bail rather
-					// than dispatch a count-mismatched batch.
-					return;
-				}
-				ordered.push(...staged);
-			}
-			stagedDecisionsByInterruptIdRef.current.clear();
-			window.dispatchEvent(new CustomEvent("hitl-decision", { detail: { decisions: ordered } }));
-		},
-		[pendingInterrupts]
-	);
-
-	const handleEditDialogChoice = useCallback(
-		async (choice: EditMessageDialogChoice) => {
-			const pending = editDialogState;
-			if (!pending) return;
-			setEditDialogState(null);
-			if (choice === "cancel") return;
-			await handleRegenerate(
-				pending.userQuery,
-				{
-					userMessageContent: pending.userMessageContent,
-					userImages: pending.userImages,
-					sourceUserMessageId: `msg-${pending.fromMessageId}`,
-				},
-				{
-					fromMessageId: pending.fromMessageId,
-					revertActions: choice === "revert",
-				}
-			);
-		},
-		[editDialogState, handleRegenerate]
-	);
-
-	// Handle reloading/refreshing the last AI response
-	const onReload = useCallback(async () => {
-		// parentId is the ID of the message to reload from (the user message)
-		// We call regenerate without a query to use the same query
-		await handleRegenerate(null);
-	}, [handleRegenerate]);
+	}, [buildCtx, pendingInterrupts, activeThreadId]);
 
 	// Surface the thread's deliverables to the layout-level artifacts sidebar.
-	useSyncChatArtifacts(messages);
+	useSyncChatArtifacts(displayMessages);
 
 	// Create external store runtime
 	const runtime = useExternalStoreRuntime({
-		messages,
+		messages: displayMessages,
 		isRunning,
 		onNew,
 		onEdit,
 		onReload,
 		convertMessage,
-		onCancel: cancelRun,
+		onCancel,
 	});
 
 	const threadLoadError = activeThreadId
 		? (threadDetailQuery.error ?? threadMessagesQuery.error)
 		: null;
 	const shouldShowThreadLoadError =
-		!!threadLoadError && !!activeThreadId && !currentThread && messages.length === 0;
+		!!threadLoadError && !!activeThreadId && !currentThread && displayMessages.length === 0;
 	const isThreadMessagesLoading =
 		!!activeThreadId &&
 		threadMessagesQuery.isPending &&
-		messages.length === 0 &&
+		displayMessages.length === 0 &&
 		!threadMessagesQuery.error;
 
 	if (shouldShowThreadLoadError) {
diff --git a/surfsense_web/app/dashboard/[workspace_id]/playground/components/output-viewer.tsx b/surfsense_web/app/dashboard/[workspace_id]/playground/components/output-viewer.tsx
index e692734d3..72262d440 100644
--- a/surfsense_web/app/dashboard/[workspace_id]/playground/components/output-viewer.tsx
+++ b/surfsense_web/app/dashboard/[workspace_id]/playground/components/output-viewer.tsx
@@ -3,7 +3,6 @@
 import { Check, Copy, Download } from "lucide-react";
 import { useMemo, useState } from "react";
 import { Button } from "@/components/ui/button";
-import { Tabs, TabsList, TabsTrigger } from "@/components/ui/tabs";
 import {
 	Table,
 	TableBody,
@@ -12,6 +11,7 @@ import {
 	TableHeader,
 	TableRow,
 } from "@/components/ui/table";
+import { Tabs, TabsList, TabsTrigger } from "@/components/ui/tabs";
 import { downloadCsv, rowsToCsv } from "@/lib/playground/csv";
 
 const MAX_TABLE_ROWS = 200;
@@ -117,13 +117,7 @@ export function OutputViewer({ data, filenameBase }: { data: unknown; filenameBa
 				</Tabs>
 				<div className="flex items-center gap-1">
 					{items && items.length > 0 && (
-						<Button
-							type="button"
-							variant="ghost"
-							size="sm"
-							onClick={exportCsv}
-							className="gap-1.5"
-						>
+						<Button type="button" variant="ghost" size="sm" onClick={exportCsv} className="gap-1.5">
 							<Download className="h-3.5 w-3.5" />
 							Export CSV
 						</Button>
diff --git a/surfsense_web/app/dashboard/[workspace_id]/playground/components/playground-index.tsx b/surfsense_web/app/dashboard/[workspace_id]/playground/components/playground-index.tsx
index 58d56e146..732e1105c 100644
--- a/surfsense_web/app/dashboard/[workspace_id]/playground/components/playground-index.tsx
+++ b/surfsense_web/app/dashboard/[workspace_id]/playground/components/playground-index.tsx
@@ -25,7 +25,8 @@ export function PlaygroundIndex({ workspaceId }: { workspaceId: number }) {
 				<Info />
 				<AlertDescription>
 					<p>
-						Manually run SurfSense's platform-native APIs and inspect their output. To use these APIs outside SurfSense,{" "}
+						Manually run SurfSense's platform-native APIs and inspect their output. To use these
+						APIs outside SurfSense,{" "}
 						<Link
 							href={`${base}/api-keys`}
 							className="font-medium text-foreground underline-offset-4 hover:underline"
diff --git a/surfsense_web/app/dashboard/[workspace_id]/playground/components/run-detail.tsx b/surfsense_web/app/dashboard/[workspace_id]/playground/components/run-detail.tsx
index 2dab447cf..4a128f5d8 100644
--- a/surfsense_web/app/dashboard/[workspace_id]/playground/components/run-detail.tsx
+++ b/surfsense_web/app/dashboard/[workspace_id]/playground/components/run-detail.tsx
@@ -35,13 +35,7 @@ function parseJsonl(text: string | null): { items: unknown[]; total: number } {
 	return { items, total: lines.length };
 }
 
-export function RunDetail({
-	workspaceId,
-	runId,
-}: {
-	workspaceId: number;
-	runId: string;
-}) {
+export function RunDetail({ workspaceId, runId }: { workspaceId: number; runId: string }) {
 	const { data: run, isLoading, error } = useScraperRun(workspaceId, runId);
 
 	const parsed = useMemo(() => parseJsonl(run?.output_text ?? null), [run?.output_text]);
diff --git a/surfsense_web/app/dashboard/[workspace_id]/playground/components/run-progress-panel.tsx b/surfsense_web/app/dashboard/[workspace_id]/playground/components/run-progress-panel.tsx
index 33a88ae76..a4e9f0023 100644
--- a/surfsense_web/app/dashboard/[workspace_id]/playground/components/run-progress-panel.tsx
+++ b/surfsense_web/app/dashboard/[workspace_id]/playground/components/run-progress-panel.tsx
@@ -9,7 +9,9 @@ import { formatDuration } from "@/lib/playground/format";
 function eventLabel(event: ScraperRunEvent): string {
 	const base =
 		event.message ||
-		(event.phase ? event.phase.replace(/_/g, " ").replace(/^\w/, (c) => c.toUpperCase()) : "Working");
+		(event.phase
+			? event.phase.replace(/_/g, " ").replace(/^\w/, (c) => c.toUpperCase())
+			: "Working");
 	if (event.current !== undefined && event.current !== null) {
 		const counter =
 			event.total !== undefined && event.total !== null
diff --git a/surfsense_web/app/dashboard/[workspace_id]/playground/components/run-status-badge.tsx b/surfsense_web/app/dashboard/[workspace_id]/playground/components/run-status-badge.tsx
index cfc75ca8a..9627fb287 100644
--- a/surfsense_web/app/dashboard/[workspace_id]/playground/components/run-status-badge.tsx
+++ b/surfsense_web/app/dashboard/[workspace_id]/playground/components/run-status-badge.tsx
@@ -14,7 +14,10 @@ export function RunStatusBadge({ status }: { status: string }) {
 	}
 	if (normalized === "success") {
 		return (
-			<Badge variant="secondary" className="bg-emerald-500/15 text-emerald-600 dark:text-emerald-400">
+			<Badge
+				variant="secondary"
+				className="bg-emerald-500/15 text-emerald-600 dark:text-emerald-400"
+			>
 				Success
 			</Badge>
 		);
diff --git a/surfsense_web/app/dashboard/[workspace_id]/playground/components/runs-table.tsx b/surfsense_web/app/dashboard/[workspace_id]/playground/components/runs-table.tsx
index 6368a1f76..57b7a547c 100644
--- a/surfsense_web/app/dashboard/[workspace_id]/playground/components/runs-table.tsx
+++ b/surfsense_web/app/dashboard/[workspace_id]/playground/components/runs-table.tsx
@@ -71,7 +71,8 @@ export function RunsTable({ workspaceId }: { workspaceId: number }) {
 			<Alert>
 				<Info />
 				<AlertDescription>
-					View all API runs for this workspace, including runs from the playground, API keys, and agents.
+					View all API runs for this workspace, including runs from the playground, API keys, and
+					agents.
 				</AlertDescription>
 			</Alert>
 
diff --git a/surfsense_web/app/dashboard/[workspace_id]/playground/components/schema-form.tsx b/surfsense_web/app/dashboard/[workspace_id]/playground/components/schema-form.tsx
index 36aee26bb..1d7eec8cf 100644
--- a/surfsense_web/app/dashboard/[workspace_id]/playground/components/schema-form.tsx
+++ b/surfsense_web/app/dashboard/[workspace_id]/playground/components/schema-form.tsx
@@ -43,12 +43,7 @@ function FieldControl({
 
 	if (field.kind === "boolean") {
 		return (
-			<Switch
-				id={id}
-				checked={Boolean(value)}
-				onCheckedChange={onChange}
-				disabled={disabled}
-			/>
+			<Switch id={id} checked={Boolean(value)} onCheckedChange={onChange} disabled={disabled} />
 		);
 	}
 
@@ -141,9 +136,7 @@ function FieldRow({
 					{field.required ? "required" : "optional"}
 				</Badge>
 			</div>
-			{field.description && (
-				<p className="text-xs text-muted-foreground">{field.description}</p>
-			)}
+			{field.description && <p className="text-xs text-muted-foreground">{field.description}</p>}
 			<FieldControl
 				field={field}
 				value={value}
@@ -156,13 +149,7 @@ function FieldRow({
 	);
 }
 
-export function SchemaForm({
-	fields,
-	values,
-	onChange,
-	disabled,
-	fieldErrors,
-}: SchemaFormProps) {
+export function SchemaForm({ fields, values, onChange, disabled, fieldErrors }: SchemaFormProps) {
 	const [showAdvanced, setShowAdvanced] = useState(false);
 
 	const { primary, advanced } = useMemo(() => {
diff --git a/surfsense_web/app/dashboard/[workspace_id]/user-settings/appearance/page.tsx b/surfsense_web/app/dashboard/[workspace_id]/user-settings/appearance/page.tsx
new file mode 100644
index 000000000..6ae0952d5
--- /dev/null
+++ b/surfsense_web/app/dashboard/[workspace_id]/user-settings/appearance/page.tsx
@@ -0,0 +1,5 @@
+import { AppearanceContent } from "../components/AppearanceContent";
+
+export default function Page() {
+	return <AppearanceContent />;
+}
diff --git a/surfsense_web/app/dashboard/[workspace_id]/user-settings/components/AppearanceContent.tsx b/surfsense_web/app/dashboard/[workspace_id]/user-settings/components/AppearanceContent.tsx
new file mode 100644
index 000000000..258a31dfe
--- /dev/null
+++ b/surfsense_web/app/dashboard/[workspace_id]/user-settings/components/AppearanceContent.tsx
@@ -0,0 +1,43 @@
+"use client";
+
+import { useAtom } from "jotai";
+import { showMessageTimestampsAtom } from "@/atoms/chat/show-timestamps.atom";
+import { Label } from "@/components/ui/label";
+import { Switch } from "@/components/ui/switch";
+
+export function AppearanceContent() {
+	const [showTimestamps, setShowTimestamps] = useAtom(showMessageTimestampsAtom);
+
+	return (
+		<div className="flex flex-col gap-4 md:gap-6">
+			<section>
+				<div className="pb-2 md:pb-3">
+					<h2 className="text-base md:text-lg font-semibold">Chat</h2>
+					<p className="text-xs md:text-sm text-muted-foreground">
+						Control how messages are displayed in your conversations.
+					</p>
+				</div>
+				<div className="flex flex-col gap-3">
+					<div className="flex items-center justify-between rounded-lg bg-accent p-4">
+						<div className="space-y-0.5">
+							<Label
+								htmlFor="show-timestamps-toggle"
+								className="text-sm font-medium cursor-pointer"
+							>
+								Show message timestamps
+							</Label>
+							<p className="text-xs text-muted-foreground">
+								Display the time under each message in a chat. Saved on this device.
+							</p>
+						</div>
+						<Switch
+							id="show-timestamps-toggle"
+							checked={showTimestamps}
+							onCheckedChange={setShowTimestamps}
+						/>
+					</div>
+				</div>
+			</section>
+		</div>
+	);
+}
diff --git a/surfsense_web/app/dashboard/[workspace_id]/user-settings/layout-shell.tsx b/surfsense_web/app/dashboard/[workspace_id]/user-settings/layout-shell.tsx
index aa73917ef..b18db9e64 100644
--- a/surfsense_web/app/dashboard/[workspace_id]/user-settings/layout-shell.tsx
+++ b/surfsense_web/app/dashboard/[workspace_id]/user-settings/layout-shell.tsx
@@ -7,6 +7,7 @@ import {
 	Library,
 	MessageCircle,
 	Monitor,
+	Palette,
 	ReceiptText,
 	ShieldCheck,
 	WandSparkles,
@@ -20,6 +21,7 @@ import { usePlatform } from "@/hooks/use-platform";
 
 export type UserSettingsTab =
 	| "profile"
+	| "appearance"
 	| "api-key"
 	| "prompts"
 	| "community-prompts"
@@ -49,6 +51,12 @@ export function UserSettingsLayoutShell({ workspaceId, children }: UserSettingsL
 				href: `/dashboard/${workspaceId}/user-settings/profile`,
 				icon: <CircleUser className="h-4 w-4" />,
 			},
+			{
+				value: "appearance" as const,
+				label: "Appearance",
+				href: `/dashboard/${workspaceId}/user-settings/appearance`,
+				icon: <Palette className="h-4 w-4" />,
+			},
 			{
 				value: "api-key" as const,
 				label: t("api_key_nav_label"),
diff --git a/surfsense_web/app/layout.tsx b/surfsense_web/app/layout.tsx
index d9e915d0f..fff38e83b 100644
--- a/surfsense_web/app/layout.tsx
+++ b/surfsense_web/app/layout.tsx
@@ -50,7 +50,7 @@ export const metadata: Metadata = {
 	alternates: {
 		canonical: "https://www.surfsense.com",
 	},
-	title: "SurfSense - Competitive Intelligence Platform for AI Agents",
+	title: "SurfSense - NotebookLM for Competitive Intelligence",
 	description:
 		"SurfSense is an open-source competitive intelligence platform. Your AI agents monitor competitors, track rankings, and listen to your market through one API or MCP server.",
 	keywords: [
@@ -68,7 +68,7 @@ export const metadata: Metadata = {
 		"SurfSense",
 	],
 	openGraph: {
-		title: "SurfSense - Competitive Intelligence Platform for AI Agents",
+		title: "SurfSense - NotebookLM for Competitive Intelligence",
 		description:
 			"SurfSense is an open-source competitive intelligence platform. Your AI agents monitor competitors, track rankings, and listen to your market through one API or MCP server.",
 		url: "https://www.surfsense.com",
@@ -86,7 +86,7 @@ export const metadata: Metadata = {
 	},
 	twitter: {
 		card: "summary_large_image",
-		title: "SurfSense - Competitive Intelligence Platform for AI Agents",
+		title: "SurfSense - NotebookLM for Competitive Intelligence",
 		description:
 			"SurfSense is an open-source competitive intelligence platform. Your AI agents monitor competitors, track rankings, and listen to your market through one API or MCP server.",
 		creator: "@SurfSenseAI",
diff --git a/surfsense_web/atoms/chat/show-timestamps.atom.ts b/surfsense_web/atoms/chat/show-timestamps.atom.ts
new file mode 100644
index 000000000..434f065ff
--- /dev/null
+++ b/surfsense_web/atoms/chat/show-timestamps.atom.ts
@@ -0,0 +1,11 @@
+import { atomWithStorage } from "jotai/utils";
+
+/**
+ * Per-device preference: show a timestamp under each chat message.
+ *
+ * Off by default to match streaming-AI chat convention (ChatGPT/Claude keep
+ * the message stream clean and put time in the conversation list). Persisted
+ * in localStorage, so it does not sync across devices — acceptable for a
+ * cosmetic display toggle.
+ */
+export const showMessageTimestampsAtom = atomWithStorage<boolean>("chat-show-timestamps:v1", false);
diff --git a/surfsense_web/components/assistant-ui/assistant-message.tsx b/surfsense_web/components/assistant-ui/assistant-message.tsx
index c4a0e86dc..a45c651b1 100644
--- a/surfsense_web/components/assistant-ui/assistant-message.tsx
+++ b/surfsense_web/components/assistant-ui/assistant-message.tsx
@@ -35,6 +35,7 @@ import {
 	useAllCitationMetadata,
 } from "@/components/assistant-ui/citation-metadata-context";
 import { MarkdownText } from "@/components/assistant-ui/markdown-text";
+import { MessageTimestamp } from "@/components/assistant-ui/message-timestamp";
 import { ReasoningMessagePart } from "@/components/assistant-ui/reasoning-message-part";
 import { RevertTurnButton } from "@/components/assistant-ui/revert-turn-button";
 import {
@@ -62,6 +63,7 @@ import { withArtifactAnchor } from "@/features/chat-artifacts";
 import { useComments } from "@/hooks/use-comments";
 import { useMediaQuery } from "@/hooks/use-media-query";
 import { useElectronAPI } from "@/hooks/use-platform";
+import { formatMessageTimestamp } from "@/lib/format-date";
 import { getProviderIcon } from "@/lib/provider-icons";
 import { tryGetHostname } from "@/lib/url";
 import { cn } from "@/lib/utils";
@@ -249,16 +251,6 @@ export const MessageError: FC = () => {
 	);
 };
 
-function formatMessageDate(date: Date): string {
-	return date.toLocaleDateString(undefined, {
-		month: "short",
-		day: "numeric",
-		hour: "numeric",
-		minute: "2-digit",
-		hour12: true,
-	});
-}
-
 /**
  * Format provider USD cost (in micro-USD) for inline display next to a
  * token count. Falls back to ``"<$0.001"`` for sub-tenth-of-a-cent
@@ -367,7 +359,7 @@ const MessageInfoDropdown: FC<{ chatTurnId: string | null | undefined }> = ({ ch
 			>
 				{createdAt && (
 					<DropdownMenuLabel className="text-xs text-muted-foreground font-normal select-none">
-						{formatMessageDate(createdAt)}
+						{formatMessageTimestamp(createdAt)}
 					</DropdownMenuLabel>
 				)}
 				{hasUsage && (
@@ -463,6 +455,8 @@ const AssistantMessageInner: FC = () => {
 				<MessageError />
 			</div>
 
+			<MessageTimestamp className="ml-2 mt-2" />
+
 			{isMobile && (
 				<div className="ml-2 mt-2">
 					<MobileCitationDrawer />
diff --git a/surfsense_web/components/assistant-ui/message-timestamp.tsx b/surfsense_web/components/assistant-ui/message-timestamp.tsx
new file mode 100644
index 000000000..65a1da9be
--- /dev/null
+++ b/surfsense_web/components/assistant-ui/message-timestamp.tsx
@@ -0,0 +1,24 @@
+import { useAuiState } from "@assistant-ui/react";
+import { useAtomValue } from "jotai";
+import type { FC } from "react";
+import { showMessageTimestampsAtom } from "@/atoms/chat/show-timestamps.atom";
+import { formatMessageTimestamp } from "@/lib/format-date";
+import { cn } from "@/lib/utils";
+
+/**
+ * Muted, always-visible timestamp under a chat message. Renders only when the
+ * user has opted in via {@link showMessageTimestampsAtom} and the message
+ * carries a ``createdAt`` (absent on optimistic pre-persist messages).
+ */
+export const MessageTimestamp: FC<{ className?: string }> = ({ className }) => {
+	const show = useAtomValue(showMessageTimestampsAtom);
+	const createdAt = useAuiState(({ message }) => message?.createdAt);
+
+	if (!show || !createdAt) return null;
+
+	return (
+		<div className={cn("select-none text-[11px] text-muted-foreground", className)}>
+			{formatMessageTimestamp(createdAt)}
+		</div>
+	);
+};
diff --git a/surfsense_web/components/assistant-ui/thread.tsx b/surfsense_web/components/assistant-ui/thread.tsx
index 47ac794ea..c51bea165 100644
--- a/surfsense_web/components/assistant-ui/thread.tsx
+++ b/surfsense_web/components/assistant-ui/thread.tsx
@@ -1070,10 +1070,7 @@ const ConnectedScraperIcons: FC<{ workspaceId: number }> = ({ workspaceId }) =>
 					return (
 						<Tooltip key={platform.id}>
 							<TooltipTrigger asChild>
-								<Avatar
-									className="size-5"
-									style={{ zIndex: platforms.length - i }}
-								>
+								<Avatar className="size-5" style={{ zIndex: platforms.length - i }}>
 									<AvatarFallback className="bg-popover text-[10px]">
 										<Icon className="size-3" />
 									</AvatarFallback>
diff --git a/surfsense_web/components/assistant-ui/user-message.tsx b/surfsense_web/components/assistant-ui/user-message.tsx
index 592dc4224..09a700ff1 100644
--- a/surfsense_web/components/assistant-ui/user-message.tsx
+++ b/surfsense_web/components/assistant-ui/user-message.tsx
@@ -22,6 +22,7 @@ import { currentThreadAtom } from "@/atoms/chat/current-thread.atom";
 import { messageDocumentsMapAtom } from "@/atoms/chat/mentioned-documents.atom";
 import { openEditorPanelAtom } from "@/atoms/editor/editor-panel.atom";
 import { MentionChip } from "@/components/assistant-ui/mention-chip";
+import { MessageTimestamp } from "@/components/assistant-ui/message-timestamp";
 import { TooltipIconButton } from "@/components/assistant-ui/tooltip-icon-button";
 import { getConnectorIcon } from "@/contracts/enums/connectorIcons";
 import { getMentionDocKey } from "@/lib/chat/mention-doc-key";
@@ -182,6 +183,7 @@ export const UserMessage: FC = () => {
 						</div>
 					)}
 				</div>
+				<MessageTimestamp className="mt-1 pl-1" />
 			</div>
 		</MessagePrimitive.Root>
 	);
diff --git a/surfsense_web/components/chat/active-chat-stream-runner.tsx b/surfsense_web/components/chat/active-chat-stream-runner.tsx
new file mode 100644
index 000000000..dd27922a0
--- /dev/null
+++ b/surfsense_web/components/chat/active-chat-stream-runner.tsx
@@ -0,0 +1,23 @@
+"use client";
+
+import { useEffect } from "react";
+import { chatStreamStore } from "@/lib/chat/stream-engine/store";
+
+/**
+ * Persistent, render-null host that scopes the in-flight chat turn's lifetime
+ * to the workspace shell, not the chat page.
+ *
+ * Mounted in ``LayoutDataProvider``, it survives in-app navigation between
+ * workspace routes and aborts the single active turn only on workspace/app
+ * teardown, so ordinary navigation disconnects the view without stopping the
+ * stream.
+ */
+export function ActiveChatStreamRunner() {
+	useEffect(() => {
+		return () => {
+			chatStreamStore.abortActive();
+		};
+	}, []);
+
+	return null;
+}
diff --git a/surfsense_web/components/homepage/hero-chat-demo.tsx b/surfsense_web/components/homepage/hero-chat-demo.tsx
index e617cd51e..a4a5ebc2a 100644
--- a/surfsense_web/components/homepage/hero-chat-demo.tsx
+++ b/surfsense_web/components/homepage/hero-chat-demo.tsx
@@ -27,7 +27,8 @@ export type HeroChatDemoScript = {
 
 type Stage = "typing" | "steps" | "answer" | "done";
 
-const PLACEHOLDER = "Track competitors, scrape platforms, automate briefs. Use / for prompts, @ for docs";
+const PLACEHOLDER =
+	"Track competitors, scrape platforms, automate briefs. Use / for prompts, @ for docs";
 
 /** Blinking caret for the typewriter (overlay only, never inside the real input). */
 function Caret() {
diff --git a/surfsense_web/components/homepage/hero-section.tsx b/surfsense_web/components/homepage/hero-section.tsx
index fc8356041..6e31891bd 100644
--- a/surfsense_web/components/homepage/hero-section.tsx
+++ b/surfsense_web/components/homepage/hero-section.tsx
@@ -708,7 +708,7 @@ export function HeroSection() {
 						"relative mt-4 max-w-4xl text-left text-4xl font-bold tracking-tight text-balance text-neutral-900 sm:text-5xl md:text-6xl dark:text-neutral-50"
 					)}
 				>
-					<Balancer>Give your AI agents competitive intelligence.</Balancer>
+					<Balancer>NotebookLM for competitive intelligence research.</Balancer>
 				</h1>
 				<div className="mt-4 flex w-full flex-col items-start justify-between gap-4 md:mt-8 md:flex-row md:items-end md:gap-10">
 					<div>
@@ -717,9 +717,10 @@ export function HeroSection() {
 								"relative mb-8 max-w-2xl text-left text-sm text-neutral-600 antialiased sm:text-base md:text-lg dark:text-neutral-400"
 							)}
 						>
-							SurfSense is an open-source competitive intelligence platform. Your AI agents monitor
-							competitors, track rankings, and listen to your market with live data from platforms
-							like Reddit, YouTube, Instagram, TikTok, Google Maps, Google Search, and the open web.
+							SurfSense is an open-source competitive intelligence platform, like NotebookLM but
+							with live scraping connectors. Your AI agents monitor competitors, track rankings, and
+							listen to your market with live data from platforms like Reddit, YouTube, Instagram,
+							TikTok, Google Maps, Google Search, and the open web.
 						</p>
 
 						<div className="relative mb-4 flex w-full flex-col justify-center gap-y-2 sm:flex-row sm:justify-start sm:space-y-0 sm:space-x-4">
diff --git a/surfsense_web/components/icons/providers/index.ts b/surfsense_web/components/icons/providers/index.ts
index 5c8276e62..f03fbec68 100644
--- a/surfsense_web/components/icons/providers/index.ts
+++ b/surfsense_web/components/icons/providers/index.ts
@@ -27,6 +27,7 @@ export { default as PerplexityIcon } from "./perplexity.svg";
 export { default as QwenIcon } from "./qwen.svg";
 export { default as RecraftIcon } from "./recraft.svg";
 export { default as ReplicateIcon } from "./replicate.svg";
+export { default as RequestyIcon } from "./requesty.svg";
 export { default as SambaNovaIcon } from "./sambanova.svg";
 export { default as TogetherAiIcon } from "./togetherai.svg";
 export { default as VertexAiIcon } from "./vertexai.svg";
diff --git a/surfsense_web/components/icons/providers/requesty.svg b/surfsense_web/components/icons/providers/requesty.svg
new file mode 100644
index 000000000..a804601b6
--- /dev/null
+++ b/surfsense_web/components/icons/providers/requesty.svg
@@ -0,0 +1 @@
+<svg fill="currentColor" fill-rule="evenodd" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path d="M14.5 2a1 1 0 000 2h2.086l-5.293 5.293a1 1 0 001.414 1.414L18 5.414V7.5a1 1 0 102 0v-4.5a1 1 0 00-1-1h-4.5zM4 6a2 2 0 00-2 2v10a2 2 0 002 2h10a2 2 0 002-2v-4a1 1 0 10-2 0v4H4V8h4a1 1 0 000-2H4z"></path></svg>
diff --git a/surfsense_web/components/layout/providers/LayoutDataProvider.tsx b/surfsense_web/components/layout/providers/LayoutDataProvider.tsx
index eec58648f..7fc862e49 100644
--- a/surfsense_web/components/layout/providers/LayoutDataProvider.tsx
+++ b/surfsense_web/components/layout/providers/LayoutDataProvider.tsx
@@ -18,6 +18,7 @@ import { workspacesAtom } from "@/atoms/workspaces/workspace-query.atoms";
 import { ActionLogDialog } from "@/components/agent-action-log/action-log-dialog";
 import { AnnouncementSpotlight } from "@/components/announcements/AnnouncementSpotlight";
 import { AnnouncementsDialog } from "@/components/announcements/AnnouncementsDialog";
+import { ActiveChatStreamRunner } from "@/components/chat/active-chat-stream-runner";
 import {
 	AlertDialog,
 	AlertDialogAction,
@@ -649,6 +650,9 @@ export function LayoutDataProvider({
 
 	return (
 		<>
+			{/* Persistent host: keeps an in-flight chat turn streaming across
+			    in-app navigation and aborts it only on workspace teardown. */}
+			<ActiveChatStreamRunner />
 			<LayoutShell
 				workspaces={workspaces}
 				activeWorkspaceId={Number(workspaceId)}
diff --git a/surfsense_web/components/layout/ui/sidebar/NotificationsDropdown.tsx b/surfsense_web/components/layout/ui/sidebar/NotificationsDropdown.tsx
index 4fe035ec2..1e9b1a33e 100644
--- a/surfsense_web/components/layout/ui/sidebar/NotificationsDropdown.tsx
+++ b/surfsense_web/components/layout/ui/sidebar/NotificationsDropdown.tsx
@@ -324,9 +324,7 @@ export function NotificationsDropdown({
 							)}
 						>
 							<span>{tab.label}</span>
-							<span
-								className="inline-flex h-5 min-w-5 items-center justify-center rounded-full bg-muted px-1.5 text-[11px] font-semibold text-muted-foreground"
-							>
+							<span className="inline-flex h-5 min-w-5 items-center justify-center rounded-full bg-muted px-1.5 text-[11px] font-semibold text-muted-foreground">
 								{formatNotificationCount(tab.count)}
 							</span>
 						</button>
diff --git a/surfsense_web/components/settings/auto-reload-settings.tsx b/surfsense_web/components/settings/auto-reload-settings.tsx
index ede826dd0..316c5975d 100644
--- a/surfsense_web/components/settings/auto-reload-settings.tsx
+++ b/surfsense_web/components/settings/auto-reload-settings.tsx
@@ -198,8 +198,8 @@ export function AutoReloadSettings() {
 					<AlertTriangle className="h-4 w-4" />
 					<AlertTitle>Last top-up failed</AlertTitle>
 					<AlertDescription>
-						Your saved card was declined and top-ups were turned off. Update your card and
-						re-enable top-ups below.
+						Your saved card was declined and top-ups were turned off. Update your card and re-enable
+						top-ups below.
 					</AlertDescription>
 				</Alert>
 			)}
@@ -290,7 +290,11 @@ export function AutoReloadSettings() {
 				</div>
 
 				<div className="flex justify-end">
-					<Button className="w-full sm:w-auto" onClick={handleSave} disabled={saveMutation.isPending}>
+					<Button
+						className="w-full sm:w-auto"
+						onClick={handleSave}
+						disabled={saveMutation.isPending}
+					>
 						{saveMutation.isPending ? (
 							<>
 								<Spinner size="xs" />
diff --git a/surfsense_web/components/settings/model-connections/default-connect-form.tsx b/surfsense_web/components/settings/model-connections/default-connect-form.tsx
index e3111202d..bc832f718 100644
--- a/surfsense_web/components/settings/model-connections/default-connect-form.tsx
+++ b/surfsense_web/components/settings/model-connections/default-connect-form.tsx
@@ -9,9 +9,17 @@ function baseUrlHint(provider: string) {
 		return "For local servers, use host.docker.internal instead of localhost.";
 	}
 	if (provider === "openai_compatible") {
-		return "Enter the full endpoint URL.";
+		return "Enter the full endpoint URL. This provider expects a /v1-compatible endpoint.";
 	}
-	if (provider === "openai" || provider === "anthropic" || provider === "openrouter") {
+	if (provider === "openai_compatible_raw") {
+		return "Enter the exact chat-completions API base URL. SurfSense will not append /v1.";
+	}
+	if (
+		provider === "openai" ||
+		provider === "anthropic" ||
+		provider === "openrouter" ||
+		provider === "requesty"
+	) {
 		return "Override only if you route through a proxy or gateway.";
 	}
 	return undefined;
diff --git a/surfsense_web/components/settings/model-connections/provider-metadata.tsx b/surfsense_web/components/settings/model-connections/provider-metadata.tsx
index 8b8a877b9..aa8879fe1 100644
--- a/surfsense_web/components/settings/model-connections/provider-metadata.tsx
+++ b/surfsense_web/components/settings/model-connections/provider-metadata.tsx
@@ -7,9 +7,11 @@ export const PROVIDER_ORDER = [
 	"bedrock",
 	"azure",
 	"openrouter",
+	"requesty",
 	"ollama_chat",
 	"lm_studio",
 	"openai_compatible",
+	"openai_compatible_raw",
 ];
 
 export const PROVIDER_DISPLAY: Record<
@@ -37,12 +39,23 @@ export const PROVIDER_DISPLAY: Record<
 		subtitle: "OpenAI-compatible endpoint",
 		iconKey: "custom",
 	},
+	openai_compatible_raw: {
+		name: "OpenAI-Compatible Raw",
+		subtitle: "Use the exact base URL, no /v1 is appended",
+		iconKey: "custom",
+	},
 	openrouter: {
 		name: "OpenRouter",
 		subtitle: "OpenRouter",
 		iconKey: "openrouter",
 		defaultBaseUrl: "https://openrouter.ai/api/v1",
 	},
+	requesty: {
+		name: "Requesty",
+		subtitle: "Requesty",
+		iconKey: "requesty",
+		defaultBaseUrl: "https://router.requesty.ai/v1",
+	},
 	vertex_ai: { name: "Gemini", subtitle: "Google Cloud Vertex AI", iconKey: "vertex_ai" },
 };
 
diff --git a/surfsense_web/components/settings/workspace-api-access-control.tsx b/surfsense_web/components/settings/workspace-api-access-control.tsx
index de74d103a..e5dae1bbe 100644
--- a/surfsense_web/components/settings/workspace-api-access-control.tsx
+++ b/surfsense_web/components/settings/workspace-api-access-control.tsx
@@ -59,7 +59,12 @@ export function WorkspaceApiAccessControl({
 
 	if (isLoading) {
 		return (
-			<div className={cn("flex flex-col gap-3 md:flex-row md:items-center md:justify-between", className)}>
+			<div
+				className={cn(
+					"flex flex-col gap-3 md:flex-row md:items-center md:justify-between",
+					className
+				)}
+			>
 				<div className="space-y-2">
 					<Skeleton className="h-4 w-32" />
 					<Skeleton className="h-3 w-56" />
@@ -71,7 +76,12 @@ export function WorkspaceApiAccessControl({
 
 	if (isError) {
 		return (
-			<div className={cn("flex flex-col gap-3 md:flex-row md:items-center md:justify-between", className)}>
+			<div
+				className={cn(
+					"flex flex-col gap-3 md:flex-row md:items-center md:justify-between",
+					className
+				)}
+			>
 				<div className="space-y-1">
 					<Label>API key access</Label>
 					<p className="text-xs text-destructive">Failed to load workspace API access.</p>
@@ -84,7 +94,12 @@ export function WorkspaceApiAccessControl({
 	}
 
 	return (
-		<div className={cn("flex flex-col gap-3 md:flex-row md:items-center md:justify-between", className)}>
+		<div
+			className={cn(
+				"flex flex-col gap-3 md:flex-row md:items-center md:justify-between",
+				className
+			)}
+		>
 			<div className="space-y-1">
 				<Label htmlFor="api-access-enabled">API key access</Label>
 				<p className="text-xs text-muted-foreground">Allow API keys to access this workspace.</p>
diff --git a/surfsense_web/content/docs/connectors/native/meta.json b/surfsense_web/content/docs/connectors/native/meta.json
index 89c8fad08..824afb980 100644
--- a/surfsense_web/content/docs/connectors/native/meta.json
+++ b/surfsense_web/content/docs/connectors/native/meta.json
@@ -1,5 +1,13 @@
 {
 	"title": "Native Connectors",
-	"pages": ["reddit", "youtube", "instagram", "tiktok", "google-maps", "google-search", "web-crawl"],
+	"pages": [
+		"reddit",
+		"youtube",
+		"instagram",
+		"tiktok",
+		"google-maps",
+		"google-search",
+		"web-crawl"
+	],
 	"defaultOpen": false
 }
diff --git a/surfsense_web/content/docs/connectors/native/tiktok.mdx b/surfsense_web/content/docs/connectors/native/tiktok.mdx
index fc4cf99c3..60506da47 100644
--- a/surfsense_web/content/docs/connectors/native/tiktok.mdx
+++ b/surfsense_web/content/docs/connectors/native/tiktok.mdx
@@ -11,15 +11,14 @@ The TikTok connector pulls structured public data from TikTok across four verbs:
 POST /api/v1/workspaces/{workspace_id}/scrapers/tiktok/scrape
 ```
 
-Give it URLs (a video, a profile, a hashtag, or a search page) and/or profiles, hashtags, or search terms; returns videos (caption, author, play/like/comment/share counts, music, hashtags, timestamps, and the web URL). At least one of `urls`, `profiles`, `hashtags`, or `search_queries` is required.
+Give it URLs (a video, a profile, a hashtag, or a search page) and/or profiles or hashtags; returns videos (caption, author, play/like/comment/share counts, music, hashtags, timestamps, and the web URL). At least one of `urls`, `profiles`, or `hashtags` is required.
 
 | Field | Default | Description |
 |-------|---------|-------------|
 | `urls` | — | TikTok URLs: a video, a profile (`/@<user>`), a hashtag (`/tag/<name>`), or a search URL (max 20 sources per call) |
 | `profiles` | — | Profile usernames, with or without a leading `@` |
 | `hashtags` | — | Hashtag names, without the `#` |
-| `search_queries` | — | Search terms to run on TikTok |
-| `results_per_page` | `10` | Max videos per profile/hashtag/search target |
+| `results_per_page` | `10` | Max videos per profile/hashtag target |
 | `max_items` | `10` | Max total videos returned across all sources (hard cap 100) |
 
 ```bash
@@ -30,7 +29,7 @@ curl -X POST "$BASE_URL/api/v1/workspaces/1/scrapers/tiktok/scrape" \
 ```
 
 <Callout type="info">
-Video and hashtag targets are the reliable video paths. A `profiles` target returns the account's **metadata** (name, followers, bio, verification) reliably, but TikTok often withholds its **video list** from automated clients — so a profile can return metadata with no videos. Keyword **video** search is login-walled and returns a surfaced error; to find accounts by keyword use **user search** below.
+Video and hashtag targets are the reliable video paths. A `profiles` target returns the account's **metadata** (name, followers, bio, verification) reliably, but TikTok often withholds its **video list** from automated clients — so a profile can return metadata with no videos. There is no keyword **video** search (TikTok's own search is login-walled); to find accounts by keyword use **user search** below.
 </Callout>
 
 ## Comments
diff --git a/surfsense_web/content/docs/docker-installation/index.mdx b/surfsense_web/content/docs/docker-installation/index.mdx
index a2db4e8f5..de65e3699 100644
--- a/surfsense_web/content/docs/docker-installation/index.mdx
+++ b/surfsense_web/content/docs/docker-installation/index.mdx
@@ -143,14 +143,48 @@ To update SurfSense, see [Updating](/docs/docker-installation/updating).
 
 ## Building from Source (Contributors)
 
-If you're contributing to SurfSense and want to build the images from your local checkout, use the dev compose file:
+If you're contributing to SurfSense and want to build the images from your local checkout, use the dev compose file. Unlike the production setup above, there's no bundled Caddy proxy — each service publishes its own port directly, and you need **three** separate `.env` files instead of one.
+
+**Requirements:** Docker with the `buildx` plugin (needed for the multi-stage `Dockerfile`; a plain `docker build` without BuildKit fails). Check with `docker buildx version` — if missing, install `docker-buildx` (or `docker-buildx-plugin` on some distros).
 
 ```bash
-cd SurfSense/docker
+git clone https://github.com/<your-fork>/SurfSense.git
+cd SurfSense
+cp docker/.env.example docker/.env
+cp surfsense_backend/.env.example surfsense_backend/.env
+cp surfsense_web/.env.example surfsense_web/.env
+```
+
+`docker/.env` only configures Docker Compose variable substitution — it is **not** passed into the containers. The backend and frontend read their own `.env` files instead (wired via `env_file:` in `docker-compose.dev.yml`).
+
+Edit before starting:
+
+- **`SECRET_KEY`** in `surfsense_backend/.env` — required, generate with `openssl rand -base64 32`. Note this is separate from `SECRET_KEY` in `docker/.env`; the dev compose file does not forward one to the other.
+
+Everything else in the three example files (auth type, Stripe, connector OAuth credentials, messaging bots, proxy settings, etc.) is optional — only needed if you're testing that specific integration.
+
+```bash
+cd docker
 docker compose -f docker-compose.dev.yml up --build
 ```
 
-It builds the backend and frontend from source, publishes raw service ports for debugging, and includes pgAdmin at [http://localhost:5050](http://localhost:5050). There's also a `docker-compose.deps-only.yml` that runs just the dependencies (Postgres, Redis, zero-cache) in Docker while you run the backend and frontend natively — see [Manual Installation](/docs/manual-installation#alternative-let-docker-manage-all-dependencies).
+| Service | Port | Notes |
+|---------|------|-------|
+| `frontend` | `localhost:3000` | Next.js dev server |
+| `backend` | `localhost:8000` | FastAPI, `/ready` for healthcheck |
+| `pgadmin` | `localhost:5050` | Postgres GUI |
+| `zero-cache` | `localhost:4848` (ws) | Real-time sync |
+| `celery_worker` | — | Background task processing, no exposed port |
+| `celery_beat` | — | Periodic task scheduler, no exposed port |
+| `otel-lgtm` | `localhost:3001` | Grafana + Loki + Tempo + Mimir bundle, for tracing/metrics |
+
+Observability (`otel-lgtm`) isn't needed for regular dev work — it's the heaviest non-essential service, so skip it if you're not debugging traces/metrics:
+
+```bash
+docker compose -f docker-compose.dev.yml up --build db redis zero-cache backend celery_worker celery_beat frontend
+```
+
+There's also a `docker-compose.deps-only.yml` that runs just the dependencies (Postgres, Redis, zero-cache) in Docker while you run the backend and frontend natively — see [Manual Installation](/docs/manual-installation#alternative-let-docker-manage-all-dependencies).
 
 ## Troubleshooting
 
diff --git a/surfsense_web/hooks/use-run-stream.ts b/surfsense_web/hooks/use-run-stream.ts
index 6e7f9b766..5d737e059 100644
--- a/surfsense_web/hooks/use-run-stream.ts
+++ b/surfsense_web/hooks/use-run-stream.ts
@@ -89,17 +89,12 @@ export function useRunStream(workspaceId: number) {
 					setState((s) => ({
 						...s,
 						latest: ev,
-						events:
-							ev.type === "run.progress"
-								? [...s.events.slice(-(MAX_LOG - 1)), ev]
-								: s.events,
+						events: ev.type === "run.progress" ? [...s.events.slice(-(MAX_LOG - 1)), ev] : s.events,
 					}));
 				}
 			} catch (e) {
 				if (signal.aborted) return;
-				setState((s) =>
-					s.status === "running" ? { ...s, status: "error", error: e } : s
-				);
+				setState((s) => (s.status === "running" ? { ...s, status: "error", error: e } : s));
 			}
 		},
 		[workspaceId, queryClient]
@@ -113,12 +108,7 @@ export function useRunStream(workspaceId: number) {
 			startedAtRef.current = Date.now();
 			setState({ ...INITIAL, status: "running" });
 			try {
-				const started = await scrapersApiService.runAsync(
-					workspaceId,
-					platform,
-					verb,
-					payload
-				);
+				const started = await scrapersApiService.runAsync(workspaceId, platform, verb, payload);
 				runIdRef.current = started.run_id;
 				trackWeeklyUser("api_run", workspaceId);
 				setState((s) => ({ ...s, runId: started.run_id }));
diff --git a/surfsense_web/lib/apis/scrapers-api.service.ts b/surfsense_web/lib/apis/scrapers-api.service.ts
index 0de3ef720..69b403d5c 100644
--- a/surfsense_web/lib/apis/scrapers-api.service.ts
+++ b/surfsense_web/lib/apis/scrapers-api.service.ts
@@ -1,15 +1,15 @@
 import {
 	type ListScraperRunsParams,
-	type ScraperRunEvent,
-	type StartAsyncRunResponse,
 	listCapabilitiesResponse,
 	listRunsResponse,
+	type ScraperRunEvent,
+	type StartAsyncRunResponse,
 	scraperRunDetail,
 	startAsyncRunResponse,
 } from "@/contracts/types/scraper.types";
+import { authenticatedFetch } from "@/lib/auth-fetch";
 import { readSSEStream } from "@/lib/chat/streaming-state";
 import { buildBackendUrl } from "@/lib/env-config";
-import { authenticatedFetch } from "@/lib/auth-fetch";
 import { baseApiService } from "./base-api.service";
 
 const base = (workspaceId: number | string) => `/api/v1/workspaces/${workspaceId}/scrapers`;
diff --git a/surfsense_web/lib/auth-utils.ts b/surfsense_web/lib/auth-utils.ts
index 8c8d919c5..7d9320fb0 100644
--- a/surfsense_web/lib/auth-utils.ts
+++ b/surfsense_web/lib/auth-utils.ts
@@ -40,6 +40,7 @@ const PUBLIC_ROUTE_PREFIXES = [
 	"/external-mcp-connectors",
 	"/reddit",
 	"/instagram",
+	"/tiktok",
 	"/youtube",
 	"/google-maps",
 	"/google-search",
diff --git a/surfsense_web/lib/chat/stream-engine/engine.ts b/surfsense_web/lib/chat/stream-engine/engine.ts
new file mode 100644
index 000000000..57ff47f61
--- /dev/null
+++ b/surfsense_web/lib/chat/stream-engine/engine.ts
@@ -0,0 +1,1432 @@
+import type { AppendMessage, ThreadMessageLike } from "@assistant-ui/react";
+import { getDefaultStore } from "jotai";
+import type { Dispatch, SetStateAction } from "react";
+import { toast } from "sonner";
+import { agentFlagsAtom } from "@/atoms/agent/agent-flags-query.atom";
+import { disabledToolsAtom } from "@/atoms/agent-tools/agent-tools.atoms";
+import {
+	deriveMentionedPayload,
+	type MentionedDocumentInfo,
+	mentionedDocumentsAtom,
+	messageDocumentsMapAtom,
+	submittedMentionsAtom,
+} from "@/atoms/chat/mentioned-documents.atom";
+import { pendingUserImageDataUrlsAtom } from "@/atoms/chat/pending-user-images.atom";
+import { setPremiumAlertForThreadAtom } from "@/atoms/chat/premium-alert.atom";
+import { type AgentCreatedDocument, agentCreatedDocumentsAtom } from "@/atoms/documents/ui.atoms";
+import { updateChatTabTitleAtom } from "@/atoms/tabs/tabs.atom";
+import { currentUserAtom } from "@/atoms/user/user-query.atoms";
+import type { HitlDecision, PendingInterruptState } from "@/features/chat-messages/hitl";
+import {
+	applyActionLogSse,
+	applyActionLogUpdatedSse,
+	markActionRevertedInCache,
+} from "@/hooks/use-agent-actions-query";
+import { getAgentFilesystemSelection } from "@/lib/agent-filesystem";
+import { authenticatedFetch } from "@/lib/auth-fetch";
+import { type ChatFlow, classifyChatError } from "@/lib/chat/chat-error-classifier";
+import { tagPreAcceptSendFailure, toHttpResponseError } from "@/lib/chat/chat-request-errors";
+import { getMentionDocKey } from "@/lib/chat/mention-doc-key";
+import { createStreamFlushHelpers } from "@/lib/chat/stream-flush";
+import { consumeSseEvents, processSharedStreamEvent } from "@/lib/chat/stream-pipeline";
+import {
+	applyTurnIdToAssistantMessageList,
+	mergeChatTurnIdIntoMessage,
+	readStreamedChatTurnId,
+	readStreamedMessageId,
+} from "@/lib/chat/stream-side-effects";
+import {
+	addToolCall,
+	buildContentForUI,
+	type ContentPartsState,
+	type FrameBatchedUpdater,
+	type ThinkingStepData,
+	updateToolCall,
+} from "@/lib/chat/streaming-state";
+import {
+	appendMessage,
+	createThread,
+	getRegenerateUrl,
+	type ThreadListItem,
+	type ThreadListResponse,
+	type ThreadRecord,
+} from "@/lib/chat/thread-persistence";
+import {
+	extractUserTurnForNewChatApi,
+	type NewChatUserImagePayload,
+} from "@/lib/chat/user-turn-api-parts";
+import { buildBackendUrl } from "@/lib/env-config";
+import {
+	trackChatBlocked,
+	trackChatCreated,
+	trackChatErrorDetailed,
+	trackChatMessageSent,
+	trackChatResponseReceived,
+} from "@/lib/posthog/events";
+import { cacheKeys } from "@/lib/query-client/cache-keys";
+import { queryClient } from "@/lib/query-client/client";
+import {
+	computeFallbackTurnCancellingRetryDelay,
+	freshSynthToolCallId,
+	pairBundleToolCallIds,
+	RECENT_CANCEL_WINDOW_MS,
+	sleep,
+	TOOLS_WITH_UI_ALL,
+} from "./helpers";
+import { chatStreamStore } from "./store";
+
+const jotaiStore = getDefaultStore();
+const tokenUsageStore = chatStreamStore.tokenUsage;
+const toolsWithUI = TOOLS_WITH_UI_ALL;
+
+/**
+ * Display-only setters, valid only while the page is mounted. The stream drives
+ * durable state through {@link chatStreamStore}; these just sync the mounted
+ * page's local view and are ignored once it unmounts.
+ */
+export interface EngineView {
+	setThreadId: Dispatch<SetStateAction<number | null>>;
+	setCurrentThread: Dispatch<SetStateAction<ThreadRecord | null>>;
+}
+
+/** Route/view context the page passes into every engine call. */
+export interface EngineContext {
+	workspaceId: number;
+	/** Currently viewed thread id (``activeThreadId`` in the page). */
+	threadId: number | null;
+	/** The page's current displayed messages — history/slice seed. */
+	priorMessages: ThreadMessageLike[];
+	view: EngineView;
+}
+
+// ---------------------------------------------------------------------------
+// Error handling
+// ---------------------------------------------------------------------------
+
+async function persistAssistantErrorMessage({
+	threadId,
+	assistantMsgId,
+	text,
+}: {
+	threadId: number | null;
+	assistantMsgId: string;
+	text: string;
+}): Promise<void> {
+	if (threadId != null) {
+		chatStreamStore.setMessages(threadId, (prev) =>
+			prev.map((m) => (m.id === assistantMsgId ? { ...m, content: [{ type: "text", text }] } : m))
+		);
+	}
+
+	if (!threadId) return;
+
+	// Persist only temporary assistant placeholders to avoid duplicate rows
+	// when the message already has a database-backed ID.
+	if (!assistantMsgId.startsWith("msg-assistant-")) return;
+
+	try {
+		const savedMessage = await appendMessage(threadId, {
+			role: "assistant",
+			content: [{ type: "text", text }],
+		});
+		const newMsgId = `msg-${savedMessage.id}`;
+		tokenUsageStore.rename(assistantMsgId, newMsgId);
+		chatStreamStore.setMessages(threadId, (prev) =>
+			prev.map((m) => (m.id === assistantMsgId ? { ...m, id: newMsgId } : m))
+		);
+	} catch (persistErr) {
+		console.error("Failed to persist assistant error message:", persistErr);
+	}
+}
+
+async function handleChatFailure({
+	error,
+	flow,
+	threadId,
+	assistantMsgId,
+	workspaceId,
+}: {
+	error: unknown;
+	flow: ChatFlow;
+	threadId: number | null;
+	assistantMsgId: string;
+	workspaceId: number;
+}): Promise<void> {
+	const normalized = classifyChatError({
+		error,
+		flow,
+		context: { workspaceId, threadId },
+	});
+
+	const logger =
+		normalized.severity === "error"
+			? console.error
+			: normalized.severity === "warn"
+				? console.warn
+				: console.info;
+	logger(`[chat-engine] ${flow} ${normalized.kind}:`, error);
+
+	const telemetryPayload = {
+		flow,
+		kind: normalized.kind,
+		error_code: normalized.errorCode,
+		severity: normalized.severity,
+		is_expected: normalized.isExpected,
+		message: normalized.userMessage,
+	};
+	if (normalized.telemetryEvent === "chat_blocked") {
+		trackChatBlocked(workspaceId, threadId, telemetryPayload);
+	} else {
+		trackChatErrorDetailed(workspaceId, threadId, telemetryPayload);
+	}
+
+	if (normalized.channel === "silent") {
+		return;
+	}
+
+	if (normalized.channel === "pinned_inline") {
+		if (threadId) {
+			const currentUser = jotaiStore.get(currentUserAtom).data;
+			jotaiStore.set(setPremiumAlertForThreadAtom, {
+				threadId,
+				message: normalized.userMessage,
+				userId: currentUser?.id ?? null,
+			});
+		}
+		if (normalized.assistantMessage) {
+			await persistAssistantErrorMessage({
+				threadId,
+				assistantMsgId,
+				text: normalized.assistantMessage,
+			});
+		}
+		return;
+	}
+
+	if (normalized.channel === "inline") {
+		if (normalized.assistantMessage) {
+			await persistAssistantErrorMessage({
+				threadId,
+				assistantMsgId,
+				text: normalized.assistantMessage,
+			});
+		}
+		toast.error(normalized.userMessage);
+		return;
+	}
+
+	toast.error(normalized.userMessage);
+}
+
+async function handleStreamTerminalError({
+	error,
+	flow,
+	threadId,
+	assistantMsgId,
+	accepted,
+	workspaceId,
+	onAbort,
+	onPreAcceptFailure,
+	onAcceptedStreamError,
+}: {
+	error: unknown;
+	flow: ChatFlow;
+	threadId: number | null;
+	assistantMsgId: string;
+	accepted: boolean;
+	workspaceId: number;
+	onAbort?: () => Promise<void>;
+	onPreAcceptFailure?: () => Promise<void>;
+	onAcceptedStreamError?: () => Promise<void>;
+}): Promise<void> {
+	if (error instanceof Error && error.name === "AbortError") {
+		await onAbort?.();
+		return;
+	}
+
+	if (!accepted) {
+		await onPreAcceptFailure?.();
+	} else {
+		await onAcceptedStreamError?.();
+	}
+
+	await handleChatFailure({
+		error: !accepted ? tagPreAcceptSendFailure(error) : error,
+		flow,
+		threadId,
+		assistantMsgId: accepted ? assistantMsgId : "no-persist-assistant",
+		workspaceId,
+	});
+}
+
+async function fetchWithTurnCancellingRetry(runFetch: () => Promise<Response>): Promise<Response> {
+	const maxAttempts = 4;
+	for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+		const response = await runFetch();
+		if (response.ok) {
+			return response;
+		}
+		const error = await toHttpResponseError(response);
+		const withMeta = error as Error & { errorCode?: string; retryAfterMs?: number };
+		const isTurnCancelling = withMeta.errorCode === "TURN_CANCELLING";
+		const isRecentThreadBusyAfterCancel =
+			withMeta.errorCode === "THREAD_BUSY" &&
+			Date.now() - chatStreamStore.recentCancelRequestedAt <= RECENT_CANCEL_WINDOW_MS;
+		if ((isTurnCancelling || isRecentThreadBusyAfterCancel) && attempt < maxAttempts) {
+			const waitMs = withMeta.retryAfterMs ?? computeFallbackTurnCancellingRetryDelay(attempt);
+			await sleep(waitMs);
+			continue;
+		}
+		throw error;
+	}
+
+	throw Object.assign(new Error("Turn cancellation retry limit exceeded"), {
+		errorCode: "TURN_CANCELLING",
+	});
+}
+
+// ---------------------------------------------------------------------------
+// Cancel
+// ---------------------------------------------------------------------------
+
+/**
+ * Cancel the single in-flight turn. Targets the active stream's OWNER thread
+ * (not the currently-viewed thread) so cancel works even after navigation and
+ * for the lazy-create case.
+ */
+export async function cancelActiveTurn(): Promise<void> {
+	const threadId = chatStreamStore.activeThreadId;
+	if (threadId) {
+		try {
+			const response = await authenticatedFetch(
+				buildBackendUrl(`/api/v1/threads/${threadId}/cancel-active-turn`),
+				{ method: "POST" }
+			);
+			if (response.ok) {
+				const payload = (await response.json()) as { error_code?: string };
+				if (payload.error_code === "TURN_CANCELLING") {
+					chatStreamStore.markRecentCancel();
+				}
+			}
+		} catch (error) {
+			console.warn("[chat-engine] Failed to signal cancel-active-turn:", error);
+		}
+		chatStreamStore.setRunning(threadId, false);
+	}
+	chatStreamStore.abortActive();
+}
+
+// ---------------------------------------------------------------------------
+// New chat turn
+// ---------------------------------------------------------------------------
+
+export async function startNewChat(ctx: EngineContext, message: AppendMessage): Promise<void> {
+	const { workspaceId, threadId, priorMessages, view } = ctx;
+
+	// Supersede any previous in-flight turn.
+	chatStreamStore.abortActive();
+
+	// Prefer the submit-time snapshot; fall back to the live atom for the
+	// send-button path.
+	const submittedSnapshot = jotaiStore.get(submittedMentionsAtom);
+	jotaiStore.set(submittedMentionsAtom, null);
+	const mentionedDocuments = jotaiStore.get(mentionedDocumentsAtom);
+	const activeMentions = submittedSnapshot ?? mentionedDocuments;
+	const mentionPayload = deriveMentionedPayload(activeMentions);
+	if (activeMentions.length > 0) {
+		jotaiStore.set(mentionedDocumentsAtom, []);
+	}
+
+	const pendingUserImageUrls = jotaiStore.get(pendingUserImageDataUrlsAtom);
+	const urlsSnapshot = [...pendingUserImageUrls];
+	const { userQuery, userImages } = extractUserTurnForNewChatApi(message, urlsSnapshot);
+
+	if (!userQuery.trim() && userImages.length === 0) return;
+
+	const localFilesystemEnabled =
+		jotaiStore.get(agentFlagsAtom).data?.enable_desktop_local_filesystem === true;
+	const disabledTools = jotaiStore.get(disabledToolsAtom);
+	const currentUser = jotaiStore.get(currentUserAtom).data;
+
+	// Resolve filesystem selection BEFORE any optimistic UI / lazy thread
+	// creation so an unsatisfied "Local Folder" requirement bails cleanly
+	// with nothing to roll back and no thread left stuck "running".
+	let selection: Awaited<ReturnType<typeof getAgentFilesystemSelection>>;
+	try {
+		selection = await getAgentFilesystemSelection(workspaceId, { localFilesystemEnabled });
+	} catch (error) {
+		await handleChatFailure({
+			error: tagPreAcceptSendFailure(error),
+			flow: "new",
+			threadId,
+			assistantMsgId: "no-persist-assistant",
+			workspaceId,
+		});
+		return;
+	}
+	if (
+		selection.filesystem_mode === "desktop_local_folder" &&
+		(!selection.local_filesystem_mounts || selection.local_filesystem_mounts.length === 0)
+	) {
+		toast.error("Select a local folder before using Local Folder mode.");
+		return;
+	}
+
+	// Lazy thread creation: create thread on first message if it doesn't exist.
+	let currentThreadId = threadId;
+	let isNewThread = false;
+	if (!currentThreadId) {
+		try {
+			const newThread = await createThread(workspaceId, "New Chat");
+			currentThreadId = newThread.id;
+			view.setThreadId(currentThreadId);
+			view.setCurrentThread(newThread);
+			queryClient.setQueryData(cacheKeys.threads.detail(newThread.id), newThread);
+			queryClient.setQueryData(cacheKeys.threads.messages(newThread.id), { messages: [] });
+
+			trackChatCreated(workspaceId, currentThreadId);
+
+			isNewThread = true;
+			// Update URL silently using browser API (not router.replace) to avoid
+			// interrupting the ongoing fetch/streaming with React navigation.
+			window.history.replaceState(
+				null,
+				"",
+				`/dashboard/${workspaceId}/new-chat/${currentThreadId}`
+			);
+		} catch (error) {
+			console.error("[chat-engine] Failed to create thread:", error);
+			await handleChatFailure({
+				error: tagPreAcceptSendFailure(error),
+				flow: "new",
+				threadId: currentThreadId,
+				assistantMsgId: "no-persist-assistant",
+				workspaceId,
+			});
+			return;
+		}
+	}
+
+	// Seed the durable per-thread overlay with the pre-turn conversation and
+	// flip it to running so the page renders the live stream.
+	const streamThreadId = currentThreadId;
+	chatStreamStore.begin(streamThreadId, priorMessages);
+
+	if (urlsSnapshot.length > 0) {
+		jotaiStore.set(pendingUserImageDataUrlsAtom, (prev) =>
+			prev.filter((u) => !urlsSnapshot.includes(u))
+		);
+	}
+
+	// Add user message to state. Mutable because the SSE
+	// ``data-user-message-id`` handler renames this optimistic id to the
+	// canonical ``msg-{db_id}`` once ``persist_user_turn`` resolves.
+	let userMsgId = `msg-user-${Date.now()}`;
+
+	const authorMetadata = currentUser
+		? {
+				custom: {
+					author: {
+						displayName: currentUser.display_name ?? null,
+						avatarUrl: currentUser.avatar_url ?? null,
+					},
+				},
+			}
+		: undefined;
+
+	const existingImageUrls = new Set(
+		message.content
+			.filter(
+				(p): p is { type: "image"; image: string } =>
+					typeof p === "object" && p !== null && "type" in p && p.type === "image" && "image" in p
+			)
+			.map((p) => p.image)
+	);
+	const extraImageParts = urlsSnapshot
+		.filter((u) => !existingImageUrls.has(u))
+		.map((image) => ({ type: "image" as const, image }));
+	const userDisplayContent = [...message.content, ...extraImageParts];
+
+	const userMessage: ThreadMessageLike = {
+		id: userMsgId,
+		role: "user",
+		content: userDisplayContent,
+		createdAt: new Date(),
+		metadata: authorMetadata,
+	};
+	chatStreamStore.setMessages(streamThreadId, (prev) => [...prev, userMessage]);
+
+	trackChatMessageSent(workspaceId, streamThreadId, {
+		hasAttachments: userImages.length > 0,
+		hasMentionedDocuments:
+			mentionPayload.document_ids.length > 0 ||
+			mentionPayload.folder_ids.length > 0 ||
+			mentionPayload.connector_ids.length > 0,
+		messageLength: userQuery.length,
+	});
+
+	// Collect unique mention chips for display & persistence.
+	const allMentionedDocs: MentionedDocumentInfo[] = [];
+	const seenDocKeys = new Set<string>();
+	for (const doc of activeMentions) {
+		const key = getMentionDocKey(doc);
+		if (seenDocKeys.has(key)) continue;
+		seenDocKeys.add(key);
+		allMentionedDocs.push(doc);
+	}
+
+	if (allMentionedDocs.length > 0) {
+		jotaiStore.set(messageDocumentsMapAtom, (prev) => ({
+			...prev,
+			[userMsgId]: allMentionedDocs,
+		}));
+	}
+
+	const controller = new AbortController();
+	chatStreamStore.beginActive(streamThreadId, controller);
+
+	// Prepare assistant message. Mutable for the same reason as ``userMsgId``.
+	let assistantMsgId = `msg-assistant-${Date.now()}`;
+	const currentThinkingSteps = new Map<string, ThinkingStepData>();
+	const contentPartsState: ContentPartsState = {
+		contentParts: [],
+		currentTextPartIndex: -1,
+		currentReasoningPartIndex: -1,
+		toolCallIndices: new Map(),
+	};
+	const { contentParts } = contentPartsState;
+	let wasInterrupted = false;
+	let newAccepted = false;
+	let streamBatcher: FrameBatchedUpdater | null = null;
+
+	try {
+		// Build message history for context.
+		const messageHistory = priorMessages
+			.filter((m) => m.role === "user" || m.role === "assistant")
+			.map((m) => {
+				let text = "";
+				for (const part of m.content) {
+					if (typeof part === "object" && part.type === "text" && "text" in part) {
+						text += part.text;
+					}
+				}
+				return { role: m.role, content: text };
+			})
+			.filter((m) => m.content.length > 0);
+
+		const hasDocumentIds = mentionPayload.document_ids.length > 0;
+		const hasFolderIds = mentionPayload.folder_ids.length > 0;
+		const hasConnectorIds = mentionPayload.connector_ids.length > 0;
+		const hasThreadIds = mentionPayload.thread_ids.length > 0;
+
+		const response = await fetchWithTurnCancellingRetry(() =>
+			authenticatedFetch(buildBackendUrl("/api/v1/new_chat"), {
+				method: "POST",
+				headers: { "Content-Type": "application/json" },
+				body: JSON.stringify({
+					chat_id: streamThreadId,
+					user_query: userQuery.trim(),
+					workspace_id: workspaceId,
+					filesystem_mode: selection.filesystem_mode,
+					client_platform: selection.client_platform,
+					local_filesystem_mounts: selection.local_filesystem_mounts,
+					messages: messageHistory,
+					mentioned_document_ids: hasDocumentIds ? mentionPayload.document_ids : undefined,
+					mentioned_folder_ids: hasFolderIds ? mentionPayload.folder_ids : undefined,
+					mentioned_connector_ids: hasConnectorIds ? mentionPayload.connector_ids : undefined,
+					mentioned_connectors: hasConnectorIds ? mentionPayload.connectors : undefined,
+					mentioned_thread_ids: hasThreadIds ? mentionPayload.thread_ids : undefined,
+					mentioned_documents: allMentionedDocs.length > 0 ? allMentionedDocs : undefined,
+					disabled_tools: disabledTools.length > 0 ? disabledTools : undefined,
+					...(userImages.length > 0 ? { user_images: userImages } : {}),
+				}),
+				signal: controller.signal,
+			})
+		);
+
+		if (!response.ok) {
+			throw await toHttpResponseError(response);
+		}
+		newAccepted = true;
+		chatStreamStore.setMessages(streamThreadId, (prev) => [
+			...prev,
+			{
+				id: assistantMsgId,
+				role: "assistant",
+				content: [{ type: "text", text: "" }],
+				createdAt: new Date(),
+			},
+		]);
+
+		const flushMessages = () => {
+			chatStreamStore.setMessages(streamThreadId, (prev) =>
+				prev.map((m) =>
+					m.id === assistantMsgId
+						? { ...m, content: buildContentForUI(contentPartsState, toolsWithUI) }
+						: m
+				)
+			);
+		};
+		const { batcher, scheduleFlush, forceFlush } = createStreamFlushHelpers(flushMessages);
+		streamBatcher = batcher;
+
+		await consumeSseEvents(response, async (parsed) => {
+			if (
+				processSharedStreamEvent(parsed, {
+					contentPartsState,
+					toolsWithUI,
+					currentThinkingSteps,
+					scheduleFlush,
+					forceFlush,
+					onTokenUsage: (data) => {
+						tokenUsageStore.set(assistantMsgId, data);
+					},
+					onTurnStatus: (data) => {
+						if (data.status === "cancelling") {
+							chatStreamStore.markRecentCancel();
+						}
+					},
+				})
+			) {
+				return;
+			}
+			switch (parsed.type) {
+				case "data-thread-title-update": {
+					const titleData = parsed.data as { threadId: number; title: string };
+					if (titleData?.title && titleData?.threadId === streamThreadId) {
+						view.setCurrentThread((prev) => (prev ? { ...prev, title: titleData.title } : prev));
+						jotaiStore.set(updateChatTabTitleAtom, {
+							chatId: streamThreadId,
+							title: titleData.title,
+						});
+						queryClient.setQueriesData<ThreadListResponse>(
+							{ queryKey: ["threads", String(workspaceId)] },
+							(old) => {
+								if (!old) return old;
+								const updateTitle = (list: ThreadListItem[]) =>
+									list.map((t) =>
+										t.id === titleData.threadId ? { ...t, title: titleData.title } : t
+									);
+								return {
+									...old,
+									threads: updateTitle(old.threads),
+									archived_threads: updateTitle(old.archived_threads),
+								};
+							}
+						);
+					}
+					break;
+				}
+
+				case "data-documents-updated": {
+					const docEvent = parsed.data as {
+						action: string;
+						document: AgentCreatedDocument;
+					};
+					if (docEvent?.document?.id) {
+						jotaiStore.set(agentCreatedDocumentsAtom, (prev) => {
+							if (prev.some((d) => d.id === docEvent.document.id)) return prev;
+							return [...prev, docEvent.document];
+						});
+					}
+					break;
+				}
+
+				case "data-interrupt-request": {
+					wasInterrupted = true;
+					const interruptData = parsed.data as Record<string, unknown>;
+					const actionRequests = (interruptData.action_requests ?? []) as Array<{
+						name: string;
+						args: Record<string, unknown>;
+					}>;
+					const paired = pairBundleToolCallIds(
+						contentPartsState.toolCallIndices,
+						contentPartsState.contentParts,
+						actionRequests
+					);
+					const bundleToolCallIds: string[] = [];
+					for (let i = 0; i < actionRequests.length; i++) {
+						const action = actionRequests[i];
+						let targetTcId = paired[i];
+						if (!targetTcId) {
+							targetTcId = freshSynthToolCallId(contentPartsState.toolCallIndices, action.name, i);
+							addToolCall(
+								contentPartsState,
+								toolsWithUI,
+								targetTcId,
+								action.name,
+								action.args,
+								true
+							);
+						}
+						updateToolCall(contentPartsState, targetTcId, {
+							result: { __interrupt__: true, ...interruptData },
+						});
+						bundleToolCallIds.push(targetTcId);
+					}
+					chatStreamStore.setMessages(streamThreadId, (prev) =>
+						prev.map((m) =>
+							m.id === assistantMsgId
+								? { ...m, content: buildContentForUI(contentPartsState, toolsWithUI) }
+								: m
+						)
+					);
+					// ``tool_call_id`` is stamped on the backend by
+					// ``checkpointed_subagent_middleware``. Without it we can't
+					// address the paused subagent on resume — skip rather than
+					// fabricate a synthetic key.
+					const interruptId = String(interruptData.tool_call_id ?? "");
+					if (interruptId) {
+						const incoming: PendingInterruptState = {
+							interruptId,
+							threadId: streamThreadId,
+							assistantMsgId,
+							interruptData,
+							bundleToolCallIds,
+						};
+						chatStreamStore.setPendingInterrupts(streamThreadId, (prev) => {
+							const without = prev.filter((p) => p.interruptId !== interruptId);
+							return [...without, incoming];
+						});
+					}
+					break;
+				}
+
+				case "data-action-log": {
+					applyActionLogSse(queryClient, streamThreadId, workspaceId, parsed.data);
+					break;
+				}
+
+				case "data-action-log-updated": {
+					applyActionLogUpdatedSse(
+						queryClient,
+						streamThreadId,
+						parsed.data.id,
+						parsed.data.reversible
+					);
+					break;
+				}
+
+				case "data-turn-info": {
+					const turnId = readStreamedChatTurnId(parsed.data);
+					if (turnId) {
+						chatStreamStore.setMessages(streamThreadId, (prev) =>
+							applyTurnIdToAssistantMessageList(prev, assistantMsgId, turnId)
+						);
+					}
+					break;
+				}
+
+				case "data-user-message-id": {
+					const parsedMsg = readStreamedMessageId(parsed.data);
+					if (!parsedMsg) break;
+					const newUserMsgId = `msg-${parsedMsg.messageId}`;
+					const oldUserMsgId = userMsgId;
+					chatStreamStore.setMessages(streamThreadId, (prev) =>
+						prev.map((m) =>
+							m.id === oldUserMsgId
+								? mergeChatTurnIdIntoMessage({ ...m, id: newUserMsgId }, parsedMsg.turnId)
+								: m
+						)
+					);
+					if (allMentionedDocs.length > 0) {
+						jotaiStore.set(messageDocumentsMapAtom, (prev) => {
+							if (!(oldUserMsgId in prev)) {
+								return { ...prev, [newUserMsgId]: allMentionedDocs };
+							}
+							const { [oldUserMsgId]: _removed, ...rest } = prev;
+							return { ...rest, [newUserMsgId]: allMentionedDocs };
+						});
+					}
+					userMsgId = newUserMsgId;
+					if (isNewThread) {
+						queryClient.invalidateQueries({
+							queryKey: ["threads", String(workspaceId)],
+						});
+					}
+					break;
+				}
+
+				case "data-assistant-message-id": {
+					const parsedMsg = readStreamedMessageId(parsed.data);
+					if (!parsedMsg) break;
+					const newAssistantMsgId = `msg-${parsedMsg.messageId}`;
+					const oldAssistantMsgId = assistantMsgId;
+					tokenUsageStore.rename(oldAssistantMsgId, newAssistantMsgId);
+					chatStreamStore.setMessages(streamThreadId, (prev) =>
+						prev.map((m) =>
+							m.id === oldAssistantMsgId
+								? mergeChatTurnIdIntoMessage({ ...m, id: newAssistantMsgId }, parsedMsg.turnId)
+								: m
+						)
+					);
+					chatStreamStore.setPendingInterrupts(streamThreadId, (prev) =>
+						prev.map((p) =>
+							p.assistantMsgId === oldAssistantMsgId
+								? { ...p, assistantMsgId: newAssistantMsgId }
+								: p
+						)
+					);
+					assistantMsgId = newAssistantMsgId;
+					break;
+				}
+			}
+		});
+
+		batcher.flush();
+
+		if (contentParts.length > 0 && !wasInterrupted) {
+			trackChatResponseReceived(workspaceId, streamThreadId);
+		}
+	} catch (error) {
+		streamBatcher?.dispose();
+		await handleStreamTerminalError({
+			error,
+			flow: "new",
+			threadId: streamThreadId,
+			assistantMsgId,
+			accepted: newAccepted,
+			workspaceId,
+			onPreAcceptFailure: async () => {
+				// Pre-accept failure means the BE never accepted the request — no
+				// server-side persistence ran. Roll back the optimistic UI.
+				chatStreamStore.setMessages(streamThreadId, (prev) =>
+					prev.filter((m) => m.id !== userMsgId)
+				);
+				jotaiStore.set(messageDocumentsMapAtom, (prev) => {
+					if (!(userMsgId in prev)) return prev;
+					const { [userMsgId]: _removed, ...rest } = prev;
+					return rest;
+				});
+			},
+		});
+	} finally {
+		chatStreamStore.setRunning(streamThreadId, false);
+		chatStreamStore.clearActive(controller);
+		void queryClient.invalidateQueries({
+			queryKey: cacheKeys.threads.messages(streamThreadId),
+		});
+		void queryClient.invalidateQueries({
+			queryKey: cacheKeys.threads.detail(streamThreadId),
+		});
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Resume (HITL decisions)
+// ---------------------------------------------------------------------------
+
+export async function resumeChat(
+	ctx: EngineContext,
+	decisions: Array<{
+		type: string;
+		message?: string;
+		edited_action?: { name: string; args: Record<string, unknown> };
+	}>
+): Promise<void> {
+	const { workspaceId, threadId } = ctx;
+	if (threadId == null) return;
+	const pendingInterrupts = chatStreamStore.getPendingInterrupts(threadId);
+	if (pendingInterrupts.length === 0) return;
+
+	const resumeThreadId = pendingInterrupts[0].threadId;
+	let assistantMsgId = pendingInterrupts[0].assistantMsgId;
+	const allBundleToolCallIds = pendingInterrupts.flatMap((p) => p.bundleToolCallIds);
+	chatStreamStore.setPendingInterrupts(resumeThreadId, () => []);
+	chatStreamStore.setRunning(resumeThreadId, true);
+
+	const controller = new AbortController();
+	chatStreamStore.beginActive(resumeThreadId, controller);
+
+	const localFilesystemEnabled =
+		jotaiStore.get(agentFlagsAtom).data?.enable_desktop_local_filesystem === true;
+	const disabledTools = jotaiStore.get(disabledToolsAtom);
+
+	const currentThinkingSteps = new Map<string, ThinkingStepData>();
+	const contentPartsState: ContentPartsState = {
+		contentParts: [],
+		currentTextPartIndex: -1,
+		currentReasoningPartIndex: -1,
+		toolCallIndices: new Map(),
+	};
+	const { contentParts, toolCallIndices } = contentPartsState;
+	let resumeAccepted = false;
+	let streamBatcher: FrameBatchedUpdater | null = null;
+
+	const existingMsg = chatStreamStore
+		.getMessages(resumeThreadId)
+		.find((m) => m.id === assistantMsgId);
+	if (existingMsg && Array.isArray(existingMsg.content)) {
+		contentPartsState.suppressStepSeparators = true;
+		for (const part of existingMsg.content) {
+			if (typeof part === "object" && part !== null) {
+				const p = part as Record<string, unknown>;
+				if (p.type === "text") {
+					contentParts.push({ type: "text", text: String(p.text ?? "") });
+					contentPartsState.currentTextPartIndex = contentParts.length - 1;
+				} else if (p.type === "tool-call") {
+					toolCallIndices.set(String(p.toolCallId), contentParts.length);
+					contentParts.push({
+						type: "tool-call",
+						toolCallId: String(p.toolCallId),
+						toolName: String(p.toolName),
+						args: (p.args as Record<string, unknown>) ?? {},
+						result: p.result as unknown,
+						...(typeof p.argsText === "string" ? { argsText: p.argsText } : {}),
+						...(typeof p.langchainToolCallId === "string"
+							? { langchainToolCallId: p.langchainToolCallId }
+							: {}),
+						...(p.metadata && typeof p.metadata === "object"
+							? { metadata: p.metadata as Record<string, unknown> }
+							: {}),
+					});
+					contentPartsState.currentTextPartIndex = -1;
+				} else if (p.type === "data-thinking-steps") {
+					const stepsData = p.data as { steps: ThinkingStepData[] } | undefined;
+					contentParts.push({
+						type: "data-thinking-steps",
+						data: { steps: stepsData?.steps ?? [] },
+					});
+					for (const step of stepsData?.steps ?? []) {
+						currentThinkingSteps.set(step.id, step);
+					}
+				}
+			}
+		}
+	}
+
+	// Apply each decision to its own card by toolCallId so mixed bundles
+	// (approve/edit/reject) do not collapse onto ``decisions[0]``.
+	const decisionByTcId = new Map<string, (typeof decisions)[number]>();
+	const tcIds = allBundleToolCallIds;
+	if (decisions.length === tcIds.length) {
+		for (let i = 0; i < tcIds.length; i++) decisionByTcId.set(tcIds[i], decisions[i]);
+	}
+	if (decisionByTcId.size > 0) {
+		for (const part of contentParts) {
+			if (part.type !== "tool-call") continue;
+			const tcId = part.toolCallId as string | undefined;
+			const d = tcId ? decisionByTcId.get(tcId) : undefined;
+			if (!d) continue;
+			if (typeof part.result !== "object" || part.result === null) continue;
+			if (!("__interrupt__" in (part.result as Record<string, unknown>))) continue;
+			const decided = d.type;
+			if (decided === "edit" && d.edited_action) {
+				const mergedArgs = { ...part.args, ...d.edited_action.args };
+				part.args = mergedArgs;
+				part.argsText = JSON.stringify(mergedArgs, null, 2);
+			}
+			part.result = {
+				...(part.result as Record<string, unknown>),
+				__decided__: decided,
+			};
+		}
+	}
+
+	try {
+		const selection = await getAgentFilesystemSelection(workspaceId, { localFilesystemEnabled });
+		const response = await fetchWithTurnCancellingRetry(() =>
+			authenticatedFetch(buildBackendUrl(`/api/v1/threads/${resumeThreadId}/resume`), {
+				method: "POST",
+				headers: { "Content-Type": "application/json" },
+				body: JSON.stringify({
+					workspace_id: workspaceId,
+					decisions,
+					disabled_tools: disabledTools.length > 0 ? disabledTools : undefined,
+					filesystem_mode: selection.filesystem_mode,
+					client_platform: selection.client_platform,
+					local_filesystem_mounts: selection.local_filesystem_mounts,
+				}),
+				signal: controller.signal,
+			})
+		);
+
+		if (!response.ok) {
+			throw await toHttpResponseError(response);
+		}
+		resumeAccepted = true;
+
+		const flushMessages = () => {
+			chatStreamStore.setMessages(resumeThreadId, (prev) =>
+				prev.map((m) =>
+					m.id === assistantMsgId
+						? { ...m, content: buildContentForUI(contentPartsState, toolsWithUI) }
+						: m
+				)
+			);
+		};
+		const { batcher, scheduleFlush, forceFlush } = createStreamFlushHelpers(flushMessages);
+		streamBatcher = batcher;
+
+		await consumeSseEvents(response, async (parsed) => {
+			if (
+				processSharedStreamEvent(parsed, {
+					contentPartsState,
+					toolsWithUI,
+					currentThinkingSteps,
+					scheduleFlush,
+					forceFlush,
+					onTokenUsage: (data) => {
+						tokenUsageStore.set(assistantMsgId, data);
+					},
+					onTurnStatus: (data) => {
+						if (data.status === "cancelling") {
+							chatStreamStore.markRecentCancel();
+						}
+					},
+				})
+			) {
+				return;
+			}
+			switch (parsed.type) {
+				case "data-interrupt-request": {
+					const interruptData = parsed.data as Record<string, unknown>;
+					const actionRequests = (interruptData.action_requests ?? []) as Array<{
+						name: string;
+						args: Record<string, unknown>;
+					}>;
+					const paired = pairBundleToolCallIds(
+						contentPartsState.toolCallIndices,
+						contentPartsState.contentParts,
+						actionRequests
+					);
+					const bundleToolCallIds: string[] = [];
+					for (let i = 0; i < actionRequests.length; i++) {
+						const action = actionRequests[i];
+						let targetTcId = paired[i];
+						if (!targetTcId) {
+							targetTcId = freshSynthToolCallId(contentPartsState.toolCallIndices, action.name, i);
+							addToolCall(
+								contentPartsState,
+								toolsWithUI,
+								targetTcId,
+								action.name,
+								action.args,
+								true
+							);
+						}
+						updateToolCall(contentPartsState, targetTcId, {
+							result: { __interrupt__: true, ...interruptData },
+						});
+						bundleToolCallIds.push(targetTcId);
+					}
+					chatStreamStore.setMessages(resumeThreadId, (prev) =>
+						prev.map((m) =>
+							m.id === assistantMsgId
+								? { ...m, content: buildContentForUI(contentPartsState, toolsWithUI) }
+								: m
+						)
+					);
+					{
+						const interruptId = String(interruptData.tool_call_id ?? "");
+						if (interruptId) {
+							const incoming: PendingInterruptState = {
+								interruptId,
+								threadId: resumeThreadId,
+								assistantMsgId,
+								interruptData,
+								bundleToolCallIds,
+							};
+							chatStreamStore.setPendingInterrupts(resumeThreadId, (prev) => {
+								const without = prev.filter((p) => p.interruptId !== interruptId);
+								return [...without, incoming];
+							});
+						}
+					}
+					break;
+				}
+
+				case "data-action-log": {
+					applyActionLogSse(queryClient, resumeThreadId, workspaceId, parsed.data);
+					break;
+				}
+
+				case "data-action-log-updated": {
+					applyActionLogUpdatedSse(
+						queryClient,
+						resumeThreadId,
+						parsed.data.id,
+						parsed.data.reversible
+					);
+					break;
+				}
+
+				case "data-turn-info": {
+					const turnId = readStreamedChatTurnId(parsed.data);
+					if (turnId) {
+						chatStreamStore.setMessages(resumeThreadId, (prev) =>
+							applyTurnIdToAssistantMessageList(prev, assistantMsgId, turnId)
+						);
+					}
+					break;
+				}
+
+				case "data-assistant-message-id": {
+					const parsedMsg = readStreamedMessageId(parsed.data);
+					if (!parsedMsg) break;
+					const newAssistantMsgId = `msg-${parsedMsg.messageId}`;
+					const oldAssistantMsgId = assistantMsgId;
+					tokenUsageStore.rename(oldAssistantMsgId, newAssistantMsgId);
+					chatStreamStore.setMessages(resumeThreadId, (prev) =>
+						prev.map((m) =>
+							m.id === oldAssistantMsgId
+								? mergeChatTurnIdIntoMessage({ ...m, id: newAssistantMsgId }, parsedMsg.turnId)
+								: m
+						)
+					);
+					assistantMsgId = newAssistantMsgId;
+					break;
+				}
+			}
+		});
+
+		batcher.flush();
+	} catch (error) {
+		streamBatcher?.dispose();
+		await handleStreamTerminalError({
+			error,
+			flow: "resume",
+			threadId: resumeThreadId,
+			assistantMsgId,
+			accepted: resumeAccepted,
+			workspaceId,
+		});
+	} finally {
+		chatStreamStore.setRunning(resumeThreadId, false);
+		chatStreamStore.clearActive(controller);
+		void queryClient.invalidateQueries({
+			queryKey: cacheKeys.threads.messages(resumeThreadId),
+		});
+		void queryClient.invalidateQueries({
+			queryKey: cacheKeys.threads.detail(resumeThreadId),
+		});
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Regenerate (edit / reload)
+// ---------------------------------------------------------------------------
+
+export async function regenerateChat(
+	ctx: EngineContext,
+	newUserQuery: string | null,
+	editExtras?: {
+		userMessageContent: ThreadMessageLike["content"];
+		userImages: NewChatUserImagePayload[];
+		sourceUserMessageId?: string;
+	},
+	editFromPosition?: {
+		fromMessageId?: number | null;
+		revertActions?: boolean;
+	}
+): Promise<void> {
+	const { workspaceId, threadId, priorMessages } = ctx;
+	if (!threadId) {
+		toast.error("Cannot regenerate: no active chat thread");
+		return;
+	}
+	const streamThreadId = threadId;
+
+	const isEdit = newUserQuery !== null;
+
+	// Supersede any previous in-flight turn.
+	chatStreamStore.abortActive();
+
+	const messageDocumentsMap = jotaiStore.get(messageDocumentsMapAtom);
+	const localFilesystemEnabled =
+		jotaiStore.get(agentFlagsAtom).data?.enable_desktop_local_filesystem === true;
+	const disabledTools = jotaiStore.get(disabledToolsAtom);
+
+	// Extract the original user query BEFORE removing messages (reload mode).
+	let userQueryToDisplay: string | undefined;
+	let originalUserMessageContent: ThreadMessageLike["content"] | null = null;
+	let originalUserMessageMetadata: ThreadMessageLike["metadata"] | undefined;
+	let sourceUserMessageId: string | undefined = editExtras?.sourceUserMessageId;
+
+	if (!isEdit) {
+		const lastUserMessage = [...priorMessages].reverse().find((m) => m.role === "user");
+		if (lastUserMessage) {
+			sourceUserMessageId = lastUserMessage.id;
+			originalUserMessageContent = lastUserMessage.content;
+			originalUserMessageMetadata = lastUserMessage.metadata;
+			for (const part of lastUserMessage.content) {
+				if (typeof part === "object" && part.type === "text" && "text" in part) {
+					userQueryToDisplay = part.text;
+					break;
+				}
+			}
+		}
+	} else {
+		userQueryToDisplay = newUserQuery;
+	}
+
+	// Seed the durable overlay with the pre-regenerate conversation and flip
+	// to running so the page renders the live stream.
+	chatStreamStore.begin(streamThreadId, priorMessages);
+
+	const controller = new AbortController();
+	chatStreamStore.beginActive(streamThreadId, controller);
+
+	let userMsgId = `msg-user-${Date.now()}`;
+	let assistantMsgId = `msg-assistant-${Date.now()}`;
+	const currentThinkingSteps = new Map<string, ThinkingStepData>();
+
+	const contentPartsState: ContentPartsState = {
+		contentParts: [],
+		currentTextPartIndex: -1,
+		currentReasoningPartIndex: -1,
+		toolCallIndices: new Map(),
+	};
+	const { contentParts } = contentPartsState;
+	let regenerateAccepted = false;
+	let streamBatcher: FrameBatchedUpdater | null = null;
+
+	const userMessage: ThreadMessageLike = {
+		id: userMsgId,
+		role: "user",
+		content: isEdit
+			? (editExtras?.userMessageContent ?? [{ type: "text", text: newUserQuery ?? "" }])
+			: originalUserMessageContent || [{ type: "text", text: userQueryToDisplay || "" }],
+		createdAt: new Date(),
+		metadata: isEdit ? undefined : originalUserMessageMetadata,
+	};
+	const sourceMentionedDocs =
+		sourceUserMessageId && messageDocumentsMap[sourceUserMessageId]
+			? messageDocumentsMap[sourceUserMessageId]
+			: [];
+	try {
+		const selection = await getAgentFilesystemSelection(workspaceId, { localFilesystemEnabled });
+		const regenerateDocIds = sourceMentionedDocs.filter((d) => d.kind === "doc").map((d) => d.id);
+		const regenerateFolderIds = sourceMentionedDocs
+			.filter((d) => d.kind === "folder")
+			.map((d) => d.id);
+		const regenerateConnectors = sourceMentionedDocs.filter((d) => d.kind === "connector");
+		const regenerateThreadIds = sourceMentionedDocs
+			.filter((d) => d.kind === "thread")
+			.map((d) => d.id);
+
+		const requestBody: Record<string, unknown> = {
+			workspace_id: workspaceId,
+			user_query: newUserQuery,
+			disabled_tools: disabledTools.length > 0 ? disabledTools : undefined,
+			filesystem_mode: selection.filesystem_mode,
+			client_platform: selection.client_platform,
+			local_filesystem_mounts: selection.local_filesystem_mounts,
+			mentioned_document_ids: regenerateDocIds.length > 0 ? regenerateDocIds : undefined,
+			mentioned_folder_ids: regenerateFolderIds.length > 0 ? regenerateFolderIds : undefined,
+			mentioned_connector_ids:
+				regenerateConnectors.length > 0 ? regenerateConnectors.map((d) => d.id) : undefined,
+			mentioned_connectors: regenerateConnectors.length > 0 ? regenerateConnectors : undefined,
+			mentioned_thread_ids: regenerateThreadIds.length > 0 ? regenerateThreadIds : undefined,
+			mentioned_documents: sourceMentionedDocs.length > 0 ? sourceMentionedDocs : undefined,
+		};
+		if (isEdit) {
+			requestBody.user_images = editExtras?.userImages ?? [];
+		}
+		if (editFromPosition?.fromMessageId != null) {
+			requestBody.from_message_id = editFromPosition.fromMessageId;
+			if (editFromPosition.revertActions) {
+				requestBody.revert_actions = true;
+			}
+		}
+		const response = await fetchWithTurnCancellingRetry(() =>
+			authenticatedFetch(getRegenerateUrl(streamThreadId), {
+				method: "POST",
+				headers: { "Content-Type": "application/json" },
+				body: JSON.stringify(requestBody),
+				signal: controller.signal,
+			})
+		);
+
+		if (!response.ok) {
+			throw await toHttpResponseError(response);
+		}
+		regenerateAccepted = true;
+
+		chatStreamStore.setMessages(streamThreadId, (prev) => {
+			let base = prev;
+			if (editFromPosition?.fromMessageId != null) {
+				const targetId = `msg-${editFromPosition.fromMessageId}`;
+				const sliceIndex = prev.findIndex((m) => m.id === targetId);
+				if (sliceIndex >= 0) {
+					base = prev.slice(0, sliceIndex);
+				}
+			} else if (prev.length >= 2) {
+				base = prev.slice(0, -2);
+			}
+			return [
+				...base,
+				userMessage,
+				{
+					id: assistantMsgId,
+					role: "assistant",
+					content: [{ type: "text", text: "" }],
+					createdAt: new Date(),
+				},
+			];
+		});
+		if (sourceMentionedDocs.length > 0) {
+			jotaiStore.set(messageDocumentsMapAtom, (prev) => ({
+				...prev,
+				[userMsgId]: sourceMentionedDocs,
+			}));
+		}
+
+		const flushMessages = () => {
+			chatStreamStore.setMessages(streamThreadId, (prev) =>
+				prev.map((m) =>
+					m.id === assistantMsgId
+						? { ...m, content: buildContentForUI(contentPartsState, toolsWithUI) }
+						: m
+				)
+			);
+		};
+		const { batcher, scheduleFlush, forceFlush } = createStreamFlushHelpers(flushMessages);
+		streamBatcher = batcher;
+
+		await consumeSseEvents(response, async (parsed) => {
+			if (
+				processSharedStreamEvent(parsed, {
+					contentPartsState,
+					toolsWithUI,
+					currentThinkingSteps,
+					scheduleFlush,
+					forceFlush,
+					onTokenUsage: (data) => {
+						tokenUsageStore.set(assistantMsgId, data);
+					},
+					onTurnStatus: (data) => {
+						if (data.status === "cancelling") {
+							chatStreamStore.markRecentCancel();
+						}
+					},
+				})
+			) {
+				return;
+			}
+			switch (parsed.type) {
+				case "data-action-log": {
+					applyActionLogSse(queryClient, streamThreadId, workspaceId, parsed.data);
+					break;
+				}
+
+				case "data-action-log-updated": {
+					applyActionLogUpdatedSse(
+						queryClient,
+						streamThreadId,
+						parsed.data.id,
+						parsed.data.reversible
+					);
+					break;
+				}
+
+				case "data-turn-info": {
+					const turnId = readStreamedChatTurnId(parsed.data);
+					if (turnId) {
+						chatStreamStore.setMessages(streamThreadId, (prev) =>
+							applyTurnIdToAssistantMessageList(prev, assistantMsgId, turnId)
+						);
+					}
+					break;
+				}
+
+				case "data-user-message-id": {
+					const parsedMsg = readStreamedMessageId(parsed.data);
+					if (!parsedMsg) break;
+					const newUserMsgId = `msg-${parsedMsg.messageId}`;
+					const oldUserMsgId = userMsgId;
+					chatStreamStore.setMessages(streamThreadId, (prev) =>
+						prev.map((m) =>
+							m.id === oldUserMsgId
+								? mergeChatTurnIdIntoMessage({ ...m, id: newUserMsgId }, parsedMsg.turnId)
+								: m
+						)
+					);
+					if (sourceMentionedDocs.length > 0) {
+						jotaiStore.set(messageDocumentsMapAtom, (prev) => {
+							if (!(oldUserMsgId in prev)) {
+								return { ...prev, [newUserMsgId]: sourceMentionedDocs };
+							}
+							const { [oldUserMsgId]: _removed, ...rest } = prev;
+							return { ...rest, [newUserMsgId]: sourceMentionedDocs };
+						});
+					}
+					userMsgId = newUserMsgId;
+					break;
+				}
+
+				case "data-assistant-message-id": {
+					const parsedMsg = readStreamedMessageId(parsed.data);
+					if (!parsedMsg) break;
+					const newAssistantMsgId = `msg-${parsedMsg.messageId}`;
+					const oldAssistantMsgId = assistantMsgId;
+					tokenUsageStore.rename(oldAssistantMsgId, newAssistantMsgId);
+					chatStreamStore.setMessages(streamThreadId, (prev) =>
+						prev.map((m) =>
+							m.id === oldAssistantMsgId
+								? mergeChatTurnIdIntoMessage({ ...m, id: newAssistantMsgId }, parsedMsg.turnId)
+								: m
+						)
+					);
+					assistantMsgId = newAssistantMsgId;
+					break;
+				}
+
+				case "data-revert-results": {
+					const summary = parsed.data;
+					const failureCount =
+						summary.failed + summary.not_reversible + (summary.permission_denied ?? 0);
+					if (failureCount > 0) {
+						toast.warning(
+							`Pre-revert: ${summary.reverted}/${summary.total} undone, ${failureCount} could not be rolled back.`
+						);
+					} else if (summary.reverted > 0) {
+						toast.success(
+							summary.reverted === 1
+								? "Reverted 1 downstream action before regenerating."
+								: `Reverted ${summary.reverted} downstream actions before regenerating.`
+						);
+					}
+					for (const r of summary.results) {
+						if (r.status === "reverted" || r.status === "already_reverted") {
+							markActionRevertedInCache(
+								queryClient,
+								streamThreadId,
+								r.action_id,
+								r.new_action_id ?? null
+							);
+						}
+					}
+					break;
+				}
+			}
+		});
+
+		batcher.flush();
+
+		if (contentParts.length > 0) {
+			trackChatResponseReceived(workspaceId, streamThreadId);
+		}
+	} catch (error) {
+		streamBatcher?.dispose();
+		await handleStreamTerminalError({
+			error,
+			flow: "regenerate",
+			threadId: streamThreadId,
+			assistantMsgId,
+			accepted: regenerateAccepted,
+			workspaceId,
+		});
+	} finally {
+		chatStreamStore.setRunning(streamThreadId, false);
+		chatStreamStore.clearActive(controller);
+		void queryClient.invalidateQueries({
+			queryKey: cacheKeys.threads.messages(streamThreadId),
+		});
+		void queryClient.invalidateQueries({
+			queryKey: cacheKeys.threads.detail(streamThreadId),
+		});
+	}
+}
+
+export type { HitlDecision };
diff --git a/surfsense_web/lib/chat/stream-engine/helpers.ts b/surfsense_web/lib/chat/stream-engine/helpers.ts
new file mode 100644
index 000000000..afa1851e1
--- /dev/null
+++ b/surfsense_web/lib/chat/stream-engine/helpers.ts
@@ -0,0 +1,154 @@
+import { z } from "zod";
+import type { MentionedDocumentInfo } from "@/atoms/chat/mentioned-documents.atom";
+import type { ToolUIGate } from "@/lib/chat/streaming-state";
+
+/**
+ * Every tool call renders a card. The sentinel ``"all"`` matches every tool
+ * — the legacy ``BASE_TOOLS_WITH_UI`` allowlist was dropped so unknown tool
+ * calls route through the generic ``ToolFallback``. Persisted payload size
+ * stays bounded because the backend's ``format_thinking_step`` summarisation
+ * and the ``result_length``-only default for unknown tools keep the JSON
+ * from ballooning.
+ */
+export const TOOLS_WITH_UI_ALL: ToolUIGate = "all";
+
+export const TURN_CANCELLING_INITIAL_DELAY_MS = 200;
+export const TURN_CANCELLING_BACKOFF_FACTOR = 2;
+export const TURN_CANCELLING_MAX_DELAY_MS = 1500;
+export const RECENT_CANCEL_WINDOW_MS = 5_000;
+
+export function sleep(ms: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export function computeFallbackTurnCancellingRetryDelay(attempt: number): number {
+	const safeAttempt = Math.max(1, attempt);
+	const raw =
+		TURN_CANCELLING_INITIAL_DELAY_MS * TURN_CANCELLING_BACKOFF_FACTOR ** (safeAttempt - 1);
+	return Math.min(raw, TURN_CANCELLING_MAX_DELAY_MS);
+}
+
+/**
+ * Generate a synthetic ``toolCallId`` for an action_request that has no
+ * matching streamed tool-call card (HITL-blocked subagent calls don't surface
+ * as tool-call events). Suffixes a counter when the base id is already taken
+ * — sequential interrupts for the same tool name otherwise collide on
+ * ``interrupt-${name}-${i}`` and crash assistant-ui with a duplicate-key error.
+ */
+export function freshSynthToolCallId(
+	toolCallIndices: Map<string, number>,
+	toolName: string,
+	index: number
+): string {
+	const base = `interrupt-${toolName}-${index}`;
+	if (!toolCallIndices.has(base)) return base;
+	let n = 1;
+	while (toolCallIndices.has(`${base}-${n}`)) n++;
+	return `${base}-${n}`;
+}
+
+/**
+ * Pair each ``action_request`` to a unique pending tool-call card, preserving
+ * order so ``decisions[i]`` lines up with ``action_requests[i]`` on the wire.
+ *
+ * Same-name bundles (e.g. three ``create_jira_issue``) used to collapse onto
+ * one card because the matcher keyed by name; this consumes each card via the
+ * ``claimed`` set and walks forward in DOM order.
+ */
+export function pairBundleToolCallIds(
+	toolCallIndices: Map<string, number>,
+	contentParts: Array<{
+		type: string;
+		toolName?: string;
+		result?: unknown;
+	}>,
+	actionRequests: ReadonlyArray<{ name: string }>
+): Array<string | null> {
+	const claimed = new Set<string>();
+	const paired: Array<string | null> = [];
+	for (const action of actionRequests) {
+		let matched: string | null = null;
+		for (const [tcId, idx] of toolCallIndices) {
+			if (claimed.has(tcId)) continue;
+			const part = contentParts[idx];
+			if (!part || part.type !== "tool-call" || part.toolName !== action.name) continue;
+			const result = part.result as Record<string, unknown> | undefined | null;
+			if (result == null || (result.__interrupt__ === true && !result.__decided__)) {
+				matched = tcId;
+				claimed.add(tcId);
+				break;
+			}
+		}
+		paired.push(matched);
+	}
+	return paired;
+}
+
+/**
+ * Zod schema for mentioned document info (for type-safe parsing).
+ *
+ * ``kind`` defaults to ``"doc"`` so messages persisted before folder
+ * mentions existed deserialise unchanged.
+ */
+const MentionedDocumentInfoSchema = z.object({
+	id: z.number(),
+	title: z.string(),
+	document_type: z.string().optional(),
+	kind: z
+		.union([z.literal("doc"), z.literal("folder"), z.literal("connector"), z.literal("thread")])
+		.optional()
+		.default("doc"),
+	connector_type: z.string().optional(),
+	account_name: z.string().optional(),
+});
+
+const MentionedDocumentsPartSchema = z.object({
+	type: z.literal("mentioned-documents"),
+	documents: z.array(MentionedDocumentInfoSchema),
+});
+
+/**
+ * Extract mentioned documents from message content (type-safe with Zod).
+ */
+export function extractMentionedDocuments(content: unknown): MentionedDocumentInfo[] {
+	if (!Array.isArray(content)) return [];
+
+	for (const part of content) {
+		const result = MentionedDocumentsPartSchema.safeParse(part);
+		if (result.success) {
+			return result.data.documents.map<MentionedDocumentInfo>((doc) => {
+				if (doc.kind === "connector") {
+					return {
+						id: doc.id,
+						title: doc.title,
+						kind: "connector",
+						connector_type: doc.connector_type ?? doc.document_type ?? "UNKNOWN",
+						account_name: doc.account_name ?? doc.title,
+					};
+				}
+				if (doc.kind === "folder") {
+					return {
+						id: doc.id,
+						title: doc.title,
+						kind: "folder",
+					};
+				}
+				if (doc.kind === "thread") {
+					return {
+						id: doc.id,
+						title: doc.title,
+						kind: "thread",
+					};
+				}
+				return {
+					id: doc.id,
+					title: doc.title,
+					document_type: doc.document_type ?? "UNKNOWN",
+					kind: "doc",
+				};
+			});
+		}
+	}
+
+	return [];
+}
diff --git a/surfsense_web/lib/chat/stream-engine/store.ts b/surfsense_web/lib/chat/stream-engine/store.ts
new file mode 100644
index 000000000..44627663f
--- /dev/null
+++ b/surfsense_web/lib/chat/stream-engine/store.ts
@@ -0,0 +1,177 @@
+import type { ThreadMessageLike } from "@assistant-ui/react";
+import { createTokenUsageStore } from "@/components/assistant-ui/token-usage-context";
+import type { PendingInterruptState } from "@/features/chat-messages/hitl";
+
+/**
+ * Durable, per-thread streaming state for a single in-flight chat turn.
+ *
+ * Lives at module scope (see {@link chatStreamStore}) so a running turn's
+ * messages / interrupts survive the chat page unmounting during in-app
+ * navigation. The React tree consumes it through ``useChatStream`` via
+ * ``useSyncExternalStore`` (state lives outside the render cycle).
+ */
+export interface ThreadStreamState {
+	threadId: number;
+	messages: ThreadMessageLike[];
+	isRunning: boolean;
+	pendingInterrupts: PendingInterruptState[];
+}
+
+type Listener = () => void;
+
+/**
+ * Module-level singleton external store for chat streaming.
+ *
+ * Single-active-stream invariant: at most one turn streams at a time,
+ * tracked by {@link active}. Per-thread state is still keyed by threadId so
+ * the currently-streaming thread and the currently-viewed thread can differ
+ * (e.g. a stream finishes while the user is on another chat).
+ *
+ * ponytail: unbounded ``states`` map is bounded in practice by
+ * ``clearInactive`` (called on navigation) + ``clear`` (called after the DB
+ * re-hydrates a finished turn). Upgrade path if that ever leaks: LRU cap.
+ */
+class ChatStreamStore {
+	private states = new Map<number, ThreadStreamState>();
+	private listeners = new Set<Listener>();
+
+	/** Shared, cross-navigation token-usage store (one instance app-wide). */
+	readonly tokenUsage = createTokenUsageStore();
+
+	/** The one in-flight turn's abort handle, or null when idle. */
+	private active: { threadId: number; controller: AbortController } | null = null;
+
+	/** Timestamp of the last explicit cancel, for the THREAD_BUSY retry window. */
+	recentCancelRequestedAt = 0;
+
+	subscribe = (listener: Listener): (() => void) => {
+		this.listeners.add(listener);
+		return () => {
+			this.listeners.delete(listener);
+		};
+	};
+
+	private notify(): void {
+		for (const l of this.listeners) l();
+	}
+
+	/** Snapshot for ``useSyncExternalStore``; stable ref between mutations. */
+	getSnapshot = (threadId: number | null): ThreadStreamState | null => {
+		if (threadId == null) return null;
+		return this.states.get(threadId) ?? null;
+	};
+
+	isRunning(threadId: number | null): boolean {
+		if (threadId == null) return false;
+		return this.states.get(threadId)?.isRunning ?? false;
+	}
+
+	getMessages(threadId: number): ThreadMessageLike[] {
+		return this.states.get(threadId)?.messages ?? [];
+	}
+
+	getPendingInterrupts(threadId: number): PendingInterruptState[] {
+		return this.states.get(threadId)?.pendingInterrupts ?? [];
+	}
+
+	private ensure(threadId: number): ThreadStreamState {
+		let s = this.states.get(threadId);
+		if (!s) {
+			s = { threadId, messages: [], isRunning: false, pendingInterrupts: [] };
+			this.states.set(threadId, s);
+		}
+		return s;
+	}
+
+	private commit(threadId: number, next: ThreadStreamState): void {
+		this.states.set(threadId, next);
+		this.notify();
+	}
+
+	/** Seed a thread's state at the start of a fresh turn (running=true). */
+	begin(threadId: number, messages: ThreadMessageLike[]): void {
+		this.commit(threadId, { threadId, messages, isRunning: true, pendingInterrupts: [] });
+	}
+
+	setMessages(threadId: number, updater: (prev: ThreadMessageLike[]) => ThreadMessageLike[]): void {
+		const prev = this.ensure(threadId);
+		const messages = updater(prev.messages);
+		if (messages === prev.messages) return;
+		this.commit(threadId, { ...prev, messages });
+	}
+
+	setRunning(threadId: number, running: boolean): void {
+		const prev = this.ensure(threadId);
+		if (prev.isRunning === running) return;
+		this.commit(threadId, { ...prev, isRunning: running });
+	}
+
+	setPendingInterrupts(
+		threadId: number,
+		updater: (prev: PendingInterruptState[]) => PendingInterruptState[]
+	): void {
+		const prev = this.ensure(threadId);
+		const pendingInterrupts = updater(prev.pendingInterrupts);
+		if (pendingInterrupts === prev.pendingInterrupts) return;
+		this.commit(threadId, { ...prev, pendingInterrupts });
+	}
+
+	/**
+	 * A thread whose overlay must survive DB re-hydration / navigation: it is
+	 * either streaming or paused awaiting a HITL decision (the pending
+	 * interrupts + interrupt cards live only in the overlay).
+	 */
+	private isPinned(s: ThreadStreamState): boolean {
+		return s.isRunning || s.pendingInterrupts.length > 0;
+	}
+
+	/** Drop a thread's overlay once the DB is authoritative. No-op while pinned. */
+	clear(threadId: number): void {
+		const s = this.states.get(threadId);
+		if (!s || this.isPinned(s)) return;
+		this.states.delete(threadId);
+		this.notify();
+	}
+
+	/** Evict every non-pinned thread except ``exceptThreadId`` (memory bound). */
+	clearInactive(exceptThreadId: number | null): void {
+		let changed = false;
+		for (const [id, s] of this.states) {
+			if (id === exceptThreadId || this.isPinned(s)) continue;
+			this.states.delete(id);
+			changed = true;
+		}
+		if (changed) this.notify();
+	}
+
+	// ---- active-stream lifecycle -------------------------------------------
+
+	/** Register a new in-flight turn, aborting any previous one first. */
+	beginActive(threadId: number, controller: AbortController): void {
+		this.abortActive();
+		this.active = { threadId, controller };
+	}
+
+	get activeThreadId(): number | null {
+		return this.active?.threadId ?? null;
+	}
+
+	/** Clear the active handle iff it still points at ``controller``. */
+	clearActive(controller: AbortController): void {
+		if (this.active?.controller === controller) this.active = null;
+	}
+
+	/** Abort the in-flight turn's fetch (client disconnect, not a server stop). */
+	abortActive(): void {
+		if (this.active) {
+			this.active.controller.abort();
+			this.active = null;
+		}
+	}
+
+	markRecentCancel(): void {
+		this.recentCancelRequestedAt = Date.now();
+	}
+}
+
+export const chatStreamStore = new ChatStreamStore();
diff --git a/surfsense_web/lib/chat/stream-engine/use-chat-stream.ts b/surfsense_web/lib/chat/stream-engine/use-chat-stream.ts
new file mode 100644
index 000000000..ccfb32481
--- /dev/null
+++ b/surfsense_web/lib/chat/stream-engine/use-chat-stream.ts
@@ -0,0 +1,18 @@
+"use client";
+
+import { useCallback, useSyncExternalStore } from "react";
+import { chatStreamStore, type ThreadStreamState } from "./store";
+
+/**
+ * Subscribe to the durable streaming state for a given thread.
+ *
+ * Returns the live ``ThreadStreamState`` while a turn is streaming (or
+ * pending re-hydration from the DB), or ``null`` when the thread has no
+ * active overlay — in which case the page falls back to its DB-hydrated
+ * messages. State lives in the module-level {@link chatStreamStore}, so it
+ * survives the chat page unmounting during in-app navigation.
+ */
+export function useChatStream(threadId: number | null): ThreadStreamState | null {
+	const getSnapshot = useCallback(() => chatStreamStore.getSnapshot(threadId), [threadId]);
+	return useSyncExternalStore(chatStreamStore.subscribe, getSnapshot, () => null);
+}
diff --git a/surfsense_web/lib/connectors-marketing/instagram.tsx b/surfsense_web/lib/connectors-marketing/instagram.tsx
index d22400b7a..5422a0c90 100644
--- a/surfsense_web/lib/connectors-marketing/instagram.tsx
+++ b/surfsense_web/lib/connectors-marketing/instagram.tsx
@@ -6,28 +6,32 @@ export const instagram: ConnectorPageContent = {
 	name: "Instagram",
 	icon: IconBrandInstagram,
 
-	metaTitle: "Instagram Scraper API for Creator Research | SurfSense",
+	metaTitle: "Instagram Scraper API for Profiles and Reels | SurfSense",
 	metaDescription:
-		"Scrape public Instagram posts, reels, and profiles at scale with the SurfSense Instagram Scraper API. No login, no official API, plus a free tier. Start now.",
+		"Instagram scraper API for public profiles, posts, and reels. No login or Graph API review. Structured data for AI agents, plus a free tier. Start now.",
 	keywords: [
 		"instagram scraper",
 		"instagram scraper api",
 		"instagram api",
 		"instagram api alternative",
 		"scrape instagram",
+		"instagram scraping",
 		"instagram graph api alternative",
 		"instagram profile scraper",
 		"instagram post scraper",
+		"instagram posts scraper",
 		"instagram reel scraper",
+		"instagram reels scraper",
+		"instagram data scraper",
 		"instagram data api",
 		"instagram mcp server",
 		"creator research",
 		"social listening",
 	],
 
-	h1: "Instagram Scraper API for Creator Research and Social Listening",
+	h1: "Instagram Scraper API for Profiles, Posts, and Reels",
 	heroLede:
-		"The SurfSense Instagram API extracts public posts, reels, and profile details without logging in or registering for the Instagram Graph API. Give your AI agents a live feed of what creators post, so you spot trends and shifts in engagement first.",
+		"The SurfSense Instagram scraper extracts public profiles, posts, and reels without logging in or registering for the Instagram Graph API. Give your AI agents a live feed of what creators post, so you spot trends and shifts in engagement first.",
 
 	transcript: {
 		prompt: "Pull recent reels from @competitor and summarize what they're posting",
@@ -54,48 +58,48 @@ export const instagram: ConnectorPageContent = {
 	},
 
 	extractIntro:
-		"Every call returns structured items keyed by type. Point the API at a public profile, post, or reel URL, or discover creators with a search query.",
+		"Every Instagram scraper call returns structured items keyed by type. Point the API at a public profile, post, or reel URL, or discover creators with a search query.",
 	extractFields: [
 		{
-			label: "Posts & Reels",
+			label: "Posts and reels",
 			description:
-				"Caption, hashtags, mentions, like and comment counts, media URLs, dimensions, and timestamp.",
+				"Caption, hashtags, mentions, like and comment counts, media URLs, dimensions, and timestamp from any public post or reel.",
 		},
 		{
-			label: "Profiles",
+			label: "Profile data",
 			description:
-				"Follower, following, and post counts, bio, external URL, verified and business flags.",
+				"Follower, following, and post counts, bio, external URL, verified and business flags for public Instagram profiles.",
 		},
 		{
-			label: "Owner & Media",
+			label: "Owner and media",
 			description:
 				"Owner username and id on every item, plus image and video URLs, alt text, and view counts.",
 		},
 	],
 
-	useCasesHeading: "What teams do with the Instagram API",
+	useCasesHeading: "What teams do with the Instagram scraper API",
 	useCases: [
 		{
 			title: "Creator and competitor monitoring",
 			description:
-				"Track what your competitors and target creators post, and how engagement moves. Feed the stream to an agent that flags viral formats, launches, and shifts in cadence the moment they land.",
+				"Scrape Instagram profiles and feeds to track what competitors and target creators post, and how engagement moves. Feed the stream to an agent that flags viral formats, launches, and shifts in cadence the moment they land.",
 		},
 		{
 			title: "Content and format research",
 			description:
-				"Study a creator's recent posts and reels to see which formats earn the most likes and comments, and turn that into a content calendar your team can act on.",
+				"Pull a creator's recent posts and reels to see which formats earn the most likes and comments, and turn that into a content calendar your team can act on.",
 		},
 		{
 			title: "Influencer vetting and outreach",
 			description:
-				"Verify a creator's follower count, post cadence, and real engagement from public data before you pay for a partnership.",
+				"Use the Instagram profile scraper to verify follower count, post cadence, and real engagement from public data before you pay for a partnership.",
 		},
 	],
 
 	comparison: {
-		heading: "An Instagram API alternative built for agents",
+		heading: "An Instagram Graph API alternative built for agents",
 		intro:
-			"The official Instagram Graph API requires a Business account, app review, and access tokens, and it can't read arbitrary public profiles. Here is how SurfSense compares.",
+			"The official Instagram Graph API requires a Business account, app review, and access tokens, and it cannot read arbitrary public profiles. SurfSense is an Instagram API alternative for public data. Here is how it compares.",
 		columnLabel: "Instagram Graph API",
 		rows: [
 			{
@@ -259,7 +263,12 @@ export const instagram: ConnectorPageContent = {
 		{
 			question: "Do I need an Instagram account or the Graph API?",
 			answer:
-				"No. This is an independent alternative to the Instagram Graph API, not a wrapper. You do not create a Business account, pass app review, or manage access tokens. You call the SurfSense API with one key, or add the MCP server to your agent, and get structured data back.",
+				"No. This Instagram scraper API is an independent alternative to the Instagram Graph API, not a wrapper. You do not create a Business account, pass app review, or manage access tokens. You call SurfSense with one key, or add the MCP server to your agent, and get structured profile, post, and reel data back.",
+		},
+		{
+			question: "What Instagram data can I scrape?",
+			answer:
+				"Public profiles, posts, and reels. Each item includes captions, hashtags, mentions, engagement counts, media URLs, and owner metadata. Point the Instagram profile scraper at a handle, or pass post and reel URLs directly. Discover creators with search queries when you do not have a URL yet.",
 		},
 		{
 			question: "What are the rate limits?",
@@ -274,11 +283,11 @@ export const instagram: ConnectorPageContent = {
 	],
 
 	related: [
-		{ label: "Reddit API", href: "/reddit" },
+		{ label: "TikTok API", href: "/tiktok" },
 		{ label: "YouTube API", href: "/youtube" },
+		{ label: "Reddit API", href: "/reddit" },
 		{ label: "Google Maps API", href: "/google-maps" },
 		{ label: "SERP API", href: "/google-search" },
 		{ label: "SurfSense MCP Server", href: "/mcp-server" },
-		{ label: "Read the docs", href: "/docs" },
 	],
 };
diff --git a/surfsense_web/lib/connectors-marketing/tiktok.tsx b/surfsense_web/lib/connectors-marketing/tiktok.tsx
index d77865633..6063fd1ae 100644
--- a/surfsense_web/lib/connectors-marketing/tiktok.tsx
+++ b/surfsense_web/lib/connectors-marketing/tiktok.tsx
@@ -6,30 +6,33 @@ export const tiktok: ConnectorPageContent = {
 	name: "TikTok",
 	icon: IconBrandTiktok,
 
-	metaTitle: "TikTok Scraper API for Trend and Creator Research | SurfSense",
+	metaTitle: "TikTok Scraper API for Videos and Comments | SurfSense",
 	metaDescription:
-		"Scrape public TikTok videos, comments, accounts, and trending feeds by hashtag, profile, or URL with the SurfSense TikTok Scraper API. No approval process or research-API gatekeeping, plus a free tier. Start now.",
+		"TikTok scraper API for public videos, comments, hashtags, and profiles. No Research API approval. Structured data for AI agents, plus a free tier. Start now.",
 	keywords: [
 		"tiktok scraper",
 		"tiktok scraper api",
 		"tiktok api",
 		"tiktok api alternative",
 		"scrape tiktok",
+		"tiktok scraping",
+		"tiktok research api alternative",
 		"tiktok data api",
-		"tiktok hashtag scraper",
 		"tiktok comments scraper",
+		"tiktok comment scraper",
+		"tiktok hashtag scraper",
+		"tiktok profile scraper",
+		"tiktok video scraper",
 		"tiktok trending scraper",
 		"tiktok user search",
-		"tiktok trend tracking",
 		"tiktok mcp",
 		"social listening",
 		"influencer research tool",
-		"short-form video analytics",
 	],
 
-	h1: "TikTok Scraper API for Trend and Creator Research",
+	h1: "TikTok Scraper API for Videos, Comments, and Trend Research",
 	heroLede:
-		"The SurfSense TikTok API extracts public videos by hashtag, creator profile, or URL without TikTok's approval-gated Research API. Give your AI agents a live feed of what your market watches and shares, so you catch a trend while it is still rising.",
+		"The SurfSense TikTok scraper extracts public videos by hashtag, creator profile, or URL, plus comment threads and trending feeds, without TikTok's approval-gated Research API. Give your AI agents a live feed of what your market watches and shares, so you catch a trend while it is still rising.",
 
 	transcript: {
 		prompt: "Find trending TikToks about meal prep this week",
@@ -55,46 +58,48 @@ export const tiktok: ConnectorPageContent = {
 	},
 
 	extractIntro:
-		"Every call returns structured items. Scrape videos from a hashtag, creator profile, or video URL — or switch verbs to pull a video's comments, discover accounts by keyword, or fetch the current trending feed.",
+		"Every TikTok scraper call returns structured items. Scrape videos from a hashtag, creator profile, or video URL, or switch verbs to pull a video's comments, discover accounts by keyword, or fetch the current trending feed.",
 	extractFields: [
 		{
 			label: "Videos",
-			description: "Caption text, canonical web URL, duration, and cover image for each video.",
+			description:
+				"Caption text, canonical web URL, duration, and cover image for each TikTok video.",
 		},
 		{
 			label: "Engagement",
 			description:
-				"Play, like, comment, share, and save counts — the signal for what is breaking out.",
+				"Play, like, comment, share, and save counts, the signal for what is breaking out.",
 		},
 		{
-			label: "Authors",
+			label: "Authors and profiles",
 			description: "Creator handle, nickname, follower and heart counts, and verified status.",
 		},
+		{
+			label: "Comments",
+			description:
+				"Public comment threads on any video URL, so you can read audience reaction beyond vanity views.",
+		},
 		{
 			label: "Music",
-			description: "Track name, artist, and whether the sound is original — the seed of a trend.",
+			description: "Track name, artist, and whether the sound is original, the seed of a trend.",
 		},
 		{
 			label: "Hashtags",
 			description: "Every hashtag on a video, so you can map a topic cluster or campaign.",
 		},
-		{
-			label: "Timestamps",
-			description: "Created and scraped times so you can track a video's momentum over runs.",
-		},
 	],
 
-	useCasesHeading: "What teams do with the TikTok API",
+	useCasesHeading: "What teams do with the TikTok scraper API",
 	useCases: [
 		{
 			title: "Trend and hashtag monitoring",
 			description:
-				"Track a hashtag and feed the stream to an agent that flags breakout videos, rising sounds, and formats before they saturate. Catch the wave while it is still rising, not after.",
+				"Use the TikTok hashtag scraper to track a topic and feed the stream to an agent that flags breakout videos, rising sounds, and formats before they saturate. Catch the wave while it is still rising, not after.",
 		},
 		{
 			title: "Creator and influencer discovery",
 			description:
-				"Surface the creators driving a topic, ranked by real engagement, so your team shortlists partners from data instead of a manager's pitch deck.",
+				"Scrape TikTok profiles and search users by keyword to surface the creators driving a topic, ranked by real engagement, so your team shortlists partners from data instead of a manager's pitch deck.",
 		},
 		{
 			title: "Competitor content analysis",
@@ -102,16 +107,16 @@ export const tiktok: ConnectorPageContent = {
 				"Watch what your category posts and what actually lands. Turn a competitor's best-performing formats and hooks into your own content brief.",
 		},
 		{
-			title: "Campaign and sentiment tracking",
+			title: "Campaign and comment sentiment",
 			description:
-				"Measure how a launch or branded hashtag spreads across TikTok — video count, reach, and engagement over time — then pull the comments on top videos to read how the audience actually reacts, not just a vanity view count.",
+				"Measure how a launch or branded hashtag spreads across TikTok, then use the TikTok comments scraper on top videos to read how the audience actually reacts, not just a vanity view count.",
 		},
 	],
 
 	comparison: {
-		heading: "A TikTok API alternative built for agents",
+		heading: "A TikTok Research API alternative built for agents",
 		intro:
-			"TikTok's official Research API is approval-gated and largely limited to academic and nonprofit use. If you cannot get access or need it for commercial research, here is how SurfSense compares.",
+			"TikTok's official Research API is approval-gated and largely limited to academic and nonprofit use. If you cannot get access or need commercial TikTok scraping, SurfSense is a TikTok API alternative. Here is how it compares.",
 		columnLabel: "Official TikTok API",
 		rows: [
 			{
@@ -154,7 +159,7 @@ export const tiktok: ConnectorPageContent = {
 
 	schema: {
 		requestNote:
-			"Provide at least one source: urls, profiles, hashtags, or search_queries. Up to 20 sources per call.",
+			"Provide at least one source: urls, profiles, or hashtags. Up to 20 sources per call. To find accounts by keyword, use the user search verb.",
 		request: [
 			{
 				name: "urls",
@@ -175,13 +180,6 @@ export const tiktok: ConnectorPageContent = {
 				defaultValue: "[]",
 				description: "Hashtag names to scrape, without the # prefix. Max 20.",
 			},
-			{
-				name: "search_queries",
-				type: "string[]",
-				defaultValue: "[]",
-				description:
-					"Keyword search terms. Keyword video search is login-walled and returns no videos — use hashtags/profiles/urls for videos, or user_search for accounts. Max 20.",
-			},
 			{
 				name: "results_per_page",
 				type: "integer",
@@ -253,9 +251,19 @@ export const tiktok: ConnectorPageContent = {
 				"SurfSense reads only public TikTok data, the same videos any logged-out visitor can see. It never logs in and cannot access private or deleted content. As always, review TikTok's terms and your own compliance needs before you run at scale.",
 		},
 		{
-			question: "Does this need the official TikTok API?",
+			question: "Does this need the official TikTok Research API?",
 			answer:
-				"No. It is an independent alternative, not a wrapper on the Research API, so there is no application or approval process. You call the SurfSense API with one key, or add the MCP server to your agent, and get structured videos back.",
+				"No. This TikTok scraper API is an independent alternative, not a wrapper on the Research API, so there is no application or approval process. You call SurfSense with one key, or add the MCP server to your agent, and get structured videos, comments, and profile data back.",
+		},
+		{
+			question: "What TikTok data can I scrape?",
+			answer:
+				"Four verbs: scrape (videos by hashtag, profile, or URL), comments (a video's public comment thread), user search (find accounts by keyword), and trending (the current Explore feed). Each returns structured items and is billed per item returned.",
+		},
+		{
+			question: "Can I scrape TikTok comments and hashtags?",
+			answer:
+				"Yes. Pass a video URL to the comments endpoint for the public comment thread. Pass hashtag names or /tag/ URLs to the TikTok hashtag scraper to pull videos under that tag. Keyword video search is login-walled on TikTok, so hashtags and direct URLs are the reliable discovery paths; to find accounts by keyword, use the user search verb.",
 		},
 		{
 			question: "What are the rate limits?",
@@ -265,18 +273,14 @@ export const tiktok: ConnectorPageContent = {
 		{
 			question: "Can I scrape a specific creator's videos?",
 			answer:
-				"Pass a profile or profile URL and you always get the account's metadata — name, followers, bio, verification. TikTok often withholds the profile video list from automated clients, so that list can come back empty even for a public account; for reliable video results, scrape by hashtag or by a direct video URL.",
-		},
-		{
-			question: "What TikTok data can I scrape?",
-			answer:
-				"Four verbs: scrape (videos by hashtag, profile, or URL), comments (a video's public comment thread), user search (find accounts by keyword — the reliable discovery path, since keyword video search is login-walled), and trending (the current Explore feed). Each returns structured items and is billed per item returned.",
+				"Pass a profile or profile URL and you always get the account's metadata: name, followers, bio, verification. TikTok often withholds the profile video list from automated clients, so that list can come back empty even for a public account. For reliable video results, scrape by hashtag or by a direct video URL.",
 		},
 	],
 
 	related: [
-		{ label: "Reddit API", href: "/reddit" },
+		{ label: "Instagram API", href: "/instagram" },
 		{ label: "YouTube API", href: "/youtube" },
+		{ label: "Reddit API", href: "/reddit" },
 		{ label: "Google Maps API", href: "/google-maps" },
 		{ label: "SERP API", href: "/google-search" },
 		{ label: "Web Crawl API", href: "/web-crawl" },
diff --git a/surfsense_web/lib/format-date.ts b/surfsense_web/lib/format-date.ts
index c2f445537..a062b08fa 100644
--- a/surfsense_web/lib/format-date.ts
+++ b/surfsense_web/lib/format-date.ts
@@ -68,3 +68,17 @@ export function formatRelativeFutureDate(dateString: string): string {
 export function formatThreadTimestamp(dateString: string): string {
 	return format(new Date(dateString), "MMM d, yyyy 'at' h:mm a");
 }
+
+/**
+ * Format a chat message timestamp for inline display under a bubble.
+ * Locale-aware, 12-hour clock. Example: "Jul 13, 10:42 PM".
+ */
+export function formatMessageTimestamp(date: Date): string {
+	return date.toLocaleDateString(undefined, {
+		month: "short",
+		day: "numeric",
+		hour: "numeric",
+		minute: "2-digit",
+		hour12: true,
+	});
+}
diff --git a/surfsense_web/lib/playground/code-snippets.selfcheck.ts b/surfsense_web/lib/playground/code-snippets.selfcheck.ts
index 33cb82124..c646d1a6c 100644
--- a/surfsense_web/lib/playground/code-snippets.selfcheck.ts
+++ b/surfsense_web/lib/playground/code-snippets.selfcheck.ts
@@ -23,7 +23,11 @@ assert.deepEqual(payload, {
 	query: "<query>",
 });
 
-const snippets = buildSnippets("https://api.example.com", "/api/v1/workspaces/1/scrapers/x/y", payload);
+const snippets = buildSnippets(
+	"https://api.example.com",
+	"/api/v1/workspaces/1/scrapers/x/y",
+	payload
+);
 
 // Every popular language is present.
 assert.deepEqual(
diff --git a/surfsense_web/lib/playground/format.ts b/surfsense_web/lib/playground/format.ts
index 0e9b75d24..fac6ccef6 100644
--- a/surfsense_web/lib/playground/format.ts
+++ b/surfsense_web/lib/playground/format.ts
@@ -11,9 +11,7 @@ export function formatCost(costMicros: number | null | undefined): string {
 /** One meter as a per-1k rate, e.g. 3500 micros/place -> "$3.50 / 1k places". */
 export function formatRate(meter: ScraperPricingMeter): string {
 	const perThousand = (meter.micros_per_unit * 1000) / 1_000_000;
-	const dollars = Number.isInteger(perThousand)
-		? perThousand.toString()
-		: perThousand.toFixed(2);
+	const dollars = Number.isInteger(perThousand) ? perThousand.toString() : perThousand.toFixed(2);
 	return `$${dollars} / 1k ${meter.unit}s`;
 }
 
diff --git a/surfsense_web/lib/playground/json-schema.ts b/surfsense_web/lib/playground/json-schema.ts
index 7cbd83be9..0e1e4544e 100644
--- a/surfsense_web/lib/playground/json-schema.ts
+++ b/surfsense_web/lib/playground/json-schema.ts
@@ -8,13 +8,7 @@
 
 type JsonObject = Record<string, unknown>;
 
-export type FieldKind =
-	| "string"
-	| "string_array"
-	| "integer"
-	| "number"
-	| "boolean"
-	| "enum";
+export type FieldKind = "string" | "string_array" | "integer" | "number" | "boolean" | "enum";
 
 export interface FormField {
 	name: string;
diff --git a/surfsense_web/lib/provider-icons.tsx b/surfsense_web/lib/provider-icons.tsx
index d3e799720..20016fdf2 100644
--- a/surfsense_web/lib/provider-icons.tsx
+++ b/surfsense_web/lib/provider-icons.tsx
@@ -29,6 +29,7 @@ import {
 	QwenIcon,
 	RecraftIcon,
 	ReplicateIcon,
+	RequestyIcon,
 	SambaNovaIcon,
 	TogetherAiIcon,
 	VertexAiIcon,
@@ -117,6 +118,8 @@ export function getProviderIcon(
 			return <RecraftIcon className={cn(className)} />;
 		case "REPLICATE":
 			return <ReplicateIcon className={cn(className)} />;
+		case "REQUESTY":
+			return <RequestyIcon className={cn(className)} />;
 		case "SAMBANOVA":
 			return <SambaNovaIcon className={cn(className)} />;
 		case "TOGETHER_AI":
diff --git a/surfsense_web/package.json b/surfsense_web/package.json
index 918b25f33..21894d224 100644
--- a/surfsense_web/package.json
+++ b/surfsense_web/package.json
@@ -1,6 +1,6 @@
 {
 	"name": "surfsense_web",
-	"version": "0.0.31",
+	"version": "0.0.32",
 	"private": true,
 	"packageManager": "pnpm@10.26.0",
 	"description": "SurfSense Frontend",